1 ==============================
2 Full installation instructions
3 ==============================
7 This document provides detailed documentation about building and installing
8 the gmxapi Python package.
10 GROMACS is a high performance computational science tool that is optimized for
11 a variety of specialized hardware and parallel computing environments.
12 To make the best use of a computing environment, GROMACS is usually built from
15 Users of Python based molecular science tools may have various requirements and
16 use a variety of Python distributions,
17 so gmxapi extension code is most useful when built from source code for a specific
18 GROMACS installation and Python environment.
20 Read this document if the :doc:`/quickstart` instructions are not sufficient for you.
21 If you don't need a lot of reference material, you may just jump ahead to the :ref:`installation`.
23 Command line examples assume the `bash <https://www.gnu.org/software/bash/>`_ shell.
25 .. note:: Regarding multiple GROMACS installations:
26 Many GROMACS users switch between multiple GROMACS installations on the same
27 computer using an HPC module system and/or a GMXRC configuration script.
28 For the equivalent sort of environment switching with the ``gmxapi`` Python package,
29 we recommend installing it in a different
30 `Python virtual environment <https://www.google.com/search?q=python+virtual+environment>`_
31 for each GROMACS installation.
32 Once built, a particular copy of the ``gmxapi`` Python package always refers to the
33 same GROMACS installation.
35 .. contents:: Contents
41 The following documentation contains frequent references to the ``pip`` tool
42 for installing Python packages. In some cases, an unprivileged user should
43 use the ``--user`` command line flag to tell ``pip`` to install packages
44 into the user site-packages directory rather than the default site-packages
45 directory for the Python installation. This flag is not appropriate when
46 running ``pip`` in a virtual environment (as recommended) and is omitted in
47 this documentation. If you need the ``--user`` flag, you should modify the
48 example commands to look something like ``pip install --upgrade somepackage --user``
53 ``gmxapi`` comes in three parts:
55 * GROMACS gmxapi library for C++
56 * This Python package, supporting Python 3.5 and higher
57 * MD restraint plugins and sample gmxapi client code
59 Build system requirements
60 -------------------------
62 gmxapi can be built for Python 3.5 and higher.
64 You will need a C++ 14 compatible compiler and a reasonably up-to-date version
66 Full gmxapi functionality may also require an MPI compiler (e.g. ``mpicc``).
68 The Python package requires a GROMACS installation.
70 `GROMACS <http://manual.gromacs.org/documentation/current/install-guide/index.html>`_
71 before proceeding. Be sure to configure CMake with the ``GMXAPI=ON`` option.
73 Then, "source" the GMXRC file from the GROMACS installation as you normally would
74 before using GROMACS, or note its installation location so that you can pass it
75 to the build configuration.
79 If you are using a managed computing resource, such as a research HPC cluster,
80 GROMACS may already be installed, but you will need GROMACS 2020 or later, and
81 it must be configured with ``GMXAPI=ON``.
83 Important: To build a module that can be imported by Python, you need a Python
84 installation that includes the Python headers. Unfortunately, it is not always
85 obvious whether these headers are present or where to find them. The simplest
86 answer is to just try to build the Python package using these instructions, and
87 if gmxapi is unable to find the Python tools it needs, try a different Python
88 installation or install the additional development packages.
90 On a Linux system, this may require installing packages such as ``python-dev``
91 and/or ``python3-dev``. Alternatively, various Python distributions provide a
92 sufficient build environment while only requiring installation into a user
93 home directory. (Some examples below.)
95 If you are using an HPC system with software available through modules you may
96 be able to just ``module load`` a different Python installation and find one
99 Python environment requirements
100 -------------------------------
102 gmxapi requires Python 3.5 or higher. Check your version with
103 ``python3 --version`` or ``python --version``.
107 The following documentation assumes you do not need to use a trailing '3' to
108 access a Python 3 interpreter on your system.
109 The default Python interpreter on your system may use ``python3`` and ``pip3``
110 instead of ``python`` and ``pip``. You can check the version with
111 ``python3 --version`` or ``python --version`` and ``pip --version``.
113 To build and install, you also need the packages ``cmake``,
114 ``setuptools``, ``networkx``, and ``scikit-build``.
116 For full functionality, you should also have ``mpi4py`` and ``numpy``.
117 These requirements and version numbers are listed in ``requirements.txt``.
119 The easiest way to make sure you have the requirements installed, first update
120 ``pip``, then use the ``requirements.txt`` file provided with the repository.
121 File paths in this section are relative to the root directory of your local copy
122 of the GROMACS source.
124 Confirm that ``pip`` is available, install ``pip`` if it is missing, or get
125 instructions on how to install ``pip``::
127 python -m ensurepip --default-pip
129 Install or upgrade required components::
131 python -m pip install --upgrade pip
132 pip install --upgrade setuptools
133 pip install -r python_packaging/src/requirements.txt
135 If building documentation or running tests,
136 ``pip install -r python_packaging/requirements-docs.txt`` or
137 ``pip install -r python_packaging/requirements-test.txt``,
138 respectively, or see below.
142 Documentation build requirements
143 --------------------------------
145 Documentation is built with `Sphinx <http://www.sphinx-doc.org/>`_
146 from a combination of static content in ``rst``
147 files and from embedded documentation in the Python package. To build documentation
148 locally, you will need a reasonably current copy of Sphinx and the RTD theme.
151 pip install --upgrade Sphinx Pygments sphinx-rtd-theme
153 .. seealso:: :ref:`documentation`
155 .. _testing_requirements:
160 Testing is performed with `pytest <https://docs.pytest.org/en/latest/>`_.
161 Tests also require ``numpy``.
162 You can probably install both with ``pip``::
164 pip install pytest numpy
166 To test the full functionality also requires an MPI parallel environment.
167 You will need the ``mpi4py`` Python package and an MPI launcher
168 (such as ``mpiexec``, ``mpirun``, a launcher provided by your HPC queuing system,
169 or whatever is provided by your favorite MPI package for your operating system).
171 .. _mpi_requirements:
176 For the ensemble simulations features, you will need an MPI installation. On an HPC system, this means you will
177 probably have to use ``module load`` to load a compatible set of MPI tools and compilers. Check your HPC
178 documentation or try ``module avail`` to look for an ``openmpi``, ``mpich``, or ``mvapich`` module and matching compiler
179 module. This may be as simple as
185 Note that the compilers loaded might not be the first compilers discovered automatically by the build tools we will use
186 below, so you may have to specify compilers on the command line for consistency. It may be necessary to require that
187 GROMACS, gmxapi, and the sample code are built with the same compiler(s).
189 Note that strange errors have been known to occur when ``mpi4py`` is built with
190 different a different tool set than has been used to build Python and gmxapi.
191 If the default compilers on your system are not sufficient for GROMACS or gmxapi,
192 you may need to build, e.g., OpenMPI or MPICH, and/or build ``mpi4py`` with a
193 specific MPI compiler wrapper. This can complicate building in environments such
196 Set the MPICC environment variable to the MPI compiler wrapper and forcibly
197 reinstall ``mpi4py``.
200 export MPICC=`which mpicc`
201 pip install --no-cache-dir --upgrade --no-binary \":all:\" --force-reinstall mpi4py
203 Installing the Python package
204 =============================
206 We recommend you install the gmxapi package in a Python virtual environment
207 (``virtualenv`` or ``venv``). There are several ways to do this, and it is also
208 possible to install without a virtual environment. If installing without a
209 virtual environment as an un-privileged user, you may need to set the CMake
210 variable ``GMXAPI_USER_INSTALL`` (``-DGMXAPI_USER_INSTALL=ON`` on the ``cmake``
211 command line) and / or use the ``--user`` option with ``pip install``.
213 Sometimes the build environment can choose a different Python interpreter than
214 the one you intended.
215 You can set the ``PYTHON_EXECUTABLE`` CMake variable to explicitly choose the
216 Python interpreter for your chosen installation.
217 For example: ``-DPYTHON_EXECUTABLE=\`which python\```
221 Recommended installation
222 ------------------------
224 Locate or install GROMACS
225 ^^^^^^^^^^^^^^^^^^^^^^^^^
227 You need a GROMACS installation that includes the gmxapi headers and library.
228 If GROMACS 2020 or higher is already installed,
229 *and* was configured with ``GMXAPI=ON`` at build time,
230 you can just source the GMXRC
231 (so that the Python package knows where to find GROMACS)
232 and skip to the next section.
234 Otherwise, install a supported version of GROMACS. For instance, clone one of
235 the two following ``git`` repositories.
237 .. rubric:: Official GROMACS release branch
241 git clone https://github.com/gromacs/gromacs.git gromacs
244 .. rubric:: The Kasson Lab GROMACS fork...
246 ... may have experimental features that have not yet appeared in an official GROMACS
251 git clone https://github.com/kassonlab/gromacs-gmxapi.git gromacs
253 # for that absolute latest code, check out the "development branch" (optional)
256 .. todo:: Update w.r.t. https://github.com/kassonlab/gmxapi/issues/188
258 Configure and build GROMACS. Install into a ``gromacs-gmxapi`` directory in your
259 home directory (or wherever you prefer, using ``CMAKE_INSTALL_PREFIX``).
260 Complete instructions are provided in the GROMACS installation documentation;
261 a brief example is provided below with the GMXAPI=ON flag.
267 cmake ../gromacs -DCMAKE_CXX_COMPILER=`which g++` \
268 -DCMAKE_C_COMPILER=`which gcc` \
269 -DCMAKE_INSTALL_PREFIX=$HOME/gromacs-gmxapi \
270 -DGMX_THREAD_MPI=ON \
272 make -j && make install
276 ``make -j`` uses multiple CPU threads to build in parallel
277 (using more CPU *and memory*).
278 Adjust according to your computing resources.
280 Set the environment variables for the GROMACS installation so that the gmxapi
281 headers and library can be found when building the Python package.
282 If you installed to a ``gromacs-gmxapi`` directory in your home directory as
283 above and you use the ``bash`` shell, do::
285 source $HOME/gromacs-gmxapi/bin/GMXRC
287 Set up a Python virtual environment
288 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
290 We recommend installing the Python package in a virtual environment.
291 If not installing in a virtual environment, you may not be able to install
292 necessary prerequisites (e.g. if you are not an administrator of the system you are on).
294 Create a Python 3 virtual environment.
296 For Python 3, use the ``venv`` module.
297 Depending on your computing environment, the Python 3 interpreter may be accessed
298 with the command ``python`` or ``python3``. Use ``python --version`` and
299 ``python3 --version`` to figure out which you need to use. The following assumes
300 the Python 3 interpreter is accessed with ``python3``.
304 After activating the venv, ``python`` and ``pip`` are sufficient. (The '3'
305 suffix will no longer be necessary and will be omitted in the rest of this
310 python3 -m venv $HOME/myvenv
312 Activate the virtual environment. Your shell prompt will probably be updated with the name of the environment you
313 created to make it more obvious.
317 $ source $HOME/myvenv/bin/activate
320 Activating the virtual environment changes your shell prompt to indicate the
321 environment is active. The prompt is omitted from the remainging examples, but
322 the remaining examples assume the virtualenv is still active.
323 (Don't do it now, but you can deactivate the environment by running ``deactivate``.)
325 Install some dependencies. For MPI, we use mpi4py.
326 Make sure it is using the same MPI installation that we are building
327 GROMACS against and building with compatible compilers.
331 python -m pip install --upgrade pip setuptools
332 MPICC=`which mpicc` pip install --upgrade mpi4py
337 Get a copy of `the source code <https://github.com/gromacs/gromacs>`_,
338 if you haven't already.
339 The python package source code is in the GROMACS repository under
340 ``python_packaging/src``
343 You will need to install some additional dependencies.
344 The :file:`requirements.txt` file is provided for convenience.
348 cd python_packaging/src
349 pip install -r requirements.txt
357 Documentation for the Python classes and functions in the gmx module can
358 be accessed in the usual ways, using ``pydoc`` from the command line or
359 ``help()`` in an interactive Python session.
361 Additional documentation can be browsed on
362 `readthedocs.org <http://gmxapi.readthedocs.io/en/readthedocs/>`__ or
363 built with Sphinx after installation.
365 .. seealso:: :ref:`build_docs`
367 Install the ``gmxapi`` package so that its built-in documentation can be extracted
368 for the API reference. Then build all of the documentation with Sphinx using
372 pip install -r requirements-docs.txt
373 sphinx-build -b html documentation docs
375 Then open :file:`docs/index.html`
377 .. note:: The ``docs`` build target puts the built documentation in your build directory.
379 Alternatively, build the ``docs`` Docker image from ``python_packaging/docker/docs.dockerfile``.
384 Couldn't find ``gmxapi``? If you don't want to "source" your ``GMXRC`` file, you
385 can tell the package where to find a gmxapi compatible GROMACS installation with
386 ``gmxapi_DIR``. E.g. ``gmxapi_DIR=/path/to/gromacs pip install .``
388 Before updating the ``gmxapi`` package it is generally a good idea to remove the
389 previous installation and to start with a fresh build directory. You should be
390 able to just ``pip uninstall gmx``.
392 Do you see something like the following?
396 CMake Error at gmx/core/CMakeLists.txt:45 (find_package):
397 Could not find a package configuration file provided by "gmxapi" with any
398 of the following names:
403 Add the installation prefix of "gmxapi" to CMAKE_PREFIX_PATH or set
404 "gmxapi_DIR" to a directory containing one of the above files. If "gmxapi"
405 provides a separate development package or SDK, be sure it has been
408 This could be because
410 * GROMACS is not already installed
411 * GROMACS was built without the CMake variable ``GMXAPI=ON``
412 * or if ``gmxapi_DIR`` (or ``GROMACS_DIR``) is not a path containing directories
413 like ``bin`` and ``share``.
415 If you are not a system administrator you are encouraged to install in a Python
416 virtual environment, created with virtualenv or Conda.
417 Otherwise, you will need to specify the ``--user`` flag to ``pip``.
419 Two of the easiest problems to run into are incompatible compilers and
420 incompatible Python. Try to make sure that you use the same C and C++
421 compilers for GROMACS, for the Python package, and for the sample
422 plugin. These compilers should also correspond to the ``mpicc`` compiler
423 wrapper used to compile ``mpi4py``. In order to build the Python
424 package, you will need the Python headers or development installation,
425 which might not already be installed on the machine you are using. (If
426 not, then you will get an error about missing ``Python.h`` at some
427 point.) If you have multiple Python installations (or modules available
428 on an HPC system), you could try one of the other Python installations,
429 or you or a system administrator could install an appropriate Python dev
430 package. Alternatively, you might try installing your own Anaconda or
431 MiniConda in your home directory.
433 If an attempted installation fails with CMake errors about missing
434 “gmxapi”, make sure that Gromacs is installed and can be found during
435 installation. For instance,
439 gmxapi_DIR=/Users/eric/gromacs python setup.py install --verbose
441 Pip and related Python package management tools can be a little too
442 flexible and ambiguous sometimes. If things get really messed up, try
443 explicitly uninstalling the ``gmx`` module and its dependencies, then do
444 it again and repeat until ``pip`` can no longer find any version of any
453 Successfully running the test suite is not essential to having a working
454 ``gmxapi`` package. We are working to make the testing more robust, but
455 right now the test suite is a bit delicate and may not work right, even
456 though you have a successfully built ``gmxapi`` package. If you want to
457 troubleshoot, though, the main problems seem to be that automatic
458 installation of required python packages may not work (requiring manual
459 installations, such as with ``pip install somepackage``) and ambiguities
460 between python versions.
462 If you are working in a development branch of the repository, note that
463 the upstream branch may be reset to ``master`` after a new release is
464 tagged. In general, but particularly on the ``devel`` branch, when you
465 do a ``git pull``, you should use the ``--rebase`` flag.
467 If you fetch this repository and then see a git status like this::
471 Your branch and 'origin/devel' have diverged,
472 and have 31 and 29 different commits each, respectively.
474 then ``gmxapi`` has probably entered a new development cycle. You can
475 do ``git pull --rebase`` to update to the latest development branch.
477 If you do a ``git pull`` while in ``devel`` and get a bunch of unexpected
478 merge conflicts, do ``git merge --abort; git pull --rebase`` and you should
481 If you are developing code for gmxapi, this should be an indication to
482 rebase your feature branches for the new development cycle.