USER-DPD: Added support to use VV integrator with USER-DPD if desired.

Includes documentation and examples.
NOTE: VV requires very small timesteps under isoenergetic conditions.
Consider using fix_shardlow instead, since this VV support is
primarily for comparison purposes.

doc/src/Eqs/pair_dpd_conservative.tex

@@ -1,9 +0,0 @@
-\documentclass[12pt]{article}
-\pagestyle{empty}
-\begin{document}
-
-$$
-F^C = A \omega_{ij} \qquad \qquad r_{ij} < r_c
-$$
-
-\end{document}

doc/src/Eqs/pair_dpd_energy.tex

@@ -0,0 +1,12 @@
+\documentclass[12pt]{article}
+\pagestyle{empty}
+\begin{document}
+
+\begin{eqnarray*}
+  du_{i}^{cond} & = & \kappa_{ij}(\frac{1}{\theta_{i}}-\frac{1}{\theta_{j}})\omega_{ij}^{2} + \alpha_{ij}\omega_{ij}\zeta_{ij}^{q}(\Delta{t})^{-1/2} \\
+  du_{i}^{mech} & = & -\frac{1}{2}\gamma_{ij}\omega_{ij}^{2}(\frac{\vec{r_{ij}}}{r_{ij}}\bullet\vec{v_{ij}})^{2} - 
+  \frac{\sigma^{2}_{ij}}{4}(\frac{1}{m_{i}}+\frac{1}{m_{j}})\omega_{ij}^{2} - 
+  \frac{1}{2}\sigma_{ij}\omega_{ij}(\frac{\vec{r_{ij}}}{r_{ij}}\bullet\vec{v_{ij}})\zeta_{ij}(\Delta{t})^{-1/2} \\
+\end{eqnarray*}                           
+
+\end{document}

doc/src/Eqs/pair_dpd_energy_terms.tex

@@ -0,0 +1,11 @@
+\documentclass[12pt]{article}
+\pagestyle{empty}
+\begin{document}
+
+\begin{eqnarray*}
+  \alpha_{ij}^{2} & = & 2k_{B}\kappa_{ij} \\
+  \sigma^{2}_{ij} & = & 2\gamma_{ij}k_{B}\Theta_{ij} \\
+  \Theta_{ij}^{-1} & = & \frac{1}{2}(\frac{1}{\theta_{i}}+\frac{1}{\theta_{j}}) \\
+\end{eqnarray*}                           
+
+\end{document}

doc/src/fix_dpd_energy.txt

@@ -0,0 +1,83 @@
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+fix dpd/energy command :h3
+
+[Syntax:]
+
+fix ID group-ID dpd/energy :pre
+
+ID, group-ID are documented in "fix"_fix.html command
+dpd/energy = style name of this fix command :ul
+
+[Examples:]
+
+fix 1 all dpd/energy :pre
+
+[Description:]
+
+Perform constant energy dissipative particle dynamics (DPD-E) integration.
+The fix {dpd/energy} updates the internal energies for particles in the group 
+at each timestep.  The fix {dpd/energy} must be used in conjunction with a 
+deterministic integrator (e.g. "fix nve"_fix_nve.html) that updates 
+the particle positions and velocities.
+
+For fix {dpd/energy}, the particle internal temperature is related to 
+the particle internal energy through a mesoparticle equation of state.  
+An additional fix must be specified that defines the equation of state 
+for each particle, e.g. "fix eos/cv"_fix_eos_cv.html.
+
+The fix {dpd/energy} must be used with the "pair_style
+dpd/fdt/energy"_pair_style.html command.
+
+Note that numerous variants of DPD can be specified by choosing an
+appropriate combination of the integrator and "pair_style
+dpd/fdt/energy"_pair_style.html command.  DPD under isoenergetic conditions 
+can be specified by using fix {dpd/energy}, fix {nve} and pair_style
+{dpd/fdt/energy}.  DPD under isoenthalpic conditions can
+be specified by using fix {dpd/energy}, fix {nph} and pair_style
+{dpd/fdt/energy}.  Examples of each DPD variant are provided in the
+examples/USER/dpd directory.
+
+:line
+
+[Restrictions:] 
+
+This command is part of the USER-DPD package.  It is only enabled if
+LAMMPS was built with that package.  See the "Making
+LAMMPS"_Section_start.html#start_3 section for more info.
+
+This fix must be used with an additional fix that specifies time
+integration, e.g. "fix nve"_fix_nve.html.
+
+The fix {dpd/energy} requires the {dpd} "atom_style"_atom_style.html 
+to be used in order to properly account for the particle internal 
+energies and temperature.
+
+The fix {dpd/energy} must be used with an additional fix that specifies the 
+mesoparticle equation of state for each particle.
+
+[Related commands:]
+
+"fix nve"_fix_nve.html "fix eos/cv"_fix_eos_cv.html
+
+[Default:] none
+
+:line
+
+:link(Lisal)
+[(Lisal)] M. Lisal, J.K. Brennan, J. Bonet Avalos, "Dissipative
+particle dynamics at isothermal, isobaric, isoenergetic, and
+isoenthalpic conditions using Shardlow-like splitting algorithms.",
+J. Chem. Phys., 135, 204105 (2011).
+
+:link(Larentzos)
+[(Larentzos)] J.P. Larentzos, J.K. Brennan, J.D. Moore, and
+W.D. Mattson, "LAMMPS Implementation of Constant Energy Dissipative
+Particle Dynamics (DPD-E)", ARL-TR-6863, U.S. Army Research
+Laboratory, Aberdeen Proving Ground, MD (2014).

