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 GMXRC 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 :command:`pip` tool
29 for installing Python packages. In some cases, an unprivileged user should
30 use the ``--user`` command line flag to tell :py:mod:`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 as you normally would
108 before using GROMACS, or note its installation location so that you can pass it
109 to the build configuration.
111 Build system requirements
112 -------------------------
114 gmxapi can be built for Python 3.6 and higher.
116 You will need a C++ 14 compatible compiler and a reasonably up-to-date version
118 Full gmxapi functionality may also require an MPI compiler (e.g. :command:`mpicc`).
120 Important: To build a module that can be imported by Python, you need a Python
121 installation that includes the Python headers. Unfortunately, it is not always
122 obvious whether these headers are present or where to find them. The simplest
123 answer is to just try to build the Python package using these instructions, and
124 if gmxapi is unable to find the Python tools it needs, try a different Python
125 installation or install the additional development packages.
127 On a Linux system, this may require installing packages such as ``python-dev``
128 and/or ``python3-dev``.
129 If you are building Python, either from scratch or with a tool like
130 :command:`pyenv install` (see
131 `wiki entry <https://github.com/pyenv/pyenv/wiki#how-to-build-cpython-with---enable-shared>`_
133 be sure to enable installation of the Python C library with the
134 ``--enable-shared`` flag.
135 Alternatively, various Python distributions provide a
136 sufficient build environment while only requiring installation into a user
137 home directory. (Some examples below.)
139 If you are using an HPC system with software available through modules you may
140 be able to just :command:`module load` a different Python installation and find one
143 Python environment requirements
144 -------------------------------
146 gmxapi requires Python 3.6 or higher. Check your version with
147 :command:`python3 --version` or :command:`python --version`.
151 The following documentation assumes you do not need to use a trailing '3' to
152 access a Python 3 interpreter on your system.
153 The default Python interpreter on your system may use :command:`python3` and :command:`pip3`
154 instead of :command:`python` and :command:`pip`. You can check the version with
155 :command:`python3 --version` or :command:`python --version` and :command:`pip --version`.
157 To build and install, you also need the packages :py:mod:`cmake`,
158 :py:mod:`setuptools`, :py:mod:`networkx`, and :py:mod:`scikit-build`.
160 For full functionality, you should also have :py:mod:`mpi4py` and :py:mod:`numpy`.
161 These requirements and version numbers are listed in :file:`requirements.txt`.
163 The easiest way to make sure you have the requirements installed, first update
164 :py:mod:`pip`, then use the :file:`requirements.txt` file provided with the repository.
165 File paths in this section are relative to the root directory of your local copy
166 of the GROMACS source.
168 Confirm that :py:mod:`pip` is available, install :py:mod:`pip` if it is missing, or get
169 instructions on how to install :py:mod:`pip`::
171 python -m ensurepip --default-pip
173 Install or upgrade required components::
175 python -m pip install --upgrade pip
176 pip install --upgrade setuptools
178 "requirements" files in GROMACS source tree
179 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
181 If you are building from source code in a local copy of the GROMACS source
182 repository, some helpful files allow you to preinstall the Python requirements
183 before installing the :py:mod:`gmxapi` package.
185 pip install -r python_packaging/src/requirements.txt
187 If building documentation or running tests,
188 :command:`pip install -r python_packaging/requirements-docs.txt` or
189 :command:`pip install -r python_packaging/requirements-test.txt`,
190 respectively, or see below.
192 Documentation build requirements
193 --------------------------------
195 See :ref:`gmxapi_package_documentation`
197 .. _testing_requirements:
202 Testing is performed with `pytest <https://docs.pytest.org/en/latest/>`_.
203 Tests also require :py:mod:`numpy`.
204 You can probably install both with :command:`pip`::
206 pip install pytest numpy
208 To test the full functionality also requires an MPI parallel environment.
209 You will need the :py:mod:`mpi4py` Python package and an MPI launcher
210 (such as :command:`mpiexec`, :command:`mpirun`, a launcher provided by your HPC queuing system,
211 or whatever is provided by your favorite MPI package for your operating system).
213 .. _mpi_requirements:
218 For the ensemble simulations features, you will need an MPI installation.
219 On an HPC system, this means you will probably have to use :command:`module load`
220 to load a compatible set of MPI tools and compilers.
221 Check your HPC documentation or try :command:`module avail` to look for an
222 ``openmpi``, ``mpich``, or ``mvapich`` module and matching compiler module.
223 This may be as simple as::
228 Note that the compilers loaded might not be the first compilers discovered
229 automatically by the build tools we will use below,
230 so you may have to specify compilers on the command line for consistency.
231 It may be necessary to require that GROMACS, gmxapi,
232 and the sample code are built with the same compiler(s).
234 Note that strange errors have been known to occur when :py:mod:`mpi4py` is built with
235 different a different tool set than has been used to build Python and gmxapi.
236 If the default compilers on your system are not sufficient for GROMACS or gmxapi,
237 you may need to build, e.g., OpenMPI or MPICH, and/or build :py:mod:`mpi4py` with a
238 specific MPI compiler wrapper. This can complicate building in environments such
241 Set the MPICC environment variable to the MPI compiler wrapper and forcibly
242 reinstall :py:mod:`mpi4py`::
244 export MPICC=`which mpicc`
245 pip install --no-cache-dir --upgrade --no-binary \":all:\" --force-reinstall mpi4py
247 If you have a different MPI C compiler wrapper, substitute it for :command:`mpicc` above.
251 Installing the Python package
252 =============================
254 We recommend using Python's `pip <https://pip.pypa.io/en/stable/>`_
255 package installer to automatically download, build, and install the latest
256 version of the gmxapi package into a Python
257 `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_,
258 though it is also possible to install without a virtual environment.
259 If installing without a virtual environment as an un-privileged user,
260 you may need to set the CMake variable ``GMXAPI_USER_INSTALL``
261 (``-DGMXAPI_USER_INSTALL=ON`` on the :command:`cmake` command line)
262 and / or use the ``--user`` option with :command:`pip install`.
264 Recommended installation
265 ------------------------
267 The instructions in this section assume that *pip* is able to download files
268 from the internet. Alternatively, refer to :ref:`gmxapi offline install`.
270 Locate or install GROMACS
271 ^^^^^^^^^^^^^^^^^^^^^^^^^
273 You need a GROMACS installation that includes the gmxapi headers and library.
274 If GROMACS 2020 or higher is already installed,
275 *and* was configured with ``GMXAPI=ON`` at build time,
276 you can just source the GMXRC
277 (so that the Python package knows where to find GROMACS)
278 and skip to the next section.
280 Otherwise, install a supported version of GROMACS.
281 When building GROMACS from source, be sure to configure cmake with the flag
282 ``-DGMXAPI=ON`` (default).
284 Set the environment variables for the GROMACS installation so that the gmxapi
285 headers and library can be found when building the Python package.
286 If you installed to a :file:`gromacs-gmxapi` directory in your home directory as
287 above and you use the :command:`bash` shell, do::
289 source $HOME/gromacs-gmxapi/bin/GMXRC
293 Set up a Python virtual environment
294 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
296 We recommend installing the Python package in a virtual environment.
297 If not installing in a virtual environment, you may not be able to install
298 necessary prerequisites (e.g. if you are not an administrator of the system you are on).
300 The following instructions use the :py:mod:`venv` module.
301 Alternative virtual environments, such as Conda_,
302 should work fine, but are beyond the scope of this document.
303 (We welcome contributed recipes!)
305 Depending on your computing environment, the Python 3 interpreter may be accessed
306 with the command :command:`python` or :command:`python3`. Use :command:`python --version` and
307 :command:`python3 --version` to figure out which you need to use. The following assumes
308 the Python 3 interpreter is accessed with :command:`python3`.
310 Create a Python 3 virtual environment::
312 python3 -m venv $HOME/myvenv
314 Activate the virtual environment. Your shell prompt will probably be updated with the name of the environment you
315 created to make it more obvious.
319 $ source $HOME/myvenv/bin/activate
324 After activating the *venv*, :command:`python` and :command:`pip` are sufficient.
325 (The '3' suffix will no longer be necessary and will be omitted in the rest
328 Activating the virtual environment may change your shell prompt to indicate the
329 environment is active. The prompt is omitted from the remaining examples, but
330 the remaining examples assume the virtual environment is still active.
331 (Don't do it now, but you can deactivate the environment by running :command:`deactivate`.)
336 It is always a good idea to update :py:mod:`pip` and :py:mod:`setuptools` before installing
337 new Python packages::
339 pip install --upgrade pip setuptools
341 The gmxapi installer requires a few additional packages. It is best to make sure
342 they are installed and up to date before proceeding.
346 pip install --upgrade cmake scikit-build
348 For MPI, we use :py:mod:`mpi4py`.
349 Make sure it is using the same MPI installation that we are building
350 GROMACS against and building with compatible compilers.
354 python -m pip install --upgrade pip setuptools
355 MPICC=`which mpicc` pip install --upgrade mpi4py
357 .. seealso:: :ref:`mpi_requirements`
359 Install the latest version of gmxapi
360 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
362 Fetch and install the latest version of gmxapi from the Python Packaging Index::
366 If :command:`pip` does not find your GROMACS installation, use one of the following
367 environment variables to provide a hint.
372 If you have a single GROMACS installation at :file:`/path/to/gromacs`, it is usually
373 sufficient to provide this location to :command:`pip` through the :envvar:`gmxapi_DIR`
374 environment variable.
378 gmxapi_DIR=/path/to/gromacs pip install gmxapi
383 If you have multiple builds of GROMACS distinguished by suffixes
384 (e.g. *_d*, *_mpi*, etcetera), or if you need to provide extra hints to :command:`pip`
385 about the software tools that were used to build GROMACS, you can specify a
386 directory in which the installer can find a CMake "tool chain".
388 In the following example, ``${SUFFIX}`` is the suffix that distinguishes the
389 particular build of GROMACS you want to target (refer to GROMACS installation
390 instructions for more information.) ``${SUFFIX}`` may simply be empty, or ``''``.
394 GMXTOOLCHAINDIR=/path/to/gromacs/share/cmake/gromacs${SUFFIX} pip install gmxapi
399 You can also install the :py:mod:`gmxapi` Python package from within a local copy of
400 the GROMACS source repository. Assuming you have already obtained the GROMACS
401 source code and you are in the root directory of the source tree, you will find
402 the :py:mod`gmxapi` Python package sources in the :file:`python_packaging/src` directory.
406 cd python_packaging/src
407 pip install -r requirements.txt
410 .. _gmxapi offline install:
415 If the required dependencies are already installed, you can do a quick installation
416 without internet access, either from the source directory or from a source archive.
418 For example, the last line of the previous example could be replaced with::
420 pip install --no-cache-dir --no-deps --no-index --no-build-isolation .
422 Refer to :py:mod:`pip` documentation for descriptions of these options.
424 If you have built or downloaded a source distribution archive, you can provide
425 the archive file to :command:`pip` instead of the ``.`` argument::
427 pip install gmxapi-0.1.0.tar.gz
429 In this example, the archive file name is as was downloaded from
430 `PyPI <https://pypi.org/project/gmxapi/#history>`_ or as built locally,
431 according to the following instructions.
433 Building a source archive
434 -------------------------
436 A source archive for the gmxapi python package can be built from the GROMACS
437 source repository using Python ``setuptools`` and ``scikit-build``.
441 pip install --upgrade setuptools scikit-build
442 cd python_packaging/src
443 python setup.py sdist
445 This command will create a ``dist`` directory containing a source distribution
446 archive file. The file name has the form *gmxapi-<version>.<suffix>*, where
447 *<version>* is the version from the ``setup.py`` file, and *<suffix>* is
448 determined by the local environment or by additional arguments to ``setup.py``.
452 Python documentation for
453 `creating a source distribution
454 <https://docs.python.org/3/distutils/sourcedist.html#creating-a-source-distribution>`_
456 Package maintainers may update the online respository by uploading a freshly
457 built ``sdist`` with ``python -m twine upload dist/*``
459 .. _gmxapi_package_documentation:
461 Accessing gmxapi documentation
462 ==============================
464 Documentation for the Python classes and functions in the gmx module can
465 be accessed in the usual ways, using ``pydoc`` from the command line or
466 ``help()`` in an interactive Python session.
468 The complete documentation (which you are currently reading)
469 can be browsed `online <http://manual.gromacs.org/current/gmxapi/>`__
470 or built from a copy of the GROMACS source repository.
472 Documentation is built from a combination of Python module documentation and
473 static content, and requires a local copy of the GROMACS source repository.
478 To build the full gmxapi documentation with GROMACS, configure GROMACS with
479 ``-DGMX_PYTHON_PACKAGE=ON`` and build the GROMACS documentation normally.
480 This will first build the *gmxapi* Python package and install it to a temporary
481 location in the build tree. Sphinx can then import the package to automatically
482 extract Python docstrings.
484 Sometimes the build environment can choose a different Python interpreter than
485 the one you intended.
486 You can set the ``PYTHON_EXECUTABLE`` CMake variable to explicitly choose the
487 Python interpreter for your chosen installation.
488 For example: ``-DPYTHON_EXECUTABLE=\`which python\```
493 Alternatively, build the ``docs`` Docker image from ``python_packaging/docker/docs.dockerfile``
494 or pull a prebuilt image from DockerHub. Refer to the dockerfile or to
495 https://hub.docker.com/r/gmxapi/docs for more information.
499 Document sample_restraint package. Reference issue
500 `3027 <https://gitlab.com/gromacs/gromacs/-/issues/3027>`_
502 .. _gmxapi install troubleshooting:
507 Couldn't find the ``gmxapi`` support library?
508 If you don't want to "source" your ``GMXRC`` file, you
509 can tell the package where to find a gmxapi compatible GROMACS installation with
510 ``gmxapi_DIR``. E.g. ``gmxapi_DIR=/path/to/gromacs pip install .``
512 Before updating the ``gmxapi`` package it is generally a good idea to remove the
513 previous installation and to start with a fresh build directory. You should be
514 able to just ``pip uninstall gmxapi``.
516 Do you see something like the following?
520 CMake Error at gmx/core/CMakeLists.txt:45 (find_package):
521 Could not find a package configuration file provided by "gmxapi" with any
522 of the following names:
527 Add the installation prefix of "gmxapi" to CMAKE_PREFIX_PATH or set
528 "gmxapi_DIR" to a directory containing one of the above files. If "gmxapi"
529 provides a separate development package or SDK, be sure it has been
532 This could be because
534 * GROMACS is not already installed
535 * GROMACS was built without the CMake variable ``GMXAPI=ON``
536 * or if ``gmxapi_DIR`` (or ``GROMACS_DIR``) is not a path containing directories
537 like ``bin`` and ``share``.
539 If you are not a system administrator you are encouraged to install in a Python
540 virtual environment, created with virtualenv or Conda_.
541 Otherwise, you will need to specify the ``--user`` flag to ``pip``.
543 Two of the easiest problems to run into are incompatible compilers and
544 incompatible Python. Try to make sure that you use the same C and C++
545 compilers for GROMACS, for the Python package, and for the sample
546 plugin. These compilers should also correspond to the :command:`mpicc` compiler
547 wrapper used to compile :py:mod:`mpi4py`. In order to build the Python
548 package, you will need the Python headers or development installation,
549 which might not already be installed on the machine you are using. (If
550 not, then you will get an error about missing :file:`Python.h` at some
551 point.) If you have multiple Python installations (or modules available
552 on an HPC system), you could try one of the other Python installations,
553 or you or a system administrator could install an appropriate Python dev
554 package. Alternatively, you might try installing your own Anaconda or
555 MiniConda in your home directory.
557 If an attempted installation fails with CMake errors about missing
558 “gmxapi”, make sure that Gromacs is installed and can be found during
559 installation. For instance,
563 gmxapi_DIR=/Users/eric/gromacs python setup.py install --verbose
565 Pip and related Python package management tools can be a little too
566 flexible and ambiguous sometimes. If things get really messed up, try
567 explicitly uninstalling the :py:mod:`gmxapi` module and its dependencies, then do
568 it again and repeat until :command:`pip` can no longer find any version of any
577 Successfully running the test suite is not essential to having a working
578 :py:mod:`gmxapi` package. We are working to make the testing more robust, but
579 right now the test suite is a bit delicate and may not work right, even
580 though you have a successfully built the :py:mod:`gmxapi` package. If you want to
581 troubleshoot, though, the main problems seem to be that automatic
582 installation of required python packages may not work (requiring manual
583 installations, such as with :command:`pip install somepackage`) and ambiguities
584 between python versions.
586 If you are working in a development branch of the repository, note that
587 the upstream branch may be reset to ``master`` after a new release is
588 tagged. In general, but particularly on the ``devel`` branch, when you
589 do a :command:`git pull`, you should use the ``--rebase`` flag.
591 If you fetch this repository and then see a git status like this::
595 Your branch and 'origin/devel' have diverged,
596 and have 31 and 29 different commits each, respectively.
598 then :py:mod:`gmxapi` has probably entered a new development cycle. You can
599 do :command:`git pull --rebase` to update to the latest development branch.
601 If you do a :command:`git pull` while in ``devel`` and get a bunch of unexpected
602 merge conflicts, do :command:`git merge --abort; git pull --rebase` and you should
605 If you are developing code for gmxapi, this should be an indication to
606 rebase your feature branches for the new development cycle.
608 .. _Conda: https://docs.conda.io/en/latest/