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 an mpiexec -n prefix?

• Answer: That’s not directly supported but if you just want to change how mdrun is launched then you can create a custom MDrunner 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)

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.

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)

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)

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

signal_handler(signum, frame)

Custom signal handler for SIGINT.

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.

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

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)

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)

posthook(**kwargs)

Shut down smpd

prehook(**kwargs)

Launch local smpd.

5.2.5.4. 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:

logfilefilename

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