doc/src/pair_dpd_fdt.txt

@@ -33,78 +33,95 @@ pair_coeff * * 3.0 1.0 0.1 2.5 :pre
 
 [Description:]
 
-Styles {dpd/fdt} and {dpd/fdt/energy} set the fluctuation-dissipation
-theorem parameters and compute the conservative force for dissipative
-particle dynamics (DPD). The conservative force on atom I due to atom
-J is given by
+Styles {dpd/fdt} and {dpd/fdt/energy} compute the force for dissipative 
+particle dynamics (DPD) simulations.  The {dpd/fdt} style is used to 
+perform DPD simulations under isothermal and isobaric conditions, 
+while the {dpd/fdt/energy} style is used to perform DPD simulations 
+under isoenergetic and isoenthalpic conditions (see "(Lisal)"_#Lisal). 
+For DPD simulations in general, the force on atom I due to atom J is 
+given as a sum of 3 terms
 
-:c,image(Eqs/pair_dpd_conservative.jpg)
+:c,image(Eqs/pair_dpd.jpg)
 
-where the weighting factor, omega_ij, varies between 0 and 1, and is
-chosen to have the following functional form:
+where Fc is a conservative force, Fd is a dissipative force, and Fr is
+a random force.  Rij is a unit vector in the direction Ri - Rj, Vij is
+the vector difference in velocities of the two atoms = Vi - Vj, alpha
+is a Gaussian random number with zero mean and unit variance, dt is
+the timestep size, and w(r) is a weighting factor that varies between
+0 and 1.  Rc is the cutoff.  The weighting factor, omega_ij, varies 
+between 0 and 1, and is chosen to have the following functional form:
 
 :c,image(Eqs/pair_dpd_omega.jpg)
 
-where Rij is a unit vector in the direction Ri - Rj, and Rc is the
-cutoff.  Note that alternative definitions of the weighting function
-exist, but would have to be implemented as a separate pair style
-command.
+Note that alternative definitions of the weighting function exist, but 
+would have to be implemented as a separate pair style command. 
 
-These pair style differ from the other dpd styles in that the
-dissipative and random forces are not computed within the pair style.
-This style can be combined with the "fix shardlow"_fix_shardlow.html
-to perform the stochastic integration of the dissipative and random
-forces through the Shardlow splitting algorithm approach.
+For style {dpd/fdt}, the fluctuation-dissipation theorem defines gamma
+to be set equal to sigma*sigma/(2 T), where T is the set point
+temperature specified as a pair style parameter in the above examples.
+The following coefficients must be defined for each pair of atoms types 
+via the "pair_coeff"_pair_coeff.html command as in the examples above, 
+or in the data file or restart files read by the 
+"read_data"_read_data.html or "read_restart"_read_restart.html commands:
+
+A (force units)
+sigma (force*time^(1/2) units)
+cutoff (distance units) :ul
+
+The last coefficient is optional.  If not specified, the global DPD
+cutoff is used.
+
+Style {dpd/fdt/energy} is used to perform DPD simulations 
+under isoenergetic and isoenthalpic conditions.  The fluctuation-dissipation 
+theorem defines gamma to be set equal to sigma*sigma/(2 dpdTheta), where
+dpdTheta is the average internal temperature for the pair. The particle 
+internal temperature is related to the particle internal energy through 
+a mesoparticle equation of state (see "fix eos"_fix.html). The 
+differential internal conductive and mechanical energies are computed 
+within style {dpd/fdt/energy} as:
+
+:c,image(Eqs/pair_dpd_energy.jpg)
+
+where 
+
+:c,image(Eqs/pair_dpd_energy_terms.jpg)
+
+Zeta_ij^q is a second Gaussian random number with zero mean and unit 
+variance that is used to compute the internal conductive energy. The 
+fluctuation-dissipation theorem defines alpha*alpha to be set
+equal to 2*kB*kappa, where kappa is the mesoparticle thermal
+conductivity parameter.   The following coefficients must be defined for 
+each pair of atoms types via the "pair_coeff"_pair_coeff.html 
+command as in the examples above, or in the data file or restart files 
+read by the "read_data"_read_data.html or "read_restart"_read_restart.html
+commands:
+
+A (force units)
+sigma (force*time^(1/2) units)
+kappa (energy*temperature/time units)
+cutoff (distance units) :ul
+
+The last coefficient is optional.  If not specified, the global DPD
+cutoff is used.
 
 The pairwise energy associated with styles {dpd/fdt} and
 {dpd/fdt/energy} is only due to the conservative force term Fc, and is
 shifted to be zero at the cutoff distance Rc.  The pairwise virial is
 calculated using only the conservative term.
 
-For style {dpd/fdt}, the fluctuation-dissipation theorem defines gamma
-to be set equal to sigma*sigma/(2 T), where T is the set point
-temperature specified as a pair style parameter in the above examples.
-This style can be combined with "fix shardlow"_fix_shardlow.html to
-perform DPD simulations under isothermal and isobaric conditions (see
-"(Lisal)"_#Lisal).  The following coefficients must be defined for
-each pair of atoms types via the "pair_coeff"_pair_coeff.html command
-as in the examples above, or in the data file or restart files read by
-the "read_data"_read_data.html or "read_restart"_read_restart.html
-commands:
-
-A (force units)
-sigma (force*time^(1/2) units)
-cutoff (distance units) :ul
-
-The last coefficient is optional.  If not specified, the global DPD
-cutoff is used.
-
-For style {dpd/fdt/energy}, the fluctuation-dissipation theorem
-defines gamma to be set equal to sigma*sigma/(2 dpdTheta), where
-dpdTheta is the average internal temperature for the pair.
-Furthermore, the fluctuation-dissipation defines alpha*alpha to be set
-equal to 2*kB*kappa, where kappa is the mesoparticle thermal
-conductivity parameter.  This style can be combined with "fix
-shardlow"_fix_shardlow.html to perform DPD simulations under
-isoenergetic and isoenthalpic conditions (see "(Lisal)"_#Lisal).  The
-following coefficients must be defined for each pair of atoms types
-via the "pair_coeff"_pair_coeff.html command as in the examples above,
-or in the data file or restart files read by the
-"read_data"_read_data.html or "read_restart"_read_restart.html
-commands:
-
-A (force units)
-sigma (force*time^(1/2) units)
-kappa (1/time units)
-cutoff (distance units) :ul
-
-The last coefficient is optional.  If not specified, the global DPD
-cutoff is used.
-
-For style {dpd/fdt/energy}, the particle internal temperature is
-related to the particle internal energy through a mesoparticle
-equation of state.  Thus, an an additional "fix eos"_fix.html must be
-specified.
+The forces computed through the {dpd/fdt} and {dpd/fdt/energy} styles 
+can be integrated with the velocity-Verlet integration scheme or the
+Shardlow splitting integration scheme described by "(Lisal)"_#Lisal.  
+In the cases when these pair styles are combined with the 
+"fix shardlow"_fix_shardlow.html, these pair styles differ from the 
+other dpd styles in that the dissipative and random forces are split
+from the force calculation and are not computed within the pair style. 
+Thus, only the conservative force is computed by the pair style, 
+while the stochastic integration of the dissipative and random forces 
+are handled through the Shardlow splitting algorithm approach.  The 
+Shardlow splitting algorithm is advantageous, especially when 
+performing DPD under isoenergetic conditions, as it allows 
+significantly larger timesteps to be taken.
 
 :line
 
@@ -115,7 +132,7 @@ enabled if LAMMPS was built with that package.  See the "Making
 LAMMPS"_Section_start.html#start_3 section for more info.
 
 Pair styles {dpd/fdt} and {dpd/fdt/energy} require use of the
-"comm_modify vel yes"_comm_modify.html option so that velocites are
+"communicate vel yes"_communicate.html option so that velocites are
 stored by ghost atoms.
 
 Pair style {dpd/fdt/energy} requires "atom_style dpd"_atom_style.html
@@ -132,6 +149,6 @@ energies and temperatures.
 
 :link(Lisal)
 [(Lisal)] M. Lisal, J.K. Brennan, J. Bonet Avalos, "Dissipative
-particle dynamics as isothermal, isobaric, isoenergetic, and
+particle dynamics at isothermal, isobaric, isoenergetic, and
 isoenthalpic conditions using Shardlow-like splitting algorithms.",
 J. Chem. Phys., 135, 204105 (2011).