Package gromacs
[hide private]
[frames] | no frames]

Package gromacs

source code


:mod:`gromacs` -- GromacsWrapper Package Overview
=================================================

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

.. _`Gromacs`: http://www.gromacs.org
.. _`ipython`: http://ipython.scipy.org


Modules
-------

:mod:`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).

:mod:`gromacs.config`
     Configuration options. Not really used much at the moment.

:mod:`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.

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

:mod:`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.

:mod:`gromacs.utilities`
     Convenience functions and mixin-classes that are used as helpers
     in other modules.

:mod:`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.

:mod:`gromacs.qsub`
     Functions to handle batch submission queuing systems.

:mod:`gromacs.run`
     Classes to run :program:`mdrun` in various way, including on
     multiprocessor systems.

:mod:`gromacs.analysis`
     A package that collects whole analysis tasks. It uses the gromacs 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 :func:`gromacs.cbook.grompp_qtot` for a more robust implementation of this
application.)


Warnings and Exceptions
-----------------------

A number of package-specific exceptions (:exc:`GromacsError`) and
warnings (:exc:`Gromacs*Warning`, :exc:`AutoCorrectionWarning`,
:exc:`BadParameterWarning`) can be raised.

If you want to stop execution at, for instance, a :exc:`AutoCorrectionWarning` or
:exc:`BadParameterWarning` then use the python :mod:`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:

.. autoexception:: GromacsError
.. autoexception:: MissingDataError
.. autoexception:: ParseError

The following *warnings* are defined:

.. autoexception:: GromacsFailureWarning
.. autoexception:: GromacsImportWarning
.. autoexception:: GromacsValueWarning
.. autoexception:: AutoCorrectionWarning
.. autoexception:: BadParameterWarning
.. autoexception:: MissingDataWarning
.. autoexception:: UsageWarning
.. autoexception:: LowAccuracyWarning


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
:data:`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 :mod:`gromacs.config`
for more details on configuration.

.. _logging: http://docs.python.org/library/logging.html

Version
-------

The package version can be queried with the :func:`gromacs.get_version` function.

.. autofunction:: get_version
.. autofunction:: get_version_tuple

Submodules [hide private]

Classes [hide private]
  AutoCorrectionWarning
Warns about cases when the code is choosing new values automatically.
  BadParameterWarning
Warns if some parameters or variables are unlikely to be appropriate or correct.
  GromacsError
Error raised when a gromacs tool fails.
  GromacsFailureWarning
Warning about failure of a Gromacs tool.
  GromacsImportWarning
Warns about problems with using a gromacs tool.
  GromacsValueWarning
Warns about problems with the value of an option or variable.
  LowAccuracyWarning
Warns that results may possibly have low accuracy.
  MissingDataError
Error raised when prerequisite data are not available.
  MissingDataWarning
Warns when prerequisite data/files are not available.
  NullHandler
  ParseError
Error raised when parsing of a file failed.
  UsageWarning
Warns if usage is unexpected/documentation ambiguous.
Functions [hide private]
 
disable_gromacs_warnings(categories=None)
Disable ("ignore") specified warnings from the gromacs package.
source code
 
enable_gromacs_warnings(categories=None)
Enable ("always") specified warnings from the gromacs package.
source code
 
filter_gromacs_warnings(action, categories=None)
Set the :meth:`warnings.simplefilter` to *action*.
source code
 
get_version()
Return current package version as a string.
source code
 
get_version_tuple()
Return current package version as a tuple (MAJOR, MINOR, PATCHLEVEL).
source code
Variables [hide private]
  VERSION = (0, 1, 12)
