# 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**.
mdrun is the only other binary that
can be built; in the normal
build it can be run with **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 `

or
*command*`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
- See Selection syntax and usage.

## Commands by name¶

- gmx - molecular dynamics simulation suite
- gmx anadock - Cluster structures from Autodock runs
- gmx anaeig - Analyze eigenvectors/normal modes
- gmx analyze - Analyze data sets
- gmx angle - Calculate distributions and correlations for angles and dihedrals
- 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 modifed run-input file
- 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 do_dssp - Assign secondary structure and calculate solvent accessible surface area
- gmx dos - Analyze density of states and properties based on that
- gmx dump - Make binary files human readable
- gmx dyecoupl - Extract dye dynamics from trajectories
- gmx dyndom - Interpolate and extrapolate structure rotations
- 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 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 morph - Interpolate linearly between conformations
- gmx msd - Calculates mean square displacements
- gmx nmeig - Diagonalize the Hessian for normal mode analysis
- gmx nmens - Generate an ensemble of structures from the normal modes
- gmx nmtraj - Generate a virtual oscillating trajectory from an eigenvector
- 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 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 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 view - View a trajectory on an X-Windows terminal
- 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 distance
- Calculate distances between pairs of positions
- gmx freevolume
- Calculate free volume
- 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

### 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 modifed run-input file

### Viewing trajectories¶

- gmx nmtraj
- Generate a virtual oscillating trajectory from an eigenvector
- gmx view
- View a trajectory on an X-Windows terminal

### 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 dyndom
- Interpolate and extrapolate structure rotations
- gmx filter
- Frequency filter trajectories, useful for making smooth movies
- gmx lie
- Estimate free energy from linear combinations
- gmx morph
- Interpolate linearly between conformations
- 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

### 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 msd
- Calculates mean square displacements
- 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 anadock
- Cluster structures from Autodock runs
- 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 do_dssp
- Assign secondary structure and calculate solvent accessible surface area
- 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 `

on the command line.*topic*

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

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

).

### 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 a`com of`

as the reference selection.*<selection>*`-rdf`

can be replaced with a suitable set of selections (e.g.,`res_com of`

) and/or using*<selection>*`-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.