The gmxapi project provides interfaces for managing and extending molecular
dynamics simulation workflows. In this repository, a Python package provides the
gmx
module for high-level interaction with GROMACS via gmxapi 0.0.7.
gmx.core
provides Python bindings to the gmxapi
C++ GROMACS external API.
The gmxapi 0.0.7 Python project for GROMACS 2019 is hosted at
GitHub
and includes the gmxapi
repository along with supporting respositories.
(For current version, see GROMACS 2020+ or the
latest work
from the Kasson Lab.)
A sample repository illustrates how to implement a GROMACS plugin that applies restrained-ensemble forces to a loosely-coupled ensemble of simulation trajectories.
The whole thing is driven at the highest level by a simple Python interface.
See the version 0.0.7 documentation or the latest documentation at http://gmxapi.readthedocs.io/
Note that gmxapi is now (after 0.0.7) maintained as part of the GROMACS project.
Irrgang, M. E., Hays, J. M., & Kasson, P. M. gmxapi: a high-level interface for advanced control and extension of molecular dynamics simulations. Bioinformatics 2018. DOI: 10.1093/bioinformatics/bty484
To run a simulation as you would with the gmx
command-line tool, a gmxapi
Python script would look simply like the following.
import gmx
md = gmx.workflow.from_tpr('myTPRfile.tpr')
gmx.run(md)
With a plugin, such as the sample ensemble-restraint, you can
run a coupled ensemble of simulations that collectively refine a bias potential.
Assuming tpr_list
is a Python list of input files defining the ensemble, and
params
is a Python dictionary of keyword arguments,
import gmx
import myplugin
md = gmx.workflow.from_tpr(tpr_list)
potential = gmx.workflow.WorkElement(
namespace="myplugin",
operation="ensemble_restraint",
depends=[],
params=params)
potential.name = "ensemble_restraint_1"
md.add_dependency(potential)
gmx.run(md)
Currently, given an MPI environment, gmxapi would run the above workflow on a
number of nodes equal to the length of the tpr_list
array, parallelizing each
simulation across a single node, periodically sharing data via MPI calls across
the ensemble.
Many more features and more flexibility are still to come. Feel free to make suggestions or describe your own priorities and research needs in the issue tracking system.
GROMACS 2019 with
GMXAPI=ON
must be installed before building the Python package.
We recommend installing gmxapi in a Python virtual environment. See docs/install.rst for details or refer to the online user documentation.