Development environment

Create an independent development environment

High possibility you are both aiida-core developer and user, so you probably don't want to mess your production AiiDA setup by the code you changed. There are different ways to create an independent environment.

Using the aiida-core-with-serivces docker container

(We may provide the aiida-core-dev image in the future which include all the tools that helps for development.) By using container, it also have independent pre-requisite services, namely PostgreSQL and RabbitMQ which already configured and start in the container. You need having a docker in your PC, checking here for how to properly install docker.

Once the docker is installed, you can start the environment by:

docker run -it --name aiida-dev aiidateam/aiida-core-with-services:latest bash

You can use vscode to attach the container and modify codes directly. By using vscode, the github credential is synchronous in to the container so you don't need to set up the GitHub token in the container. Now you have the independent environment with independent services, you can jump to "Getting the code" section.

Using python virtual environment

We recommend creating a separate virtual python environment for AiiDA development in order not to pollute the system python environment. If you don't already have your own tools to do this, we strongly recommend using mamba instead of the default conda (or environment resolution may time out).

Consider using Mambaforge when starting from scratch, or conda install -c conda-forge mamba.

• Download and install Miniconda
• mamba create -n aiida python=3.10
• mamba activate aiida

You can also use the tox configuration (located in pyproject.toml), optionally with tox-conda, to automate the generation of virtual environments when running tests:

pip install --upgrade pip tox tox-conda
tox -av
tox path/to/test/file.py -- -x

Getting the code

• fork the aiida-core repository

• git clone your fork to have a local copy.

• Check out the right branch and create a new one for your development:

  git checkout main
  git checkout -b my-new-addition
  

Pre-commit hooks

The AiiDA pre-commit hooks help you write clean code by running

• code formatting
• syntax checking
• static analysis
• checks for missing docstrings
• checks for consistency of dependencies and version numbers
• ...

locally at every commit you make.

Set up the hooks as follows:

cd aiida-core
pip install -e .[pre-commit]
pre-commit install
pre-commit run  # test running the hooks
# from now on, hooks will check the *changed* files on every commit

Besides of pre-commit, you may want to take a look at other complements you can also install such as tests and docs (take a look at the "extras_require" inside of the setup.json).

Note:

• If you work in a conda environment on a system that also has virtualenv installed, you may need to conda install virtualenv to avoid problems with virtualenv inside conda.
• On Ubuntu-18.04 you may need to sudo apt install ruby-dev

Useful commands

• Use pre-commit run to run the checks without committing
• If you ever need to commit a 'work in progress' you may skip the checks via git commit --no-verify. Yet, keep in mind that the pre-commit hooks will also run (and fail) at the continuous integration stage when you push them upstream.

Troubleshooting

• In some cases of very long strings, yapf will not be able to split the string and then prospector will complain. In this case just split the string manually. See discussion in #2114.

Using Windows Subsystem for Linux (WSL)

For speed considerations WSL 2 is recommended. WSL 2 introduces a full-blown VM for your Linux distributions, meaning faster I/O-operations and no need for Windows "support" services (like RabbitMQ). In other words, WSL 2 should provide a more self-contained installation and running experience.

Note, however that it is only available through the Windows Insider Program, using Windows 10 builds 18917 and higher. For more information, see the WSL documentation.

Tip:

Consider using Visual Studio Code with the Remote WSL extension for a full IDE experience, if you're not using in-terminal IDEs. See the VS Code WSL documentation for more information.