Table Of Contents

Previous topic

gromacs.utilities – Helper functions and classes

Next topic

Gromacs building blocks

This Page

gromacs.tools – Gromacs commands classes

A Gromacs command class acts as a factory function that produces an instance of a gromacs command (gromacs.core.GromacsCommand) with initial default values.

By convention, a class has the capitalized name of the corresponding Gromacs tool; dots are replaced by underscores to make it a valid python identifier.

The list of Gromacs tools to be loaded is configured in gromacs.config.gmx_tool_groups.

It is also possible to extend the basic commands and patch in additional functionality. For example, the GromacsCommandMultiIndex class makes a command accept multiple index files and concatenates them on the fly; the behaviour mimics Gromacs’ “multi-file” input that has not yet been enabled for all tools.

class gromacs.tools.GromacsCommandMultiIndex(**kwargs)

Initialize instance.

  1. Sets up the combined index file.
  2. Inititialize GromacsCommand with the new index file.

See the documentation for gromacs.core.GromacsCommand for details.

run(*args, **kwargs)

Run the command; make a combined multi-index file if necessary.

_fake_multi_ndx(**kwargs)

Combine multiple index file into a single one and return appropriate kwargs.

Calling the method combines multiple index files into a a single temporary one so that Gromacs tools that do not (yet) support multi file input for index files can be used transparently as if they did.

If a temporary index file is required then it is deleted once the object is destroyed.

Returns :

The method returns the input keyword arguments with the necessary changes to use the temporary index files.

Keywords :

Only the listed keywords have meaning for the method:

n : filename or list of filenames

possibly multiple index files; n is replaced by the name of the temporary index file.

s : filename

structure file (tpr, pdb, ...) or None; if a structure file is supplied then the Gromacs default index groups are automatically added to the temporary indexs file.

Example :

Used in derived classes that replace the standard run() (or __init__()) methods with something like:

def run(self,*args,**kwargs):
    kwargs = self._fake_multi_ndx(**kwargs)            
    return super(G_mindist, self).run(*args, **kwargs)
__del__()

Clean up temporary multi-index files if they were used.

Example

In this example we create two instances of the gromacs.tools.Trjconv command (which runs the Gromacs trjconv command):

import gromacs.tools as tools

trjconv = tools.Trjconv()
trjconv_compact = tools.Trjconv(ur='compact', center=True, boxcenter='tric', pbc='mol',
                                input=('protein','system'),
                                doc="Returns a compact representation of the system centered on the protein")

The first one, trjconv, behaves as the standard commandline tool but the second one, trjconv_compact, will by default create a compact representation of the input data by taking into account the shape of the unit cell. Of course, the same effect can be obtained by providing the corresponding arguments to trjconv but by naming the more specific command differently one can easily build up a library of small tools that will solve a specifi, repeatedly encountered problem reliably. This is particularly helpful when doing interactive work.

Gromacs tools

class gromacs.tools.Mdrun(*args, **kwargs)

Gromacs tool ‘mdrun’.

Set up the command with gromacs flags as keyword arguments.

The following are generic instructions; refer to the Gromacs command usage information that should have appeared before this generic documentation.

As an example, a generic Gromacs command could use the following flags:

cmd = GromacsCommand('v', f=['md1.xtc','md2.xtc'], o='processed.xtc', t=200, ...)

which would correspond to running the command in the shell as

GromacsCommand -v -f md1.xtc md2.xtc -o processed.xtc -t 200

Gromacs command line arguments

Gromacs boolean switches (such as -v) are given as python positional arguments ('v') or as keyword argument (v=True); note the quotes in the first case. Negating a boolean switch can be done with 'nov', nov=True or v=False (and even nov=False works as expected: it is the same as v=True).

Any Gromacs options that take parameters are handled as keyword arguments. If an option takes multiple arguments (such as the multi-file input -f file1 file2 ...) then the list of files must be supplied as a python list.

If a keyword has the python value None then it will not be added to the Gromacs command line; this allows for flexible scripting if it is not known in advance if an input file is needed. In this case the default value of the gromacs tool is used.

Keywords must be legal python keywords or the interpreter raises a SyntaxError but of course Gromacs commandline arguments are not required to be legal python. In this case “quote” the option with an underscore (_) and the underscore will be silently stripped. For instance, -or translates to the illegal keyword or so it must be underscore-quoted:

cmd(...., _or='mindistres.xvg')

Command execution

The command is executed with the run() method or by calling it as a function. The two next lines are equivalent:

cmd(...)
cmd.run(...)

When the command is run one can override options that were given at initialization or one can add additional ones. The same rules for supplying Gromacs flags apply as described above.

Non-Gromacs keyword arguments

The other keyword arguments (listed below) are not passed on to the Gromacs tool but determine how the command class behaves. They are only useful when instantiating a class, i.e. they determine how this tool behaves during all future invocations although it can be changed by setting failuremode. This is mostly of interest to developers.
Keywords :
failure

determines how a failure of the gromacs command is treated; it can be one of the following:

‘raise’

raises GromacsError if command fails

‘warn’

issue a GromacsFailureWarning

None

just continue silently

doc : string

additional documentation []

class gromacs.tools.GridMAT_MD(*args, **kwargs)

