.. _user-guide-install: 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 :ref:`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 :ref:`requirements ` can be installed :ref:`using pip ` or :ref:`using conda ` as described below. We also describe how it can be installed directly from the source code :ref:`using git `. | .. _user-guide-install-requirements: 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 :download:`requirements.txt ` in the source code directory. These packages can be installed by: .. code-block:: pyretis python -m pip install -r requirements.txt after downloading the :download:`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 and graphviz, which must be installed separately as described below. | .. _user-guide-prereq: 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 :ref:`requirements list ` is shown above. .. _user-guide-install-pip: | Installing via ``pip`` ---------------------- The latest version of |pyretis| can be installed using `pip `_ with the following command: .. code-block:: pyretis python -m pip install git+https://gitlab.com/pyretis/pyretis.git A direct installation of PyRETIS 4 (stable release): .. code-block:: pyretis python -m pip install pyretis |pyretis| offers an analysis and visualization tool, named |pyvisa|. Its GUI requires PyQt5, `mdtraj `_, ``scikit-learn``, and `graphviz `_. To install them via pip: .. code-block:: pyretis python -m pip install pyqt5 mdtraj 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. | .. _user-guide-install-conda: Installing via ``conda`` ------------------------ |pyretis| can be installed using `conda `_ with the following commands: .. code-block:: pyretis conda create --name pyretis python=3.12 conda activate pyretis conda install pyretis -c conda-forge |pyretis| offers an analysis and visualization tool, named |pyvisa|. Its GUI requires PyQt5, mdtraj, scikit-learn, and graphviz to be executed. To install them via conda: .. code-block:: pyretis conda install pyqt mdtraj 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``: .. code-block:: pyretis git clone git@gitlab.com:pyretis/pyretis.git or, .. code-block:: pyretis 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): .. code-block:: pyretis 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``, ``mdtraj``, ``scikit-learn``, and ``graphviz``: .. code-block:: pyretis python -m pip install pyqt5 mdtraj scikit-learn graphviz .. _user-guide-install-develop: | 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.: .. code-block:: pyretis 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): .. code-block:: pyretis pip install -r requirements-dev.txt Finally, install |pyretis| using: .. code-block:: pyretis pip install -e . .. _user-guide-install-test: | Testing your installation ------------------------- After installing from the |pyretis| source, your installation can be tested by running the unit-test suite from the main directory: .. code-block:: pyretis python -m pytest test To also run style and lint checks alongside the unit tests, use the provided helper script: .. code-block:: pyretis ./test-easy.sh To exercise the bundled engine examples (internal, GROMACS, PyVisA, CP2K, OpenMM, LAMMPS) end-to-end, run: .. code-block:: pyretis ./test-heavy.sh The example suite has a longer runtime than the unit tests because it covers two complementary parts, both chained together by ``test-heavy.sh``: * **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 a reduced *smoke* scope by default; set ``PYRETIS_GROMACS_SCOPE=full`` to run the complete GROMACS matrix. * **Tutorials** (``examples/run-tutorials.sh``) -- every documented tutorial, run to confirm that its commands still work. Their length is controlled by ``PYRETIS_TUTORIAL_TIMEOUT``: ``test-heavy.sh`` sets it to ``2s`` so each tutorial only has to *start* cleanly (a short smoke check), whereas running the driver with the variable unset -- its default -- lets every tutorial run to completion at *full length*.