13 |Gromacs| includes many tools for preparing, running and analyzing
14 molecular dynamics simulations. These are all structured as part of a single
15 :command:`gmx` wrapper binary, and invoked with commands like :command:`gmx grompp`.
16 :ref:`mdrun <gmx mdrun>` is the only other binary that
17 :ref:`can be built <building just the mdrun binary>`; in the normal
18 build it can be run with :command:`gmx mdrun`. Documentation for these can
19 be found at the respective sections below, as well as on man pages (e.g.,
20 :manpage:`gmx-grompp(1)`) and with :samp:`gmx help {command}` or
21 :samp:`gmx {command} -h`.
23 If you've installed an MPI version of |Gromacs|, by default the
24 :command:`gmx` binary is called :command:`gmx_mpi` and you should adapt
27 Command-line interface and conventions
28 --------------------------------------
30 All |Gromacs| commands require an option before any arguments (i.e., all
31 command-line arguments need to be preceded by an argument starting with a
32 dash, and values not starting with a dash are arguments to the preceding
33 option). Most options, except for boolean flags, expect an argument (or
34 multiple in some cases) after the option name.
35 The argument must be a separate command-line argument, i.e., separated by
36 space, as in ``-f traj.xtc``. If more than one argument needs to be given to
37 an option, they should be similarly separated from each other.
38 Some options also have default arguments, i.e., just specifying the option
39 without any argument uses the default argument.
40 If an option is not specified at all, a default value is used; in the case of
41 optional files, the default might be not to use that file (see below).
43 All |Gromacs| command options start with a single dash, whether they are
44 single- or multiple-letter options. However, two dashes are also recognized
47 In addition to command-specific options, some options are handled by the
48 :command:`gmx` wrapper, and can be specified for any command. See
49 :doc:`wrapper binary help </onlinehelp/gmx>` for the list of such options.
50 These options are recognized both before the command name (e.g.,
51 :command:`gmx -quiet grompp`) as well as after the command name (e.g.,
52 :command:`gmx grompp -quiet`).
53 There is also a ``-hidden`` option that can be specified in combination with
54 ``-h`` to show help for advanced/developer-targeted options.
56 Most analysis commands can process a trajectory with fewer atoms than the
57 run input or structure file, but only if the trajectory consists of the
58 first *n* atoms of the run input or structure file.
60 Handling specific types of command-line options
61 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
64 Boolean flags can be specified like ``-pbc`` and negated like ``-nopbc``.
65 It is also possible to use an explicit value like ``-pbc no`` and
68 Options that accept files names have features that support using default file
69 names (where the default file name is specific to that option):
71 * If a required option is not set, the default is used.
72 * If an option is marked optional, the file is not used unless the option
73 is set (or other conditions make the file required).
74 * If an option is set, and no file name is provided, the default is used.
76 All such options will accept file names without a file extension.
77 The extension is automatically appended in such a case.
78 When multiple input formats are accepted, such as a generic structure format,
79 the directory will be searched for files of each type with the supplied or
80 default name. When no file with a recognized extension is found, an error is given.
81 For output files with multiple formats, a default file type will be used.
83 Some file formats can also be read from compressed (:file:`.Z` or
86 Enumerated options (enum) should be used with one of the arguments listed in
87 the option description. The argument may be abbreviated, and the first match
88 to the shortest argument in the list will be selected.
90 Some options accept a vector of values. Either 1 or 3 parameters can be
91 supplied; when only one parameter is supplied the two other values are also
94 See :doc:`/onlinehelp/selections`.
99 .. include:: /fragments/byname.rst
104 .. include:: /fragments/bytopic.rst
109 The information in these topics is also accessible through
110 :samp:`gmx help {topic}` on the command line.
112 Selection syntax and usage
113 ^^^^^^^^^^^^^^^^^^^^^^^^^^
117 /onlinehelp/selections
121 Command changes between versions
122 --------------------------------
124 Starting from |Gromacs| 5.0, some of the analysis commands (and a few other
125 commands as well) have changed significantly.
127 One main driver for this has been that many new tools mentioned below now
128 accept selections through one or more command-line options instead of prompting
129 for a static index group. To take full advantage of selections, the interface
130 to the commands has changed somewhat, and some previous command-line options
131 are no longer present as the same effect can be achieved with suitable
133 Please see :doc:`/onlinehelp/selections` additional information on how to use
136 In the process, some old analysis commands have been removed in favor of more
137 powerful functionality that is available through an alternative tool.
138 For removed or replaced commands, this page documents how to perform the same
139 tasks with new tools.
140 For new commands, a brief note on the available features is given. See the
141 linked help for the new commands for a full description.
143 This section lists only major changes; minor changes like additional/removed
144 options or bug fixes are not typically included.
146 For more information about changed features, please check out the
147 :ref:`release notes <release-notes>`.
157 :ref:`gmx trajectory` has been introduced as a selection-enabled version of
158 :ref:`gmx traj`. It supports output of coordinates, velocities, and/or forces
159 for positions calculated for selections.
164 Analysis on arbitrary subsets of atoms
165 ......................................
167 Tools implemented in the new analysis framework can now operate upon trajectories
168 that match only a subset of the atoms in the input structure file.
175 :ref:`gmx insert-molecules` has gained an option ``-replace`` that makes it
176 possible to insert molecules into a solvated configuration, replacing any
177 overlapping solvent atoms. In a fully solvated box, it is also possible to
178 insert into a certain region of the solvent only by selecting a subset of the
179 solvent atoms (``-replace`` takes a selection that can also contain expressions
180 like ``not within 1 of ...``).
187 The normalization for the output RDF can now also be the radial number density.
194 Removed ``-block``, ``-sort`` and ``-shuffle``.
202 Symbolic links from 5.0 are no longer supported. The only way to invoke a
203 command is through :samp:`gmx {<command>}`.
210 :ref:`gmx pairdist` has been introduced as a selection-enabled replacement for
211 :ref:`gmx mindist` (``gmx mindist`` still exists unchanged). It can calculate
212 min/max pairwise distances between a pair of selections, including, e.g.,
213 per-residue minimum distances or distances from a single point to a set of
214 residue-centers-of-mass.
221 :ref:`gmx rdf` has been rewritten for 5.1 to use selections for specifying the
222 points from which the RDFs are calculated. The interface is mostly the same,
223 except that there are new command-line options to specify the selections.
224 The following additional changes have been made:
226 * ``-com`` and ``-rdf`` options have been removed. Equivalent functionality is
227 available through selections:
229 * ``-com`` can be replaced with a :samp:`com of {<selection>}` as the
231 * ``-rdf`` can be replaced with a suitable set of selections (e.g.,
232 :samp:`res_com of {<selection>}`) and/or using ``-seltype``.
234 * ``-rmax`` option is added to specify a cutoff for the RDFs. If set to a
235 value that is significantly smaller than half the box size, it can speed up
236 the calculation significantly if a grid-based neighborhood search can be
238 * ``-hq`` and ``-fade`` options have been removed, as they are simply
239 postprocessing steps on the raw numbers that can be easily done after the
248 Version 5.0 introduced the :command:`gmx` wrapper binary.
249 For backwards compatibility, this version still creates symbolic links by default for
250 old tools: e.g., ``g_order <options>`` is equivalent to ``gmx order <options>``, and
251 ``g_order`` is simply a symbolic link on the file system.
258 This tool has been removed in 5.0. A replacement is :ref:`gmx distance`.
260 You can provide your existing index file to :ref:`gmx distance`, and it will
261 calculate the same distances. The differences are:
263 * ``-blen`` and ``-tol`` options have different default values.
264 * You can control the output histogram with ``-binw``.
265 * ``-aver`` and ``-averdist`` options are not present. Instead, you can choose
266 between the different things to calculate using ``-oav`` (corresponds to
267 ``-d`` with ``-averdist``), ``-oall`` (corresponds to ``-d`` without
268 ``-averdist``), ``-oh`` (corresponds to ``-o`` with ``-aver``), and
269 ``-oallstat`` (corresponds to ``-l`` without ``-aver``).
271 You can produce any combination of output files. Compared to ``g_bond``,
272 ``gmx distance -oall`` is currently missing labels for the output columns.
279 This tool has been removed in 5.0. A replacement is :ref:`gmx distance` (for
280 most options) or :ref:`gmx select` (for ``-dist`` or ``-lt``).
282 If you had index groups A and B in :file:`index.ndx` for ``g_dist``, you can use the
283 following command to compute the same distance with ``gmx distance``::
285 gmx distance -n index.ndx -select 'com of group "A" plus com of group "B"' -oxyz -oall
287 The ``-intra`` switch is replaced with ``-nopbc``.
289 If you used ``-dist D``, you can do the same calculation with ``gmx select``::
291 gmx select -n index.ndx -select 'group "B" and within D of com of group "A"' -on/-oi/-os/-olt
293 You can select the output option that best suits your post-processing needs
294 (``-olt`` is a replacement for ``g_dist -dist -lt``)
301 :ref:`gmx distance` has been introduced as a selection-enabled replacement for
302 various tools that computed distances between fixed pairs of atoms (or
303 centers-of-mass of groups). It has a combination of the features of ``g_bond``
304 and ``g_dist``, allowing computation of one or multiple distances, either
305 between atom-atom pairs or centers-of-mass of groups, and providing a
306 combination of output options that were available in one of the tools.
313 :ref:`gmx gangle` has been introduced as a selection-enabled replacement for
314 ``g_sgangle``. In addition to supporting atom-atom vectors, centers-of-mass
315 can be used as endpoints of the vectors, and there are a few additional angle
316 types that can be calculated. The command also has basic support for
317 calculating normal angles between three atoms and/or centers-of-mass, making it
318 a partial replacement for :ref:`gmx angle` as well.
325 This was a very old tool originally written for united atom force fields,
326 where it was necessary to generate all hydrogens after running a trajectory
327 in order to calculate e.g. distance restraint violations. The functionality
328 to simply protonate a structure is available in :ref:`gmx pdb2gmx`.
329 If there is significant interest, we might reintroduce it after moving to new
330 topology formats in the future.
337 This tool has been introduced in 5.0. It uses a Monte Carlo sampling method to
338 calculate the fraction of free volume within the box (using a probe of a given
346 This tool has been rewritten in 5.0, and renamed to :ref:`gmx sasa` (the
347 underlying surface area calculation algorithm is still the same).
349 The main difference in the new tool is support for selections. Instead of
350 prompting for an index group, a (potentially dynamic) selection for the
351 calculation can be given with ``-surface``. Any number of output groups can be
352 given with ``-output``, allowing multiple parts of the surface area to be
353 computed in a single run. The total area of the ``-surface`` group is now
356 The tool no longer automatically divides the surface into hydrophobic and
357 hydrophilic areas, and there is no ``-f_index`` option. The same effects can
358 be obtained by defining suitable selections for ``-output``. If you want
359 output that contains the same numbers as with the old tool for a calculation
360 group ``A`` and output group ``B``, you can use ::
362 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"'
364 Solvation free energy estimates are now calculated only if separately requested
365 with ``-odg``, and are written into a separate file.
367 Output option ``-i`` for a position restraint file is not currently implemented
368 in the new tool, but would not be very difficult to add if requested.
375 This tool has been removed in 5.0. A replacement is :ref:`gmx gangle` (for
376 angle calculation) and :ref:`gmx distance` (for ``-od``, ``-od1``, ``-od2``).
378 If you had index groups A and B in index.ndx for ``g_sgangle``, you can use the
379 following command to compute the same angle with ``gmx gangle``::
381 gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 vector/plane -group2 'group "B"' -oav
383 You need to select either ``vector`` or ``plane`` for the ``-g1`` and ``-g2``
384 options depending on which one your index groups specify.
386 If you only had a single index group A in index.ndx and you used ``g_sgangle``
387 ``-z`` or ``-one``, you can use::
389 gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 z/t0 -oav
391 For the distances, you can use :ref:`gmx distance` to compute one or more
392 distances as you want. Both distances between centers of groups or individual
393 atoms are supported using the new selection syntax.
398 This tool has been split to :ref:`gmx solvate` and :ref:`gmx insert-molecules`.
403 This tool has been renamed :ref:`gmx convert-tpr`.