new averaging option for fix temp/rescale

doc/fix_temp_rescale.html

@@ -15,17 +15,28 @@ <H3>fix temp/rescale/kk command
 </H3>
 <P><B>Syntax:</B>
 </P>
-<PRE>fix ID temp/rescale N Tstart Tstop 
+<PRE>fix ID temp/rescale N Tstart Tstop keyword value ... 
 </PRE>
-<UL><LI>ID is documented in <A HREF = "fix.html">fix</A> command
-<LI>temp/rescale = style name of this fix command
-<LI>N = thermostat every N timesteps
+<UL><LI>ID is documented in <A HREF = "fix.html">fix</A> command 
+
+<LI>temp/rescale = style name of this fix command 
+
+<LI>N = thermostat every N timesteps 
+
 <LI>Tstart,Tstop = desired temperature at start/end of run (temperature units) 
+
+<LI>zero or more keyword/args pairs may be appended 
+
+<LI>keyword = <I>ave</I> 
+
+<PRE>  ave values = <I>yes</I> or <I>no</I> 
+</PRE>
+
 </UL>
 <P><B>Examples:</B>
 </P>
 <PRE>fix 1 temp/rescale 100 300.0 300.0
-fix 5 temp/rescale 10 300.0 10.0 
+fix 5 temp/rescale 10 300.0 10.0 ave yes 
 </PRE>
 <P><B>Description:</B>
 </P>
@@ -40,9 +51,9 @@ <H3>fix temp/rescale/kk command
 for the particles.  Their rotational or vibrational degrees of freedom
 are not altered.
 </P>
-<P>Rescaling is performed every N timesteps. The target temperature is a
-ramped value between the Tstart and Tstop temperatures at the
-beginning and end of the run.
+<P>Rescaling is performed every N timesteps. The target temperature
+(Ttarget) is a ramped value between the Tstart and Tstop temperatures
+at the beginning and end of the run.
 </P>
 <P>This fix performs thermostatting on a per grid cell basis.  For each
 grid cell, the center-of-mass velocity and thermal temperature of the
@@ -55,13 +66,36 @@ <H3>fix temp/rescale/kk command
 temp/global/rescale</A> doc page for a
 command that thermostats the temperature of the global system.
 </P>
-<P>From the current thermal temperature and the current target
-temperature, a velocity scale factor is calculated.  That factor is
-applied to each of the components of the thermal velocity for each
-particle in the grid cell.
+<P>How the rescaling of particle velocities is done depends on the value
+of the <I>ave</I> keyword.
+</P>
+<P>For <I>ave</I> with a value <I>no</I> (the default), the thermal temperature
+(Tthermal) of each cell is used to compute a velocity scale factor for
+that cell, which is
+</P>
+<PRE>vscale = sqrt(Ttarget/Tthermal) 
+</PRE>
+<P>The vscale factor is applied to each of the components of the thermal
+velocity for each particle in the grid cell.  Only cells with 2 or
+more particles have their particle velocities rescaled.
+</P>
+<P>For <I>ave</I> with a value <I>yes</I>, the thermal temperatures of all the
+cells are averaged.  The average thermal temperature is simply the sum
+of cell thermal temperatures divided by the number of cells.  Cells
+with less than 2 particles or whose thermal temperature = 0.0
+contribute a thermal temperaure = Ttarget to the average.  The average
+thermal temperature (Tthermal_ave) for all cells is used to compute a
+velocity scale factor for all cells, which is
+</P>
+<PRE>vscale = sqrt(Ttarget/Tthermal_ave) 
+</PRE>
+<P>This single vscale factor is applied to each of the components of the
+thermal velocity for each particle in all the grid cells, including
+the particles in single-particle cells.
 </P>
-<P>After this rescaling, if the thermal temperature were re-computed for
-the grid cell, it would be exactly the target temperature.
+<P>After rescaling, for either <I>ave</I> = <I>no</I> or <I>yes</I>, if the thermal
+temperature were re-computed for any grid cell with more than one
+particle, it would be exactly the target temperature.
 </P>
 <HR>
 
@@ -107,6 +141,8 @@ <H3>fix temp/rescale/kk command
 </P>
 <P><A HREF = "fix_temp_global_rescale.html">fix temp/global/rescale</A>
 </P>
-<P><B>Default:</B> none
+<P><B>Default:</B>
+</P>
+<P>The default is ave = no.
 </P>
 </HTML>

doc/fix_temp_rescale.txt

@@ -11,17 +11,21 @@ fix temp/rescale/kk command :h3
 
 [Syntax:]
 
-fix ID temp/rescale N Tstart Tstop :pre
+fix ID temp/rescale N Tstart Tstop keyword value ... :pre
 
-ID is documented in "fix"_fix.html command
-temp/rescale = style name of this fix command
-N = thermostat every N timesteps
-Tstart,Tstop = desired temperature at start/end of run (temperature units) :ul
+ID is documented in "fix"_fix.html command :ulb,l
+temp/rescale = style name of this fix command :l
+N = thermostat every N timesteps :l
+Tstart,Tstop = desired temperature at start/end of run (temperature units) :l
+zero or more keyword/args pairs may be appended :l
+keyword = {ave} :l
+  ave values = {yes} or {no} :pre
+:ule
 
 [Examples:]
 
 fix 1 temp/rescale 100 300.0 300.0
