aiidalab_chemshell package¶

Subpackages¶

Submodules¶

aiidalab_chemshell.containers module¶

Logic for installing the ChemShell container and creating an AiiDA code.

This module contains the pure (non-UI) logic used to provision a ChemShell runtime for AiiDA. The intended flow is:

Detect an available container engine (Apptainer first, then Docker).
Reuse an existing local image, or acquire one by pulling the project’s image from the GitHub Container Registry.
Create (or reuse) an AiiDA ContainerizedCode on the localhost computer pointing at that image.

Apptainer is preferred; Docker is used automatically as a fallback when Apptainer is not available. The two engines differ in how images are stored (Apptainer keeps a local .sif file, Docker keeps the image in its daemon’s store) and in the engine_command used by the created code, but the executable path, code label and bind convention are identical for both.

aiidalab_chemshell.containers.build_image(engine: str, on_progress: Callable[[str], None] | None = None) → tuple[bool, str]¶

Acquire the ChemShell image for engine (Apptainer pull or Docker pull).

Parameters:

engine (str) – Either APPTAINER or DOCKER.
on_progress (Callable[[str], None], optional) – Optional callback invoked with human-readable progress messages.

Returns:

A tuple (ok, message) as returned by build_sif() or pull_docker_image().

Return type:

tuple[bool, str]

aiidalab_chemshell.containers.build_sif(on_progress: Callable[[str], None] | None = None) → tuple[bool, str]¶

Build the local ChemShell .sif image by pulling from the registry.

This pulls CONTAINER_IMAGE_URI into sif_path() using apptainer pull.

Parameters:: on_progress (Callable[[str], None], optional) – Optional callback invoked with human-readable progress messages.
Returns:: A tuple (ok, message) where ok is True on success. message contains a success note or the captured error output on failure.
Return type:: tuple[bool, str]

aiidalab_chemshell.containers.check_apptainer() → tuple[bool, str]¶

Check that Apptainer is installed and can be executed.

Returns:: A tuple (ok, message) where ok is True if Apptainer is available and returned successfully. message contains the reported version on success or a human-readable error otherwise.
Return type:: tuple[bool, str]

aiidalab_chemshell.containers.check_docker() → tuple[bool, str]¶

Check that Docker is installed and its daemon is reachable.

docker version --format '{{.Server.Version}}' is used because it contacts the daemon: a present CLI with a stopped daemon exits non-zero and is correctly reported as unavailable.

Returns:: A tuple (ok, message) where ok is True if Docker is available and the daemon responded. message contains the reported server version on success or a human-readable error otherwise.
Return type:: tuple[bool, str]

aiidalab_chemshell.containers.chemshell_code_exists() → bool¶

Return whether the ChemShell AiiDA code already exists.

Returns:: True if a code labelled chemsh@localhost exists, False otherwise.
Return type:: bool

aiidalab_chemshell.containers.create_chemshell_code(engine: str = 'apptainer')¶

Create (or reuse) the ChemShell containerized AiiDA code.

If a code labelled chemsh@localhost already exists it is loaded and returned unchanged. Otherwise a new ContainerizedCode is created for the requested engine (pointing at the local .sif image for Apptainer, or the Docker image ref for Docker), stored, and returned.

Parameters:: engine (str, optional) – Either APPTAINER (default) or DOCKER.
Returns:: The stored (or pre-existing) ChemShell code.
Return type:: aiida.orm.ContainerizedCode

aiidalab_chemshell.containers.detect_engine() → tuple[str | None, str]¶

Detect an available container engine, preferring Apptainer over Docker.

Returns:: A tuple (engine, message). engine is APPTAINER or DOCKER when one is available (Apptainer takes priority), or None when neither is. message reports the chosen engine’s version on success, or the combined reason both were rejected.
Return type:: tuple[str | None, str]

aiidalab_chemshell.containers.docker_image_exists() → bool¶

Return whether the ChemShell Docker image is present in the local store.

Returns:: True if docker image inspect reports the image, False otherwise (including when Docker is unavailable).
Return type:: bool

aiidalab_chemshell.containers.ensure_use_double_quotes(computer) → bool¶

Ensure computer escapes command-line arguments with double quotes.

Containerized codes require this: the engine_command relies on shell variable expansion ($PWD in the bind-mount arguments), which only happens inside double quotes. With the AiiDA default of single-quote escaping the $PWD token is passed literally and the bind mount is broken.

The setting is computer-wide but narrow in reach: it governs the escaping of the engine command, MPI arguments and the stdin/stdout/stderr file names. Each code’s own executable and arguments are escaped by the separate per-code use_double_quotes attribute, so enabling this does not change how other codes’ arguments are quoted.

Parameters:: computer (aiida.orm.Computer) – The computer to check and, if necessary, update.
Returns:: True if the setting was changed (was disabled, now enabled), False if it was already enabled.
Return type:: bool

aiidalab_chemshell.containers.get_localhost_computer()¶

Return the localhost AiiDA computer, creating it if necessary.

In AiiDAlab deployments the localhost computer is normally pre-created by the base-image startup scripts, so this typically just loads it. If it does not exist, a minimal local computer is created and configured as a safety fallback.

Returns:: The configured localhost computer.
Return type:: aiida.orm.Computer

aiidalab_chemshell.containers.image_exists(engine: str) → bool¶

Return whether the ChemShell image for engine is already available.

Parameters:: engine (str) – Either APPTAINER or DOCKER.
Returns:: True if the engine’s local image is present, False otherwise.
Return type:: bool

