.. _user-guide-install: Obtaining and installing |pyretis| ================================== |pyretis| and its :ref:`requirements ` can be installed :ref:`using pip ` or :ref:`using conda ` as described below. We also describe how |pyretis| can be installed in a :ref:`virtual environment ` and how it can be installed directly from the source code :ref:`using git `. | .. _user-guide-prereq: Prerequisites ------------- |pyretis| requires **Python 3.9** 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|. A list of the dependencies :ref:`can be found below `. .. _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 2: .. code-block:: pyretis python -m pip install pyretis |pyretis| offers an analysis tool, named |pyvisa|. Its GUI requires PyQt5 to be executed. To install PyQt5 via pip: .. code-block:: pyretis python -m pip install pyqt5 |pyvisa| also requires `mdtraj `_ and this has to be installed **after** installing |pyretis|: .. code-block:: pyretis python -m pip install git+https://github.com/mdtraj/mdtraj.git **Note:** Please make sure that you are using a Python environment of version 3.7 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 conda activate pyretis conda install pyretis -c conda-forge (working only with pyretis 2) |pyretis| offers an analysis tool, named |pyvisa|. Its GUI requires PyQt5 and mdtraj to be executed. To install PyQt5 and mdtraj via conda: .. code-block:: pyretis conda install pyqt -c conda-forge conda install mdtraj -c conda-forge **Note:** Since |pyretis| will **only work with Python 3.7 or newer**, please make sure that you are using an environment with a recent version of Python. | .. _user-guide-install-virtual-environment: Optional: Setting up a virtual environment for pip -------------------------------------------------- You can also install |pyretis| in a `virtual environment `_. Using a virtual environment makes it easier to maintain different versions of |pyretis| and it's dependencies. The following steps are needed to set up a virtual environment: 1. Install the `virtualenv package `_. This can be done using ``pip``: .. code-block:: pyretis [sudo] python -m pip install virtualenv or using a package manager for your operative system, for instance ``apt`` if you are using a Debian-like Linux: .. code-block:: pyretis [sudo] apt-get install virtualenv 2. Create a folder dedicated to your virtual environments, for instance in your home directory: .. code-block:: pyretis mkdir ~/name-of-environment-folder cd ~/name-of-environment-folder 3. Install the new environment with the desired Python3 interpreter, using the path to the desired Python executable (usually found in ``/usr/bin/``), and a name for the virtual environment folder (``pyretis-env``): .. code-block:: pyretis virtualenv -p /usr/bin/python3 ~/name-of-environment-folder/pyretis-env Note, if you want more control over which version of Python to use, you can use the ``-p`` option in the command above to specify this. For instance, for version **3.8**: .. code-block:: pyretis virtualenv -p /usr/bin/python3.8 ~/name-of-environment-folder/pyretis-env 4. Activate the environment: .. code-block:: pyretis source ~/name-of-environment-folder/pyretis-env/bin/activate 5. Install |pyretis|: .. code-block:: pyretis python -m pip install git+https://gitlab.com/pyretis/pyretis.git 6. (Optional) |pyvisa|'s GUI requisite: .. code-block:: pyretis python -m pip install pyqt5 7. (Optional) |pyvisa|'s also requisite `mdtraj `_: .. code-block:: pyretis python -m pip install git+https://github.com/mdtraj/mdtraj.git The folder ``~/name-of-environment-folder/pyretis-env`` now contains a new Python environment where |pyretis| has been installed. Since you have sourced the virtual environment, ``python -m pip`` will now refer to the version of ``pip`` installed in the environment and when you install packages, they will be installed inside the folder ``~/name-of-environment-folder/pyretis-env``. **Note:** that you will have to source the environment each time you want to make use of it using the ``source`` command given above. | .. _user-guide-install-git: 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 python -m pip install . or, alternatively: .. code-block:: pyretis python setup.py install and, to be able to run |pyvisa|'s GUI, add ``pyqt5``: .. code-block:: pyretis python -m pip install pyqt5 Then, install ``mdtraj``: .. code-block:: pyretis python -m pip install git+https://github.com/mdtraj/mdtraj.git .. _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 python -m pip install -r requirements-dev.txt Finally, install |pyretis| using: .. code-block:: pyretis python -m pip install -e . .. _user-guide-install-test: | Testing your installation ------------------------- After installing from the |pyretis| source, your installation can be tested by running the tests from the main directory: .. code-block:: pyretis python -m unittest discover -v -s test .. _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 package |pyvisa| requires PyQt5 and mdtraj, which has to be installed separately as described above.