Command-line reference#
GROMACS includes many tools for preparing, running and analyzing
molecular dynamics simulations. These are all structured as part of a single
gmx wrapper binary, and invoked with commands like gmx grompp.
or gmx mdrun. Documentation for these can
be found at the respective sections below, as well as on man pages (e.g.,
gmx-grompp(1)) and with gmx help command
or
gmx command -h
.
If you’ve installed an MPI version of GROMACS, by default the gmx binary is called gmx_mpi and you should adapt accordingly.
Command-line interface and conventions#
All GROMACS commands require an option before any arguments (i.e., all
command-line arguments need to be preceded by an argument starting with a
dash, and values not starting with a dash are arguments to the preceding
option). Most options, except for boolean flags, expect an argument (or
multiple in some cases) after the option name.
The argument must be a separate command-line argument, i.e., separated by
space, as in -f traj.xtc
. If more than one argument needs to be given to
an option, they should be similarly separated from each other.
Some options also have default arguments, i.e., just specifying the option
without any argument uses the default argument.
If an option is not specified at all, a default value is used; in the case of
optional files, the default might be not to use that file (see below).
All GROMACS command options start with a single dash, whether they are single- or multiple-letter options. However, two dashes are also recognized (starting from 5.1).
In addition to command-specific options, some options are handled by the
gmx wrapper, and can be specified for any command. See
wrapper binary help for the list of such options.
These options are recognized both before the command name (e.g.,
gmx -quiet grompp) as well as after the command name (e.g.,
gmx grompp -quiet).
There is also a -hidden
option that can be specified in combination with
-h
to show help for advanced/developer-targeted options.
Most analysis commands can process a trajectory with fewer atoms than the run input or structure file, but only if the trajectory consists of the first n atoms of the run input or structure file.
Handling specific types of command-line options#
- boolean options
Boolean flags can be specified like
-pbc
and negated like-nopbc
. It is also possible to use an explicit value like-pbc no
and-pbc yes
.- file name options
Options that accept files names have features that support using default file names (where the default file name is specific to that option):
If a required option is not set, the default is used.
If an option is marked optional, the file is not used unless the option is set (or other conditions make the file required).
If an option is set, and no file name is provided, the default is used.
All such options will accept file names without a file extension. The extension is automatically appended in such a case. When multiple input formats are accepted, such as a generic structure format, the directory will be searched for files of each type with the supplied or default name. When no file with a recognized extension is found, an error is given. For output files with multiple formats, a default file type will be used.
Some file formats can also be read from compressed (
.Z
or.gz
) formats.- enum options
Enumerated options (enum) should be used with one of the arguments listed in the option description. The argument may be abbreviated, and the first match to the shortest argument in the list will be selected.
- vector options
Some options accept a vector of values. Either 1 or 3 parameters can be supplied; when only one parameter is supplied the two other values are also set to this value.
- selection options
Commands by name#
gmx - molecular dynamics simulation suite
gmx anaeig - Analyze eigenvectors/normal modes
gmx analyze - Analyze data sets
gmx angle - Calculate distributions and correlations for angles and dihedrals
gmx awh - Extract data from an accelerated weight histogram (AWH) run
gmx bar - Calculate free energy difference estimates through Bennett’s acceptance ratio
gmx bundle - Analyze bundles of axes, e.g., helices
gmx check - Check and compare files
gmx chi - Calculate everything you want to know about chi and other dihedrals
gmx cluster - Cluster structures
gmx clustsize - Calculate size distributions of atomic clusters
gmx confrms - Fit two structures and calculates the RMSD
gmx convert-tpr - Make a modified run-input file
gmx convert-trj - Converts between different trajectory types
gmx covar - Calculate and diagonalize the covariance matrix
gmx current - Calculate dielectric constants and current autocorrelation function
gmx density - Calculate the density of the system
gmx densmap - Calculate 2D planar or axial-radial density maps
gmx densorder - Calculate surface fluctuations
gmx dielectric - Calculate frequency dependent dielectric constants
gmx dipoles - Compute the total dipole plus fluctuations
gmx disre - Analyze distance restraints
gmx distance - Calculate distances between pairs of positions
gmx dos - Analyze density of states and properties based on that
gmx dssp - Calculate protein secondary structure via DSSP algorithm
gmx dump - Make binary files human readable
gmx dyecoupl - Extract dye dynamics from trajectories
gmx editconf - Convert and manipulates structure files
gmx eneconv - Convert energy files
gmx enemat - Extract an energy matrix from an energy file
gmx energy - Writes energies to xvg files and display averages
gmx extract-cluster - Allows extracting frames corresponding to clusters from trajectory
gmx filter - Frequency filter trajectories, useful for making smooth movies
gmx freevolume - Calculate free volume
gmx gangle - Calculate angles
gmx genconf - Multiply a conformation in ‘random’ orientations
gmx genion - Generate monoatomic ions on energetically favorable positions
gmx genrestr - Generate position restraints or distance restraints for index groups
gmx grompp - Make a run input file
gmx gyrate - Calculate the radius of gyration
gmx h2order - Compute the orientation of water molecules
gmx hbond - Compute and analyze hydrogen bonds
gmx helix - Calculate basic properties of alpha helices
gmx helixorient - Calculate local pitch/bending/rotation/orientation inside helices
gmx help - Print help information
gmx hydorder - Compute tetrahedrality parameters around a given atom
gmx insert-molecules - Insert molecules into existing vacancies
gmx lie - Estimate free energy from linear combinations
gmx make_edi - Generate input files for essential dynamics sampling
gmx make_ndx - Make index files
gmx mdmat - Calculate residue contact maps
gmx mdrun - Perform a simulation, do a normal mode analysis or an energy minimization
gmx mindist - Calculate the minimum distance between two groups
gmx mk_angndx - Generate index files for ‘gmx angle’
gmx msd - Compute mean squared displacements
gmx nmeig - Diagonalize the Hessian for normal mode analysis
gmx nmens - Generate an ensemble of structures from the normal modes
gmx nmr - Analyze nuclear magnetic resonance properties from an energy file
gmx nmtraj - Generate a virtual oscillating trajectory from an eigenvector
gmx nonbonded-benchmark - Benchmarking tool for the non-bonded pair kernels.
gmx order - Compute the order parameter per atom for carbon tails
gmx pairdist - Calculate pairwise distances between groups of positions
gmx pdb2gmx - Convert coordinate files to topology and FF-compliant coordinate files
gmx pme_error - Estimate the error of using PME with a given input file
gmx polystat - Calculate static properties of polymers
gmx potential - Calculate the electrostatic potential across the box
gmx principal - Calculate principal axes of inertia for a group of atoms
gmx rama - Compute Ramachandran plots
gmx rdf - Calculate radial distribution functions
gmx report-methods - Write short summary about the simulation setup to a text file and/or to the standard output.
gmx rms - Calculate RMSDs with a reference structure and RMSD matrices
gmx rmsdist - Calculate atom pair distances averaged with power -2, -3 or -6
gmx rmsf - Calculate atomic fluctuations
gmx rotacf - Calculate the rotational correlation function for molecules
gmx rotmat - Plot the rotation matrix for fitting to a reference structure
gmx saltbr - Compute salt bridges
gmx sans - Compute small angle neutron scattering spectra
gmx sasa - Compute solvent accessible surface area
gmx saxs - Compute small angle X-ray scattering spectra
gmx select - Print general information about selections
gmx sham - Compute free energies or other histograms from histograms
gmx sigeps - Convert c6/12 or c6/cn combinations to and from sigma/epsilon
gmx solvate - Solvate a system
gmx sorient - Analyze solvent orientation around solutes
gmx spatial - Calculate the spatial distribution function
gmx spol - Analyze solvent dipole orientation and polarization around solutes
gmx tcaf - Calculate viscosities of liquids
gmx traj - Plot x, v, f, box, temperature and rotational energy from trajectories
gmx trajectory - Print coordinates, velocities, and/or forces for selections
gmx trjcat - Concatenate trajectory files
gmx trjconv - Convert and manipulates trajectory files
gmx trjorder - Order molecules according to their distance to a group
gmx tune_pme - Time mdrun as a function of PME ranks to optimize settings
gmx vanhove - Compute Van Hove displacement and correlation functions
gmx velacc - Calculate velocity autocorrelation functions
gmx wham - Perform weighted histogram analysis after umbrella sampling
gmx wheel - Plot helical wheels
gmx x2top - Generate a primitive topology from coordinates
gmx xpm2ps - Convert XPM (XPixelMap) matrices to postscript or XPM
Commands by topic#
Trajectory analysis#
- gmx gangle
Calculate angles
- gmx convert-trj
Converts between different trajectory types
- gmx distance
Calculate distances between pairs of positions
- gmx dssp
Calculate protein secondary structure via DSSP algorithm
- gmx extract-cluster
Allows extracting frames corresponding to clusters from trajectory
- gmx freevolume
Calculate free volume
- gmx msd
Compute mean squared displacements
- gmx pairdist
Calculate pairwise distances between groups of positions
- gmx rdf
Calculate radial distribution functions
- gmx sasa
Compute solvent accessible surface area
- gmx select
Print general information about selections
- gmx trajectory
Print coordinates, velocities, and/or forces for selections
Generating topologies and coordinates#
- gmx editconf
Edit the box and write subgroups
- gmx x2top
Generate a primitive topology from coordinates
- gmx solvate
Solvate a system
- gmx insert-molecules
Insert molecules into existing vacancies
- gmx genconf
Multiply a conformation in ‘random’ orientations
- gmx genion
Generate monoatomic ions on energetically favorable positions
- gmx genrestr
Generate position restraints or distance restraints for index groups
- gmx pdb2gmx
Convert coordinate files to topology and FF-compliant coordinate files
Running a simulation#
- gmx grompp
Make a run input file
- gmx mdrun
Perform a simulation, do a normal mode analysis or an energy minimization
- gmx convert-tpr
Make a modified run-input file
Viewing trajectories#
- gmx nmtraj
Generate a virtual oscillating trajectory from an eigenvector
Processing energies#
- gmx enemat
Extract an energy matrix from an energy file
- gmx energy
Writes energies to xvg files and display averages
- gmx mdrun
(Re)calculate energies for trajectory frames with -rerun
Converting files#
- gmx editconf
Convert and manipulates structure files
- gmx eneconv
Convert energy files
- gmx sigeps
Convert c6/12 or c6/cn combinations to and from sigma/epsilon
- gmx trjcat
Concatenate trajectory files
- gmx trjconv
Convert and manipulates trajectory files
- gmx xpm2ps
Convert XPM (XPixelMap) matrices to postscript or XPM
Tools#
- gmx analyze
Analyze data sets
- gmx awh
Extract data from an accelerated weight histogram (AWH) run
- gmx filter
Frequency filter trajectories, useful for making smooth movies
- gmx lie
Estimate free energy from linear combinations
- gmx pme_error
Estimate the error of using PME with a given input file
- gmx sham
Compute free energies or other histograms from histograms
- gmx spatial
Calculate the spatial distribution function
- gmx traj
Plot x, v, f, box, temperature and rotational energy from trajectories
- gmx tune_pme
Time mdrun as a function of PME ranks to optimize settings
- gmx wham
Perform weighted histogram analysis after umbrella sampling
- gmx check
Check and compare files
- gmx dump
Make binary files human readable
- gmx make_ndx
Make index files
- gmx mk_angndx
Generate index files for ‘gmx angle’
- gmx trjorder
Order molecules according to their distance to a group
- gmx xpm2ps
Convert XPM (XPixelMap) matrices to postscript or XPM
- gmx report-methods
Write short summary about the simulation setup to a text file and/or to the standard output.
Distances between structures#
- gmx cluster
Cluster structures
- gmx confrms
Fit two structures and calculates the RMSD
- gmx rms
Calculate RMSDs with a reference structure and RMSD matrices
- gmx rmsf
Calculate atomic fluctuations
Distances in structures over time#
- gmx mindist
Calculate the minimum distance between two groups
- gmx mdmat
Calculate residue contact maps
- gmx polystat
Calculate static properties of polymers
- gmx rmsdist
Calculate atom pair distances averaged with power -2, -3 or -6
Mass distribution properties over time#
- gmx gyrate
Calculate the radius of gyration
- gmx polystat
Calculate static properties of polymers
- gmx rdf
Calculate radial distribution functions
- gmx rotacf
Calculate the rotational correlation function for molecules
- gmx rotmat
Plot the rotation matrix for fitting to a reference structure
- gmx sans
Compute small angle neutron scattering spectra
- gmx saxs
Compute small angle X-ray scattering spectra
- gmx traj
Plot x, v, f, box, temperature and rotational energy from trajectories
- gmx vanhove
Compute Van Hove displacement and correlation functions
Analyzing bonded interactions#
- gmx angle
Calculate distributions and correlations for angles and dihedrals
- gmx mk_angndx
Generate index files for ‘gmx angle’
Structural properties#
- gmx bundle
Analyze bundles of axes, e.g., helices
- gmx clustsize
Calculate size distributions of atomic clusters
- gmx disre
Analyze distance restraints
- gmx hbond
Compute and analyze hydrogen bonds
- gmx order
Compute the order parameter per atom for carbon tails
- gmx principal
Calculate principal axes of inertia for a group of atoms
- gmx rdf
Calculate radial distribution functions
- gmx saltbr
Compute salt bridges
- gmx sorient
Analyze solvent orientation around solutes
- gmx spol
Analyze solvent dipole orientation and polarization around solutes
Kinetic properties#
- gmx bar
Calculate free energy difference estimates through Bennett’s acceptance ratio
- gmx current
Calculate dielectric constants and current autocorrelation function
- gmx dos
Analyze density of states and properties based on that
- gmx dyecoupl
Extract dye dynamics from trajectories
- gmx principal
Calculate principal axes of inertia for a group of atoms
- gmx tcaf
Calculate viscosities of liquids
- gmx traj
Plot x, v, f, box, temperature and rotational energy from trajectories
- gmx vanhove
Compute Van Hove displacement and correlation functions
- gmx velacc
Calculate velocity autocorrelation functions
Electrostatic properties#
- gmx current
Calculate dielectric constants and current autocorrelation function
- gmx dielectric
Calculate frequency dependent dielectric constants
- gmx dipoles
Compute the total dipole plus fluctuations
- gmx potential
Calculate the electrostatic potential across the box
- gmx spol
Analyze solvent dipole orientation and polarization around solutes
- gmx genion
Generate monoatomic ions on energetically favorable positions
Protein-specific analysis#
- gmx chi
Calculate everything you want to know about chi and other dihedrals
- gmx helix
Calculate basic properties of alpha helices
- gmx helixorient
Calculate local pitch/bending/rotation/orientation inside helices
- gmx rama
Compute Ramachandran plots
- gmx wheel
Plot helical wheels
Interfaces#
- gmx bundle
Analyze bundles of axes, e.g., helices
- gmx density
Calculate the density of the system
- gmx densmap
Calculate 2D planar or axial-radial density maps
- gmx densorder
Calculate surface fluctuations
- gmx h2order
Compute the orientation of water molecules
- gmx hydorder
Compute tetrahedrality parameters around a given atom
- gmx order
Compute the order parameter per atom for carbon tails
- gmx potential
Calculate the electrostatic potential across the box
Covariance analysis#
- gmx anaeig
Analyze the eigenvectors
- gmx covar
Calculate and diagonalize the covariance matrix
- gmx make_edi
Generate input files for essential dynamics sampling
Normal modes#
- gmx anaeig
Analyze the normal modes
- gmx nmeig
Diagonalize the Hessian for normal mode analysis
- gmx nmtraj
Generate a virtual oscillating trajectory from an eigenvector
- gmx nmens
Generate an ensemble of structures from the normal modes
- gmx grompp
Make a run input file
- gmx mdrun
Find a potential energy minimum and calculate the Hessian
Special topics#
The information in these topics is also accessible through
gmx help topic
on the command line.
Selection syntax and usage#
- Selection syntax and usage
- Specifying selections from command line
- Selection syntax
- Specifying positions in selections
- Arithmetic expressions in selections
- Selection keywords
- Selecting atoms by name - atomname, name, pdbatomname, pdbname
- Selecting based on distance - dist, distance, mindist, mindistance, within
- Selecting atoms in a solid angle - insolidangle
- Merging selections - merge, plus
- Permuting selections - permute
- Selecting atoms by residue number - resid, residue, resindex, resnr
- Extending selections - same
- Selection evaluation and optimization
- Selection limitations
- Selection examples
Command changes between versions#
Starting from GROMACS 5.0, some of the analysis commands (and a few other commands as well) have changed significantly.
One main driver for this has been that many new tools mentioned below now accept selections through one or more command-line options instead of prompting for a static index group. To take full advantage of selections, the interface to the commands has changed somewhat, and some previous command-line options are no longer present as the same effect can be achieved with suitable selections. Please see Selection syntax and usage additional information on how to use selections.
In the process, some old analysis commands have been removed in favor of more powerful functionality that is available through an alternative tool. For removed or replaced commands, this page documents how to perform the same tasks with new tools. For new commands, a brief note on the available features is given. See the linked help for the new commands for a full description.
This section lists only major changes; minor changes like additional/removed options or bug fixes are not typically included.
For more information about changed features, please check out the Release notes.
Version 2020#
gmx convert-trj#
new
gmx convert-trj has been introduced as a selection-enabled alternative for exchanging trajectory file format (previously done in gmx trjconv).
gmx extract-cluster#
new
gmx extract-cluster has been introduced as a selection-enabled way to write sub-trajectories based on the output from a cluster analysis. The corresponding option -sub in gmx trjconv has been removed.
Version 2018#
gmx trajectory#
new
gmx trajectory has been introduced as a selection-enabled version of gmx traj. It supports output of coordinates, velocities, and/or forces for positions calculated for selections.
Version 2016#
Analysis on arbitrary subsets of atoms#
Tools implemented in the new analysis framework can now operate upon trajectories that match only a subset of the atoms in the input structure file.
gmx insert-molecules#
improved
gmx insert-molecules has gained an option -replace
that makes it
possible to insert molecules into a solvated configuration, replacing any
overlapping solvent atoms. In a fully solvated box, it is also possible to
insert into a certain region of the solvent only by selecting a subset of the
solvent atoms (-replace
takes a selection that can also contain expressions
like not within 1 of ...
).
gmx rdf#
improved
The normalization for the output RDF can now also be the radial number density.
gmx genconf#
simplified
Removed -block
, -sort
and -shuffle
.
Version 5.1#
General#
Symbolic links from 5.0 are no longer supported. The only way to invoke a
command is through gmx <command>
.
gmx pairdist#
new
gmx pairdist has been introduced as a selection-enabled replacement for
gmx mindist (gmx mindist
still exists unchanged). It can calculate
min/max pairwise distances between a pair of selections, including, e.g.,
per-residue minimum distances or distances from a single point to a set of
residue-centers-of-mass.
gmx rdf#
rewritten
gmx rdf has been rewritten for 5.1 to use selections for specifying the points from which the RDFs are calculated. The interface is mostly the same, except that there are new command-line options to specify the selections. The following additional changes have been made:
-com
and-rdf
options have been removed. Equivalent functionality is available through selections:-com
can be replaced with acom of <selection>
as the reference selection.-rdf
can be replaced with a suitable set of selections (e.g.,res_com of <selection>
) and/or using-seltype
.
-rmax
option is added to specify a cutoff for the RDFs. If set to a value that is significantly smaller than half the box size, it can speed up the calculation significantly if a grid-based neighborhood search can be used.-hq
and-fade
options have been removed, as they are simply postprocessing steps on the raw numbers that can be easily done after the analysis.
Version 5.0#
General#
Version 5.0 introduced the gmx wrapper binary.
For backwards compatibility, this version still creates symbolic links by default for
old tools: e.g., g_order <options>
is equivalent to gmx order <options>
, and
g_order
is simply a symbolic link on the file system.
g_bond#
replaced
This tool has been removed in 5.0. A replacement is gmx distance.
You can provide your existing index file to gmx distance, and it will calculate the same distances. The differences are:
-blen
and-tol
options have different default values.You can control the output histogram with
-binw
.-aver
and-averdist
options are not present. Instead, you can choose between the different things to calculate using-oav
(corresponds to-d
with-averdist
),-oall
(corresponds to-d
without-averdist
),-oh
(corresponds to-o
with-aver
), and-oallstat
(corresponds to-l
without-aver
).
You can produce any combination of output files. Compared to g_bond
,
gmx distance -oall
is currently missing labels for the output columns.
g_dist#
replaced
This tool has been removed in 5.0. A replacement is gmx distance (for
most options) or gmx select (for -dist
or -lt
).
If you had index groups A and B in index.ndx
for g_dist
, you can use the
following command to compute the same distance with gmx distance
:
gmx distance -n index.ndx -select 'com of group "A" plus com of group "B"' -oxyz -oall
The -intra
switch is replaced with -nopbc
.
If you used -dist D
, you can do the same calculation with gmx select
:
gmx select -n index.ndx -select 'group "B" and within D of com of group "A"' -on/-oi/-os/-olt
You can select the output option that best suits your post-processing needs
(-olt
is a replacement for g_dist -dist -lt
)
gmx distance#
new
gmx distance has been introduced as a selection-enabled replacement for
various tools that computed distances between fixed pairs of atoms (or
centers-of-mass of groups). It has a combination of the features of g_bond
and g_dist
, allowing computation of one or multiple distances, either
between atom-atom pairs or centers-of-mass of groups, and providing a
combination of output options that were available in one of the tools.
gmx gangle#
new
gmx gangle has been introduced as a selection-enabled replacement for
g_sgangle
. In addition to supporting atom-atom vectors, centers-of-mass
can be used as endpoints of the vectors, and there are a few additional angle
types that can be calculated. The command also has basic support for
calculating normal angles between three atoms and/or centers-of-mass, making it
a partial replacement for gmx angle as well.
gmx protonate#
replaced
This was a very old tool originally written for united atom force fields, where it was necessary to generate all hydrogens after running a trajectory in order to calculate e.g. distance restraint violations. The functionality to simply protonate a structure is available in gmx pdb2gmx. If there is significant interest, we might reintroduce it after moving to new topology formats in the future.
gmx freevolume#
new
This tool has been introduced in 5.0. It uses a Monte Carlo sampling method to calculate the fraction of free volume within the box (using a probe of a given size).
g_sas#
rewritten
This tool has been rewritten in 5.0, and renamed to gmx sasa (the underlying surface area calculation algorithm is still the same).
The main difference in the new tool is support for selections. Instead of
prompting for an index group, a (potentially dynamic) selection for the
calculation can be given with -surface
. Any number of output groups can be
given with -output
, allowing multiple parts of the surface area to be
computed in a single run. The total area of the -surface
group is now
always calculated.
The tool no longer automatically divides the surface into hydrophobic and
hydrophilic areas, and there is no -f_index
option. The same effects can
be obtained by defining suitable selections for -output
. If you want
output that contains the same numbers as with the old tool for a calculation
group A
and output group B
, you can use
gmx sasa -surface 'group "A"' -output '"Hydrophobic" group "A" and charge {-0.2 to 0.2}; "Hydrophilic" group "B" and not charge {-0.2 to 0.2}; "Total" group "B"'
Solvation free energy estimates are now calculated only if separately requested
with -odg
, and are written into a separate file.
Output option -i
for a position restraint file is not currently implemented
in the new tool, but would not be very difficult to add if requested.
g_sgangle#
replaced
This tool has been removed in 5.0. A replacement is gmx gangle (for
angle calculation) and gmx distance (for -od
, -od1
, -od2
).
If you had index groups A and B in index.ndx for g_sgangle
, you can use the
following command to compute the same angle with gmx gangle
:
gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 vector/plane -group2 'group "B"' -oav
You need to select either vector
or plane
for the -g1
and -g2
options depending on which one your index groups specify.
If you only had a single index group A in index.ndx and you used g_sgangle
-z
or -one
, you can use:
gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 z/t0 -oav
For the distances, you can use gmx distance to compute one or more distances as you want. Both distances between centers of groups or individual atoms are supported using the new selection syntax.
genbox#
This tool has been split to gmx solvate and gmx insert-molecules.
tpbconv#
This tool has been renamed gmx convert-tpr.