Implement user guide

[alexxy/gromacs.git] / docs / manual / defunits.tex

diff --git a/docs/manual/defunits.tex b/docs/manual/defunits.tex
index 41d546a859f047c20ec3a3862d5e28763c6f7078..401d3d607930e3da15a2637faafdcf9086e1897e 100644 (file)
--- a/docs/manual/defunits.tex
+++ b/docs/manual/defunits.tex
@@ -1,7 +1,7 @@
 %
 % This file is part of the GROMACS molecular simulation package.
 %
-% Copyright (c) 2013,2014, by the GROMACS development team, led by
+% Copyright (c) 2013,2014,2015, by the GROMACS development team, led by
 % Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
 % and including many others, as listed in the AUTHORS file in the
 % top-level source directory and at http://www.gromacs.org.
@@ -217,5 +217,53 @@ Density            & $\rho^*$      & N $\sigma ^3~V^{-1}$          \\
 \end{table}
 
 
+\section{Mixed or Double precision}
+{\gromacs} can be compiled in either mixed\index{mixed
+precision|see{precision, mixed}}\index{precision, mixed} or
+\pawsindex{double}{precision}. Documentation of previous {\gromacs}
+versions referred to ``single precision'', but the implementation
+has made selective use of double precision for many years.
+Using single precision
+for all variables would lead to a significant reduction in accuracy.
+Although in ``mixed precision'' all state vectors, i.e. particle coordinates,
+velocities and forces, are stored in single precision, critical variables
+are double precision. A typical example of the latter is the virial,
+which is a sum over all forces in the system, which have varying signs.
+In addition, in many parts of the code we managed to avoid double precision
+for arithmetic, by paying attention to summation order or reorganization
+of mathematical expressions. The default configuration uses mixed precision,
+but it is easy to turn on double precision by adding the option
+{\tt -DGMX_DOUBLE=on} to {\tt cmake}. Double precision
+will be 20 to 100\% slower than mixed precision depending on the
+architecture you are running on. Double precision will use somewhat
+more memory and run input, energy and full-precision trajectory files
+will be almost twice as large.
+
+The energies in mixed precision are accurate up to the last decimal,
+the last one or two decimals of the forces are non-significant.
+The virial is less accurate than the forces, since the virial is only one
+order of magnitude larger than the size of each element in the sum over
+all atoms (\secref{virial}).
+In most cases this is not really a problem, since the fluctuations in the
+virial can be two orders of magnitude larger than the average.
+Using cut-offs for the Coulomb interactions cause large errors
+in the energies, forces, and virial.
+Even when using a reaction-field or lattice sum method, the errors
+are larger than, or comparable to, the errors due to the partial use of
+single precision.
+Since MD is chaotic, trajectories with very similar starting conditions will
+diverge rapidly, the divergence is faster in mixed precision than in double
+precision.
+
+For most simulations, mixed precision is accurate enough.
+In some cases double precision is required to get reasonable results:
+\begin{itemize}
+\item normal mode analysis,
+for the conjugate gradient or l-bfgs minimization and the calculation and
+diagonalization of the Hessian
+\item long-term energy conservation, especially for large systems
+\end{itemize}
+
+
 % LocalWords:  ij basicunits derivedunits kJ mol mV kcal consts LJ BT
 % LocalWords:  nm ps