aiidalab_chemshell.containers.pull_docker_image(on_progress: Callable[[str], None] | None = None) → tuple[bool, str]¶

Pull the ChemShell Docker image into the local daemon’s image store.

Parameters:: on_progress (Callable[[str], None], optional) – Optional callback invoked with human-readable progress messages.
Returns:: A tuple (ok, message) where ok is True on success. message contains a success note or the captured error output on failure.
Return type:: tuple[bool, str]

aiidalab_chemshell.containers.sif_exists() → bool¶

Return whether the local ChemShell .sif image already exists.

Returns:: True if the .sif file exists, False otherwise.
Return type:: bool

aiidalab_chemshell.containers.sif_path() → Path¶

Return the absolute path to the local ChemShell .sif image.

Returns:: The path where the .sif image is (or would be) stored.
Return type:: pathlib.Path

aiidalab_chemshell.history module¶

Defines the process history applicaion page.

class aiidalab_chemshell.history.HistoryApp¶

Bases: object

The process history page’s main app.

class aiidalab_chemshell.history.HistoryAppView(*args: t.Any, **kwargs: t.Any)¶

Bases: VBox

Main view for the process history page.

class aiidalab_chemshell.history.HistoryModel(*args: t.Any, **kwargs: t.Any)¶

Bases: ProcessModel

MVC Model for process history app data management.

aiidalab_chemshell.main module¶

Defines the AiiDAlab application pages (new calculation and batch processing).

class aiidalab_chemshell.main.App(batch: bool = False)¶

Bases: object

An AiiDAlab ChemShell application page.

A single application shell shared by the “New Calculation” and “Batch Processing” pages. The batch flag selects the underlying model, wizard, and subtitle while keeping the surrounding layout/styling identical.

class aiidalab_chemshell.main.AppView(*args: t.Any, **kwargs: t.Any)¶

Bases: VBox

The shared application view (header, navigation, body wizard, footer).

class aiidalab_chemshell.main.BatchApp¶

Bases: App

The batch processing AiiDAlab application page.

class aiidalab_chemshell.main.MainApp¶

Bases: App

The main “New Calculation” AiiDAlab application page.

aiidalab_chemshell.process module¶

Module for handling AiiDA processes.

class aiidalab_chemshell.process.BaseAppModel(*args: t.Any, **kwargs: t.Any)¶

Bases: HasTraits

The shared AiiDAlab application MVC model.

A single model backing both the “New Calculation” and “Batch Processing” pages. The batch flag selects the process class used on submission and constrains the batch page to single point energy calculations, while the composed sub-models and submission wiring remain identical.

block_results¶: A boolean (True, False) trait.

reset() → None¶: Reset the state of the model.

class aiidalab_chemshell.process.BatchAppModel(*args: t.Any, **kwargs: t.Any)¶

Bases: BaseAppModel

The batch processing AiiDAlab application MVC model.

class aiidalab_chemshell.process.ChemShellProcess(model: BaseAppModel)¶

Bases: object

Class to handle a ChemShell AiiDA process.

submit_process()¶: Submit the AiiDA process.

classmethod validate_model(model: BaseAppModel) → bool¶

Validate the main application model.

Parameters:: model (AppModel) – The application model to validate.
Returns:: True if the model is valid, False otherwise.
Return type:: bool

class aiidalab_chemshell.process.MainAppModel(*args: t.Any, **kwargs: t.Any)¶

Bases: BaseAppModel

The main “New Calculation” AiiDAlab application MVC model.

aiidalab_chemshell.resources module¶

Defines a resource setup widget based on foundations from aiidalab-widgets-base.

class aiidalab_chemshell.resources.ChemShellContainerSetupWidget(*args: t.Any, **kwargs: t.Any)¶

Bases: VBox

Widget for one-click install of the ChemShell container and AiiDA code.

class aiidalab_chemshell.resources.CodeSetupWidget(*args: t.Any, **kwargs: t.Any)¶

Bases: VBox, HasTraits

Widget to setup a new code instance.

aiidalab_chemshell.utils module¶

Contains utility functions used throughout the python package.

aiidalab_chemshell.utils.get_app_dir() → Path¶

Return the absolute path for the root directory of this project.

Return the path to the root of the AiiDAlab application where the jupyter notebooks are contained to enable navigation between notebooks. This assumes that the environment variable AIIDALAB_APPS has been configured to point at the directory containing the app source code.

Returns:: The path to the root AiiDAlab application directory.
Return type:: pathlib.Path

aiidalab_chemshell.utils.get_chem_shell_params(key: str) → tuple¶

Return the ChemShell input dictionary keys defined by the aiida-chemshell plugin.

Parameters:: key (str) – The input field to be queried (“sp”: “Single Point”, “op”: “Geometry Optimisation”, “qm”: “Quantum Mechanics”, “mm”: “Molecular Mechanics”)
Returns:: A list of the input dictionary keys for the requested input field as defined by the aiida-chemshell plugin.
Return type:: tuple

aiidalab_chemshell.utils.get_py_app_dir() → Path¶

Return the absolute path for the AiiDAlab ALC app python package.

Returns:: The path to the root python package directory.
Return type:: pathlib.Path

aiidalab_chemshell.utils.open_link_in_new_tab(path: str, _=None) → None¶

Open a given link in a new browser tab.

Parameters:: path (str) – The link to be opened.

aiidalab_chemshell.utils.test_aiida_chemsh_import() → bool¶

Test if the aiida-chemshell plugin is installed.

Returns:: True if the aiida-chemshell plugin is installed, False otherwise.
Return type:: bool

Module contents¶

The main AiiDAlab ChemShell python package.