aiidalab-launch 2024.1020

Tool to launch AiiDAlab on a local workstation.

AiiDAlab Launch

AiiDAlab Launch makes it easy to run AiiDAlab on your own workstation or laptop.

Getting Started

To use AiiDAlab launch you will have to

1. Install Docker on your workstation or laptop. (you can also use Podman, see below)

2. Install AiiDAlab launch with pipx (recommended):

   pipx install aiidalab-launch
   

   Or directly with pip (pip install aiidalab-launch).

3. Start AiiDAlab with

   aiidalab-launch start
   

4. Follow the instructions on screen to open AiiDAlab in the browser.

See aiidalab-launch --help for detailed help.

Instance Management

You can inspect the status of all configured AiiDAlab profiles with:

aiidalab-launch status

Profile Management

The tool allows to manage multiple profiles, e.g., with different home directories or ports. See aiidalab-launch profile --help for more information.

Data Management

By default AiiDAlab will store all of its data in a Docker volume defined in the profile configuration option home_mount. You can also provide an absolute path to the AiiDAlab home directory on the host system (so called bind mount). If this directory does not exist, AiiDAlab launch will try to create it on startup.

Additional volumes to be mounted to the the AiiDAlab container can be specified via the extra_mounts option using the "docker-compose "short syntax" source:target:mode. source is either a volume name or an absolute path to an existing directory on the host system, target is a path within the AiiDAlab container, and mode is either rw for read-write volume (default) or ro for read-only volume.

As an example, here's how you can mount a quantum chemistry program installed on the host system to make it accessible to AiiDA inside the AiiDAlab container:

extra_mounts = ["/path/to/qcprogram:/opt/qcprogram:ro",]

Finally, AiiDAlab launch will create a dedicated volume for the local conda environment (~/.conda). That is because some conda packages are not compatible with non-linux file systems, meaning that they cannot be installed if the home directory was, for example, bound to a Mac OS-X file system on the host.

Forward AiiDAlab from a remote server via SSH

Please see here for instructions on how to run AiiDAlab on a remote machine and then forward it to your local terminal.

Compatibility

This package follows the Python compatibility and deprecation schedule specified by NEP 29.

Using Podman instead of Docker

You should be able to use Podman as as a drop-in replacement for Docker, with just a little extra setup. The following was tested on Fedora 39 which comes with Podman pre-installed.

systemctl --user enable podman.socket
systemctl --user start podman.socket
systemctl --user status podman.socket
export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock

Development

Setting up a development environment

To develop this package, first clone it and then install the development dependencies with pip install -e '.[dev]'. We recommend to install the pre-commit hooks to avoid unnecessary iterations when pushing new changes. To install the pre-commit hooks, switch into the repository root directly and execute:

pre-commit install

Run automated tests

To run the automated tests suite, clone the repository, install test dependencies with pip install -e '.[tests]', and then execute tests with

pytest

for all standard tests, and

pytest --slow

to run the full test suite, including tests that will start docker instances and may take multiple minutes.

The continuous integration workflow will run all tests, including the "slow" ones.

Note: On Mac OS-X you may have to override the standard temporary base directory to successfully run all tests (e.g. pytest --basetemp=$HOME/tmp) since the default base directory may not be accessible to the Docker runtime.

Creating a new release

To create a new release, clone the repository, install development dependencies with pip install -e '.[dev]', and then execute bumpver update. This will:

1. Create a tagged release with bumped version and push it to the repository.
2. Trigger a GitHub actions workflow that creates a GitHub release.

Additional notes:

• Use the --dry option to preview the release change.
• The release should be created directly on the main branch, and as such you need special permissions for writing to it.
• The release tag (e.g. a/b/rc) is determined from the last release. Use the --tag option to switch the release tag.

Authors

• Carl Simon Adorf (EPFL) - @csadorf
• AiiDAlab team

See also the list of contributors.

Citation

Users of AiiDAlab are kindly asked to cite the following publication in their own work:

A. V. Yakutovich et al., Comp. Mat. Sci. 188, 110165 (2021). DOI:10.1016/j.commatsci.2020.110165

Contact

[e-mail]

Contributions

Contributions in any form are very welcome. Please see CONTRIBUTING.md for contribution guidelines.

MIT License

Copyright (c) 2021 Carl Simon Adorf (EPFL)

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements

This work is supported by the MARVEL National Centre for Competency in Research funded by the Swiss National Science Foundation, the MARKETPLACE project funded by Horizon 2020 under the H2020-NMBP-25-2017 call (Grant No. 760173), as well as by the MaX European Centre of Excellence funded by the Horizon 2020 EINFRA-5 program, Grant No. 676598.