-fix 5 temp/rescale 10 300.0 10.0 :pre
+fix 5 temp/rescale 10 300.0 10.0 ave yes :pre
 
 [Description:]
 
@@ -36,9 +40,9 @@ The rescaling is applied to only the translational degrees of freedom
 for the particles.  Their rotational or vibrational degrees of freedom
 are not altered.
 
-Rescaling is performed every N timesteps. The target temperature is a
-ramped value between the Tstart and Tstop temperatures at the
-beginning and end of the run.
+Rescaling is performed every N timesteps. The target temperature
+(Ttarget) is a ramped value between the Tstart and Tstop temperatures
+at the beginning and end of the run.
 
 This fix performs thermostatting on a per grid cell basis.  For each
 grid cell, the center-of-mass velocity and thermal temperature of the
@@ -51,13 +55,36 @@ doc page for the equations.  See the "fix
 temp/global/rescale"_fix_temp_globalrescale.html doc page for a
 command that thermostats the temperature of the global system.
 
-From the current thermal temperature and the current target
-temperature, a velocity scale factor is calculated.  That factor is
-applied to each of the components of the thermal velocity for each
-particle in the grid cell.
+How the rescaling of particle velocities is done depends on the value
+of the {ave} keyword.
 
-After this rescaling, if the thermal temperature were re-computed for
-the grid cell, it would be exactly the target temperature.
+For {ave} with a value {no} (the default), the thermal temperature
+(Tthermal) of each cell is used to compute a velocity scale factor for
+that cell, which is
+
+vscale = sqrt(Ttarget/Tthermal) :pre
+
+The vscale factor is applied to each of the components of the thermal
+velocity for each particle in the grid cell.  Only cells with 2 or
+more particles have their particle velocities rescaled.
+
+For {ave} with a value {yes}, the thermal temperatures of all the
+cells are averaged.  The average thermal temperature is simply the sum
+of cell thermal temperatures divided by the number of cells.  Cells
+with less than 2 particles or whose thermal temperature = 0.0
+contribute a thermal temperaure = Ttarget to the average.  The average
+thermal temperature (Tthermal_ave) for all cells is used to compute a
+velocity scale factor for all cells, which is
+
+vscale = sqrt(Ttarget/Tthermal_ave) :pre
+
+This single vscale factor is applied to each of the components of the
+thermal velocity for each particle in all the grid cells, including
+the particles in single-particle cells.
+
+After rescaling, for either {ave} = {no} or {yes}, if the thermal
+temperature were re-computed for any grid cell with more than one
+particle, it would be exactly the target temperature.
 
 :line
 
@@ -103,4 +130,6 @@ effectively.
 
 "fix temp/global/rescale"_fix_temp_global_rescale.html
 
-[Default:] none
+[Default:]
+
+The default is ave = no.

doc/surf_collide.html

@@ -21,7 +21,8 @@ <H3>surf_collide command
 
 <LI>args = arguments for specific style 
 
-<PRE>  <I>specular</I> or <I>specular/kk</I> args = none
+<PRE>  <I>specular</I> or <I>specular/kk</I> args = noslip (optional)
+    noslip = reflect all velocity components off surface (not just normal component)
   <I>diffuse</I> or <I>diffuse/kk</I> args = Tsurf acc
     Tsurf = temperature of surface (temperature units)
             Tsurf can be a variable (see below)
@@ -129,6 +130,13 @@ <H3>surf_collide command
 reversed with respect to the outward normal of the surface element.
 The particle's speed is unchanged.
 </P>
+<P>Specular reflection means that a particle bounce off a surface element
+reverses only the component of its velocity normal to the surface. If
+the optional <I>noslip</I> keyword is used, the particle bounce flips the sign
+of all 3 xyz components of the particle's incident velocity, so that it
+now moves in the opposite direction, creating a no slip boundary condition.
+In either case, the particle's speed is unchanged.
+</P>
 <HR>
 
 <P>The <I>diffuse</I> style computes a simple diffusive reflection model.

examples/thermostat/in.thermostat_ave

@@ -0,0 +1,46 @@
+################################################################################
+# thermal gas in a 3d box with collisions
+# the fix temp/rescale command is used to ramp and cool the temperature
+# the compute thermal/grid command is used to measure the temperature
+
+# Note:
+#  - The "comm/sort” option to the “global” command is used to match MPI runs.
+#  - The “twopass” option is used to match Kokkos runs.
+# The "comm/sort" and "twopass" options should not be used for production runs.
+################################################################################
+
+seed	    	    12345
+dimension   	    3
+global              gridcut 1.0e-5 comm/sort yes
+
+boundary	    rr rr rr
+
+create_box  	    0 0.0001 0 0.0001 0 0.0001
+create_grid 	    10 10 10
+
+balance_grid        rcb part
+
+species		    ar.species Ar
+mixture		    air Ar vstream 0.0 0.0 0.0 temp 300.0
+
+global              nrho 7.07043E22
+global              fnum 7.07043E6
+
+collide		    vss air ar.vss
+
+create_particles    air n 10000 twopass
+
+compute             1 thermal/grid all air temp
+compute             2 reduce ave c_1[1]
+
+stats		    100
+compute             temp temp
+stats_style	    step cpu np nattempt ncoll c_temp c_2
+
+timestep 	    7.00E-9
+
+fix                 tstat temp/rescale 200 300 600 ave yes
+run 		    1000
+
+fix                 tstat temp/rescale 200 600 100 ave yes
+run 		    1000