Obtaining and installing PyRETIS

Note

You are reading the documentation for PyRETIS 4 (v4.0.0.dev), a development version that is not yet released on PyPI. To use the version these docs describe, install PyRETIS from source with git: clone the repository and check out the develop branch. The step-by-step instructions – including the development requirements – are given in Installing a development version later on this page. If you want the latest stable release (PyRETIS 3) instead, install it directly with pip install pyretis.

PyRETIS and its requirements can be installed using pip or using conda as described below. We also describe how it can be installed directly from the source code using git.


Requirements for PyRETIS

In order to run PyRETIS, several Python libraries are needed, for instance SciPy, NumPy, and matplotlib (see also the information on installing the SciPy Stack). A list of the requirements can be found in the file requirements.txt in the source code directory. These packages can be installed by:

python -m pip install -r requirements.txt

after downloading the requirements.txt file. This should be automatically done if you are installing PyRETIS using pip/conda. Notes: (1) the analysis and visualization package PyVisA requires PyQt5, scikit-learn and graphviz for its GUI, which must be installed separately as described below.


Prerequisites

PyRETIS requires Python 3.11 or higher. Please make sure that you have an updated version of Python installed on your system. PyRETIS depends on several other Python packages, however, these should be installed automatically as part of the installation of PyRETIS. The requirements list is shown above.


Installing via pip

PyRETIS 4, the version these pages describe, is not yet on PyPI. It can be installed with pip from its develop branch:

python -m pip install git+https://gitlab.com/pyretis/pyretis.git@develop

python -m pip install pyretis installs the latest stable release, PyRETIS 3, which has no pyretis command (it runs with pyretisrun and pyretisanalyse) and reads other input files than the ones these pages describe.

PyRETIS offers an analysis and visualization tool, named PyVisA. Its GUI requires PyQt5, scikit-learn, and graphviz. To install them via pip:

python -m pip install pyqt5 scikit-learn graphviz

Note: Please make sure that you are using a Python environment of version 3.11 or newer. On some systems, Python 2 may still be the default version and pip might actually try to install for Python 2. In this case, use pip3 in the command above.


Installing via conda

PyRETIS 4 is not on conda-forge, which holds only older releases of PyRETIS (2.5.0 and earlier), built for Python 3.11 at most. To use PyRETIS 4 in a conda environment, create and activate the environment:

conda create --name pyretis python=3.12
conda activate pyretis

and install PyRETIS in it with pip, as described in Installing via pip, or from a clone, as described in Installing a development version.

PyRETIS offers an analysis and visualization tool, named PyVisA. Its GUI requires PyQt5, scikit-learn, and graphviz to be executed. To install them via conda:

conda install pyqt scikit-learn python-graphviz -c conda-forge

Note: Since PyRETIS will only work with Python 3.11 or newer, please make sure that you are using an environment with a recent version of Python.


Optional: Installing from the PyRETIS git repository

Previous versions and the latest (possibly unstable) sources can be obtained using git:

git clone git@gitlab.com:pyretis/pyretis.git

or,

git clone https://gitlab.com/pyretis/pyretis.git

After cloning the repository, PyRETIS can be installed via pip (after navigating to the main source directory):

pip install .

Note: If you want to be able to make modifications locally and to apply them, you can install the package with the -e option. PyRETIS will be executed with the files present in the folder you created.

To be able to run PyVisA’s GUI, you need to install pyqt5, scikit-learn, and graphviz:

python -m pip install pyqt5 scikit-learn graphviz

Optional: Installing a development version from the PyRETIS git repository

After cloning the repository as described above, check out the development branch you are interested in, e.g.:

git checkout develop

Then install the development requirements (these are defined in the file requirements-dev.txt, note that they include pyqt5, which is not supported in some environments):

pip install -r requirements-dev.txt

Finally, install PyRETIS using:

pip install -e .

Testing your installation

After installing from the PyRETIS source, your installation can be tested by running the unit-test suite from the main directory:

python -m pytest test

test-easy.sh runs the same tests on four workers, except the long ones marked heavy (test-heavy.sh runs those), with the style and lint checks beside them:

./test-easy.sh

To exercise the bundled engine examples (internal, GROMACS, PyVisA, CP2K, OpenMM, LAMMPS) end-to-end, run:

./test-heavy.sh

test-heavy.sh takes longer than the unit tests because it runs four parts:

  • Consistency tests (examples/run-tests.sh) – the engine reference-data suites (internal, GROMACS, PyVisA, CP2K, OpenMM and LAMMPS). Each regenerates output and compares it against pre-computed reference data, so the checks are deterministic and re-runnable. The GROMACS sub-suite runs its complete matrix of 10 cases; set PYRETIS_GROMACS_SCOPE=smoke to run the quick 6-case subset. It runs beside the other suites and its output is printed after theirs; set PYRETIS_SUITES_PARALLEL=0 to run every suite in turn, each printing as it runs.

  • Tutorials (examples/run-tutorials.sh) – every documented tutorial, run to confirm that its commands still work. Their length is controlled by PYRETIS_TUTORIAL_TIMEOUT and PYRETIS_TUTORIAL_STEPS: test-heavy.sh sets them to 2s and 20, so the path-sampling tutorials the driver shortens (most of those of the internal engine, and the LAMMPS H2 infinite-swapping one) run 20 cycles and are analysed with pyretis analyse, and every other tutorial only has to start cleanly (a short smoke check), whereas running the driver with the variables unset – its default – lets every tutorial run to completion at full length.

  • Long end-to-end tests – the tests of test/ marked heavy, which test-easy.sh leaves out: complete simulations and analyses that take up to a few minutes each.

  • Documentation checks (devtools/docs/run_checks.py) – the documentation is built with sphinx-build -W, so that any warning fails the build, and checked as the continuous integration checks it before it is published. The build goes to a temporary directory, which is removed at the end. The Python that runs this part needs Sphinx, sphinx_bootstrap_theme and myst_parser (python -m pip install sphinx sphinx_bootstrap_theme myst-parser) and the packages of the PyVisA GUI (PyQt5, scikit-learn and graphviz, installed as described above). If the python on your PATH lacks them, set PYRETIS_DOCS_PYTHON to a Python 3.11 or later that has them and the dependencies of PyRETIS; otherwise this part fails and names the missing packages.