Package: aiidalab-launch
AiiDAlab LaunchAiiDAlab Launch makes it easy to runAiiDAlabon your own workstation or laptop.Getting StartedTo use AiiDAlab launch you will have toInstall Docker on your workstation or laptop.(you can also use Podman,see below)Install AiiDAlab launch withpipx(recommended):pipx install aiidalab-launchOr directly with pip (pip install aiidalab-launch).Start AiiDAlab withaiidalab-launch startFollow the instructions on screen to open AiiDAlab in the browser.Seeaiidalab-launch --helpfor detailed help.Instance ManagementYou can inspect the status of all configured AiiDAlab profiles with:aiidalab-launch statusProfile ManagementThe tool allows to manage multiple profiles, e.g., with different home directories or ports.
Seeaiidalab-launch profile --helpfor more information.Data ManagementBy default AiiDAlab will store all of its data in aDocker volumedefined in the profile configuration optionhome_mount.
You can also provide an absolute path to the AiiDAlab home directory on the host system (so calledbind 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 theextra_mountsoption using the"docker-compose "short syntax"source:target:mode.sourceis either a volume name or an absolute path to an existing directory on the host system,targetis a path within the AiiDAlab container,
and mode is eitherrwfor read-write volume (default) orrofor 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 SSHPlease seeherefor instructions on how to run AiiDAlab on a remote machine and then forward it to your local terminal.CompatibilityThis package follows the Python compatibility and deprecation schedule specified byNEP 29.Using Podman instead of DockerYou 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.socketsystemctl --user start podman.socketsystemctl --user status podman.socketexport DOCKER_HOST=unix:///run/user/$UID/podman/podman.sockDevelopmentSetting up a development environmentTo develop this package, first clone it and then install the development dependencies withpip install -e '.[dev]'.
We recommend to install thepre-commithooks to avoid unnecessary iterations when pushing new changes.
To install the pre-commit hooks, switch into the repository root directly and execute:pre-commit installRun automated testsTo run the automated tests suite, clone the repository, install test dependencies withpip install -e '.[tests]', and then execute tests withpytestfor all standard tests, andpytest --slowto 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 releaseTo create a new release, clone the repository, install development dependencies withpip install -e '.[dev]', and then executebumpver update.
This will:Create a tagged release with bumped version and push it to the repository.Trigger a GitHub actions workflow that creates a GitHub release.Additional notes:Use the--dryoption to preview the release change.The release should be created directly on themainbranch,
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--tagoption to switch the release tag.AuthorsCarl Simon Adorf (EPFL)-@csadorfAiiDAlab teamSee also the list ofcontributors.CitationUsers 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.110165Contactaiidalab@materialscloud.orgContributionsContributions in any form are very welcome.
Please seeCONTRIBUTING.mdfor contribution guidelines.MIT LicenseCopyright (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.AcknowledgementsThis work is supported by theMARVEL National Centre for Competency in Researchfunded by theSwiss National Science Foundation,
the MARKETPLACE project funded byHorizon 2020under the H2020-NMBP-25-2017 call (Grant No. 760173),
as well as by theMaX
European Centre of Excellencefunded by the Horizon 2020 EINFRA-5 program,
Grant No. 676598.