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


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.
  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, 10)
Package version; this is the only place where it is set.
  _have_g_commands = ['anadock', 'do_dssp', 'editconf', 'eneconv...
  _missing_g_commands = []
  anadock = <gromacs.tools.Anadock object at 0x14162b0>
  do_dssp = <gromacs.tools.Do_dssp object at 0x1416470>
  editconf = <gromacs.tools.Editconf object at 0x140efd0>
  eneconv = <gromacs.tools.Eneconv object at 0x1416270>
  g_anaeig = <gromacs.tools.G_anaeig object at 0x14167d0>
  g_analyze = <gromacs.tools.G_analyze object at 0x140ee50>
  g_angle = <gromacs.tools.G_angle object at 0x140e910>
  g_bond = <gromacs.tools.G_bond object at 0x1416190>
  g_bundle = <gromacs.tools.G_bundle object at 0x1416490>
  g_chi = <gromacs.tools.G_chi object at 0x1416990>
  g_cluster = <gromacs.tools.G_cluster object at 0x14165f0>
  g_clustsize = <gromacs.tools.G_clustsize object at 0x140e930>
  g_confrms = <gromacs.tools.G_confrms object at 0x140ed70>
  g_covar = <gromacs.tools.G_covar object at 0x14160f0>
  g_current = <gromacs.tools.G_current object at 0x140ec90>
  g_density = <gromacs.tools.G_density object at 0x1416a90>
  g_densmap = <gromacs.tools.G_densmap object at 0x1416070>
  g_dielectric = <gromacs.tools.G_dielectric object at 0x140ec50>
  g_dih = <gromacs.tools.G_dih object at 0x1416af0>
  g_dipoles = <gromacs.tools.G_dipoles object at 0x1416650>
  g_disre = <gromacs.tools.G_disre object at 0x140ee70>
  g_dist = <gromacs.tools.G_dist object at 0x140ead0>
  g_dyndom = <gromacs.tools.G_dyndom object at 0x140eeb0>
  g_enemat = <gromacs.tools.G_enemat object at 0x1416a30>
  g_energy = <gromacs.tools.G_energy object at 0x1416230>
  g_filter = <gromacs.tools.G_filter object at 0x140ebd0>
  g_gyrate = <gromacs.tools.G_gyrate object at 0x14160b0>
  g_h2order = <gromacs.tools.G_h2order object at 0x140eaf0>
  g_hbond = <gromacs.tools.G_hbond object at 0x1416890>
  g_helix = <gromacs.tools.G_helix object at 0x1416150>
  g_helixorient = <gromacs.tools.G_helixorient object at 0x1416050>
  g_lie = <gromacs.tools.G_lie object at 0x1416670>
  g_mdmat = <gromacs.tools.G_mdmat object at 0x1416210>
  g_mindist = <gromacs.tools.G_mindist object at 0x140e9b0>
  g_morph = <gromacs.tools.G_morph object at 0x1416950>
  g_msd = <gromacs.tools.G_msd object at 0x140edb0>
  g_nmeig = <gromacs.tools.G_nmeig object at 0x1416b70>
  g_nmens = <gromacs.tools.G_nmens object at 0x1416870>
  g_nmtraj = <gromacs.tools.G_nmtraj object at 0x140ecd0>
  g_order = <gromacs.tools.G_order object at 0x140eed0>
  g_polystat = <gromacs.tools.G_polystat object at 0x140ed30>
  g_potential = <gromacs.tools.G_potential object at 0x140ed10>
  g_principal = <gromacs.tools.G_principal object at 0x1416030>
  g_rama = <gromacs.tools.G_rama object at 0x14166d0>
  g_rdf = <gromacs.tools.G_rdf object at 0x1416330>
  g_rms = <gromacs.tools.G_rms object at 0x140eb30>
  g_rmsf = <gromacs.tools.G_rmsf object at 0x1416550>
  g_rotacf = <gromacs.tools.G_rotacf object at 0x14166b0>
  g_saltbr = <gromacs.tools.G_saltbr object at 0x14162f0>
  g_sas = <gromacs.tools.G_sas object at 0x140e9f0>
  g_sdf = <gromacs.tools.G_sdf object at 0x14164d0>
  g_sgangle = <gromacs.tools.G_sgangle object at 0x14164b0>
  g_sham = <gromacs.tools.G_sham object at 0x140ec70>
  g_sorient = <gromacs.tools.G_sorient object at 0x1416510>
  g_spatial = <gromacs.tools.G_spatial object at 0x140ebf0>
  g_spol = <gromacs.tools.G_spol object at 0x1416a50>
  g_tcaf = <gromacs.tools.G_tcaf object at 0x1416110>
  g_traj = <gromacs.tools.G_traj object at 0x1416730>
  g_vanhove = <gromacs.tools.G_vanhove object at 0x1416770>
  g_velacc = <gromacs.tools.G_velacc object at 0x140ec30>
  g_wham = <gromacs.tools.G_wham object at 0x1416570>
  genbox = <gromacs.tools.Genbox object at 0x140eb50>
  genconf = <gromacs.tools.Genconf object at 0x1416850>
  genion = <gromacs.tools.Genion object at 0x14168d0>
  genrestr = <gromacs.tools.Genrestr object at 0x1416910>
  gmxcheck = <gromacs.tools.Gmxcheck object at 0x140e7d0>
  gmxdump = <gromacs.tools.Gmxdump object at 0x14165b0>
  gridMAT_MD = <gromacs.tools.GridMAT_MD object at 0x140ea10>
  grompp = <gromacs.tools.Grompp object at 0x14163b0>
  less_important_warnings = ['AutoCorrectionWarning', 'UsageWarn...
  logger = log.create('gromacs', logfile= 'gromacs.log')
  luck = <gromacs.tools.Luck object at 0x14163d0>
  make_edi = <gromacs.tools.Make_edi object at 0x1416b30>
  make_ndx = <gromacs.tools.Make_ndx object at 0x1416a10>
  mdrun = <gromacs.tools.Mdrun object at 0x140ef10>
  mdrun_d = <gromacs.tools.Mdrun_d object at 0x140eab0>
  mk_angndx = <gromacs.tools.Mk_angndx object at 0x14161d0>
  pdb2gmx = <gromacs.tools.Pdb2gmx object at 0x140efb0>
  protonate = <gromacs.tools.Protonate object at 0x140ec10>
  sigeps = <gromacs.tools.Sigeps object at 0x140ea50>
  tpbconv = <gromacs.tools.Tpbconv object at 0x1416b50>
  trjcat = <gromacs.tools.Trjcat object at 0x140ef90>
  trjconv = <gromacs.tools.Trjconv object at 0x14163f0>
  trjorder = <gromacs.tools.Trjorder object at 0x140ee10>
  wheel = <gromacs.tools.Wheel object at 0x140edf0>
  x2top = <gromacs.tools.X2top object at 0x14167b0>
  xpm2ps = <gromacs.tools.Xpm2ps object at 0x14166f0>
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',
...

less_important_warnings

Value:
['AutoCorrectionWarning', 'UsageWarning']