External tool ‘GridMAT-MD.pl’

GridMAT-MD: A Grid-based Membrane Analysis Tool for use with Molecular Dynamics.

This GridMAT-MD is a patched version of the original GridMAT-MD.pl v1.0.2, written by WJ Allen, JA Lemkul and DR Bevan. The original version is available from the GridMAT-MD home page,

Please cite

W. J. Allen, J. A. Lemkul, and D. R. Bevan. (2009) “GridMAT-MD: A Grid-based Membrane Analysis Tool for Use With Molecular Dynamics.” J. Comput. Chem. 30 (12): 1952-1958.

when using this programme.

Usage:

class GridMAT_MD(config[, structure])
Arguments :
  • config : See the original documentation for a description for the configuration file.
  • structure : A gro or pdb file that overrides the value for bilayer in the configuration file.

.

Set up the command class.

The arguments can always be provided as standard positional arguments such as

"-c", "config.conf", "-o", "output.dat", "--repeats=3", "-v", "input.dat"

In addition one can also use keyword arguments such as

c="config.conf", o="output.dat", repeats=3, v=True

These are automatically transformed appropriately according to simple rules:

  • Any single-character keywords are assumed to be POSIX-style options and will be prefixed with a single dash and the value separated by a space.
  • Any other keyword is assumed to be a GNU-style long option and thus will be prefixed with two dashes and the value will be joined directly with an equals sign and no space.

If this does not work (as for instance for the options of the UNIX find command) then provide options and values in the sequence of positional arguments.

class gromacs.tools.A_gridcalc
class gromacs.tools.A_ri3dc
class gromacs.tools.Demux_pl
class gromacs.tools.Do_dssp
class gromacs.tools.Editconf
class gromacs.tools.Eneconv
class gromacs.tools.G_anadock
class gromacs.tools.G_anaeig
class gromacs.tools.G_analyze
class gromacs.tools.G_angle
class gromacs.tools.G_bar
class gromacs.tools.G_bond
class gromacs.tools.G_bundle
class gromacs.tools.G_chi
class gromacs.tools.G_cluster
class gromacs.tools.G_clustsize
class gromacs.tools.G_confrms
class gromacs.tools.G_count
class gromacs.tools.G_covar
class gromacs.tools.G_current
class gromacs.tools.G_density
class gromacs.tools.G_densmap
class gromacs.tools.G_dielectric
class gromacs.tools.G_dih
class gromacs.tools.G_dipoles
class gromacs.tools.G_disre
class gromacs.tools.G_dist
class gromacs.tools.G_dyndom
class gromacs.tools.G_enemat
class gromacs.tools.G_energy
class gromacs.tools.G_filter
class gromacs.tools.G_flux
class gromacs.tools.G_gyrate
class gromacs.tools.G_h2order
class gromacs.tools.G_hbond
class gromacs.tools.G_helix
class gromacs.tools.G_helixorient
class gromacs.tools.G_kinetics
class gromacs.tools.G_lie
class gromacs.tools.G_luck
class gromacs.tools.G_mdmat
class gromacs.tools.G_membed
class gromacs.tools.G_mindist
class gromacs.tools.G_morph
class gromacs.tools.G_msd
class gromacs.tools.G_nmeig
class gromacs.tools.G_nmens
class gromacs.tools.G_nmtraj
class gromacs.tools.G_order
class gromacs.tools.G_pme_error
class gromacs.tools.G_polystat
class gromacs.tools.G_potential
class gromacs.tools.G_principal
class gromacs.tools.G_protonate
class gromacs.tools.G_rama
class gromacs.tools.G_rdf
class gromacs.tools.G_ri3dc
class gromacs.tools.G_rms
class gromacs.tools.G_rmsdist
class gromacs.tools.G_rmsf
class gromacs.tools.G_rotacf
class gromacs.tools.G_rotmat
class gromacs.tools.G_saltbr
class gromacs.tools.G_sas
class gromacs.tools.G_select
class gromacs.tools.G_sgangle
class gromacs.tools.G_sham
class gromacs.tools.G_sigeps
class gromacs.tools.G_sorient
class gromacs.tools.G_spatial
class gromacs.tools.G_spol
class gromacs.tools.G_tcaf
class gromacs.tools.G_traj
class gromacs.tools.G_tune_pme
class gromacs.tools.G_vanhove
class gromacs.tools.G_velacc
class gromacs.tools.G_wham
class gromacs.tools.G_wheel
class gromacs.tools.G_x2top
class gromacs.tools.Genbox
class gromacs.tools.Genconf
class gromacs.tools.Genion
class gromacs.tools.Genrestr
class gromacs.tools.Gmxcheck
class gromacs.tools.Gmxdump
class gromacs.tools.Grompp
class gromacs.tools.Make_edi
class gromacs.tools.Make_ndx
class gromacs.tools.Mdrun
class gromacs.tools.Mdrun_d
class gromacs.tools.Mk_angndx
class gromacs.tools.Pdb2gmx
class gromacs.tools.Tpbconv
class gromacs.tools.Trjcat
class gromacs.tools.Trjconv
class gromacs.tools.Trjorder
class gromacs.tools.Xplor2gmx_pl
class gromacs.tools.Xpm2ps