gromacs.run – Running simulations

Helper functions and classes around gromacs.tools.Mdrun.

class gromacs.run.MDrunner(dirname='.', **kwargs)

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 the mdrun executable
  • MDrunner.mpiexec with the path to the MPI launcher
  • MDrunner.mpicommand() with a function that returns the mpi command as a list

In addition there are two methods named prehook() and posthook() 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 in mdrun that can be found on the PATH is chosen (with find_gromacs_command()). For example, gmx mdrun from Gromacs 5.x but just mdrun 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()

Check if mdrun finished successfully.

(See check_mdrun_success() for details)

commandline(**mpiargs)

Returns simple command line to invoke mdrun.

If mpiexec is set then mpicommand() provides the mpi launcher command that prefixes the actual mdrun invocation:

mpiexec [mpiargs] mdrun [mdrun-args]

The mdrun-args are set on initializing the class. Override mpicommand() to fit your system if the simple default OpenMP launcher is not appropriate.

mpicommand(*args, **kwargs)

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.)

posthook(**kwargs)

Called directly after the process terminated (also if it failed).

prehook(**kwargs)

Called directly before launching the process.

run(pre=None, post=None, mdrunargs=None, **mpiargs)

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)

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 successfully
  • False otherwise
class gromacs.run.MDrunnerDoublePrecision(dirname='.', **kwargs)

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.

Example implementations

class gromacs.run.MDrunnerOpenMP(dirname='.', **kwargs)

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.
class gromacs.run.MDrunnerMpich2Smpd(dirname='.', **kwargs)

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.

Helper functions

gromacs.run.check_mdrun_success(logfile)

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:
logfile : filename

Logfile produced by mdrun.
Returns:

True if all ok, False if not finished, and None if the logfile cannot be opened
gromacs.run.get_double_or_single_prec_mdrun()

Return double precision mdrun or fall back to single precision.

This convenience function tries gromacs.mdrun_d() first and if it cannot run it, falls back to gromacs.mdrun() (without further checking).

New in version 0.5.1.

gromacs.run.find_gromacs_command(commands)

Return driver and name of the first command that can be found on PATH