1 ==============================
2 Full installation instructions
3 ==============================
7 Installation instructions for the :py:mod:`gmxapi` Python package,
10 Command line examples assume the `bash <https://www.gnu.org/software/bash/>`_ shell.
12 .. note:: Regarding multiple GROMACS installations:
13 Many GROMACS users switch between multiple GROMACS installations on the same
14 computer using an HPC module system and/or a :ref:`GMXRC <getting access to |Gromacs|>` configuration script.
15 For the equivalent sort of environment switching with the :py:mod:`gmxapi` Python package,
16 we recommend installing it in a different
17 `Python virtual environment <https://www.google.com/search?q=python+virtual+environment>`_
18 for each GROMACS installation.
19 Once built, a particular copy of the :py:mod:`gmxapi` Python package always refers to the
20 same GROMACS installation.
22 .. contents:: Contents
28 The following documentation contains frequent references to the pip_ tool
29 for installing Python packages. In some cases, an unprivileged user should
30 use the ``--user`` command line flag to tell pip_ to install packages
31 into the user site-packages directory rather than the default site-packages
32 directory for the Python installation. This flag is not appropriate when
33 running :command:`pip` in a virtual environment (as recommended) and is omitted in
34 this documentation. If you need the ``--user`` flag, you should modify the
35 example commands to look something like :command:`pip install --upgrade somepackage --user`
39 These instructions use the executable names :command:`python` and :command:`pip`
40 instead of :command:`python3` or :command:`pip3`. Some Python installations require the ``3``
41 suffix, but it is usually not necessary if you have already activated a Python
42 virtual environment (recommended).
47 Typically, setting up the *gmxapi* Python package follows these three steps.
48 If this overview is sufficient for your computing environment,
49 you may disregard the rest of this document.
54 Locate your GROMACS installation, or build and install GROMACS 2020 or higher.
56 .. seealso:: `GROMACS installation <http://manual.gromacs.org/documentation/current/install-guide/index.html>`_
58 The following assumes GROMACS is installed to :file:`/path/to/gromacs`
60 Set up a Python virtual environment
61 -----------------------------------
65 python3 -m venv $HOME/myvenv
66 . $HOME/myvenv/bin/activate
67 python -m ensurepip --default-pip
68 pip install --upgrade pip setuptools
69 pip install --upgrade cmake scikit-build
71 .. seealso:: :ref:`gmxapi venv`
73 Install the gmxapi Python package
74 ---------------------------------
78 . /path/to/gromacs/bin/GMXRC
81 .. seealso:: :ref:`installation`
86 *gmxapi* comes in three parts:
88 * GROMACS gmxapi library for C++.
89 * This Python package, supporting Python 3.6 and higher
90 * MD restraint plugins and sample gmxapi client code
95 The Python package requires a GROMACS installation.
96 Locate an existing GROMACS installation, or
97 `build and install GROMACS <http://manual.gromacs.org/documentation/current/install-guide/index.html>`_
102 Note that gmxapi requires that GROMACS is configured with ``GMXAPI=ON`` and ``BUILD_SHARED_LIBS=ON``.
103 These are enabled by default in most cases. If these options were overridden
104 for your GROMACS installation, you will see CMake errors when trying to build
105 and install the gmxapi Python package or other client software.
107 Then, "source" the :file:`GMXRC` file from the GROMACS installation
108 :ref:`as you normally would <getting access to |Gromacs|>`
109 before using GROMACS, or note its installation location so that you can pass it
110 to the build configuration.
112 Build system requirements
113 -------------------------
115 gmxapi can be built for Python 3.6 and higher.
117 You will need a C++ 14 compatible compiler and a reasonably up-to-date version
119 Full gmxapi functionality may also require an MPI compiler (e.g. :command:`mpicc`).
121 Important: To build a module that can be imported by Python, you need a Python
122 installation that includes the Python headers. Unfortunately, it is not always
123 obvious whether these headers are present or where to find them. The simplest
124 answer is to just try to build the Python package using these instructions, and
125 if gmxapi is unable to find the Python tools it needs, try a different Python
126 installation or install the additional development packages.
128 On a Linux system, this may require installing packages such as ``python-dev``
129 and/or ``python3-dev``.
130 If you are building Python, either from scratch or with a tool like
131 :command:`pyenv install` (see
132 `wiki entry <https://github.com/pyenv/pyenv/wiki#how-to-build-cpython-with---enable-shared>`_
134 be sure to enable installation of the Python C library with the
135 ``--enable-shared`` flag.
136 Alternatively, various Python distributions provide a
137 sufficient build environment while only requiring installation into a user
138 home directory. (Some examples below.)
140 If you are using an HPC system with software available through modules you may
141 be able to just :command:`module load` a different Python installation and find one
144 Python environment requirements
145 -------------------------------
147 gmxapi requires Python 3.6 or higher. Check your version with
148 :command:`python3 --version` or :command:`python --version`.
152 The following documentation assumes you do not need to use a trailing '3' to
153 access a Python 3 interpreter on your system.
154 The default Python interpreter on your system may use :command:`python3` and :command:`pip3`
155 instead of :command:`python` and :command:`pip`. You can check the version with
156 :command:`python3 --version` or :command:`python --version` and :command:`pip --version`.
158 To build and install, you need the Python packages for
159 cmake_, networkx_, scikit-build_, and setuptools_
160 (all available from `PyPI with pip <https://pip.pypa.io/en/stable/>`_).
162 For full functionality, you should also have mpi4py_ and numpy_.
163 These requirements and version numbers are listed in :file:`requirements.txt`.
165 The easiest way to make sure you have the requirements installed, first update
166 pip_, then use the :file:`requirements.txt` file provided with the repository.
167 File paths in this section are relative to the root directory of your local copy
168 of the GROMACS source.
170 Confirm that pip_ is available, install pip_ if it is missing, or get
171 instructions on how to install pip_::
173 python -m ensurepip --default-pip
175 Install or upgrade required components::
177 python -m pip install --upgrade pip
178 pip install --upgrade setuptools
180 "requirements" files in GROMACS source tree
181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
183 If you are building from source code in a local copy of the GROMACS source
184 repository, some helpful files allow you to preinstall the Python requirements
185 before installing the :py:mod:`gmxapi` package.
187 pip install -r python_packaging/src/requirements.txt
189 If building documentation or running tests,
190 :command:`pip install -r python_packaging/requirements-docs.txt` or
191 :command:`pip install -r python_packaging/requirements-test.txt`,
192 respectively, or see below.
194 Documentation build requirements
195 --------------------------------
197 See :ref:`gmxapi_package_documentation`
199 .. _testing requirements:
204 Note that the test suite is only available in the GROMACS source tree.
205 (It is not part of the installed package.)
206 Acquire the GROMACS sources with :command:`git` or by downloading an archive, as documented elsewhere.
208 Testing is performed with `pytest <https://docs.pytest.org/en/latest/>`_.
210 :file:`python_packaging/requirements-test.txt` lists additional requirements for testing.
213 pip install -r python_packaging/requirements-test.txt
215 To test the full functionality also requires an MPI parallel environment.
216 You will need the mpi4py_ Python package and an MPI launcher
217 (such as :command:`mpiexec`, :command:`mpirun`, a launcher provided by your HPC queuing system,
218 or whatever is provided by your favorite MPI package for your operating system).
220 .. _mpi_requirements:
225 For the ensemble simulations features, you will need an MPI installation.
226 On an HPC system, this means you will probably have to use :command:`module load`
227 to load a compatible set of MPI tools and compilers.
228 Check your HPC documentation or try :command:`module avail` to look for an
229 ``openmpi``, ``mpich``, or ``mvapich`` module and matching compiler module.
230 This may be as simple as::
235 Note that the compilers loaded might not be the first compilers discovered
236 automatically by the build tools we will use below,
237 so you may have to specify compilers on the command line for consistency.
238 It may be necessary to require that GROMACS, gmxapi,
239 and the sample code are built with the same compiler(s).
241 Note that strange errors have been known to occur when mpi4py_ is built with
242 different a different tool set than has been used to build Python and gmxapi.
243 If the default compilers on your system are not sufficient for GROMACS or gmxapi,
244 you may need to build, e.g., OpenMPI or MPICH, and/or build mpi4py_ with a
245 specific MPI compiler wrapper. This can complicate building in environments such
248 Set the MPICC environment variable to the MPI compiler wrapper and forcibly
251 export MPICC=`which mpicc`
252 pip install --no-cache-dir --upgrade --no-binary ":all:" --force-reinstall mpi4py
254 If you have a different MPI C compiler wrapper, substitute it for :command:`mpicc` above.
258 Installing the Python package
259 =============================
261 We recommend using Python's `pip <https://pip.pypa.io/en/stable/>`_
262 package installer to automatically download, build, and install the latest
263 version of the gmxapi package into a Python
264 `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_,
265 though it is also possible to install without a virtual environment.
266 If installing without a virtual environment as an un-privileged user,
267 you may need to set the CMake variable ``GMXAPI_USER_INSTALL``
268 (``-DGMXAPI_USER_INSTALL=ON`` on the :command:`cmake` command line)
269 and / or use the ``--user`` option with :command:`pip install`.
271 Recommended installation
272 ------------------------
274 The instructions in this section assume that *pip* is able to download files
275 from the internet. Alternatively, refer to :ref:`gmxapi offline install`.
277 Locate or install GROMACS
278 ^^^^^^^^^^^^^^^^^^^^^^^^^
280 You need a GROMACS installation that includes the gmxapi headers and library.
281 If GROMACS 2020 or higher is already installed,
282 *and* was configured with ``GMXAPI=ON`` at build time,
283 you can just source the :ref:`GMXRC <getting access to |Gromacs|>`
284 (so that the Python package knows where to find GROMACS)
285 and skip to the next section.
287 Otherwise, install a supported version of GROMACS.
288 When building GROMACS from source, be sure to configure cmake with the flag
289 ``-DGMXAPI=ON`` (default).
291 Set the environment variables for the GROMACS installation so that the gmxapi
292 headers and library can be found when building the Python package.
293 If you installed to a :file:`gromacs-gmxapi` directory in your home directory as
294 above and you use the :command:`bash` shell, do::
296 source $HOME/gromacs-gmxapi/bin/GMXRC
300 Set up a Python virtual environment
301 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
303 We recommend installing the Python package in a virtual environment.
304 If not installing in a virtual environment, you may not be able to install
305 necessary prerequisites (e.g. if you are not an administrator of the system you are on).
307 The following instructions use the :py:mod:`venv` module.
308 Alternative virtual environments, such as Conda_,
309 should work fine, but are beyond the scope of this document.
310 (We welcome contributed recipes!)
312 Depending on your computing environment, the Python 3 interpreter may be accessed
313 with the command :command:`python` or :command:`python3`. Use :command:`python --version` and
314 :command:`python3 --version` to figure out which you need to use. The following assumes
315 the Python 3 interpreter is accessed with :command:`python3`.
317 Create a Python 3 virtual environment::
319 python3 -m venv $HOME/myvenv
321 Activate the virtual environment. Your shell prompt will probably be updated with the name of the environment you
322 created to make it more obvious.
326 $ source $HOME/myvenv/bin/activate
331 After activating the *venv*, :command:`python` and :command:`pip` are sufficient.
332 (The '3' suffix will no longer be necessary and will be omitted in the rest
335 Activating the virtual environment may change your shell prompt to indicate the
336 environment is active. The prompt is omitted from the remaining examples, but
337 the remaining examples assume the virtual environment is still active.
338 (Don't do it now, but you can deactivate the environment by running :command:`deactivate`.)
343 It is always a good idea to update pip_ and setuptools_ before installing
344 new Python packages::
346 pip install --upgrade pip setuptools
348 The gmxapi installer requires a few additional packages. It is best to make sure
349 they are installed and up to date before proceeding.
353 pip install --upgrade cmake scikit-build
355 For MPI, we use mpi4py_.
356 Make sure it is using the same MPI installation that we are building
357 GROMACS against and building with compatible compilers.
361 python -m pip install --upgrade pip setuptools
362 MPICC=`which mpicc` pip install --upgrade mpi4py
364 .. seealso:: :ref:`mpi_requirements`
366 Install the latest version of gmxapi
367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
369 Fetch and install the latest official version of gmxapi from the Python Packaging Index::
371 # Get the latest official release.
374 The `PyPI repository <https://pypi.org/project/gmxapi/#history>`_
375 may include pre-release versions,
376 but :command:`pip` will ignore them unless you use the ``--pre`` flag::
378 # Get the latest version, including pre-release versions.
379 pip install --pre gmxapi
381 If :command:`pip` does not find your GROMACS installation, use one of the following
382 environment variables to provide a hint.
387 If you have a single GROMACS installation at :file:`/path/to/gromacs`, it is usually
388 sufficient to provide this location to :command:`pip` through the :envvar:`gmxapi_DIR`
389 environment variable.
393 gmxapi_DIR=/path/to/gromacs pip install gmxapi
398 If you have multiple builds of GROMACS distinguished by suffixes
399 (e.g. *_d*, *_mpi*, etcetera), or if you need to provide extra hints to :command:`pip`
400 about the software tools that were used to build GROMACS, you can specify a
401 directory in which the installer can find a CMake "tool chain".
403 In the following example, ``${SUFFIX}`` is the suffix that distinguishes the
404 particular build of GROMACS you want to target (refer to GROMACS installation
405 instructions for more information.) ``${SUFFIX}`` may simply be empty, or ``''``.
409 GMXTOOLCHAINDIR=/path/to/gromacs/share/cmake/gromacs${SUFFIX} pip install gmxapi
414 You can also install the :py:mod:`gmxapi` Python package from within a local copy of
415 the GROMACS source repository. Assuming you have already obtained the GROMACS
416 source code and you are in the root directory of the source tree, you will find
417 the :py:mod:`gmxapi` Python package sources in the :file:`python_packaging/src` directory.
421 cd python_packaging/src
422 pip install -r requirements.txt
425 .. _gmxapi offline install:
430 If the required dependencies are already installed, you can do a quick installation
431 without internet access, either from the source directory or from a source archive.
433 For example, the last line of the previous example could be replaced with::
435 pip install --no-cache-dir --no-deps --no-index --no-build-isolation .
437 Refer to pip_ documentation for descriptions of these options.
439 If you have built or downloaded a source distribution archive, you can provide
440 the archive file to :command:`pip` instead of the ``.`` argument::
442 pip install gmxapi-0.1.0.tar.gz
444 In this example, the archive file name is as was downloaded from
445 `PyPI <https://pypi.org/project/gmxapi/#history>`_ or as built locally,
446 according to the following instructions.
448 Building a source archive
449 -------------------------
451 A source archive for the gmxapi python package can be built from the GROMACS
452 source repository using Python ``setuptools`` and ``scikit-build``.
456 pip install --upgrade setuptools scikit-build
457 cd python_packaging/src
458 python setup.py sdist
460 This command will create a ``dist`` directory containing a source distribution
461 archive file. The file name has the form *gmxapi-<version>.<suffix>*, where
462 *<version>* is the version from the ``setup.py`` file, and *<suffix>* is
463 determined by the local environment or by additional arguments to ``setup.py``.
467 Python documentation for
468 `creating a source distribution
469 <https://docs.python.org/3/distutils/sourcedist.html#creating-a-source-distribution>`_
471 Package maintainers may update the online respository by uploading a freshly
472 built ``sdist`` with ``python -m twine upload dist/*``
474 .. _gmxapi_package_documentation:
476 Accessing gmxapi documentation
477 ==============================
479 Documentation for the Python classes and functions in the gmx module can
480 be accessed in the usual ways, using ``pydoc`` from the command line or
481 ``help()`` in an interactive Python session.
483 The complete documentation (which you are currently reading)
484 can be browsed `online <http://manual.gromacs.org/current/gmxapi/>`__
485 or built from a copy of the GROMACS source repository.
487 Documentation is built from a combination of Python module documentation and
488 static content, and requires a local copy of the GROMACS source repository.
493 To build the full gmxapi documentation with GROMACS, configure GROMACS with
494 ``-DGMX_PYTHON_PACKAGE=ON`` and build the GROMACS documentation normally.
495 This will first build the *gmxapi* Python package and install it to a temporary
496 location in the build tree. Sphinx can then import the package to automatically
497 extract Python docstrings.
499 Sometimes the build environment can choose a different Python interpreter than
500 the one you intended.
501 You can set the ``Python3_ROOT_DIR`` or ``CMAKE_PREFIX_PATH`` CMake variable to
502 explicitly choose the Python installation or *venv* directory.
504 If you use pyenv or pyenv-virtualenv to dynamically manage your Python version,
505 you can help identify a particular version with ``pyenv version-name`` and the
506 directory with ``pyenv prefix {version}``. For example::
508 -DPython3_ROOT_DIR=$(pyenv prefix $(pyenv version-name))
513 Alternatively, build the ``docs`` Docker image from ``python_packaging/docker/docs.dockerfile``
514 or pull a prebuilt image from DockerHub. Refer to the dockerfile or to
515 https://hub.docker.com/r/gmxapi/docs for more information.
519 Document sample_restraint package. Reference issue
520 `3027 <https://gitlab.com/gromacs/gromacs/-/issues/3027>`_
525 Note `testing requirements`_ above.
527 After installing the :py:mod:`gmxapi` Python package,
528 you can run the Python test suite from the GROMACS source tree.
531 # Assuming you are in the root directory of the repository:
532 pytest python_packaging/src/test/
534 Refer to :file:`python_packaging/README.md` for more detailed information.
536 .. _gmxapi install troubleshooting:
541 AttributeError: module 'enum' has no attribute 'IntFlag'
542 --------------------------------------------------------
544 If you had older versions of some of the dependencies installed,
545 you might have picked up a transitive dependency on the ``enum34`` package.
548 pip uninstall -y enum34
550 and see if that fixes the problem. If not, try a fresh virtual environment
551 (see above) to help narrow down the problem before you
552 `open an issue <https://gitlab.com/gromacs/gromacs/-/issues/>`_.
554 Couldn't find the ``gmxapi`` support library?
555 ---------------------------------------------
557 If you don't want to "source" your :ref:`GMXRC <getting access to |Gromacs|>` file, you
558 can tell the package where to find a gmxapi compatible GROMACS installation with
559 ``gmxapi_DIR``. E.g. ``gmxapi_DIR=/path/to/gromacs pip install .``
561 Before updating the ``gmxapi`` package it is generally a good idea to remove the
562 previous installation and to start with a fresh build directory. You should be
563 able to just ``pip uninstall gmxapi``.
565 Do you see something like the following?
569 CMake Error at gmx/core/CMakeLists.txt:45 (find_package):
570 Could not find a package configuration file provided by "gmxapi" with any
571 of the following names:
576 Add the installation prefix of "gmxapi" to CMAKE_PREFIX_PATH or set
577 "gmxapi_DIR" to a directory containing one of the above files. If "gmxapi"
578 provides a separate development package or SDK, be sure it has been
581 This could be because
583 * GROMACS is not already installed
584 * GROMACS was built without the CMake variable ``GMXAPI=ON``
585 * or if ``gmxapi_DIR`` (or ``GROMACS_DIR``) is not a path containing directories
586 like ``bin`` and ``share``.
588 If you are not a system administrator you are encouraged to install in a Python
589 virtual environment, created with virtualenv or Conda_.
590 Otherwise, you will need to specify the ``--user`` flag to ``pip``.
592 Two of the easiest problems to run into are incompatible compilers and
593 incompatible Python. Try to make sure that you use the same C and C++
594 compilers for GROMACS, for the Python package, and for the sample
595 plugin. These compilers should also correspond to the :command:`mpicc` compiler
596 wrapper used to compile mpi4py_. In order to build the Python
597 package, you will need the Python headers or development installation,
598 which might not already be installed on the machine you are using. (If
599 not, then you will get an error about missing :file:`Python.h` at some
600 point.) If you have multiple Python installations (or modules available
601 on an HPC system), you could try one of the other Python installations,
602 or you or a system administrator could install an appropriate Python dev
603 package. Alternatively, you might try installing your own Anaconda or
604 MiniConda in your home directory.
606 If an attempted installation fails with CMake errors about missing
607 “gmxapi”, make sure that Gromacs is installed and can be found during
608 installation. For instance,
612 gmxapi_DIR=/Users/eric/gromacs python setup.py install --verbose
614 Pip and related Python package management tools can be a little too
615 flexible and ambiguous sometimes. If things get really messed up, try
616 explicitly uninstalling the :py:mod:`gmxapi` module and its dependencies, then do
617 it again and repeat until :command:`pip` can no longer find any version of any
626 Successfully running the test suite is not essential to having a working
627 :py:mod:`gmxapi` package. We are working to make the testing more robust, but
628 right now the test suite is a bit delicate and may not work right, even
629 though you have a successfully built the :py:mod:`gmxapi` package. If you want to
630 troubleshoot, though, the main problems seem to be that automatic
631 installation of required python packages may not work (requiring manual
632 installations, such as with :command:`pip install somepackage`) and ambiguities
633 between python versions.
635 If you are working in a development branch of the repository, note that
636 the upstream branch may be reset to ``master`` after a new release is
637 tagged. In general, but particularly on the ``devel`` branch, when you
638 do a :command:`git pull`, you should use the ``--rebase`` flag.
640 If you fetch this repository and then see a git status like this::
644 Your branch and 'origin/devel' have diverged,
645 and have 31 and 29 different commits each, respectively.
647 then :py:mod:`gmxapi` has probably entered a new development cycle. You can
648 do :command:`git pull --rebase` to update to the latest development branch.
650 If you do a :command:`git pull` while in ``devel`` and get a bunch of unexpected
651 merge conflicts, do :command:`git merge --abort; git pull --rebase` and you should
654 If you are developing code for gmxapi, this should be an indication to
655 rebase your feature branches for the new development cycle.
657 .. _cmake: https://pypi.org/project/cmake/
659 .. _Conda: https://docs.conda.io/en/latest/
661 .. _mpi4py: https://pypi.org/project/mpi4py/
663 .. _networkx: https://pypi.org/project/networkx/
665 .. _numpy: https://www.numpy.org/
667 .. _pip: https://pip.pypa.io/en/stable/
669 .. _scikit-build: https://pypi.org/project/scikit-build/
671 .. _setuptools: https://pypi.org/project/setuptools/