From 8d1033f0d98245a7d00ca0b8704ac58f4cd06f85 Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Fri, 27 Mar 2015 20:39:41 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@13321
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/fix_temp_csvr.html | 73 +++++++++++++++++++++++++++++-------------
 doc/fix_temp_csvr.txt  | 70 +++++++++++++++++++++++++++-------------
 2 files changed, 98 insertions(+), 45 deletions(-)

diff --git a/doc/fix_temp_csvr.html b/doc/fix_temp_csvr.html
index 7d8e4bc17b..609e7691d9 100644
--- a/doc/fix_temp_csvr.html
+++ b/doc/fix_temp_csvr.html
@@ -11,13 +11,17 @@
 
 <H3>fix temp/csvr command 
 </H3>
+<H3>fix temp/csld command 
+</H3>
 <P><B>Syntax:</B>
 </P>
 <PRE>fix ID group-ID temp/csvr Tstart Tstop Tdamp seed 
 </PRE>
+<PRE>fix ID group-ID temp/csld Tstart Tstop Tdamp seed 
+</PRE>
 <UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command 
 
-<LI>temp/csvr = style name of this fix command 
+<LI>temp/csvr or temp/csld = style name of this fix command 
 
 <LI>Tstart,Tstop = desired temperature at start/end of run 
 
@@ -31,17 +35,26 @@
 </P>
 <PRE>fix 1 all temp/csvr 300.0 300.0 100.0 54324 
 </PRE>
+<PRE>fix 1 all temp/csld 100.0 300.0 10.0 123321 
+</PRE>
 <P><B>Description:</B>
 </P>
-<P>Adjust the temperature with a CSVR thermostat <A HREF = "#Bussi">(Bussi)</A>, which
-updates the velocities to a linear combination of the current
-velocities with a gaussian distribution at the desired temperature in
-every timestep.
+<P>Adjust the temperature with a canonical sampling thermostat that uses
+global velocity rescaling with Hamiltonian dynamics (<I>temp/csvr</I>)
+<A HREF = "#Bussi1">(Bussi1)</A>, or Langevin dynamics (<I>temp/csld</I>) <A HREF = "#Bussi2">(Bussi2)</A>.
+In the case of <I>temp/csvr</I> the thermostat is similar to the empirical
+Berendsen thermostat in <A HREF = "fix_temp_berendsen.html">temp/berendsen</A>, but
+chooses the actual scaling factor from a suitably chosen (gaussian)
+distribution rather than having it determined from the time constant
+directly. In the second case the velocities are updated to a linear
+combination of the current velocities with a gaussian distribution 
+of velocities at the desired temperature. Both termostats are applied
+in every timestep.
 </P>
 <P>The thermostat is applied to only the translational degrees of freedom
 for the particles, which is an important consideration for finite-size
 particles which have rotational degrees of freedom are being
-thermostatted with this fix.  The translational degrees of freedom can
+thermostatted with these fixes.  The translational degrees of freedom can
 also have a bias velocity removed from them before thermostatting
 takes place; see the description below.
 </P>
@@ -64,11 +77,11 @@ keywords for the simulation box parameters and timestep and elapsed
 time.  Thus it is easy to specify a time-dependent temperature.
 </P>
 <P>IMPORTANT NOTE: Unlike the <A HREF = "fix_nh.html">fix nvt</A> command which
-performs Nose/Hoover thermostatting AND time integration, this fix
-does NOT perform time integration.  It only modifies velocities to
+performs Nose/Hoover thermostatting AND time integration, these fixes
+do NOT perform time integration. They only modify velocities to
 effect thermostatting.  Thus you must use a separate time integration
 fix, like <A HREF = "fix_nve.html">fix nve</A> to actually update the positions of
-atoms using the modified velocities.  Likewise, this fix should not
+atoms using the modified velocities.  Likewise, these fixes should not
 normally be used on atoms that also have their temperature controlled
 by another fix - e.g. by <A HREF = "fix_nh.html">fix nvt</A> or <A HREF = "fix_langevin.html">fix
 langevin</A> commands.
@@ -77,7 +90,7 @@ langevin</A> commands.
 a discussion of different ways to compute temperature and perform
 thermostatting.
 </P>
-<P>This fix computes a temperature each timestep.  To do this, the fix
+<P>These fixes compute a temperature each timestep.  To do this, the fix
 creates its own compute of style "temp", as if this command had been
 issued:
 </P>
@@ -97,7 +110,7 @@ custom</A> command using the appropriate compute-ID.
 It also means that changing attributes of <I>thermo_temp</I> will have no
 effect on this fix.
 </P>
-<P>Like other fixes that perform thermostatting, this fix can be used
+<P>Like other fixes that perform thermostatting, these fixes can be used
 with <A HREF = "compute.html">compute commands</A> that calculate a temperature
 after removing a "bias" from the atom velocities.  E.g. removing the
 center-of-mass velocity from a group of atoms or only calculating
@@ -116,24 +129,37 @@ thermal degrees of freedom, and the bias is added back in.
 
 <P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
 </P>
