home | help 
GMX-DIPOLES(1)			     GROMACS			  GMX-DIPOLES(1)

NAME
     gmx-dipoles - Compute the total dipole plus fluctuations

SYNOPSIS
	gmx dipoles [-en [<.edr>]] [-f [<.xtc/.trr/...>]] [-s [<.tpr>]]
		    [-n [<.ndx>]] [-o [<.xvg>]] [-eps [<.xvg>]] [-a [<.xvg>]]
		    [-d [<.xvg>]] [-c [<.xvg>]] [-g [<.xvg>]]
		    [-adip [<.xvg>]] [-dip3d [<.xvg>]] [-cos [<.xvg>]]
		    [-cmap [<.xpm>]] [-slab [<.xvg>]] [-b <time>] [-e <time>]
		    [-dt <time>] [-[no]w] [-xvg <enum>] [-mu <real>]
		    [-mumax <real>] [-epsilonRF <real>] [-skip <int>]
		    [-temp <real>] [-corr <enum>] [-[no]pairs] [-[no]quad]
		    [-ncos <int>] [-axis <string>] [-sl <int>]
		    [-gkratom <int>] [-gkratom2 <int>] [-rcmax <real>]
		    [-[no]phi] [-nlevels <int>] [-ndegrees <int>]
		    [-acflen <int>] [-[no]normalize] [-P <enum>]
		    [-fitfn <enum>] [-beginfit <real>] [-endfit <real>]

DESCRIPTION
     gmx  dipoles  computes  the  total dipole plus fluctuations of a simulation
     system. From this you can compute e.g. the dielectric constant for  low-di-
     electric  media.	For  molecules with a net charge, the net charge is sub-
     tracted at center of mass of the molecule.

     The file Mtot.xvg contains the total dipole moment of a frame,  the  compo-
     nents  as	well  as  the  norm  of  the vector.  The file aver.xvg contains
     <|mu|^2> and |<mu>|^2 during the simulation.  The file dipdist.xvg contains
     the distribution of dipole moments during the simulation The value of  -mu-
     max is used as the highest value in the distribution graph.

     Furthermore,  the dipole autocorrelation function will be computed when op-
     tion -corr is used. The output file name is given with the -c option.   The
     correlation functions can be averaged over all molecules (mol), plotted per
     molecule  separately  (molsep)  or it can be computed over the total dipole
     moment of the simulation box (total).

     Option -g produces a plot of the distance dependent Kirkwood  G-factor,  as
     well  as  the average cosine of the angle between the dipoles as a function
     of the distance. The plot also includes gOO and hOO according to  Nymand  &
     Linse,  J.  Chem.	Phys. 112 (2000) pp 6386-6395. In the same plot, we also
     include the energy per scale computed by taking the inner	product  of  the
     dipoles divided by the distance to the third power.

     EXAMPLES

     gmx dipoles -corr mol -P 1 -o dip_sqr -mu 2.273 -mumax 5.0

     This  will  calculate the autocorrelation function of the molecular dipoles
     using a first order Legendre polynomial of the angle of the  dipole  vector
     and  itself  a time t later. For this calculation 1001 frames will be used.
     Further, the dielectric constant will be calculated using an -epsilonRF  of
     infinity  (default),  temperature	of 300 K (default) and an average dipole
     moment of the molecule of 2.273 (SPC). For the distribution function a max-
     imum of 5.0 will be used.

