Quick start¶
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.
Warning
This documentation is for gmxapi 0.0.7 on GROMACS 2019. For gmxapi 0.1 or later and GROMACS 2020 or later, refer to http://manual.gromacs.org/current/gmxapi/userguide/install.html
Quick start recipes
Please report bugs or updates at https://github.com/kassonlab/gmxapi/issues
Simple “pip” installation¶
In the simplest case, the following should just work:
git clone https://github.com/kassonlab/gmxapi.git
cd gmxapi
git checkout release-0_0_7
pip install -r requirements.txt
pip install .
cd
Note
The trailing .
after pip install
indicates to install from the
current directory.
pip
will need to be able to find a GROMACS 2019 installation with gmxapi
enabled. When building GROMACS, make sure to use the -DGMXAPI=ON
CMake
option. Then, make sure you tell pip
where to find the GROMACS installation
by setting 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 bash
shell:
source /path/to/gromacs/bin/GMXRC
Note
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
the --user
flag to pip install
.
Docker¶
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.
For a Jupyter notebook, launch docker run --rm -ti -p 8888:8888 gmxapi/sample_restraint
and point your browser at the URL that is displayed.
Then navigate to sample_restraint
-> examples
For a bash
shell, just run docker run --rm -ti gmxapi/sample_restraint bash
Singularity¶
Thanks to jmhays for contributing Singularity recipes.
singularity pull --name customname.img shub://jmhays/singularity-restrained-ensemble
See https://www.singularity-hub.org/collections/1825/usage for variants.
“User” installation¶
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 import gmx
.
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
Note
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,
do make -j8 install
.
Conda installation¶
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 conda
and 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
Minimal Ubuntu system set up example¶
This section attempts to document installation in a constrained and minimal environment, such as might be encountered in a container or testing system.
Before proceeding, consider whether an existing Docker or Singularity recipe may be sufficient for you.
The following is tested for Ubuntu 14 using the ubuntu/trusty
image from Docker Hub <hub.docker.com>
As root:
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.