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 or :command:`gmx mdrun`. Documentation for these can
17 be found at the respective sections below, as well as on man pages (e.g.,
18 :manpage:`gmx-grompp(1)`) and with :samp:`gmx help {command}` or
19 :samp:`gmx {command} -h`.
21 If you've installed an MPI version of |Gromacs|, by default the
22 :command:`gmx` binary is called :command:`gmx_mpi` and you should adapt
25 Command-line interface and conventions
26 --------------------------------------
28 All |Gromacs| commands require an option before any arguments (i.e., all
29 command-line arguments need to be preceded by an argument starting with a
30 dash, and values not starting with a dash are arguments to the preceding
31 option). Most options, except for boolean flags, expect an argument (or
32 multiple in some cases) after the option name.
33 The argument must be a separate command-line argument, i.e., separated by
34 space, as in ``-f traj.xtc``. If more than one argument needs to be given to
35 an option, they should be similarly separated from each other.
36 Some options also have default arguments, i.e., just specifying the option
37 without any argument uses the default argument.
38 If an option is not specified at all, a default value is used; in the case of
39 optional files, the default might be not to use that file (see below).
41 All |Gromacs| command options start with a single dash, whether they are
42 single- or multiple-letter options. However, two dashes are also recognized
45 In addition to command-specific options, some options are handled by the
46 :command:`gmx` wrapper, and can be specified for any command. See
47 :doc:`wrapper binary help </onlinehelp/gmx>` for the list of such options.
48 These options are recognized both before the command name (e.g.,
49 :command:`gmx -quiet grompp`) as well as after the command name (e.g.,
50 :command:`gmx grompp -quiet`).
51 There is also a ``-hidden`` option that can be specified in combination with
52 ``-h`` to show help for advanced/developer-targeted options.
54 Most analysis commands can process a trajectory with fewer atoms than the
55 run input or structure file, but only if the trajectory consists of the
56 first *n* atoms of the run input or structure file.
58 Handling specific types of command-line options
59 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
62 Boolean flags can be specified like ``-pbc`` and negated like ``-nopbc``.
63 It is also possible to use an explicit value like ``-pbc no`` and
66 Options that accept files names have features that support using default file
67 names (where the default file name is specific to that option):
69 * If a required option is not set, the default is used.
70 * If an option is marked optional, the file is not used unless the option
71 is set (or other conditions make the file required).
72 * If an option is set, and no file name is provided, the default is used.
74 All such options will accept file names without a file extension.
75 The extension is automatically appended in such a case.
76 When multiple input formats are accepted, such as a generic structure format,
77 the directory will be searched for files of each type with the supplied or
78 default name. When no file with a recognized extension is found, an error is given.
79 For output files with multiple formats, a default file type will be used.
81 Some file formats can also be read from compressed (:file:`.Z` or
84 Enumerated options (enum) should be used with one of the arguments listed in
85 the option description. The argument may be abbreviated, and the first match
86 to the shortest argument in the list will be selected.
88 Some options accept a vector of values. Either 1 or 3 parameters can be
89 supplied; when only one parameter is supplied the two other values are also
92 See :doc:`/onlinehelp/selections`.
97 .. include:: /fragments/byname.rst
102 .. include:: /fragments/bytopic.rst
107 The information in these topics is also accessible through
108 :samp:`gmx help {topic}` on the command line.
110 Selection syntax and usage
111 ^^^^^^^^^^^^^^^^^^^^^^^^^^
115 /onlinehelp/selections
119 Command changes between versions
120 --------------------------------
122 Starting from |Gromacs| 5.0, some of the analysis commands (and a few other
123 commands as well) have changed significantly.
125 One main driver for this has been that many new tools mentioned below now
126 accept selections through one or more command-line options instead of prompting
127 for a static index group. To take full advantage of selections, the interface
128 to the commands has changed somewhat, and some previous command-line options
129 are no longer present as the same effect can be achieved with suitable
131 Please see :doc:`/onlinehelp/selections` additional information on how to use
134 In the process, some old analysis commands have been removed in favor of more
135 powerful functionality that is available through an alternative tool.
136 For removed or replaced commands, this page documents how to perform the same
137 tasks with new tools.
138 For new commands, a brief note on the available features is given. See the
139 linked help for the new commands for a full description.
141 This section lists only major changes; minor changes like additional/removed
142 options or bug fixes are not typically included.
144 For more information about changed features, please check out the
145 :ref:`release notes <release-notes>`.
155 :ref:`gmx convert-trj` has been introduced as a selection-enabled alternative
156 for exchanging trajectory file format (previously done in :ref:`gmx trjconv`).
163 :ref:`gmx extract-cluster` has been introduced as a selection-enabled way to
164 write sub-trajectories based on the output from a cluster analysis. The
165 corresponding option **-sub** in :ref:`gmx trjconv` has been removed.
175 :ref:`gmx trajectory` has been introduced as a selection-enabled version of
176 :ref:`gmx traj`. It supports output of coordinates, velocities, and/or forces
177 for positions calculated for selections.
182 Analysis on arbitrary subsets of atoms
183 ......................................
185 Tools implemented in the new analysis framework can now operate upon trajectories
186 that match only a subset of the atoms in the input structure file.
193 :ref:`gmx insert-molecules` has gained an option ``-replace`` that makes it
194 possible to insert molecules into a solvated configuration, replacing any
195 overlapping solvent atoms. In a fully solvated box, it is also possible to
196 insert into a certain region of the solvent only by selecting a subset of the
197 solvent atoms (``-replace`` takes a selection that can also contain expressions
198 like ``not within 1 of ...``).
205 The normalization for the output RDF can now also be the radial number density.
212 Removed ``-block``, ``-sort`` and ``-shuffle``.
220 Symbolic links from 5.0 are no longer supported. The only way to invoke a
221 command is through :samp:`gmx {<command>}`.
228 :ref:`gmx pairdist` has been introduced as a selection-enabled replacement for
229 :ref:`gmx mindist` (``gmx mindist`` still exists unchanged). It can calculate
230 min/max pairwise distances between a pair of selections, including, e.g.,
231 per-residue minimum distances or distances from a single point to a set of
232 residue-centers-of-mass.
239 :ref:`gmx rdf` has been rewritten for 5.1 to use selections for specifying the
240 points from which the RDFs are calculated. The interface is mostly the same,
241 except that there are new command-line options to specify the selections.
242 The following additional changes have been made:
244 * ``-com`` and ``-rdf`` options have been removed. Equivalent functionality is
245 available through selections:
247 * ``-com`` can be replaced with a :samp:`com of {<selection>}` as the
249 * ``-rdf`` can be replaced with a suitable set of selections (e.g.,
250 :samp:`res_com of {<selection>}`) and/or using ``-seltype``.
252 * ``-rmax`` option is added to specify a cutoff for the RDFs. If set to a
253 value that is significantly smaller than half the box size, it can speed up
254 the calculation significantly if a grid-based neighborhood search can be
256 * ``-hq`` and ``-fade`` options have been removed, as they are simply
257 postprocessing steps on the raw numbers that can be easily done after the
266 Version 5.0 introduced the :command:`gmx` wrapper binary.
267 For backwards compatibility, this version still creates symbolic links by default for
268 old tools: e.g., ``g_order <options>`` is equivalent to ``gmx order <options>``, and
269 ``g_order`` is simply a symbolic link on the file system.
276 This tool has been removed in 5.0. A replacement is :ref:`gmx distance`.
278 You can provide your existing index file to :ref:`gmx distance`, and it will
279 calculate the same distances. The differences are:
281 * ``-blen`` and ``-tol`` options have different default values.
282 * You can control the output histogram with ``-binw``.
283 * ``-aver`` and ``-averdist`` options are not present. Instead, you can choose
284 between the different things to calculate using ``-oav`` (corresponds to
285 ``-d`` with ``-averdist``), ``-oall`` (corresponds to ``-d`` without
286 ``-averdist``), ``-oh`` (corresponds to ``-o`` with ``-aver``), and
287 ``-oallstat`` (corresponds to ``-l`` without ``-aver``).
289 You can produce any combination of output files. Compared to ``g_bond``,
290 ``gmx distance -oall`` is currently missing labels for the output columns.
297 This tool has been removed in 5.0. A replacement is :ref:`gmx distance` (for
298 most options) or :ref:`gmx select` (for ``-dist`` or ``-lt``).
300 If you had index groups A and B in :file:`index.ndx` for ``g_dist``, you can use the
301 following command to compute the same distance with ``gmx distance``::
303 gmx distance -n index.ndx -select 'com of group "A" plus com of group "B"' -oxyz -oall
305 The ``-intra`` switch is replaced with ``-nopbc``.
307 If you used ``-dist D``, you can do the same calculation with ``gmx select``::
309 gmx select -n index.ndx -select 'group "B" and within D of com of group "A"' -on/-oi/-os/-olt
311 You can select the output option that best suits your post-processing needs
312 (``-olt`` is a replacement for ``g_dist -dist -lt``)
319 :ref:`gmx distance` has been introduced as a selection-enabled replacement for
320 various tools that computed distances between fixed pairs of atoms (or
321 centers-of-mass of groups). It has a combination of the features of ``g_bond``
322 and ``g_dist``, allowing computation of one or multiple distances, either
323 between atom-atom pairs or centers-of-mass of groups, and providing a
324 combination of output options that were available in one of the tools.
331 :ref:`gmx gangle` has been introduced as a selection-enabled replacement for
332 ``g_sgangle``. In addition to supporting atom-atom vectors, centers-of-mass
333 can be used as endpoints of the vectors, and there are a few additional angle
334 types that can be calculated. The command also has basic support for
335 calculating normal angles between three atoms and/or centers-of-mass, making it
336 a partial replacement for :ref:`gmx angle` as well.
343 This was a very old tool originally written for united atom force fields,
344 where it was necessary to generate all hydrogens after running a trajectory
345 in order to calculate e.g. distance restraint violations. The functionality
346 to simply protonate a structure is available in :ref:`gmx pdb2gmx`.
347 If there is significant interest, we might reintroduce it after moving to new
348 topology formats in the future.
355 This tool has been introduced in 5.0. It uses a Monte Carlo sampling method to
356 calculate the fraction of free volume within the box (using a probe of a given
364 This tool has been rewritten in 5.0, and renamed to :ref:`gmx sasa` (the
365 underlying surface area calculation algorithm is still the same).
367 The main difference in the new tool is support for selections. Instead of
368 prompting for an index group, a (potentially dynamic) selection for the
369 calculation can be given with ``-surface``. Any number of output groups can be
370 given with ``-output``, allowing multiple parts of the surface area to be
371 computed in a single run. The total area of the ``-surface`` group is now
374 The tool no longer automatically divides the surface into hydrophobic and
375 hydrophilic areas, and there is no ``-f_index`` option. The same effects can
376 be obtained by defining suitable selections for ``-output``. If you want
377 output that contains the same numbers as with the old tool for a calculation
378 group ``A`` and output group ``B``, you can use ::
380 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"'
382 Solvation free energy estimates are now calculated only if separately requested
383 with ``-odg``, and are written into a separate file.
385 Output option ``-i`` for a position restraint file is not currently implemented
386 in the new tool, but would not be very difficult to add if requested.
393 This tool has been removed in 5.0. A replacement is :ref:`gmx gangle` (for
394 angle calculation) and :ref:`gmx distance` (for ``-od``, ``-od1``, ``-od2``).
396 If you had index groups A and B in index.ndx for ``g_sgangle``, you can use the
397 following command to compute the same angle with ``gmx gangle``::
399 gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 vector/plane -group2 'group "B"' -oav
401 You need to select either ``vector`` or ``plane`` for the ``-g1`` and ``-g2``
402 options depending on which one your index groups specify.
404 If you only had a single index group A in index.ndx and you used ``g_sgangle``
405 ``-z`` or ``-one``, you can use::
407 gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 z/t0 -oav
409 For the distances, you can use :ref:`gmx distance` to compute one or more
410 distances as you want. Both distances between centers of groups or individual
411 atoms are supported using the new selection syntax.
416 This tool has been split to :ref:`gmx solvate` and :ref:`gmx insert-molecules`.
421 This tool has been renamed :ref:`gmx convert-tpr`.