-<P>No information about this fix is written to <A HREF = "restart.html">binary restart
+<P>No information about these fixes are written to <A HREF = "restart.html">binary restart
 files</A>.
 </P>
-<P>The <A HREF = "fix_modify.html">fix_modify</A> <I>temp</I> option is supported by this
-fix.  You can use it to assign a temperature <A HREF = "compute.html">compute</A>
-you have defined to this fix which will be used in its thermostatting
+<P>The <A HREF = "fix_modify.html">fix_modify</A> <I>temp</I> option is supported by these
+fixes.  You can use it to assign a temperature <A HREF = "compute.html">compute</A>
+you have defined to these fixes which will be used in its thermostatting
 procedure, as described above.  For consistency, the group used by
-this fix and by the compute should be the same.
+these fixes and by the compute should be the same.
 </P>
-<P>This fix can ramp its target temperature over multiple runs, using the
-<I>start</I> and <I>stop</I> keywords of the <A HREF = "run.html">run</A> command.  See the
+<P>These fixes can ramp its target temperature over multiple runs, using
+the <I>start</I> and <I>stop</I> keywords of the <A HREF = "run.html">run</A> command.  See the
 <A HREF = "run.html">run</A> command for details of how to do this.
 </P>
-<P>This fix is not invoked during <A HREF = "minimize.html">energy minimization</A>.
+<P>These fixes are not invoked during <A HREF = "minimize.html">energy minimization</A>.
+</P>
+<P>These fixes compute a global scalar which can be accessed by various
+<A HREF = "Section_howto.html#howto_15">output commands</A>.  The scalar is the
+cummulative energy change due to the fix.  The scalar value
+calculated by this fix is "extensive".
 </P>
 <P><B>Restrictions:</B>
 </P>
-<P>This fix is not compatible with <A HREF = "fix_shake.html">fix shake</A>.
+<P>These fixes are not compatible with <A HREF = "fix_shake.html">fix shake</A>.
+</P>
+<P>The fix can be used with dynamic groups as defined by the
+<A HREF = "group.html">group</A> command.  Likewise it can be used with groups to
+which atoms are added or deleted over time, e.g. a deposition
+simulation.  However, the conservation properties of the thermostat
+and barostat are defined for systems with a static set of atoms.  You
+may observe odd behavior if the atoms in a group vary dramatically
+over time or the atom count becomes very small.
 </P>
 <P><B>Related commands:</B>
 </P>
@@ -146,8 +172,11 @@ temp/rescale</A>, <A HREF = "fix_langevin.html">fix langevin</A>,
 </P>
 <HR>
 
-<A NAME = "Bussi"></A>
+<A NAME = "Bussi1"></A>
 
-<P><B>(Bussi)</B> Bussi and Parrinello, Phys. Rev. E (2007)
+<A NAME = "Bussi2"></A><B>(Bussi1)</B> Bussi, Donadio and Parrinello, J. Chem. Phys. 126, 014101(2007)
+
+
+<P><B>(Bussi2)</B> Bussi and Parrinello, Phys. Rev. E 75, 056707 (2007)
 </P>
 </HTML>
diff --git a/doc/fix_temp_csvr.txt b/doc/fix_temp_csvr.txt
index daa2136638..024998e0e6 100644
--- a/doc/fix_temp_csvr.txt
+++ b/doc/fix_temp_csvr.txt
@@ -7,13 +7,15 @@
 :line
 
 fix temp/csvr command :h3
+fix temp/csld command :h3
 
 [Syntax:]
 
 fix ID group-ID temp/csvr Tstart Tstop Tdamp seed :pre
+fix ID group-ID temp/csld Tstart Tstop Tdamp seed :pre
 
 ID, group-ID are documented in "fix"_fix.html command :ulb,l
-temp/csvr = style name of this fix command :l
+temp/csvr or temp/csld = style name of this fix command :l
 Tstart,Tstop = desired temperature at start/end of run :l
   Tstart can be a variable (see below) :pre
 Tdamp = temperature damping parameter (time units) :l
@@ -22,18 +24,26 @@ seed = random number seed to use for white noise (positive integer) :l,ule
 [Examples:]
 
 fix 1 all temp/csvr 300.0 300.0 100.0 54324 :pre
+fix 1 all temp/csld 100.0 300.0 10.0 123321 :pre
 
 [Description:]
 
-Adjust the temperature with a CSVR thermostat "(Bussi)"_#Bussi, which
-updates the velocities to a linear combination of the current
-velocities with a gaussian distribution at the desired temperature in
-every timestep.
+Adjust the temperature with a canonical sampling thermostat that uses
+global velocity rescaling with Hamiltonian dynamics ({temp/csvr})
+"(Bussi1)"_#Bussi1, or Langevin dynamics ({temp/csld}) "(Bussi2)"_#Bussi2.
+In the case of {temp/csvr} the thermostat is similar to the empirical
+Berendsen thermostat in "temp/berendsen"_fix_temp_berendsen.html, but
+chooses the actual scaling factor from a suitably chosen (gaussian)
+distribution rather than having it determined from the time constant
+directly. In the second case the velocities are updated to a linear
+combination of the current velocities with a gaussian distribution 
+of velocities at the desired temperature. Both termostats are applied
+in every timestep.
 
 The thermostat is applied to only the translational degrees of freedom
 for the particles, which is an important consideration for finite-size
 particles which have rotational degrees of freedom are being
