python3 -m venv $HOME/myvenv
. $HOME/myvenv/bin/activate
python -m ensurepip --default-pip
- pip install --upgrade pip setuptools
- pip install --upgrade cmake scikit-build
+ pip install --upgrade pip setuptools wheel
.. seealso:: :ref:`gmxapi venv`
*gmxapi* comes in three parts:
* GROMACS gmxapi library for C++.
-* This Python package, supporting Python 3.6 and higher
+* This Python package, supporting Python 3.7 and higher
* MD restraint plugins and sample gmxapi client code
GROMACS requirements
Build system requirements
-------------------------
-gmxapi can be built for Python 3.6 and higher.
+gmxapi can be built for Python 3.7 and higher.
-You will need a C++ 14 compatible compiler and a reasonably up-to-date version
+You will need a C++ 17 compatible compiler and a reasonably up-to-date version
of CMake.
Full gmxapi functionality may also require an MPI compiler (e.g. :command:`mpicc`).
Python environment requirements
-------------------------------
-gmxapi requires Python 3.6 or higher. Check your version with
+gmxapi requires Python 3.7 or higher. Check your version with
:command:`python3 --version` or :command:`python --version`.
.. note::
:command:`python3 --version` or :command:`python --version` and :command:`pip --version`.
To build and install, you need the Python packages for
-cmake_, networkx_, scikit-build_, and setuptools_
+cmake_, networkx_, and setuptools_
(all available from `PyPI with pip <https://pip.pypa.io/en/stable/>`_).
For full functionality, you should also have mpi4py_ and numpy_.
See :ref:`gmxapi_package_documentation`
-.. _testing_requirements:
+.. _testing requirements:
Testing requirements
--------------------
+Note that the test suite is only available in the GROMACS source tree.
+(It is not part of the installed package.)
+Acquire the GROMACS sources with :command:`git` or by downloading an archive, as documented elsewhere.
+
Testing is performed with `pytest <https://docs.pytest.org/en/latest/>`_.
-Tests also require numpy_.
-You can probably install both with pip_::
- pip install pytest numpy
+:file:`python_packaging/requirements-test.txt` lists additional requirements for testing.
+With pip_::
+
+ pip install -r python_packaging/requirements-test.txt
To test the full functionality also requires an MPI parallel environment.
You will need the mpi4py_ Python package and an MPI launcher
reinstall mpi4py_::
export MPICC=`which mpicc`
- pip install --no-cache-dir --upgrade --no-binary \":all:\" --force-reinstall mpi4py
+ pip install --no-cache-dir --upgrade --no-binary ":all:" --force-reinstall mpi4py
If you have a different MPI C compiler wrapper, substitute it for :command:`mpicc` above.
Install dependencies
^^^^^^^^^^^^^^^^^^^^
-It is always a good idea to update pip_ and setuptools_ before installing
+It is always a good idea to update pip_, setuptools_, and wheel_ before installing
new Python packages::
pip install --upgrade pip setuptools
::
- pip install --upgrade cmake scikit-build
+ pip install --upgrade cmake pybind11
For MPI, we use mpi4py_.
Make sure it is using the same MPI installation that we are building
Install the latest version of gmxapi
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Fetch and install the latest version of gmxapi from the Python Packaging Index::
+Fetch and install the latest official version of gmxapi from the Python Packaging Index::
+ # Get the latest official release.
pip install gmxapi
+The `PyPI repository <https://pypi.org/project/gmxapi/#history>`_
+may include pre-release versions,
+but :command:`pip` will ignore them unless you use the ``--pre`` flag::
+
+ # Get the latest version, including pre-release versions.
+ pip install --pre gmxapi
+
If :command:`pip` does not find your GROMACS installation, use one of the following
environment variables to provide a hint.
You can also install the :py:mod:`gmxapi` Python package from within a local copy of
the GROMACS source repository. Assuming you have already obtained the GROMACS
source code and you are in the root directory of the source tree, you will find
-the :py:mod`gmxapi` Python package sources in the :file:`python_packaging/src` directory.
+the :py:mod:`gmxapi` Python package sources in the :file:`python_packaging/src` directory.
::
For example, the last line of the previous example could be replaced with::
- pip install --no-cache-dir --no-deps --no-index --no-build-isolation .
+ pip install --no-cache-dir --no-deps --no-index .
Refer to pip_ documentation for descriptions of these options.
-------------------------
A source archive for the gmxapi python package can be built from the GROMACS
-source repository using Python ``setuptools`` and ``scikit-build``.
+source repository using Python ``setuptools``.
Example::
- pip install --upgrade setuptools scikit-build
+ pip install --upgrade setuptools
cd python_packaging/src
python setup.py sdist
*<version>* is the version from the ``setup.py`` file, and *<suffix>* is
determined by the local environment or by additional arguments to ``setup.py``.
+The new `build <https://pypa-build.readthedocs.io/en/latest/>`__ module is somewhat tidier.
+It automatically manages a temporary venv with the necessary dependencies::
+
+ pip install --upgrade build
+ cd python_packaging/src
+ python -m build --sdist .
+
.. seealso::
Python documentation for
location in the build tree. Sphinx can then import the package to automatically
extract Python docstrings.
+Note that this is an entirely CMake-driven installation and Python dependencies
+will not be installed automatically. You can update your Python environment
+(before configuring with CMake) using the :file:`requirements.txt` files provided
+in the :file:`python_packaging/` directory of the repository. Example::
+
+ pip install -r python_packaging/requirements-docs.txt
+
+or
+
+::
+
+ pip install -r python_packaging/requirements-test.txt
+
Sometimes the build environment can choose a different Python interpreter than
the one you intended.
-You can set the ``Python3_ROOT`` or ``CMAKE_PREFIX_PATH`` CMake variable to
+You can set the ``Python3_ROOT_DIR`` or ``CMAKE_PREFIX_PATH`` CMake variable to
explicitly choose the Python installation or *venv* directory.
If you use pyenv or pyenv-virtualenv to dynamically manage your Python version,
you can help identify a particular version with ``pyenv version-name`` and the
directory with ``pyenv prefix {version}``. For example::
- -DPython3_ROOT=$(pyenv prefix $(pyenv version-name))
+ -DPython3_ROOT_DIR=$(pyenv prefix $(pyenv version-name))
Docker web server
-----------------
Document sample_restraint package. Reference issue
`3027 <https://gitlab.com/gromacs/gromacs/-/issues/3027>`_
+Testing
+=======
+
+Note `testing requirements`_ above.
+
+After installing the :py:mod:`gmxapi` Python package,
+you can run the Python test suite from the GROMACS source tree.
+Example::
+
+ # Assuming you are in the root directory of the repository:
+ pytest python_packaging/src/test/
+
+Refer to :file:`python_packaging/README.md` for more detailed information.
+
.. _gmxapi install troubleshooting:
Troubleshooting
===============
+AttributeError: module 'enum' has no attribute 'IntFlag'
+--------------------------------------------------------
+
+If you had older versions of some of the dependencies installed,
+you might have picked up a transitive dependency on the ``enum34`` package.
+Try::
+
+ pip uninstall -y enum34
+
+and see if that fixes the problem. If not, try a fresh virtual environment
+(see above) to help narrow down the problem before you
+`open an issue <https://gitlab.com/gromacs/gromacs/-/issues/>`_.
+
+Errors regarding pybind11
+-------------------------
+
+An error may occur in ``setup.py`` with output that contains something like the following::
+
+ ModuleNotFoundError: No module named 'pybind11'
+ Building wheel for gmxapi (pyproject.toml): finished with status 'error'
+ ERROR: Failed building wheel for gmxapi
+ Failed to build gmxapi
+ ERROR: Could not build wheels for gmxapi, which is required to install pyproject.toml-based projects
+
+The important information here is that ``pybind11`` was not found.
+
+Build dependencies aren't always automatically installed.
+Even if you are using ``pip``, you may have disabled automatic dependency fulfillment with an option like ``--no-build-isolation`` or ``--no-deps``.
+
+In any case, the problem should be resolved by explicitly installing the ``pybind11``
+Python package before attempting to build ``gmxapi``::
+
+ pip install --upgrade pybind11
+
Couldn't find the ``gmxapi`` support library?
+---------------------------------------------
+
If you don't want to "source" your :ref:`GMXRC <getting access to |Gromacs|>` file, you
can tell the package where to find a gmxapi compatible GROMACS installation with
``gmxapi_DIR``. E.g. ``gmxapi_DIR=/path/to/gromacs pip install .``
.. _scikit-build: https://pypi.org/project/scikit-build/
.. _setuptools: https://pypi.org/project/setuptools/
+
+.. _wheel: https://pypi.org/project/wheel/