Complete installation guide#

The quick installation guide is designed to make the setup as simple and portable as possible. However, the resulting setup has some limitations concerning the available functionality and performance. This guide provides detailed information and instructions to set up a feature-complete and performant installation.

Setting up a working installation of AiiDA, involves the following steps:

  1. Install the Python Package

  2. (Optional) RabbitMQ

  3. Create a profile

Install Python Package#

Important

AiiDA requires a recent version of Python. Please refer to the Python Package Index (PyPI) for the minimum required version.

To install AiiDA, the aiida-core Python package needs to be installed which can be done in a number of ways:

Installing aiida-core from PyPI.

  1. Install pip.

  2. Install aiida-core:

    pip install aiida-core

Installing aiida-core using Conda.

  1. Install conda.

  2. Create an environment and install aiida-core:

    conda create -n aiida -c conda-forge aiida-core

    Tip

    As of conda v23.10, the dependency solver has been significantly improved. If you are experiencing long installation times, you may want to consider updating conda.

Installing aiida-core directory from source.

  1. Install git

  2. Clone the repository from Github

    git clone https://github.com/aiidateam/aiida-core

  3. Install pip.

  4. Install aiida-core:

    cd aiida-core
pip install -e .

    The -e flag installs the package in editable mode which is recommended for development. Any changes made to the source files are automatically picked up by the installation.

Optional requirements#

The aiida-core Python package defines a number of optional requirements, subdivided in the following categories:

  • atomic_tools : Requirements to deal with atomic data and structures

  • docs : Requirements to build the documentation

  • notebook : Requirements to run AiiDA in Jupyter notebooks

  • pre-commit : Requirements to automatically format and lint source code for development

  • rest : Requirements to run the REST API

  • ssh_kerberos : Requirements for enabling SSH authentication through Kerberos

  • tests : Requirements to run the test suite

  • tui : Requirements to provide a textual user interface (TUI)

These optional requirements can be installed using pip by adding them as comma separated list, for example:

pip install aiida-core[atomic_tools,docs]

RabbitMQ#

RabbitMQ is an optional but recommended service for AiiDA. It is a messsage broker that is required to run AiiDA’s daemon. The daemon is a system process that runs in the background that manages one or multiple daemon workers that can run AiiDA processes. This way, the daemon helps AiiDA to scale as it is possible to run many processes in parallel on the daemon workers instead of blockingly in a single Python interpreter. To facilitate communication with the daemon workers, RabbitMQ is required.

Although it is possible to run AiiDA without a daemon it does provide significant benefits and therefore it is recommended to install RabbitMQ.

  1. Install conda.

  2. Create an environment and install aiida-core.services:

    conda create -n aiida -c conda-forge aiida-core.services

Important

The aiida-core.services package ensures that RabbitMQ is installed in the conda environment. However, it is not a service, in the sense that it is not automatically started, but has to be started manually.

rabbitmq-server -detached

Note that this has to be done each time after the machine has been rebooted. The server can be stopped with:

rabbitmqctl stop

  1. Install RabbitMQ through the apt package manager:

    sudo apt install rabbitmq-server

This should automatically install startup scripts such that the server is automatically started when the machine boots.

  1. Install Homebrew <https://docs.brew.sh/Installation>.

  2. Install RabbitMQ:

    brew install rabbitmq
brew services start rabbitmq

Important

The service has to manually be started each time the machine reboots.

For all other cases, please refer to the official documentation of RabbitMQ.

Create a profile#

After the aiida-core package is installed, a profile needs to be created. A profile defines where the data generated by AiiDA is to be stored. The data storage can be customized through plugins and so the required configuration changes based on the selected storage plugin.

To create a new profile, run:

verdi profile setup <storage_entry_point>

where <storage_entry_point> is the entry point name of the storage plugin selected for the profile. To list the available storage plugins, run:

verdi plugin list aiida.storage

AiiDA ships with a number of storage plugins and it is recommended to select one of the following:

core.sqlite_dos

Use this for use-cases to explore AiiDA where performance is not critical.

This storage plugin does not require any services, making it easy to install and use.

Create a core.sqlite_dos profile

core.psql_dos

Use this for production work where database performance is important.

This storage plugin uses PostgreSQL for the database and provides the greatest performance.

Create a core.psql_dos profile

See also

See the topic on storage to see a more detailed overview of the storage plugins provided by aiida-core with their strengths and weaknesses.

Other packages may provide additional storage plugins, which are also installable through verdi profile setup.

Common options#

