This is an AiiDAlab application plugin for ChemShell based scientific workflows, maintained by the Ada Lovelace Center (ALC). The app is still in early development stage and any input/contributions are welcome. Full documentation can be found here: https://stfc.github.io/aiidalab-chemshell/.
This plugin is hosted on the AiiDAlab plugin registry and therefore can be installed via the AiiDAlab plugin management UI page from within the AiiDAlab application interface. Instructions for how to run AiiDAlab itself can be found in its documentation and are also included in the documentation associated with this project https://stfc.github.io/aiidalab-chemshell/. It is generally recommended to run AiiDAlab through a container engine such as Docker or Apptainer, both of which are discussed in more detail in the documentation provided. In general the core docker image applicable to most use cases is aiidalab/full-stack:latest however, many other options exist for more tailored startup environments.
Multiple docker images are provided with this repository which build on the core foundation of the images provided by AiiDAlab bundling various components of the ChemShell workflows on-top of the core AiiDAlab application. At present two images are available; base includes the AiiDAlab ChemShell plugin pre-installed including all required dependencies, full builds upon the base package including a working installation of ChemShell (version 25) configured with DL_POLY, NWChem and PySCF as available backends.
To run one of the provided containers, first install and setup your desired container engine, then run the image as follows,
docker run -it --rm -p 8888:8888 -v $HOME:/home/jovyan ghcr.io/stfc/aiidalab-chemshell/base:latestThe additional run parameters will run the container interactively (-it), delete it when it is finished
(--rm), expose the required port for the jupyter notebook instance (-p 8888:8888) and the final flag
(-v) binds the home directory into the containers home directory so data can be made available and will
persist beyond the container instance. For more information on how to configure containers for AiiDAlab
see https://stfc.github.io/alc-ux.
This package uses pre-commit hooks to check for style consistency, to use these the pre-commit tool is required.
This can be installed alongside the base package by running,
pip install .[dev]or separately via,
pip install pre-commit Once installed run,
pre-commit install in the base repository to enable the pre-commit hooks. This will now run style and formatting checks on every commit.
This package uses pytest
to run all unit tests which is included in the [dev] optional
package dependencies. Once installed it can be run from the project root directory.
The CI workflows are configured to ensure all tests pass
before a pull request can be accepted into the main repository.
It is important that any new additions to the code base are accompanied
by appropriate testing, maintaining a high code coverage. The coverage
can be checked via,
pytest --cov=aiidalab_alc The documentation, including a User Guide, Developer Guide and an API reference,
is built using sphinx. The source
for which is contained in the docs/ directory. At present
only the html generator has been fully tested. All required packages can
be installed alongside the core package via,
pip install .[docs]and then the documentation can be built using sphinx-build,
sphinx-build -b html docs/source/ docs/build/html from the root directory.
Contributors to this project were funded by
