5.2.5. gromacs.run
– Running simulations¶
The gromacs.run
module contains tools for launching a Gromacs MD
simulation with gmx mdrun. The basic tool is the MDrunner
class that customizes how mdrun
is actually
called. It enables setting a driver such as mpiexec for launching
MPI-enabled runs. The Example: How to create your own MDrunner with mpiexec -n should make clearer what one
needs to do.
Additionally, Helper functions are provided to check and manage MD runs.
5.2.5.1. Example: How to create your own MDrunner with mpiexec -n
¶
Question: How do I change the GromacsWrapper configuration file so that
mdrun
gets called with anmpiexec -n
prefix?Answer: That’s not directly supported but if you just want to change how
mdrun
is launched then you can create a customMDrunner
for this purpose.
In many cases, you really only need the path to mpiexec and then you
can just derive your own class MDrunnerMPI
:
import gromacs.run
class MDrunnerMPI(gromacs.run.MDrunner):
"""Manage running :program:`mdrun` as an MPI multiprocessor job."""
mdrun = "gmx_mpi mdrun"
mpiexec = "/opt/local/bin/mpiexec"
The full path to the MPI runner mpiexec (or mpirun) is
stored in the class attribute MDrunnerMPI.mpiexec
.
This class can then be used as
mdrun_mpi = MDrunnerMPI(s="md.tpr", deffnm="md")
rc = mdrun_mpi.run(ncores=16)
Our MDrunnerMPI
only supports running mpiexec -n ncores
gmx mdrun ...
, i.e., only the -n ncores
arguments for mpiexec
is supported. If you need more functionality then you need write your own
MDrunner.mpicommand()
method, which you would add to your own
MDrunnerMPI
class.
The included MDrunnerOpenMP
could be used instead of our own
MDrunnerMPI
; the only difference is that multiple names of MPI-enabled
mdrun
binaries are stored as a tuple in the attribute
MDrunnerOpenMP.mdrun
so that the class works for old Gromacs 4.x and
modern Gromacs ≥ 2016.
If you need to run some code before or after launching you can add it as the
MDrunnerMPI.prehook()
and MDrunnerMPI.posthook()
methods as shown
in MDrunnerMpich2Smpd
.
5.2.5.2. MDrunner¶
The MDrunner
wraps gromacs.tools.Mdrun
to customize launching
a Gromacs MD simulation from inside the Python interpreter.
- class gromacs.run.MDrunner(dirname='.', **kwargs)[source]¶
A class to manage running mdrun in various ways.
In order to do complicated multiprocessor runs with mpiexec or similar you need to derive from this class and override
MDrunner.mdrun
with the path to themdrun
executableMDrunner.mpiexec
with the path to the MPI launcherMDrunner.mpicommand()
with a function that returns the mpi command as a list
In addition there are two methods named
prehook()
andposthook()
that are called right before and after the process is started. If they are overriden appropriately then they can be used to set up a mpi environment.The
run()
method can take arguments for the mpiexec launcher but it can also be used to supersede the arguments for mdrun.The actual mdrun command is set in the class-level attribute
mdrun
. This can be a single string or a sequence (tuple) of strings. On instantiation, the first entry inmdrun
that can be found on thePATH
is chosen (withfind_gromacs_command()
). For example,gmx mdrun
from Gromacs 5.x but justmdrun
for Gromacs 4.6.x. Similarly, alternative executables (such as double precision) need to be specified here (e.g.("mdrun_d", "gmx_d mdrun")
).Note
Changing mdrun arguments permanently changes the default arguments for this instance of
MDrunner
. (This is arguably a bug.)Changed in version 0.5.1: Added detection of bare Gromacs commands (Gromacs 4.6.x) or commands run through gmx (Gromacs 5.x).
Changed in version 0.6.0: Changed syntax for Gromacs 5.x commands.
Set up a simple run with
mdrun
.- Keywords:
- dirname
Change to this directory before launching the job. Input files must be supplied relative to this directory.
- keywords
All other keword arguments are used to construct the
mdrun
commandline. Note that only keyword arguments are allowed.
- check_success()[source]¶
Check if mdrun finished successfully.
(See
check_mdrun_success()
for details)
- commandline(**mpiargs)[source]¶
Returns simple command line to invoke mdrun.
If
mpiexec
is set thenmpicommand()
provides the mpi launcher command that prefixes the actualmdrun
invocation:The mdrun-args are set on initializing the class. Override
mpicommand()
to fit your system if the simple default OpenMP launcher is not appropriate.
- mdrun = ('mdrun', 'gmx mdrun')¶
Path to the mdrun executable (or the name if it can be found on
PATH
); this can be a tuple and then the program names are tried in sequence. For Gromacs 5 prefix with the driver command, e.g.,gmx mdrun
.New in version 0.5.1.
- mpicommand(*args, **kwargs)[source]¶
Return a list of the mpi command portion of the commandline.
- Only allows primitive mpi at the moment:
mpiexec -n ncores mdrun mdrun-args
(This is a primitive example for OpenMP. Override it for more complicated cases.)
- mpiexec = None¶
path to the MPI launcher (e.g. mpiexec)
- run(pre=None, post=None, mdrunargs=None, **mpiargs)[source]¶
Execute the mdrun command (possibly as a MPI command) and run the simulation.
- Keywords:
- pre
a dictionary containing keyword arguments for the
prehook()
- post
a dictionary containing keyword arguments for the
posthook()
- mdrunargs
a dictionary with keyword arguments for mdrun which supersede and update the defaults given to the class constructor
- mpiargs
all other keyword arguments that are processed by
mpicommand()
- run_check(**kwargs)[source]¶
Run mdrun and check if run completed when it finishes.
This works by looking at the mdrun log file for ‘Finished mdrun on node’. It is useful to implement robust simulation techniques.
- Arguments:
kwargs are keyword arguments that are passed on to
run()
(typically used for mpi things)- Returns:
True
if run completed successfullyFalse
otherwise
- class gromacs.run.MDrunnerDoublePrecision(dirname='.', **kwargs)[source]¶
Manage running mdrun_d.
Set up a simple run with
mdrun
.- Keywords:
- dirname
Change to this directory before launching the job. Input files must be supplied relative to this directory.
- keywords
All other keword arguments are used to construct the
mdrun
commandline. Note that only keyword arguments are allowed.
5.2.5.3. Example implementations¶
- class gromacs.run.MDrunnerOpenMP(dirname='.', **kwargs)[source]¶
Manage running mdrun as an OpenMP multiprocessor job.
Set up a simple run with
mdrun
.- Keywords:
- dirname
Change to this directory before launching the job. Input files must be supplied relative to this directory.
- keywords
All other keword arguments are used to construct the
mdrun
commandline. Note that only keyword arguments are allowed.
- mdrun = ('mdrun_openmp', 'gmx_openmp mdrun')¶
Path to the mdrun executable (or the name if it can be found on
PATH
); this can be a tuple and then the program names are tried in sequence. For Gromacs 5 prefix with the driver command, e.g.,gmx mdrun
.New in version 0.5.1.
- mpiexec = 'mpiexec'¶
path to the MPI launcher (e.g. mpiexec)
- class gromacs.run.MDrunnerMpich2Smpd(dirname='.', **kwargs)[source]¶
Manage running mdrun as mpich2 multiprocessor job with the SMPD mechanism.
Set up a simple run with
mdrun
.- Keywords:
- dirname
Change to this directory before launching the job. Input files must be supplied relative to this directory.
- keywords
All other keword arguments are used to construct the
mdrun
commandline. Note that only keyword arguments are allowed.
- mdrun = 'mdrun_mpich2'¶
Path to the mdrun executable (or the name if it can be found on
PATH
); this can be a tuple and then the program names are tried in sequence. For Gromacs 5 prefix with the driver command, e.g.,gmx mdrun
.New in version 0.5.1.
- mpiexec = 'mpiexec'¶
path to the MPI launcher (e.g. mpiexec)
5.2.5.4. Helper functions¶
- gromacs.run.check_mdrun_success(logfile)[source]¶
Check if
mdrun
finished successfully.Analyses the output from
mdrun
in logfile. Right now we are simply looking for the line “Finished mdrun on node” in the last 1kb of the file. (The file must be seeakable.)- Arguments:
- logfilefilename
Logfile produced by
mdrun
.
- Returns:
True
if all ok,False
if not finished, andNone
if the logfile cannot be opened