The exact options available for the verdi profile setup command depend on the selected storage plugin, but there are a number of common options and functionality:

  • --profile-name: The name of the profile.

  • --set-as-default: Whether the new profile should be defined as the new default.

  • --email: Email for the default user that is created.

  • --first-name: First name for the default user that is created.

  • --last-name: Last name for the default user that is created.

  • --institution: Institution for the default user that is created.

  • --use-rabbitmq/--no-use-rabbitmq: Whether to configure the RabbitMQ broker. Required to enable the daemon and submitting processes to it. The default is --use-rabbitmq, in which case the command tries to connect to RabbitMQ running on the localhost with default connection parameters. If this fails, a warning is issued and the profile is configured without a broker. Once the profile is created, RabbitMQ can still be enabled through verdi profile configure-rabbitmq which allows to customize the connection parameters.

  • --non-interactive: By default, the command prompts to specify a value for all options. Alternatively, the --non-interactive flag can be specified, in which case the command never prompts and the options need to be specified directly on the command line. This is useful when using verdi profile setup is used in non-interactive environments, such as scripts.

  • --config: Instead of passing all options through command line options, the value can be defined in a YAML file and pass its filepath through this option.

core.sqlite_dos#

Tip

The verdi presto command provides a fully automated way to set up a profile with the core.sqlite_dos storage plugin if no configuration is required.

This storage plugin uses SQLite and the disk-objectstore to store data. The disk-objectstore is a Python package that is automatically installed as a dependency when installing aiida-core, which was covered in the Python package installation section. The installation instructions for SQLite depend on your system; please visit the SQLite website for details.

Once the prerequisistes are met, create a profile with:

verdi profile setup core.sqlite_dos

The options specific to the core.sqlite_dos storage plugin are:

  • --filepath: Filepath of the directory in which to store data for this backend.

core.psql_dos#

Tip

The creation of the PostgreSQL user and database as explained below is implemented in an automated way in the verdi presto command. Instead of performing the steps below manually and running verdi profile setup core.psql_dos, it is possible to run:

verdi presto --use-postgres

The verdi presto command also automatically tries to configure RabbitMQ as the broker if it is running locally. Therefore, if the command succeeds in connecting to both PostgreSQL and RabbitMQ, verdi presto --use-postgres provides a fully automated way to create a profile suitable for production workloads.

This storage plugin uses PostgreSQL and the disk-objectstore to store data. The disk-objectstore is a Python package that is automatically installed as a dependency when installing aiida-core, which was covered in the Python package installation section. The storage plugin can connect to a PostgreSQL instance running on the localhost or on a server that can be reached over the internet. Instructions for installing PostgreSQL is beyond the scope of this guide.

Before creating a profile, a database (and optionally a custom database user) has to be created. First, connect to PostgreSQL using psql, the native command line client for PostgreSQL:

psql -h <hostname> -U <username> -W

If PostgreSQL is installed on the localhost, <hostname> can be replaced with localhost, and the default <username> is postgres. While possible to use the postgres default user for the AiiDA profile, it is recommended to create a custom user:

CREATE USER aiida-user WITH PASSWORD '<password>';

replacing <password> with a secure password. The name aiida-user is just an example name and can be customized. Note the selected username and password as they are needed when creating the profile later on.

After the user has been created, create a database:

CREATE DATABASE aiida-database OWNER aiida-user ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8';

Again, the selected database name aiida-database is purely an example and can be customized. Make sure that the OWNER is set to the user that was created in the previous step. Next, grant all privileges on this database to the user:

GRANT ALL PRIVILEGES ON DATABASE aiida-database to aiida-user;

After the database has been created, the interactive psql shell can be closed. To test if the database was created successfully, run the following command:

psql -h <hostname> -d <database> -U <username> -W

replacing <database> and <username> with the chosen names for the database and user in the previous steps, and providing the chosen password when prompted.

Once the database has been created, create a profile with:

verdi profile setup core.psql_dos

The options specific to the core.psql_dos storage plugin are:

  • --database-engine The engine to use to connect to the database.

  • --database-hostname The hostname of the PostgreSQL server.

  • --database-port The port of the PostgreSQL server.

  • --database-username The username with which to connect to the PostgreSQL server.

  • --database-password The password with which to connect to the PostgreSQL server.

  • --database-name The name of the database in the PostgreSQL server.

  • --repository-uri URI to the file repository.

Validate installation#

Once a profile has been created, validate that everything is correctly set up with:

verdi status

The output should look something like the following:

✔ version:     AiiDA v2.5.1
✔ config:      /path/.aiida
✔ profile:     profile-name
✔ storage:     SqliteDosStorage[/path/.aiida/repository/profile-name]: open,
✔ broker:      RabbitMQ v3.8.2 @ amqp://guest:guest@127.0.0.1:5672?heartbeat=600
⏺ daemon:      The daemon is not running.

If no lines show red crosses, AiiDA has been correctly installed and is ready to go. When a new profile is created, the daemon will not yet be running, but it can be started using:

verdi daemon start

Note

The storage information depends on the storage plugin that was selected. The broker may be shown as not having been configured which occurs for profiles created with the quick installation method. This is fine, however, some functionality is not supported for broker-less profiles.

Not all green?

If the status reports any problems, please refer to the troubleshooting section.

On this page
Edit on GitHub
Show Source