gromacs – GromacsWrapper Package Overview — GromacsWrapper 0.4.0-dev documentation

### Navigation

- index
- modules |
- next |
- previous |
- GromacsWrapper 0.4.0-dev documentation »
- GromacsWrapper package »

# `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.formats`
  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:

    help(gromacs.g_dist)
    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.

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

### Navigation

- index
- modules |
- next |
- previous |
- GromacsWrapper 0.4.0-dev documentation »
- GromacsWrapper package »