5.1.7. `gromacs.tools` – Gromacs commands classes

The underlying idea of GromacsWrapper is to automatically generate Python classes that run the actual GROMACS tools. These classes are written in such a way that they can be called as if they were functions with parameters resembling the GROMACS tools commandline arguments. This a two-step process when gromacs is imported: First a tool class is generated for each GROMACS tool (the Command list). Then an instance of each of these classes is instantiated in placed into the top level gromacs module. Thus, gromacs.grompp is an instance of gromacs.tools.Grompp. Users typically only access the tool instances at the top level of the module.

Note

Because the tool instances are autogenerated on the fly and depend on the installed GROMACS release, there is no autogenerated documentation available for them. Use in Python help(gromacs.grompp) to get help.

The following documentation for the gromacs.tools module describes in more detail how GROMACS tools are generated and managed and is primarily of interest to developers.

5.1.7.1. Gromacs tool instantiation

A Gromacs command class produces an instance of a Gromacs tool command (gromacs.core.GromacsCommand), any argument or keyword argument supplied will be used as default values for when the command is run.

Classes have the same name of the corresponding Gromacs tool with the first letter capitalized and dot and dashes replaced by underscores to make it a valid python identifier.

The list of tools to be loaded is configured with the tools and groups options of the ~/.gromacswrapper.cfg file. Guesses are made if these options are not provided; see gromacs.config for details.

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

from gromacs.tools import Trjconv

trjconv = tools.Trjconv()
trjconv_compact = tools.Trjconv(ur='compact', center=True, boxcenter='tric', pbc='mol',
                                input=('protein','system'))

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 specific, repeatedly encountered problem reliably. This is particularly helpful when doing interactive work.

5.1.7.2. Aliased commands

GromacsWrapper has been around since ancient GROMACS 4.5.x and throughout the history it has provided a way to run different versions of GROMACS commands with the same Python script in a backwards compatible manner by aliasing equivalent GROMACS tools to the same GromacsWrapper tool (using NAMES5TO4). Modern GROMACS (since 5.x and throughout 2016-2023) tools are aliased to their Gromacs 4 tool names for backwards compatibility.

For example, in “classic” GROMACS we had the g_sas command that became gmx sasa since GROMACS 5.x. In GromacsWrapper you can access the same tool as gromacs.g_sas or gromacs.sasa.

Warning

You should check that the different GROMACS versions of tools give equivalent answers for your problem. The aliasing just makes it easy for you to call the tool in the same manner. You are still responsible for validating your own results.

Sometimes GROMACS changes commands in an way that is fundamentally incompatible and in this way there is not much that GromacsWrapper can do. The best you can probably do in your own scripts is to use gromacs.release (see docs for gromacs.tools.Release) to check in your own script which release of GROMACS is running and then call different tools depending on what you find. For example, GROMACS 2023 replaced gmx do_dssp with gmx dssp which is not directly argument-compatible so GromacsWrapper does not alias it. Therefore, scripts relying on gromacs.do_dssp will break unless you account for it explicitly with code similar to

release_year = int(gromacs.release()[:4])
if release_year >= 2023:
    gromacs.dssp(s=TPR, f=XTC, sel="Protein",
                 o="dssp.dat", pbc=True, hmode="dssp")
else:
    gromacs.do_dssp(s=TPR, f=XTC, input=["Protein"]
                    ssdump="ssdump.dat", o="ss.xpm", sc="scount.xvg")

Note

It is recommended to keep a single version of all tools for a project and record the version in the methods section of a publication.

5.1.7.3. Multi index

It is possible to extend the tool 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)[source]

Command class that accept multiple index files.

It works combining multiple index files into a single temporary one so that tools that do not (yet) support multi index files as input can be used as if they did.

It creates a new file only if multiple index files are supplied.

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

docstring

additional documentation (ignored) []

Changed in version 0.6.0: The doc keyword is now ignored (because it was not worth the effort to make it work with the lazy-loading of docs).

gromacs.tools.merge_ndx(*args)[source]

Takes one or more index files and optionally one structure file and returns a path for a new merged index file.

