3. GromacsWrapper Overview

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

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

3.2. Examples

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

3.2.1. Getting help

In python:

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

In ipython:

gromacs.g_dist ?

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

3.3. 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[source]

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[source]

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[source]: Error raised when parsing of a file failed.

The following warnings are defined:

exception gromacs.GromacsFailureWarning[source]: Warning about failure of a Gromacs tool.

exception gromacs.GromacsImportWarning[source]: Warns about problems with using a gromacs tool.

exception gromacs.GromacsValueWarning[source]: Warns about problems with the value of an option or variable.

exception gromacs.AutoCorrectionWarning[source]: Warns about cases when the code is choosing new values automatically.

exception gromacs.BadParameterWarning[source]: Warns if some parameters or variables are unlikely to be appropriate or correct.

exception gromacs.MissingDataWarning[source]: Warns when prerequisite data/files are not available.

exception gromacs.UsageWarning[source]: Warns if usage is unexpected/documentation ambiguous.

exception gromacs.LowAccuracyWarning[source]: Warns that results may possibly have low accuracy.

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

3.5. Version

The package version is recorded in the gromacs.__version__ variable.

gromacs.__version__ = '0.8.5+23.g463820c.dirty'

Version of the package, following semantic versioning in the form MAJOR.MINOR.PATCH. When PATCH increases, bugs are fixed or documentation or metadata are updated. Increases in MINOR can introduce new features and deprecate old code. API-breaking and backwards incompatible changes can only occur when MAJOR is increased, except during initial development while MAJOR == 0, in which also increases in MINOR may (rarely) introduce breaking changes.

Additional information after PATCH indicates that you are working with an unreleased version, with the number of git commits after the release and the commit ID encoded in the trailing string.