3. GromacsWrapper Overview
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).
Configuration options. Not really used much at the moment.
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.
Contains classes that wrap the gromacs tools. They are automatically generated from the list of tools in
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.
Convenience functions and mixin-classes that are used as helpers in other modules.
Functions to set up a MD simulation, containing tasks such as solvation and adding ions, energy minimizqtion, MD with position-restraints, and equilibrium MD.
Functions to handle batch submission queuing systems.
Classes to run mdrun in various way, including on multiprocessor systems.
The following examples should simply convey the flavour of using the package. See the individual modules for more examples.
3.2.1. Getting help
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
gromacs.cbook.grompp_qtot() for a more robust implementation of this
3.3. Warnings and Exceptions
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:
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.Simulationthis 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.
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
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”).
The package version is recorded in the
- gromacs.__version__ = '0.8.5+4.g1001a09.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.