This document provides simple recipes for some specific installation scenarios. Refer to Full installation instructions for complete documentation about prerequisites and building from source code.
Quick start recipes
Please report bugs or updates at https://github.com/kassonlab/gmxapi/issues
In the simplest case, the following should just work:
git clone https://github.com/kassonlab/gmxapi.git cd gmxapi pip install -r requirements.txt pip install . cd
pip install indicates to install from the
pip will need to be able to find a GROMACS 2019 installation with gmxapi
enabled. When building GROMACS, make sure to use the
option. Then, make sure you tell
pip where to find the GROMACS installation
gmxapi_DIR or just “source”ing the
GMXRC file, as usual.
If you install to the directory
/path/to/gromacs, then you should have a
/path/to/gromacs/bin/GMXRC configuration script that you would normally run
or source before using
gmx command line tools. Do that first.
E.g. for the
We recommend installing in a Python virtual environment. If not using a venv
you can tell
pip to install the package to your home directory by including
--user flag to
Check out our pre-built Docker images for a quick look at gmxapi or as a starting point for simulations in containers.
The Dockerfile recipes may also be useful references when building the software.
Docker images are based on the Jupyter Docker Stacks.
bash shell, just run
docker run --rm -ti gmxapi/sample_restraint bash
singularity pull --name customname.img shub://jmhays/singularity-restrained-ensemble
See https://www.singularity-hub.org/collections/1825/usage for variants.
In the simplest case, if dependencies are already installed and you have an
appropriate Python installation on your default PATH, something like the
following should just work. This will install the
gmx Python package into
the default “user site-packages” directory for the Python installation you are
using so that you can just run Python normally and
wget https://github.com/gromacs/gromacs/archive/release-2019.zip unzip release-2019.zip mkdir gromacs-build pushd gromacs-build cmake ../gromacs-release-2019 -DGMXAPI=ON -DCMAKE_INSTALL_PREFIX=$HOME/gromacs make install popd source $HOME/gromacs/bin/GMXRC wget https://github.com/kassonlab/gmxapi/archive/release-0_0_7.zip unzip release_0_0_7.zip mkdir gmxapi-build pushd gmxapi-build cmake ../gmxapi-release-0_0_7 -DGMXAPI_USER_INSTALL=ON make install popd
If your computer has more resources available, you can try to speed up the
build by telling
make to run in parallel. To use 8 threads, for instance,
make -j8 install.
gmxapi does not provide a Conda binary package, but the following documentation may work to prepare a Conda environment for gmxapi.
Get and install Anaconda.
Alternatively, on an HPC system
an Anaconda installation may already be provided with a
module system. For example:
module load gcc module load cmake module load anaconda3 module load openmpi
You don’t have to follow all of the instructions for setting up your login profile if you don’t want to,
but if you don’t, then the
activate commands below will have to be prefixed by your
conda installation location. E.g.
~/miniconda3/bin/conda info or
source ~/miniconda3/bin/activate myEnv
Create a conda virtual environment. Replace
myEnv below with whatever convenient name you choose.
conda create -n myGmxapiEnv python=3 pip setuptools cmake networkx mpi4py
Activate, or enter the environment.
source activate myGmxapiEnv
Install the GROMACS gmxapi fork.
git clone https://github.com/kassonlab/gromacs-gmxapi.git gromacs mkdir build cd build cmake ../gromacs -DGMX_GPU=OFF -DGMX_THREAD_MPI=ON -DCMAKE_CXX_COMPILER=`which g++` -DCMAKE_C_COMPILER=`which gcc` -DCMAKE_INSTALL_PREFIX=$HOME/gromacs-gmxapi make -j12 && make install source $HOME/gromacs-gmxapi/bin/GMXRC
Make sure dependencies are up to date.
MPICC=`which mpicc` pip install --upgrade mpi4py
Install the Python module.
git clone https://github.com/kassonlab/gmxapi.git gmxapi cd gmxapi mkdir build cd build cmake .. make install
This section attempts to document installation in a constrained and minimal environment, such as might be encountered in a container or testing system.
The following is tested for Ubuntu 14 using the
ubuntu/trusty image from Docker Hub <hub.docker.com>
apt-get update apt-get install software-properties-common apt-add-repository -y "ppa:ubuntu-toolchain-r/test" apt-get update apt-get -yq --no-install-suggests --no-install-recommends install \ cmake \ cmake-data \ libblas-dev \ libcr-dev \ libfftw3-dev \ liblapack-dev \ libmpich-dev \ libxml2-dev \ make \ mpich \ zlib1g-dev # You probably want one or two more packages for convenience. For example: apt-get -yq --no-install-suggests --no-install-recommends install \ git vim wget git
To manage Python installations, you could either use the native package manager,
or something like
pyenv (see below). In Ubuntu 14, the following packages
should be sufficient.
apt-get install python python-dev python3 python3-dev
For additional ideas, take a look at our Docker recipes or our
.travis.yml Travis-CI configuration.