-thermostatted with this fix.  The translational degrees of freedom can
+thermostatted with these fixes.  The translational degrees of freedom can
 also have a bias velocity removed from them before thermostatting
 takes place; see the description below.
 
@@ -56,11 +66,11 @@ keywords for the simulation box parameters and timestep and elapsed
 time.  Thus it is easy to specify a time-dependent temperature.
 
 IMPORTANT NOTE: Unlike the "fix nvt"_fix_nh.html command which
-performs Nose/Hoover thermostatting AND time integration, this fix
-does NOT perform time integration.  It only modifies velocities to
+performs Nose/Hoover thermostatting AND time integration, these fixes
+do NOT perform time integration. They only modify velocities to
 effect thermostatting.  Thus you must use a separate time integration
 fix, like "fix nve"_fix_nve.html to actually update the positions of
-atoms using the modified velocities.  Likewise, this fix should not
+atoms using the modified velocities.  Likewise, these fixes should not
 normally be used on atoms that also have their temperature controlled
 by another fix - e.g. by "fix nvt"_fix_nh.html or "fix
 langevin"_fix_langevin.html commands.
@@ -69,7 +79,7 @@ See "this howto section"_Section_howto.html#howto_16 of the manual for
 a discussion of different ways to compute temperature and perform
 thermostatting.
 
-This fix computes a temperature each timestep.  To do this, the fix
+These fixes compute a temperature each timestep.  To do this, the fix
 creates its own compute of style "temp", as if this command had been
 issued:
 
@@ -89,7 +99,7 @@ custom"_thermo_style.html command using the appropriate compute-ID.
 It also means that changing attributes of {thermo_temp} will have no
 effect on this fix.
 
-Like other fixes that perform thermostatting, this fix can be used
+Like other fixes that perform thermostatting, these fixes can be used
 with "compute commands"_compute.html that calculate a temperature
 after removing a "bias" from the atom velocities.  E.g. removing the
 center-of-mass velocity from a group of atoms or only calculating
@@ -108,24 +118,37 @@ thermal degrees of freedom, and the bias is added back in.
 
 [Restart, fix_modify, output, run start/stop, minimize info:]
 
-No information about this fix is written to "binary restart
+No information about these fixes are written to "binary restart
 files"_restart.html.
 
-The "fix_modify"_fix_modify.html {temp} option is supported by this
-fix.  You can use it to assign a temperature "compute"_compute.html
-you have defined to this fix which will be used in its thermostatting
+The "fix_modify"_fix_modify.html {temp} option is supported by these
+fixes.  You can use it to assign a temperature "compute"_compute.html
+you have defined to these fixes which will be used in its thermostatting
 procedure, as described above.  For consistency, the group used by
-this fix and by the compute should be the same.
+these fixes and by the compute should be the same.
 
-This fix can ramp its target temperature over multiple runs, using the
-{start} and {stop} keywords of the "run"_run.html command.  See the
+These fixes can ramp its target temperature over multiple runs, using
+the {start} and {stop} keywords of the "run"_run.html command.  See the
 "run"_run.html command for details of how to do this.
 
-This fix is not invoked during "energy minimization"_minimize.html.
+These fixes are not invoked during "energy minimization"_minimize.html.
+
+These fixes compute a global scalar which can be accessed by various
+"output commands"_Section_howto.html#howto_15.  The scalar is the
+cummulative energy change due to the fix.  The scalar value
+calculated by this fix is "extensive".
 
 [Restrictions:]
 
-This fix is not compatible with "fix shake"_fix_shake.html.
+These fixes are not compatible with "fix shake"_fix_shake.html.
+
+The fix can be used with dynamic groups as defined by the
+"group"_group.html command.  Likewise it can be used with groups to
+which atoms are added or deleted over time, e.g. a deposition
+simulation.  However, the conservation properties of the thermostat
+and barostat are defined for systems with a static set of atoms.  You
+may observe odd behavior if the atoms in a group vary dramatically
+over time or the atom count becomes very small.
 
 [Related commands:]
 
@@ -138,6 +161,7 @@ temp/rescale"_fix_temp_rescale.html, "fix langevin"_fix_langevin.html,
 
 :line
 
-:link(Bussi)
-
-[(Bussi)] Bussi and Parrinello, Phys. Rev. E (2007)
+:link(Bussi1)
+[(Bussi1)] Bussi, Donadio and Parrinello, J. Chem. Phys. 126, 014101(2007)
+:link(Bussi2)
+[(Bussi2)] Bussi and Parrinello, Phys. Rev. E 75, 056707 (2007)