Installation

Independently of how you install aimmd you will need a working installation of one of the machine learning backends (pytorch, tensorflow, etc.). Please refer to their respective documentations for installation instructions.

aimmd runs its TPS simulations either through asyncmd (if managing and learning from many simulations simultaneously, possibly on a HPC cluster) or through openpathsampling (in the sequential case). openpathsampling and asyncmd can both easily be installed via pip and are automatically installed when you install aimmd with pip. Note, that for asyncmd and/or openpathsampling to work you need to install a molecular dynamics engine to perform the trajectory integration. In asyncmd the only currently supported engine is gromacs, while openpathsampling can use both gromacs and openMM (but openMM is highly recommended).

pip install from PyPi

aimmd is published on PyPi (since v0.9.1), installing is as easy as:

pip install aimmd

pip install directly from the repository

In case you you intend to run the tests or example notebooks yourself or if want to install the latest and greatest development version of aimmd (see the changelog for whats new) you will need to install aimmd from the git repository.

This will clone the repository to the current working directory and install aimmd into the current python environment:

git clone https://github.com/bio-phys/aimmd.git
cd aimmd
pip install .\[examples\]

Note

We used the examples installation target here to directly install the additional requirements needed to run the examples. This includes, e.g., jupyterlab (to actually run the notebooks) and pooch (to download some of the larger files used in the example notebooks).

Tests

Tests use pytest. To run them you can install aimmd with the tests requirements. All tests should either pass or be skipped.

This will clone the repository to the current working directory and install aimmd with the tests requirement into the current python environment:

git clone https://github.com/bio-phys/aimmd.git
cd aimmd
pip install .\[tests\]
# or use
pip install .\[tests-all\]
# to also install optional dependencies needed to run all tests

you can then run the tests (against the installed version) as

pytest
# or use
pytest -v
# to get a more detailed report

Note

The tests-all target will also install coverage and pytest-cov, see the developer installation below for more.

Documentation

The documentation can be build with sphinx, use e.g. the following to build it in html format:

cd aimmd  # Need to be at the top folder of the repository for the next line to work
sphinx-build -b html docs/source docs/build/html

The documentation is located in the docs/source/ folder and (mostly) written in MyST markdown. MyST-NB and the sphinx-book-theme are needed to build the documentation and include the example notebooks into it.

Note

Use pip install .\[docs\] to install the requirements needed to build the documentation.

Developer installation

If you intend to contribute to aimmd, it is recommended to use the dev extra and use an editable install to enable you to directly test your changes:

git clone https://github.com/bio-phys/aimmd.git
cd aimmd
pip install -e .\[dev\]

This will, in addition to the requirements to run the tests and to build the documentation, install jupyterlab such that you can easily contribute to the example notebooks. It will also install coverage and its pytest-cov plugin such that you have an idea of the test coverage for your newly added code. To get a nice html coverage report you can run the tests as

pytest --cov=aimmd --cov-report=html