Using the Python package¶
The primary user interface provided through gmxapi
is a Python module
called gmx
. The interface is designed to be maximally portable to different
execution environments, with an API that can be used and extended from Python or
C++.
For full documentation of the Python-level interface and API, use the pydoc
command line tool or the help()
interactive Python function, or refer to
the Procedural interface documentation.
Once the gmxapi
package is installed, running simulations is easy with gmx.workflow.from_tpr()
and
gmx.run()
.:
import gmx
md = gmx.workflow.from_tpr(tpr_filename)
gmx.run(md)
To run a batch of simulations, just pass an array of inputs.:
import gmx
md = gmx.workflow.from_tpr([tpr_filename1, tpr_filename2, ...])
gmx.run(md)
If additional arguments need to be provided to the simulation as they would for
the mdrun
command line tool, you can add them to the workflow specification
when you create the MD work element.:
md = gmx.workflow.from_tpr(tpr_list,
tmpi=20,
grid=[3, 3, 2],
pme_threads_per_rank=1,
pme_ranks=2,
threads_per_rank=1)
Python does not wrap a command-line tool, so once installation is complete,
there shouldn’t be any additional configuration necessary, and any errors that
occur should be caught at the Python level. Exceptions should all be descendants
of gmx.exceptions.Error
.
If you have written plugins or if you have downloaded and built the
sample plugin, you attach it
to your workflow by making it a dependency of the MD element. You can use the
add_dependency()
member function
of the gmx.workflow.WorkElement
returned by from_tpr()
. The following
example applies a harmonic spring restraint between atoms 1 and 4:
import gmx
import myplugin
assert gmx.version.is_at_least(0,0,6)
md = gmx.workflow.from_tpr([tpr_filename])
params = {'sites': [1, 4],
'R0': 2.0,
'k': 10000.0}
potential_element = gmx.workflow.WorkElement(namespace="myplugin",
operation="create_restraint",
params=params)
potential_element.name = "harmonic_restraint"
md.add_dependency(potential_element)
gmx.run(md)
Refer to the sample plugin for an additional example of an ensemble-restraint biasing potential that accumulates statistics from several trajectories in parallel to refine a pair restraint to bias for a target distribution.