User guide#
Access AiiDAlab#
As a user, you have three options to access AiiDAlab:
Log into one of the open AiiDAlab servers.
Run the AiiDAlab docker container directly on your local machine.
Download the Quantum Mobile Virtual Machine, open a terminal and run
aiidalab.
AiiDAlab launch#
To run AiiDAlab on your own workstation or laptop you can either
(recommended) Use the aiidalab-launch tool which is a thin docker wrapper, or
run the image directly with:
docker run -p 8888:8888 aiidalab/full-stack.
To use AiiDAlab launch you will have to
Install Docker on your workstation or laptop.
Note
If you are using Linux, you need to have root privileges to do post-installation steps for the Docker Engine.
Install AiiDAlab launch with pipx (recommended):
pipx install aiidalab-launchOr directly with pip (
pip install aiidalab-launch).Start AiiDAlab with
aiidalab-launch startFollow 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.
AiiDAlab Home page#
When opening AiiDAlab you see a list of installed applications. The front page is generated by the AiiDAlab home app which cannot be uninstalled. Its main features are:
File manager: manage files stored in the AiiDAlab home folder (including download/upload).
Terminal: a standard Linux bash terminal.
Tasks: view the currently running applications and stop them, if needed.
App Store: install/update/remove applications.
Help: links to the AiiDAlab documentation.
App Store#
AiiDAlab provides for the distribution of a collection of notebooks in the form of apps through the AiiDAlab app store.
These apps can be installed, updated, and removed either via the command line using the aiidalab command, or via the App store.
Tip
All Terminal commands shown below, can in principle also be executed directly from the host via AiiDAlab launch’s exec function, for example:
$ aiidalab-launch exec -- aiidalab install <app-name>
Install a new app#
You can install new apps either using the graphical user interface via the App Store or on the command line ( Terminal).
Step 1: Open the App Store.
Simply open AiiDAlab in the browser and click on the icon in the top navigation bar.
This will open the app store page in a new window or tab.
Step 2: Search for the app you would like to install.
Optionally, select one or multiple categories to filter by:
Then scroll down until you find the app you would like to install. An app that is not installed yet, will be presented like this:
Clicking on the Install button will install the app and its dependencies.
In some cases the app developers will push prereleases which can be installed by clicking on the Include prereleases check box. Use this option only if you require access to a not yet released feature or you would like to test a new app version and provide feedback to the developer(s).
Step 3: Wait for the installation process to complete.
The current process for installing the app and its dependencies will be displayed via a terminal widget. Wait until the process has completed:
Step 4: Start the app from the start page.
The newly installed app should now show up on the start page.
Each app banner also shows an indicator about whether there is an update available (see screenshot above). To update the app, click on Manage App and then on the Update buttons.
Step 1: Open the Terminal.
Open the by clicking on the corresponding icon in the nav bar.
Step 2: Install the app with the aiidalab command
$ aiidalab install <app-name>
Replace <app-name> with the name of the app you would like to install, e.g., aiidalab install quantum-espresso.
Use aiidalab search to search among available apps and their versions.
Similarly, the aiidalab list lists all currently installed apps and their versions.
Upgrade (or downgrade) an app#
Step 1: Find the app you would like to upgrade on the start page.
On the home app start page, simply look for the app you would like to upgrade.
Click on the Manage App button to open the app manager.
Step 2: Open the App Management page
The green Update button indicates that there is a newer version of the app available.
Click on the Update button to upgrade the app.
By default, the app will be upgraded to the latest available version, howevever you can alternatively select any available version, including a version that is lower than the currently installed one.
Within the Terminal, execute the following command to upgrade:
$ aiidalab install <app-name>
This will install the most recent version of an app, regardless of whether it is already installed or not. You will be prompted to confirm the operation.
You can install a specific version, by using standard PEP 440 version specifiers, for example:
$ aiidalab install quantum-espresso==v22.01.0
Uninstall an app#
Uninstalling an app works similar to upgrading or downgrading an app via the Manage App page or on the Terminal.
Step 1: Find the app you would like to uninstall on the start page.
On the home app start page, simply look for the app you would like to uninstall.
Click on the Manage App button to open the app manager.
Step 2: Uninstall
The app manager allows you to uninstall the app or to install a different version.
Click on the Uninstall button to uninstall the app.
Note
In some cases you will see a warning that uninstalling the app might lead to data loss. That warning indicates that there are local modifications to the app source code. You can safely ignore this warning and click on the “Ignore” check box in case that you are sure that any local modifications are safe to delete.
Within the Terminal, execute the following command to uninstall an app:
$ aiidalab uninstall <app-name>
You will be prompted to confirm the operation.