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.


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. 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',

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. 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.


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")
    gromacs.do_dssp(s=TPR, f=XTC, input=["Protein"]
                    ssdump="ssdump.dat", o="ss.xpm", sc="scount.xvg")


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


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.


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


raises GromacsError if command fails


issue a GromacsFailureWarning


just continue silently


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).


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


args – index files and zero or one structure file


path for the new merged index file 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.


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


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.


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
  # 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. 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.


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


dict mapping tool names to GromacsCommand classes


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.


dict mapping tool names to GromacsCommand classes


Find executables in a path.

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


path – dirname to search for


list of executables


Turns tool names into valid identifiers.


name – tool name


valid identifier

exception gromacs.tools.GromacsToolLoadingError[source]

Raised when no Gromacs tool could be found. 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. 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. 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