Updated NH docs

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@3977 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/Eqs/fix_nh1.tex

@@ -0,0 +1,38 @@
+\documentclass[24pt]{article}
+
+\pagestyle{empty}
+\Huge
+
+\begin{document}
+
+\mathchardef\mhyphen="2D
+
+% The imaginary unit
+\providecommand*{\iu}%
+	{\ensuremath{{\rm i}}}
+
+
+$$
+\exp \left(\iu{} L \Delta t \right) =
+\exp \left(\iu{} L_{\rm T\mhyphen baro} \frac{\Delta t}{2} \right)
+\exp \left(\iu{} L_{\rm T\mhyphen part} \frac{\Delta t}{2} \right)
+\exp \left(\iu{} L_{\epsilon , 2} \frac{\Delta t}{2} \right)
+\exp \left(\iu{} L_{2}^{(2)} \frac{\Delta t}{2} \right)
+$$
+$$
+\times \left[ 
+\exp \left(\iu{} L_{2}^{(1)} \frac{\Delta t}{2n} \right)
+\exp \left(\iu{} L_{\epsilon , 1} \frac{\Delta t}{n} \right)
+\exp \left(\iu{} L_1 \frac{\Delta t}{n} \right)
+\exp \left(\iu{} L_{2}^{(1)} \frac{\Delta t}{2n} \right)
+\right]^n
+$$
+$$
+\exp \left(\iu{} L_{2}^{(2)} \frac{\Delta t}{2} \right)
+\exp \left(\iu{} L_{\epsilon , 2} \frac{\Delta t}{2} \right)
+\exp \left(\iu{} L_{\rm T\mhyphen part} \frac{\Delta t}{2} \right)
+\exp \left(\iu{} L_{\rm T\mhyphen baro} \frac{\Delta t}{2} \right)
++ \mathcal{O} \left(\Delta t^3 \right)
+$$
+
+\end{document}

doc/fix_nh.html

@@ -73,13 +73,13 @@ When used correctly, the time-averaged temperature and stress tensor
 of the particles will match the target values specified by
 Tstart/Tstop and Pstart/Pstop.
 </P>
-<P>The equations of motion used are those of Shinoda et al in
+<P>The equations of motion used are those of Shinoda et al. in
 <A HREF = "#Shinoda">(Shinoda)</A>, which combine the hydrostatic equations of
 Martyna, Tobias and Klein in <A HREF = "#Martyna">(Martyna)</A> with the strain
 energy proposed by Parrinello and Rahman in
-<A HREF = "#Parrinello">(Parrinello)</A>.  The time integration schemes follow the
-time-reversible measure-preserving integrators derived by Tuckerman et
-al in <A HREF = "#Tuckerman">(Tuckerman)</A>.
+<A HREF = "#Parrinello">(Parrinello)</A>.  The time integration schemes closely 
+follow the time-reversible measure-preserving Verlet and 
+rRESPA integrators derived by Tuckerman et al. in <A HREF = "#Tuckerman">(Tuckerman)</A>. 
 </P>
 <HR>
 
@@ -386,19 +386,19 @@ simulation, otherwise its value is 3.
 follows.  The notation means there are tchain values for eta, followed
 by tchain for eta_dot, followed by ndof for omega, etc:
 </P>
