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

Please refer to the installation instructions in the documentation.

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
  

Running tests

For running the tests you need to install the extra packages

 pip install .[tests]
 pytest  # run all tests 
 pytest -m presto  # only run tests that are compatible with the presto profile

Tests for the transport plugins require that your default ssh key id_rsa can be used to connect to localhost.

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 run  # test running the hooks, will only run on staged files
pre-commit install  # optional, if you want that it will run automatically when you 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).

Running with tox

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

Be aware that we do not maintain tox at the moment so it there can be issues when running with it

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.