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

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
Variables [hide private]
  VERSION = '0.1.9'
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 0x1420270>
  do_dssp = <gromacs.tools.Do_dssp object at 0x1420430>
  editconf = <gromacs.tools.Editconf object at 0x1416f90>
  eneconv = <gromacs.tools.Eneconv object at 0x1420230>
  g_anaeig = <gromacs.tools.G_anaeig object at 0x1420790>
  g_analyze = <gromacs.tools.G_analyze object at 0x1416e10>
  g_angle = <gromacs.tools.G_angle object at 0x14168d0>
  g_bond = <gromacs.tools.G_bond object at 0x1420150>
  g_bundle = <gromacs.tools.G_bundle object at 0x1420450>
  g_chi = <gromacs.tools.G_chi object at 0x1420950>
  g_cluster = <gromacs.tools.G_cluster object at 0x14205b0>
  g_clustsize = <gromacs.tools.G_clustsize object at 0x14168f0>
  g_confrms = <gromacs.tools.G_confrms object at 0x1416d30>
  g_covar = <gromacs.tools.G_covar object at 0x14200b0>
  g_current = <gromacs.tools.G_current object at 0x1416c50>
  g_density = <gromacs.tools.G_density object at 0x1420a50>
  g_densmap = <gromacs.tools.G_densmap object at 0x1420030>
  g_dielectric = <gromacs.tools.G_dielectric object at 0x1416c10>
  g_dih = <gromacs.tools.G_dih object at 0x1420ab0>
  g_dipoles = <gromacs.tools.G_dipoles object at 0x1420610>
  g_disre = <gromacs.tools.G_disre object at 0x1416e30>
  g_dist = <gromacs.tools.G_dist object at 0x1416a90>
  g_dyndom = <gromacs.tools.G_dyndom object at 0x1416e70>
  g_enemat = <gromacs.tools.G_enemat object at 0x14209f0>
  g_energy = <gromacs.tools.G_energy object at 0x14201f0>
  g_filter = <gromacs.tools.G_filter object at 0x1416b90>
  g_gyrate = <gromacs.tools.G_gyrate object at 0x1420070>
  g_h2order = <gromacs.tools.G_h2order object at 0x1416ab0>
  g_hbond = <gromacs.tools.G_hbond object at 0x1420850>
  g_helix = <gromacs.tools.G_helix object at 0x1420110>
  g_helixorient = <gromacs.tools.G_helixorient object at 0x1416ff0>
  g_lie = <gromacs.tools.G_lie object at 0x1420630>
  g_mdmat = <gromacs.tools.G_mdmat object at 0x14201d0>
  g_mindist = <gromacs.tools.G_mindist object at 0x1416970>
  g_morph = <gromacs.tools.G_morph object at 0x1420910>
  g_msd = <gromacs.tools.G_msd object at 0x1416d70>
  g_nmeig = <gromacs.tools.G_nmeig object at 0x1420b30>
  g_nmens = <gromacs.tools.G_nmens object at 0x1420830>
  g_nmtraj = <gromacs.tools.G_nmtraj object at 0x1416c90>
  g_order = <gromacs.tools.G_order object at 0x1416e90>
  g_polystat = <gromacs.tools.G_polystat object at 0x1416cf0>
  g_potential = <gromacs.tools.G_potential object at 0x1416cd0>
  g_principal = <gromacs.tools.G_principal object at 0x1416fd0>
  g_rama = <gromacs.tools.G_rama object at 0x1420690>
  g_rdf = <gromacs.tools.G_rdf object at 0x14202f0>
  g_rms = <gromacs.tools.G_rms object at 0x1416af0>
  g_rmsf = <gromacs.tools.G_rmsf object at 0x1420510>
  g_rotacf = <gromacs.tools.G_rotacf object at 0x1420670>
  g_saltbr = <gromacs.tools.G_saltbr object at 0x14202b0>
  g_sas = <gromacs.tools.G_sas object at 0x14169b0>
  g_sdf = <gromacs.tools.G_sdf object at 0x1420490>
  g_sgangle = <gromacs.tools.G_sgangle object at 0x1420470>
  g_sham = <gromacs.tools.G_sham object at 0x1416c30>
  g_sorient = <gromacs.tools.G_sorient object at 0x14204d0>
  g_spatial = <gromacs.tools.G_spatial object at 0x1416bb0>
  g_spol = <gromacs.tools.G_spol object at 0x1420a10>
  g_tcaf = <gromacs.tools.G_tcaf object at 0x14200d0>
  g_traj = <gromacs.tools.G_traj object at 0x14206f0>
  g_vanhove = <gromacs.tools.G_vanhove object at 0x1420730>
  g_velacc = <gromacs.tools.G_velacc object at 0x1416bf0>
  g_wham = <gromacs.tools.G_wham object at 0x1420530>
  genbox = <gromacs.tools.Genbox object at 0x1416b10>
  genconf = <gromacs.tools.Genconf object at 0x1420810>
  genion = <gromacs.tools.Genion object at 0x1420890>
  genrestr = <gromacs.tools.Genrestr object at 0x14208d0>
  gmxcheck = <gromacs.tools.Gmxcheck object at 0x1416790>
  gmxdump = <gromacs.tools.Gmxdump object at 0x1420570>
  gridMAT_MD = <gromacs.tools.GridMAT_MD object at 0x14169d0>
  grompp = <gromacs.tools.Grompp object at 0x1420370>
  less_important_warnings = ['AutoCorrectionWarning', 'UsageWarn...
  logger = log.create('gromacs', logfile= 'gromacs.log')
  luck = <gromacs.tools.Luck object at 0x1420390>
  make_edi = <gromacs.tools.Make_edi object at 0x1420af0>
  make_ndx = <gromacs.tools.Make_ndx object at 0x14209d0>
  mdrun = <gromacs.tools.Mdrun object at 0x1416ed0>
  mdrun_d = <gromacs.tools.Mdrun_d object at 0x1416a70>
  mk_angndx = <gromacs.tools.Mk_angndx object at 0x1420190>
  pdb2gmx = <gromacs.tools.Pdb2gmx object at 0x1416f70>
  protonate = <gromacs.tools.Protonate object at 0x1416bd0>
  sigeps = <gromacs.tools.Sigeps object at 0x1416a10>
  tpbconv = <gromacs.tools.Tpbconv object at 0x1420b10>
  trjcat = <gromacs.tools.Trjcat object at 0x1416f50>
  trjconv = <gromacs.tools.Trjconv object at 0x14203b0>
  trjorder = <gromacs.tools.Trjorder object at 0x1416dd0>
  wheel = <gromacs.tools.Wheel object at 0x1416db0>
  x2top = <gromacs.tools.X2top object at 0x1420770>
  xpm2ps = <gromacs.tools.Xpm2ps object at 0x14206b0>
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']