-<UL><LI>eta<B>tchain</B> = particle thermostat displacements
-<LI>eta_dot<B>tchain</B> = particle thermostat velocities
-<LI>omega<B>ndof</B> = barostat displacements
-<LI>omega_dot<B>ndof</B> = barostat velocities
-<LI>etap<B>pchain</B> = barostat thermostat displacements
-<LI>etap_dot<B>pchain</B> = barostat thermostat velocities
-<LI>PE_eta<B>tchain</B> = potential energy of each particle thermostat displacement
-<LI>KE_eta_dot<B>tchain</B> = kinetic energy of each particle thermostat velocity
-<LI>PE_omega<B>ndof</B> = potential energy of each barostat displacement
-<LI>KE_omega_dot<B>ndof</B> = kinetic energy of each barostat velocity
-<LI>PE_etap<B>pchain</B> = potential energy of each barostat thermostat displacement
-<LI>KE_etap_dot<B>pchain</B> = kinetic energy of each barostat thermostat velocity
-<LI>PE_strain<B>1</B> = scalar strain energy 
+<UL><LI>eta[tchain] = particle thermostat displacements
+<LI>eta_dot[tchain] = particle thermostat velocities
+<LI>omega[ndof] = barostat displacements
+<LI>omega_dot[ndof] = barostat velocities
+<LI>etap[pchain] = barostat thermostat displacements
+<LI>etap_dot[pchain] = barostat thermostat velocities
+<LI>PE_eta[tchain] = potential energy of each particle thermostat displacement
+<LI>KE_eta_dot[tchain] = kinetic energy of each particle thermostat velocity
+<LI>PE_omega[ndof] = potential energy of each barostat displacement
+<LI>KE_omega_dot[ndof] = kinetic energy of each barostat velocity
+<LI>PE_etap[pchain] = potential energy of each barostat thermostat displacement
+<LI>KE_etap_dot[pchain] = kinetic energy of each barostat thermostat velocity
+<LI>PE_strain[1] = scalar strain energy 
 </UL>
 <P>These fixes can ramp their external temperature and pressure over
 multiple runs, using the <I>start</I> and <I>stop</I> keywords of the
@@ -408,6 +408,25 @@ how to do this.
 <P>These fixes are not invoked during <A HREF = "minimize.html">energy
 minimization</A>.
 </P>
+<P>These fixes can be used with either the <I>verlet</I> or <I>respa</I> 
+<A HREF = "run_style.html">integrators</A>. When using one of the barostat fixes
+with <I>respa</I>, LAMMPS uses an integrator constructed
+according to the following factorization of the Liouville propagator
+(for two rRESPA levels):
+</P>
+<CENTER><IMG SRC = "Eqs/fix_nh1.jpg">
+</CENTER>
+<P>This factorization differs somewhat from that of Tuckerman et al., in that
+the barostat is only updated at the outermost rRESPA level, whereas
+Tuckerman's factorization requires splitting the pressure into pieces
+corresponding to the forces computed at each rRESPA level. In theory, the
+latter method will exhibit better numerical stability. In practice,
+because Pdamp is normally chosen to be a large multiple of the 
+outermost rRESPA timestep, the barostat dynamics are not the 
+limiting factor for numerical stability. Both 
+factorizations are time-reversible and can be shown to preserve the phase 
+space measure of the underlying non-Hamiltonian equations of motion.
+</P>
 <P><B>Restrictions:</B>
 </P>
 <P>Non-periodic dimensions cannot be barostatted.  <I>Z</I>, <I>xz</I>, and <I>yz</I>,
@@ -425,7 +444,7 @@ is not allowed in the Nose/Hoover formulation.
 </P>
 <P><B>Related commands:</B>
 </P>
-<P><A HREF = "fix_nve.html">fix nve</A>, <A HREF = "fix_modify.html">fix_modify</A>
+<P><A HREF = "fix_nve.html">fix nve</A>, <A HREF = "fix_modify.html">fix_modify</A>, <A HREF = "run_style.html">run_style</A>
 </P>
 <P><B>Default:</B>
 </P>

doc/fix_nh.txt

@@ -65,13 +65,13 @@ When used correctly, the time-averaged temperature and stress tensor
 of the particles will match the target values specified by
 Tstart/Tstop and Pstart/Pstop.
 
-The equations of motion used are those of Shinoda et al in
+The equations of motion used are those of Shinoda et al. in
 "(Shinoda)"_#Shinoda, which combine the hydrostatic equations of
 Martyna, Tobias and Klein in "(Martyna)"_#Martyna with the strain
 energy proposed by Parrinello and Rahman in