Package version; this is the only place where it is set.
  __warningregistry__ = {}
  _have_g_commands = ['anadock', 'do_dssp', 'editconf', 'eneconv...
  _missing_g_commands = ['a_gridcalc', 'a_ri3dc', 'g_count', 'g_...
  anadock = <gromacs.tools.Anadock object at 0x1417670>
  do_dssp = <gromacs.tools.Do_dssp object at 0x1417fd0>
  editconf = <gromacs.tools.Editconf object at 0x14179f0>
  eneconv = <gromacs.tools.Eneconv object at 0x1417b30>
  g_anaeig = <gromacs.tools.G_anaeig object at 0x1417230>
  g_analyze = <gromacs.tools.G_analyze object at 0x14175b0>
  g_angle = <gromacs.tools.G_angle object at 0x14170f0>
  g_bond = <gromacs.tools.G_bond object at 0x1417950>
  g_bundle = <gromacs.tools.G_bundle object at 0x1417f50>
  g_chi = <gromacs.tools.G_chi object at 0x141f170>
  g_cluster = <gromacs.tools.G_cluster object at 0x1417cb0>
  g_clustsize = <gromacs.tools.G_clustsize object at 0x1417bb0>
  g_confrms = <gromacs.tools.G_confrms object at 0x1417610>
  g_covar = <gromacs.tools.G_covar object at 0x1417830>
  g_current = <gromacs.tools.G_current object at 0x14174d0>
  g_density = <gromacs.tools.G_density object at 0x14172f0>
  g_densmap = <gromacs.tools.G_densmap object at 0x1417050>
  g_dielectric = <gromacs.tools.G_dielectric object at 0x14170b0>
  g_dih = <gromacs.tools.G_dih object at 0x141f030>
  g_dipoles = <gromacs.tools.G_dipoles object at 0x1417c10>
  g_disre = <gromacs.tools.G_disre object at 0x1417570>
  g_dist = <gromacs.tools.G_dist object at 0x1417db0>
  g_dyndom = <gromacs.tools.G_dyndom object at 0x141f0f0>
  g_enemat = <gromacs.tools.G_enemat object at 0x14172b0>
  g_energy = <gromacs.tools.G_energy object at 0x1417b50>
  g_filter = <gromacs.tools.G_filter object at 0x1411df0>
  g_gyrate = <gromacs.tools.G_gyrate object at 0x1411f10>
  g_h2order = <gromacs.tools.G_h2order object at 0x14177d0>
  g_hbond = <gromacs.tools.G_hbond object at 0x1417690>
  g_helix = <gromacs.tools.G_helix object at 0x1417a30>
  g_helixorient = <gromacs.tools.G_helixorient object at 0x1411f30>
  g_lie = <gromacs.tools.G_lie object at 0x1417bd0>
  g_mdmat = <gromacs.tools.G_mdmat object at 0x1417ab0>
  g_mindist = <gromacs.tools.G_mindist object at 0x1417890>
  g_morph = <gromacs.tools.G_morph object at 0x141f130>
  g_msd = <gromacs.tools.G_msd object at 0x14174f0>
  g_nmeig = <gromacs.tools.G_nmeig object at 0x1417350>
  g_nmens = <gromacs.tools.G_nmens object at 0x1411db0>
  g_nmtraj = <gromacs.tools.G_nmtraj object at 0x1417910>
  g_order = <gromacs.tools.G_order object at 0x1417f90>
  g_polystat = <gromacs.tools.G_polystat object at 0x1417ed0>
  g_potential = <gromacs.tools.G_potential object at 0x1417e10>
  g_principal = <gromacs.tools.G_principal object at 0x1417630>
  g_rama = <gromacs.tools.G_rama object at 0x1417190>
  g_rdf = <gromacs.tools.G_rdf object at 0x14176d0>
  g_rms = <gromacs.tools.G_rms object at 0x1417450>
  g_rmsf = <gromacs.tools.G_rmsf object at 0x141f1b0>
  g_rotacf = <gromacs.tools.G_rotacf object at 0x1417d30>
  g_saltbr = <gromacs.tools.G_saltbr object at 0x1417f70>
  g_sas = <gromacs.tools.G_sas object at 0x1417870>
  g_sdf = <gromacs.tools.G_sdf object at 0x1417750>
  g_sgangle = <gromacs.tools.G_sgangle object at 0x14171d0>
  g_sham = <gromacs.tools.G_sham object at 0x1417270>
  g_sorient = <gromacs.tools.G_sorient object at 0x141f1f0>
  g_spatial = <gromacs.tools.G_spatial object at 0x14026b0>
  g_spol = <gromacs.tools.G_spol object at 0x1417d10>
  g_tcaf = <gromacs.tools.G_tcaf object at 0x1417390>
  g_traj = <gromacs.tools.G_traj object at 0x14177f0>
  g_vanhove = <gromacs.tools.G_vanhove object at 0x1417c90>
  g_velacc = <gromacs.tools.G_velacc object at 0x1417990>
  g_wham = <gromacs.tools.G_wham object at 0x1417cd0>
  genbox = <gromacs.tools.Genbox object at 0x1417410>
  genconf = <gromacs.tools.Genconf object at 0x141f0d0>
  genion = <gromacs.tools.Genion object at 0x1417210>
  genrestr = <gromacs.tools.Genrestr object at 0x1411eb0>
  gmxcheck = <gromacs.tools.Gmxcheck object at 0x1417510>
  gmxdump = <gromacs.tools.Gmxdump object at 0x1417770>
  gridMAT_MD = <gromacs.tools.GridMAT_MD object at 0x1417b90>
  grompp = <gromacs.tools.Grompp object at 0x1417110>
  less_important_warnings = ['AutoCorrectionWarning', 'UsageWarn...
  logger = log.create('gromacs', logfile= 'gromacs.log')
  luck = <gromacs.tools.Luck object at 0x1417a70>
  make_edi = <gromacs.tools.Make_edi object at 0x1417d70>
  make_ndx = <gromacs.tools.Make_ndx object at 0x141f0b0>
  mdrun = <gromacs.tools.Mdrun object at 0x14175d0>
  mdrun_d = <gromacs.tools.Mdrun_d object at 0x14173d0>
  mk_angndx = <gromacs.tools.Mk_angndx object at 0x1417af0>
  pdb2gmx = <gromacs.tools.Pdb2gmx object at 0x14179d0>
  protonate = <gromacs.tools.Protonate object at 0x1411e10>
  sigeps = <gromacs.tools.Sigeps object at 0x1411d10>
  tpbconv = <gromacs.tools.Tpbconv object at 0x1417330>
  trjcat = <gromacs.tools.Trjcat object at 0x1411e50>
  trjconv = <gromacs.tools.Trjconv object at 0x1417150>
  trjorder = <gromacs.tools.Trjorder object at 0x1417590>
  wheel = <gromacs.tools.Wheel object at 0x1417e90>
  x2top = <gromacs.tools.X2top object at 0x1417eb0>
  xpm2ps = <gromacs.tools.Xpm2ps object at 0x1417c70>
Function Details [hide private]

disable_gromacs_warnings(categories=None)

source code 

Disable ("ignore") specified warnings from the gromacs package.

categories must be a list of warning classes or strings. None selects the defaults.

enable_gromacs_warnings(categories=None)

source code 
Enable ("always") specified warnings from the gromacs package.

*categories* must be a list of warning classes or strings.
``None`` selects the defaults, :data:`gromacs._less_important_warnings`.

filter_gromacs_warnings(action, categories=None)

source code 
Set the :meth:`warnings.simplefilter` to *action*.

*categories* must be a list of warning classes or strings.
``None`` selects the defaults,  :data:`gromacs.less_important_warnings`.


Variables Details [hide private]

_have_g_commands

Value:
['anadock',
 'do_dssp',
 'editconf',
 'eneconv',
 'g_anaeig',
 'g_analyze',
 'g_angle',
 'g_bond',
...

_missing_g_commands

Value:
['a_gridcalc', 'a_ri3dc', 'g_count', 'g_flux', 'g_ri3dc', 'g_zcoord']

less_important_warnings

Value:
['AutoCorrectionWarning', 'UsageWarning']