gromacs – GromacsWrapper Package Overview

GromacsWrapper (package gromacs) is a thin shell around the Gromacs tools for light-weight integration into python scripts or interactive use in ipython.

Modules

gromacs

The top level module contains all gromacs tools; each tool can be run directly or queried for its documentation. It also defines the root logger class (name gromacs by default).

gromacs.config

Configuration options. Not really used much at the moment.

gromacs.cbook

The Gromacs cook book contains typical applications of the tools. In many cases this not more than just an often-used combination of parameters for a tool.

gromacs.tools

Contains classes that wrap the gromacs tools. They are automatically generated from the list of tools in gromacs.tools.gmx_tools.

gromacs.fileformats

Classes to represent data files in various formats such as xmgrace graphs. The classes allow reading and writing and for graphs, also plotting of the data.

gromacs.utilities

Convenience functions and mixin-classes that are used as helpers in other modules.

gromacs.setup

Functions to set up a MD simulation, containing tasks such as solvation and adding ions, energy minimizqtion, MD with position-restraints, and equilibrium MD.

gromacs.qsub

Functions to handle batch submission queuing systems.

gromacs.run

Classes to run mdrun in various way, including on multiprocessor systems.

gromacs.analysis

A package that collects whole analysis tasks. It uses the gromacs package but is otherwise only loosely coupled with the rest. At the moment it only contains the infrastructure and an example application. See the package documentation.

Examples

The following examples should simply convey the flavour of using the package. See the individual modules for more examples.

Getting help

In python:

gromacs.g_dist.help()
gromacs.g_dist.help(long=True)

In ipython:

gromacs.g_dist ?

Simple usage

Gromacs flags are given as python keyword arguments:

gromacs.g_dist(v=True, s='topol.tpr', f='md.xtc', o='dist.xvg', dist=1.2)

Input to stdin of the command can be supplied:

gromacs.make_ndx(f='topol.tpr', o='md.ndx',
                 input=('keep "SOL"', '"SOL" | r NA | r CL', 'name 2 solvent', 'q'))

Output of the command can be caught in a variable and analyzed:

rc, output, junk = gromacs.grompp(..., stdout=False)        # collects command output
for line in output.split('\n'):
    line = line.strip()
    if line.startswith('System has non-zero total charge:'):
          qtot = float(line[34:])
          break

(See gromacs.cbook.grompp_qtot() for a more robust implementation of this application.)

Warnings and Exceptions

A number of package-specific exceptions (GromacsError) and warnings (GromacsFailureWarning, GromacsImportWarning, GromacsValueWarning, AutoCorrectionWarning, BadParameterWarning) can be raised.

If you want to stop execution at, for instance, a AutoCorrectionWarning or BadParameterWarning then use the python warnings filter:

import warnings
warnings.simplefilter('error', gromacs.AutoCorrectionWarning)
warnings.simplefilter('error', gromacs.BadParameterWarning)

This will make python raise an exception instead of moving on. The default is to always report, eg:

warnings.simplefilter('always', gromacs.BadParameterWarning)

The following exceptions are defined:

exception gromacs.GromacsError

Error raised when a gromacs tool fails.

Returns error code in the errno attribute and a string in strerror. # TODO: return status code and possibly error message

exception gromacs.MissingDataError

Error raised when prerequisite data are not available.

For analysis with gromacs.analysis.core.Simulation this typically means that the analyze() method has to be run first.

exception gromacs.ParseError

Error raised when parsing of a file failed.

The following warnings are defined:

exception gromacs.GromacsFailureWarning

Warning about failure of a Gromacs tool.

exception gromacs.GromacsImportWarning

Warns about problems with using a gromacs tool.

exception gromacs.GromacsValueWarning

Warns about problems with the value of an option or variable.

exception gromacs.AutoCorrectionWarning

Warns about cases when the code is choosing new values automatically.

exception gromacs.BadParameterWarning

Warns if some parameters or variables are unlikely to be appropriate or correct.

exception gromacs.MissingDataWarning

Warns when prerequisite data/files are not available.

exception gromacs.UsageWarning

Warns if usage is unexpected/documentation ambiguous.

exception gromacs.LowAccuracyWarning

Warns that results may possibly have low accuracy.

Logging

The library uses python’s logging module to keep a history of what it has been doing. In particular, every wrapped Gromacs command logs its command line (including piped input) to the log file (configured in gromacs.config.logfilename). This facilitates debugging or simple re-use of command lines for very quick and dirty work. The logging facilty appends to the log file and time-stamps every entry. See gromacs.config for more details on configuration.

It is also possible to capture output from Gromacs commands in a file instead of displaying it on screen, as described under Input and Output.

Normally, one starts logging with the start_logging() function but in order to obtain logging messages (typically at level debug) right from the start one may set the environment variable GW_START_LOGGING to any value that evaluates to True (e.g., “True” or “1”).

Version

The package version can be queried with the gromacs.get_version() function.

gromacs.get_version()

Return current package version as a string.

gromacs.get_version_tuple()

Return current package version as a tuple (MAJOR, MINOR, PATCHLEVEL).

If the package was installed from a development version, the patch level will have the string “-dev” affixed to distinguish it from a release.