.. _gmx rdf:

gmx rdf
=======

Synopsis
--------

.. parsed-literal::

    gmx rdf [:strong:`-f` :emphasis:`[<.xtc/.trr/...>]`] [:strong:`-s` :emphasis:`[<.tpr/.gro/...>]`] [:strong:`-n` :emphasis:`[<.ndx>]`]
            [:strong:`-o` :emphasis:`[<.xvg>]`] [:strong:`-cn` :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:`-bin` :emphasis:`<real>`] [:strong:`-norm` :emphasis:`<enum>`] [:strong:`-[no]xy`]
            [:strong:`-[no]excl`] [:strong:`-cut` :emphasis:`<real>`] [:strong:`-rmax` :emphasis:`<real>`] [:strong:`-surf` :emphasis:`<enum>`]
            [:strong:`-ref` :emphasis:`<selection>`] [:strong:`-sel` :emphasis:`<selection>`]

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

``gmx rdf`` calculates radial distribution functions from one
reference set of position (set with ``-ref``) to one or more
sets of positions (set with ``-sel``).  To compute the RDF with
respect to the closest position in a set in ``-ref`` instead, use
``-surf``: if set, then ``-ref`` is partitioned into sets
based on the value of ``-surf``, and the closest position in each
set is used. To compute the RDF around axes parallel to the
*z*-axis, i.e., only in the *x*-*y* plane, use
``-xy``.

To set the bin width and maximum distance to use in the RDF, use
``-bin`` and ``-rmax``, respectively. The latter can be
used to limit the computational cost if the RDF is not of interest
up to the default (half of the box size with PBC, three times the
box size without PBC).

To use exclusions from the topology (``-s``), set ``-excl``
and ensure that both ``-ref`` and ``-sel`` only select atoms.
A rougher alternative to exclude intra-molecular peaks is to set
``-cut`` to a non-zero value to clear the RDF at small
distances.

The RDFs are normalized by 1) average number of positions in
``-ref`` (the number of groups with ``-surf``), 2) volume
of the bin, and 3) average particle density of ``-sel`` positions
for that selection. To change the normalization, use ``-norm``:

* ``rdf``: Use all factors for normalization.
  This produces a normal RDF.
* ``number_density``: Use the first two factors.
  This produces a number density as a function of distance.
* ``none``: Use only the first factor.
  In this case, the RDF is only scaled with the bin width to make
  the integral of the curve represent the number of pairs within a
  range.

Note that exclusions do not affect the normalization: even if
``-excl`` is set, or ``-ref`` and
``-sel`` contain the same selection, the normalization factor
is still N*M, not N*(M-excluded).

For ``-surf``, the selection provided to ``-ref`` must
select atoms, i.e., centers of mass are not supported. Further,
``-nonorm`` is implied, as the bins have irregular shapes and
the volume of a bin is not easily computable.

Option ``-cn`` produces the cumulative number RDF,
i.e. the average number of particles within a distance r.

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>] (rdf.xvg)
    Computed RDFs
``-cn`` [<.xvg>] (rdf_cn.xvg) (Optional)
    Cumulative RDFs

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
``-bin`` <real> (0.002)
    Bin width (nm)
``-norm`` <enum> (rdf)
    Normalization: rdf, number_density, none
``-[no]xy``  (no)
    Use only the x and y components of the distance
``-[no]excl``  (no)
    Use exclusions from topology
``-cut`` <real> (0)
    Shortest distance (nm) to be considered
``-rmax`` <real> (0)
    Largest distance (nm) to calculate
``-surf`` <enum> (no)
    RDF with respect to the surface of the reference: no, mol, res
``-ref`` <selection>
    Reference selection for RDF computation
``-sel`` <selection>
    Selections to compute RDFs for from the reference

.. only:: man

   See also
   --------

   :manpage:`gmx(1)`

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