-"(Parrinello)"_#Parrinello.  The time integration schemes follow the
-time-reversible measure-preserving integrators derived by Tuckerman et
-al in "(Tuckerman)"_#Tuckerman.
+"(Parrinello)"_#Parrinello.  The time integration schemes closely 
+follow the time-reversible measure-preserving Verlet and 
+rRESPA integrators derived by Tuckerman et al. in "(Tuckerman)"_#Tuckerman. 
 
 :line
 
@@ -378,19 +378,19 @@ The order of values in the global vector and their meaning is as
 follows.  The notation means there are tchain values for eta, followed
 by tchain for eta_dot, followed by ndof for omega, etc:
 
-eta[tchain] = particle thermostat displacements
-eta_dot[tchain] = particle thermostat velocities
-omega[ndof] = barostat displacements
-omega_dot[ndof] = barostat velocities
-etap[pchain] = barostat thermostat displacements
-etap_dot[pchain] = barostat thermostat velocities
-PE_eta[tchain] = potential energy of each particle thermostat displacement
-KE_eta_dot[tchain] = kinetic energy of each particle thermostat velocity
-PE_omega[ndof] = potential energy of each barostat displacement
-KE_omega_dot[ndof] = kinetic energy of each barostat velocity
-PE_etap[pchain] = potential energy of each barostat thermostat displacement
-KE_etap_dot[pchain] = kinetic energy of each barostat thermostat velocity
-PE_strain[1] = scalar strain energy :ul
+eta\[tchain\] = particle thermostat displacements
+eta_dot\[tchain\] = particle thermostat velocities
+omega\[ndof\] = barostat displacements
+omega_dot\[ndof\] = barostat velocities
+etap\[pchain\] = barostat thermostat displacements
+etap_dot\[pchain\] = barostat thermostat velocities
+PE_eta\[tchain\] = potential energy of each particle thermostat displacement
+KE_eta_dot\[tchain\] = kinetic energy of each particle thermostat velocity
+PE_omega\[ndof\] = potential energy of each barostat displacement
+KE_omega_dot\[ndof\] = kinetic energy of each barostat velocity
+PE_etap\[pchain\] = potential energy of each barostat thermostat displacement
+KE_etap_dot\[pchain\] = kinetic energy of each barostat thermostat velocity
+PE_strain\[1\] = scalar strain energy :ul
 
 These fixes can ramp their external temperature and pressure over
 multiple runs, using the {start} and {stop} keywords of the
@@ -400,6 +400,26 @@ how to do this.
 These fixes are not invoked during "energy
 minimization"_minimize.html.
 
+These fixes can be used with either the {verlet} or {respa} 
+"integrators"_run_style.html. When using one of the barostat fixes
+with {respa}, LAMMPS uses an integrator constructed
+according to the following factorization of the Liouville propagator
+(for two rRESPA levels):
+
+:c,image(Eqs/fix_nh1.jpg) 
+ 
+This factorization differs somewhat from that of Tuckerman et al., in that
+the barostat is only updated at the outermost rRESPA level, whereas
+Tuckerman's factorization requires splitting the pressure into pieces
+corresponding to the forces computed at each rRESPA level. In theory, the
+latter method will exhibit better numerical stability. In practice,
+because Pdamp is normally chosen to be a large multiple of the 
+outermost rRESPA timestep, the barostat dynamics are not the 
+limiting factor for numerical stability. Both 
+factorizations are time-reversible and can be shown to preserve the phase 
+space measure of the underlying non-Hamiltonian equations of motion.
+
+
 [Restrictions:]
 
 Non-periodic dimensions cannot be barostatted.  {Z}, {xz}, and {yz},
@@ -417,7 +437,7 @@ is not allowed in the Nose/Hoover formulation.
 
 [Related commands:]
 
-"fix nve"_fix_nve.html, "fix_modify"_fix_modify.html
+"fix nve"_fix_nve.html, "fix_modify"_fix_modify.html, "run_style"_run_style.html
 
 [Default:]