OPTIONS
     Options to specify input files:

     -en [<.edr>] (ener.edr) (Optional)
	    Energy file

     -f [<.xtc/.trr/...>] (traj.xtc)
	    Trajectory: xtc trr cpt gro g96 pdb tng h5md

     -s [<.tpr>] (topol.tpr)
	    Portable xdr run input file

     -n [<.ndx>] (index.ndx) (Optional)
	    Index file

     Options to specify output files:

     -o [<.xvg>] (Mtot.xvg)
	    xvgr/xmgr file

     -eps [<.xvg>] (epsilon.xvg)
	    xvgr/xmgr file

     -a [<.xvg>] (aver.xvg)
	    xvgr/xmgr file

     -d [<.xvg>] (dipdist.xvg)
	    xvgr/xmgr file

     -c [<.xvg>] (dipcorr.xvg) (Optional)
	    xvgr/xmgr file

     -g [<.xvg>] (gkr.xvg) (Optional)
	    xvgr/xmgr file

     -adip [<.xvg>] (adip.xvg) (Optional)
	    xvgr/xmgr file

     -dip3d [<.xvg>] (dip3d.xvg) (Optional)
	    xvgr/xmgr file

     -cos [<.xvg>] (cosaver.xvg) (Optional)
	    xvgr/xmgr file

     -cmap [<.xpm>] (cmap.xpm) (Optional)
	    X PixMap compatible matrix file

     -slab [<.xvg>] (slab.xvg) (Optional)
	    xvgr/xmgr file

     Other options:

     -b <time> (0)
	    Time of first frame to read from trajectory (default unit ps)

     -e <time> (0)
	    Time of last frame to read from trajectory (default unit ps)

     -dt <time> (0)
	    Only use frame when t MOD dt = first time (default unit ps)

     -[no]w (no)
	    View output .xvg, .xpm, .eps and .pdb files

     -xvg <enum> (xmgrace)
	    xvg plot formatting: xmgrace, xmgr, none

     -mu <real> (-1)
	    dipole of a single molecule (in Debye)

     -mumax <real> (5)
	    max dipole in Debye (for histogram)

     -epsilonRF <real> (0)
	    epsilon of the reaction field used during the simulation, needed for
	    dielectric constant calculation. WARNING: 0.0  means  infinity  (de-
	    fault)

     -skip <int> (0)
	    Skip steps in the output (but not in the computations)

     -temp <real> (300)
	    Average  temperature  of  the simulation (needed for dielectric con-
	    stant calculation)

     -corr <enum> (none)
	    Correlation function to calculate: none, mol, molsep, total

     -[no]pairs (yes)
	    Calculate |cos(theta)| between all pairs of molecules. May be slow

     -[no]quad (no)
	    Take quadrupole into account

     -ncos <int> (1)
	    Must be 1 or 2. Determines whether the <cos(theta)> is computed  be-
	    tween  all	molecules in one group, or between molecules in two dif-
	    ferent groups. This turns on the -g flag.

     -axis <string> (Z)
	    Take the normal on the computational box in direction X, Y or Z.

     -sl <int> (10)
	    Divide the box into this number of slices.

     -gkratom <int> (0)
	    Use the n-th atom of a molecule (starting from 1) to  calculate  the
	    distance between molecules rather than the center of charge (when 0)
	    in the calculation of distance dependent Kirkwood factors

     -gkratom2 <int> (0)
	    Same  as  previous	option in case ncos = 2, i.e. dipole interaction
	    between two groups of molecules

     -rcmax <real> (0)
	    Maximum distance to use in the dipole orientation distribution (with
	    ncos == 2). If zero, a criterion based on the  box	length	will  be
	    used.

     -[no]phi (no)
	    Plot  the  'torsion angle' defined as the rotation of the two dipole
	    vectors around the distance vector between the two molecules in  the
	    .xpm  file from the -cmap option. By default the cosine of the angle
	    between the dipoles is plotted.

     -nlevels <int> (20)
	    Number of colors in the cmap output

     -ndegrees <int> (90)
	    Number of divisions on the y-axis in the cmap output  (for	180  de-
	    grees)

     -acflen <int> (-1)
	    Length of the ACF, default is half the number of frames

     -[no]normalize (yes)
	    Normalize ACF

     -P <enum> (0)
	    Order of Legendre polynomial for ACF (0 indicates none): 0, 1, 2, 3

     -fitfn <enum> (none)
	    Fit function: none, exp, aexp, exp_exp, exp5, exp7, exp9

     -beginfit <real> (0)
	    Time where to begin the exponential fit of the correlation function

     -endfit <real> (-1)
	    Time  where  to end the exponential fit of the correlation function,
	    -1 is until the end

SEE ALSO
     gmx(1)

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

COPYRIGHT
     2026, GROMACS development team

2026.3				  Jun 25, 2026			  GMX-DIPOLES(1)
home | help