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
orv=False
(and evennov=False
works as expected: it is the same asv=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 keywordor
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).
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 withGromacs 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 tostr(gromacs.release)
. For convenience, thestartswith()
method exists, which directly works with the release string.)Added 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
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. Theregistry
is generated when thegromacs.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