Parameters:: args – index files and zero or one structure file
Returns:: path for the new merged index file

5.1.7.4. Virtual Gromacs commands

The following “commands” do not exist as tools in the Gromacs package but are added here because they are useful.

class gromacs.tools.Release[source]

Release string of the currently loaded Gromacs version.

Returns:: str, Release string such as “2018.2” or “4.6.5” or None if Gromacs can not be found.

Note

The release string is obtained from the output of gmx grompp -version, specifically the line starting with Gromacs version:. If this changes then this function will break.

Example

This command allows user code to work around known issues with old/new versions of Gromacs:

if gromacs.release.startswith("4"):
  # do something for classic Gromacs
else:
  # do it the modern way

(Note that calling gromacs.release() will simply return the release string, which is equivalent to str(gromacs.release). For convenience, the startswith() method exists, which directly works with the release string.)

New in version 0.8.0.

5.1.7.5. Helpers

These helper functions are necessary for collecting and setting up the Gromacs tools. They are mostly of interest to developers.

gromacs.tools.NAMES5TO4 = {'check': 'gmxcheck', 'convert-tpr': 'tpbconv', 'distance': 'g_dist', 'do_dssp': 'do_dssp', 'dump': 'gmxdump', 'editconf': 'editconf', 'eneconv': 'eneconv', 'gangle': 'g_sgangle', 'genconf': 'genconf', 'genion': 'genion', 'genrestr': 'genrestr', 'grompp': 'grompp', 'make_edi': 'make_edi', 'make_ndx': 'make_ndx', 'mdrun': 'mdrun', 'pdb2gmx': 'pdb2gmx', 'sasa': 'g_sas', 'solvate': 'genbox', 'trjcat': 'trjcat', 'trjconv': 'trjconv', 'trjorder': 'trjorder', 'xpm2ps': 'xpm2ps'}: dict of names in Gromacs 5 that correspond to an equivalent tool in in Gromacs 4. The names are literal Gromacs names.

gromacs.tools.V4TOOLS = ('g_cluster', 'g_dyndom', 'g_mdmat', 'g_principal', 'g_select', 'g_wham', 'mdrun', 'do_dssp', 'g_clustsize', 'g_enemat', 'g_membed', 'g_protonate', 'g_sgangle', 'g_wheel', 'mdrun_d', 'editconf', 'g_confrms', 'g_energy', 'g_mindist', 'g_rama', 'g_sham', 'g_x2top', 'mk_angndx', 'eneconv', 'g_covar', 'g_filter', 'g_morph', 'g_rdf', 'g_sigeps', 'genbox', 'pdb2gmx', 'g_anadock', 'g_current', 'g_gyrate', 'g_msd', 'g_sorient', 'genconf', 'g_anaeig', 'g_density', 'g_h2order', 'g_nmeig', 'g_rms', 'g_spatial', 'genion', 'tpbconv', 'g_analyze', 'g_densmap', 'g_hbond', 'g_nmens', 'g_rmsdist', 'g_spol', 'genrestr', 'trjcat', 'g_angle', 'g_dielectric', 'g_helix', 'g_nmtraj', 'g_rmsf', 'g_tcaf', 'gmxcheck', 'trjconv', 'g_bar', 'g_dih', 'g_helixorient', 'g_order', 'g_rotacf', 'g_traj', 'gmxdump', 'trjorder', 'g_bond', 'g_dipoles', 'g_kinetics', 'g_pme_error', 'g_rotmat', 'g_tune_pme', 'grompp', 'g_bundle', 'g_disre', 'g_lie', 'g_polystat', 'g_saltbr', 'g_vanhove', 'make_edi', 'xpm2ps', 'g_chi', 'g_dist', 'g_luck', 'g_potential', 'g_sas', 'g_velacc', 'make_ndx'): List of tools coming with standard Gromacs 4.x.

gromacs.tools.tool_factory(clsname, name, driver, base=<class 'gromacs.core.GromacsCommand'>)[source]: Factory for GromacsCommand derived types.

gromacs.tools.load_v4_tools()[source]

Load Gromacs 4.x tools automatically using some heuristic.

