.. _gmx msd:

gmx msd
=======

Synopsis
--------

.. parsed-literal::

    gmx msd [:strong:`-f` :emphasis:`[<.xtc/.trr/...>]`] [:strong:`-s` :emphasis:`[<.tpr/.gro/...>]`] [:strong:`-n` :emphasis:`[<.ndx>]`]
            [:strong:`-o` :emphasis:`[<.xvg>]`] [:strong:`-mol` :emphasis:`[<.xvg>]`] [:strong:`-b` :emphasis:`<time>`] [:strong:`-e` :emphasis:`<time>`]
            [:strong:`-dt` :emphasis:`<time>`] [:strong:`-tu` :emphasis:`<enum>`] [:strong:`-fgroup` :emphasis:`<selection>`] [:strong:`-xvg` :emphasis:`<enum>`]
            [:strong:`-[no]rmpbc`] [:strong:`-[no]pbc`] [:strong:`-sf` :emphasis:`<file>`] [:strong:`-selrpos` :emphasis:`<enum>`]
            [:strong:`-seltype` :emphasis:`<enum>`] [:strong:`-sel` :emphasis:`<selection>`] [:strong:`-type` :emphasis:`<enum>`]
            [:strong:`-lateral` :emphasis:`<enum>`] [:strong:`-trestart` :emphasis:`<real>`] [:strong:`-maxtau` :emphasis:`<real>`]
            [:strong:`-beginfit` :emphasis:`<real>`] [:strong:`-endfit` :emphasis:`<real>`]

Description
-----------

``gmx msd`` computes the mean square displacement (MSD) of atoms from
a set of initial positions. This provides an easy way to compute
the diffusion constant using the Einstein relation.
The time between the reference points for the MSD calculation
is set with ``-trestart``.
The diffusion constant is calculated by least squares fitting a
straight line (D*t + c) through the MSD(t) from ``-beginfit`` to
``-endfit`` (note that t is time from the reference positions,
not simulation time). An error estimate given, which is the difference
of the diffusion coefficients obtained from fits over the two halves
of the fit interval.

There are three, mutually exclusive, options to determine different
types of mean square displacement: ``-type``, ``-lateral``
and ``-ten``. Option ``-ten`` writes the full MSD tensor for
each group, the order in the output is: trace xx yy zz yx zx zy.

If ``-mol`` is set, ``gmx msd`` plots the MSD for individual molecules
(including making molecules whole across periodic boundaries):
for each individual molecule a diffusion constant is computed for
its center of mass. The chosen index group will be split into
molecules. With -mol, only one index group can be selected.

The diffusion coefficient is determined by linear regression of the MSD.
When ``-beginfit`` is -1, fitting starts at 10%
and when ``-endfit`` is -1, fitting goes to 90%.
Using this option one also gets an accurate error estimate
based on the statistics between individual molecules.
Note that this diffusion coefficient and error estimate are only
accurate when the MSD is completely linear between
``-beginfit`` and ``-endfit``.

By default, ``gmx msd`` compares all trajectory frames against every frame stored at
``-trestart`` intervals, so the number of frames stored scales linearly with the
number of frames processed. This can lead to long analysis times and out-of-memory errors
for long/large trajectories, and often the data at higher time deltas lacks sufficient
sampling, often manifesting as a wobbly line on the MSD plot after a straighter region at
lower time deltas. The ``-maxtau`` option can be used to cap the maximum time delta
for frame comparison, which may improve performance and can be used to avoid
out-of-memory issues.

Options
-------

Options to specify input files:

``-f`` [<.xtc/.trr/...>] (traj.xtc) (Optional)
    Input trajectory or single configuration: :ref:`xtc` :ref:`trr` :ref:`cpt` :ref:`gro` :ref:`g96` :ref:`pdb` :ref:`tng`
``-s`` [<.tpr/.gro/...>] (topol.tpr) (Optional)
    Input structure: :ref:`tpr` :ref:`gro` :ref:`g96` :ref:`pdb` brk ent
``-n`` [<.ndx>] (index.ndx) (Optional)
    Extra index groups

Options to specify output files:

``-o`` [<.xvg>] (msdout.xvg) (Optional)
    MSD output
``-mol`` [<.xvg>] (diff_mol.xvg) (Optional)
    Report diffusion coefficients for each molecule in selection

Other options:

``-b`` <time> (0)
    First frame (ps) to read from trajectory
``-e`` <time> (0)
    Last frame (ps) to read from trajectory
``-dt`` <time> (0)
    Only use frame if t MOD dt == first time (ps)
``-tu`` <enum> (ps)
    Unit for time values: fs, ps, ns, us, ms, s
``-fgroup`` <selection>
    Atoms stored in the trajectory file (if not set, assume first N atoms)
``-xvg`` <enum> (xmgrace)
    Plot formatting: xmgrace, xmgr, none
``-[no]rmpbc``  (yes)
    Make molecules whole for each frame
``-[no]pbc``  (yes)
    Use periodic boundary conditions for distance calculation
``-sf`` <file>
    Provide selections from files
``-selrpos`` <enum> (atom)
    Selection reference positions: atom, res_com, res_cog, mol_com, mol_cog, whole_res_com, whole_res_cog, whole_mol_com, whole_mol_cog, part_res_com, part_res_cog, part_mol_com, part_mol_cog, dyn_res_com, dyn_res_cog, dyn_mol_com, dyn_mol_cog
``-seltype`` <enum> (atom)
    Default selection output positions: atom, res_com, res_cog, mol_com, mol_cog, whole_res_com, whole_res_cog, whole_mol_com, whole_mol_cog, part_res_com, part_res_cog, part_mol_com, part_mol_cog, dyn_res_com, dyn_res_cog, dyn_mol_com, dyn_mol_cog
``-sel`` <selection>
    Selections to compute MSDs for from the reference
``-type`` <enum> (unused)
    : x, y, z, unused
``-lateral`` <enum> (unused)
    : x, y, z, unused
``-trestart`` <real> (10)
    Time between restarting points in trajectory (ps)
``-maxtau`` <real> (1.79769e+308)
    Maximum time delta between frames to calculate MSDs for (ps)
``-beginfit`` <real> (-1)
    Time point at which to start fitting.
``-endfit`` <real> (-1)
    End time for fitting.

.. only:: man

   See also
   --------

   :manpage:`gmx(1)`

   More information about |Gromacs| is available at <http://www.gromacs.org/>.