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

See Selection syntax and usage.

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 modifed 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 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 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 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 convert-trj

Converts between different trajectory types

gmx distance

Calculate distances between pairs of positions

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 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 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 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 topic on the command line.

Selection syntax and usage

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