Tries to load tools (1) in configured tool groups (2) and fails back to automatic detection from GMXBIN (3) then to a prefilled list.

Also load any extra tool configured in ~/.gromacswrapper.cfg

Returns:: dict mapping tool names to GromacsCommand classes

gromacs.tools.load_v5_tools()[source]

Load Gromacs 2023/…/2016/5.x tools automatically using some heuristic.

Tries to load tools (1) using the driver from configured groups (2) and falls back to automatic detection from GMXBIN (3) then to rough guesses.

In all cases the command gmx help is run to get all tools available.

Returns:: dict mapping tool names to GromacsCommand classes

gromacs.tools.find_executables(path)[source]

Find executables in a path.

Searches executables in a directory excluding some know commands unusable with GromacsWrapper.

Parameters:: path – dirname to search for
Returns:: list of executables

gromacs.tools.make_valid_identifier(name)[source]

Turns tool names into valid identifiers.

Parameters:: name – tool name
Returns:: valid identifier

exception gromacs.tools.GromacsToolLoadingError[source]: Raised when no Gromacs tool could be found.

5.1.7.6. Gromacs tools

Each command class in the Command list below is used to create a command instance in the top level gromacs module if the Gromacs tools can be found in the file system (see gromacs.config). For example, the class Grompp is used to create the command gromacs.grompp.

5.1.7.6.1. Registry

The Command list below reflects the Gromacs commands that were available when the documentation was built and can vary from installation to installation. All currently available Gromacs commands are listed in the dictionary gromacs.tools.registry, in particular, gromacs.tools.registry.keys() lists the names.

gromacs.tools.registry = {'Grompp': <gromacs.tools.Grompp', 'Mdrun': <gromacs.tools.Mdrun', ...}: dict that contains all currently available Gromacs commands as well as the Virtual Gromacs commands. The registry is generated when the gromacs.tools package is imported for the first time.

5.1.7.6.2. Command list

The list below reflects the Gromacs commands that were available when the documentation was built and can vary from installation to installation. All currently available Gromacs commands are listed in the dictionary gromacs.tools.registry, which can be processed at run time.

class gromacs.tools.Anaeig

class gromacs.tools.Analyze

class gromacs.tools.Angle

class gromacs.tools.Awh

class gromacs.tools.Bar

class gromacs.tools.Bundle

class gromacs.tools.Check

class gromacs.tools.Chi

class gromacs.tools.Cluster

class gromacs.tools.Clustsize

class gromacs.tools.Confrms

class gromacs.tools.Convert_tpr

class gromacs.tools.Convert_trj

class gromacs.tools.Covar

class gromacs.tools.Current

class gromacs.tools.Density

class gromacs.tools.Densmap

class gromacs.tools.Densorder

class gromacs.tools.Dielectric

class gromacs.tools.Dipoles

class gromacs.tools.Disre

class gromacs.tools.Distance

class gromacs.tools.Dos

class gromacs.tools.Dssp

class gromacs.tools.Dump

class gromacs.tools.Dyecoupl

class gromacs.tools.Editconf

class gromacs.tools.Eneconv

class gromacs.tools.Enemat

class gromacs.tools.Energy

class gromacs.tools.Extract_cluster

class gromacs.tools.Filter

class gromacs.tools.Freevolume

class gromacs.tools.Gangle

class gromacs.tools.Genconf

class gromacs.tools.Genion

class gromacs.tools.Genrestr

class gromacs.tools.Grompp

class gromacs.tools.Gyrate

class gromacs.tools.H2order

class gromacs.tools.Hbond

class gromacs.tools.Helix

class gromacs.tools.Helixorient

class gromacs.tools.Help

class gromacs.tools.Hydorder

class gromacs.tools.Insert_molecules

class gromacs.tools.Lie

class gromacs.tools.Make_edi

class gromacs.tools.Make_ndx

class gromacs.tools.Mdmat

class gromacs.tools.Mdrun

class gromacs.tools.Mindist

class gromacs.tools.Mk_angndx

class gromacs.tools.Msd

class gromacs.tools.Nmeig

class gromacs.tools.Nmens

class gromacs.tools.Nmr

class gromacs.tools.Nmtraj

class gromacs.tools.Nonbonded_benchmark

class gromacs.tools.Order

class gromacs.tools.Pairdist

class gromacs.tools.Pdb2gmx

class gromacs.tools.Pme_error

class gromacs.tools.Polystat

class gromacs.tools.Potential

class gromacs.tools.Principal

class gromacs.tools.Rama

class gromacs.tools.Rdf

class gromacs.tools.Report_methods

class gromacs.tools.Rms

class gromacs.tools.Rmsdist

class gromacs.tools.Rmsf

class gromacs.tools.Rotacf

class gromacs.tools.Rotmat

class gromacs.tools.Saltbr

class gromacs.tools.Sans

class gromacs.tools.Sasa

class gromacs.tools.Saxs

class gromacs.tools.Select

class gromacs.tools.Sham

class gromacs.tools.Sigeps

class gromacs.tools.Solvate

class gromacs.tools.Sorient

class gromacs.tools.Spatial

class gromacs.tools.Spol

class gromacs.tools.Tcaf

class gromacs.tools.Traj

class gromacs.tools.Trajectory

class gromacs.tools.Trjcat

class gromacs.tools.Trjconv

class gromacs.tools.Trjorder

class gromacs.tools.Tune_pme

class gromacs.tools.Vanhove

class gromacs.tools.Velacc

class gromacs.tools.Wham

class gromacs.tools.Wheel

class gromacs.tools.X2top

class gromacs.tools.Xpm2ps

class gromacs.tools.G_anaeig

class gromacs.tools.G_analyze

class gromacs.tools.G_angle

class gromacs.tools.G_awh

class gromacs.tools.G_bar

class gromacs.tools.G_bundle

class gromacs.tools.Gmxcheck

class gromacs.tools.G_chi

class gromacs.tools.G_cluster

class gromacs.tools.G_clustsize

class gromacs.tools.G_confrms

class gromacs.tools.Tpbconv

class gromacs.tools.G_convert_trj

class gromacs.tools.G_covar

class gromacs.tools.G_current

class gromacs.tools.G_density

class gromacs.tools.G_densmap

class gromacs.tools.G_densorder

class gromacs.tools.G_dielectric

class gromacs.tools.G_dipoles

class gromacs.tools.G_disre

class gromacs.tools.G_dist

class gromacs.tools.G_dos

class gromacs.tools.G_dssp

class gromacs.tools.Gmxdump

class gromacs.tools.G_dyecoupl

class gromacs.tools.G_enemat

class gromacs.tools.G_energy

class gromacs.tools.G_extract_cluster

class gromacs.tools.G_filter

class gromacs.tools.G_freevolume

class gromacs.tools.G_sgangle

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_help

class gromacs.tools.G_hydorder

class gromacs.tools.G_insert_molecules

class gromacs.tools.G_lie

class gromacs.tools.G_mdmat

class gromacs.tools.G_mindist

class gromacs.tools.G_mk_angndx

class gromacs.tools.G_msd

class gromacs.tools.G_nmeig

class gromacs.tools.G_nmens

class gromacs.tools.G_nmr

class gromacs.tools.G_nmtraj

class gromacs.tools.G_nonbonded_benchmark

class gromacs.tools.G_order

class gromacs.tools.G_pairdist

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_rama

class gromacs.tools.G_rdf

class gromacs.tools.G_report_methods

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_sans

class gromacs.tools.G_sas

class gromacs.tools.G_saxs

class gromacs.tools.G_select

class gromacs.tools.G_sham

class gromacs.tools.G_sigeps

class gromacs.tools.Genbox

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_trajectory

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

5.1.7. gromacs.tools – Gromacs commands classes

5.1.7.1. Gromacs tool instantiation

5.1.7.2. Aliased commands

5.1.7.3. Multi index

5.1.7.4. Virtual Gromacs commands

5.1.7.5. Helpers

5.1.7.6. Gromacs tools

5.1.7.6.1. Registry

5.1.7.6.2. Command list

5.1.7. `gromacs.tools` – Gromacs commands classes