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

doc/dump_modify.html

@@ -26,6 +26,7 @@
     E1,...,EN = element name, e.g. C or Fe or Ga
   <I>every</I> arg = N
     N = dump every this many timesteps
+    N can be a variable (see below)
   <I>first</I> arg = <I>yes</I> or <I>no</I>
   <I>format</I> arg = C-style format string for one line of output
   <I>flush</I> arg = <I>yes</I> or <I>no</I>
@@ -51,6 +52,8 @@
 dump_modify myDump image yes scale no flush yes
 dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2
 dump_modify xtcdump precision 10000
+dump_modify 1 every 1000
+dump_modify 1 every v_myVar 
 </PRE>
 <P><B>Description:</B>
 </P>
@@ -77,9 +80,30 @@ in the simulation.  The same element name can be given to multiple
 atom types.
 </P>
 <P>The <I>every</I> keyword changes the dump frequency originally specified by
-the <A HREF = "dump.html">dump</A> command to a new value which must be > 0.  The
+the <A HREF = "dump.html">dump</A> command to a new value.  The every keyword can be
-dump frequency cannot be changed for the dump <I>dcd</I> style.
+specified in one of two ways.  It can be a numeric value in which case
+it must be > 0.  Or it can be an <A HREF = "variable.html">equal-style variable</A>,
+which should be specified as v_name, where "name" is the variable
+name.  In this case, the variable is evaluated at the beginning of a
+run to determine the next timestep at which a dump snapshot will be
+written out.  On that timestep, the variable will be evaluated again
+to determine the next timestep, etc.  Thus the variable should return
+timestep values.  See the stagger() and logfreq() math functions for
+<A HREF = "variable.html">equal-style variables</A>, as examples of useful functions
+to use in this context.  Other similar math functions could easily be
+added as options for <A HREF = "variable.html">equal-style variables</A>.  When
+using the variable option with the <I>every</I> keyword, you also need to
+use the <I>first</I> option if you want an initial snapshot written to the
+dump file.  The <I>every</I> keyword cannot be used with the dump <I>dcd</I>
+style.
 </P>
+<P>For example, the following commands will
+write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
+</P>
+<PRE>variable	s equal logfreq(10,3,10)
+dump		1 all atom 100 tmp.dump
+dump_modify	1 every v_s first yes 
+</PRE>
 <P>The <I>first</I> keyword determines whether a dump snapshot is written on
 the very first timestep after the dump command is invoked.  This will
 always occur if the current timestep is a multiple of N, the frequency

doc/dump_modify.txt

@@ -20,6 +20,7 @@ keyword = {append} or {every} or {flush} or {format} or {image} or {label} or {p
     E1,...,EN = element name, e.g. C or Fe or Ga
   {every} arg = N
     N = dump every this many timesteps
+    N can be a variable (see below)
   {first} arg = {yes} or {no}
   {format} arg = C-style format string for one line of output
   {flush} arg = {yes} or {no}
@@ -43,7 +44,9 @@ keyword = {append} or {every} or {flush} or {format} or {image} or {label} or {p
 dump_modify 1 format "%d %d %20.15g %g %g" scale yes
 dump_modify myDump image yes scale no flush yes
 dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2
-dump_modify xtcdump precision 10000 :pre
+dump_modify xtcdump precision 10000
+dump_modify 1 every 1000
+dump_modify 1 every v_myVar :pre
 
 [Description:]
 
@@ -70,8 +73,29 @@ in the simulation.  The same element name can be given to multiple
 atom types.
 
 The {every} keyword changes the dump frequency originally specified by
-the "dump"_dump.html command to a new value which must be > 0.  The
+the "dump"_dump.html command to a new value.  The every keyword can be
-dump frequency cannot be changed for the dump {dcd} style.
+specified in one of two ways.  It can be a numeric value in which case
+it must be > 0.  Or it can be an "equal-style variable"_variable.html,
+which should be specified as v_name, where "name" is the variable
+name.  In this case, the variable is evaluated at the beginning of a
+run to determine the next timestep at which a dump snapshot will be
+written out.  On that timestep, the variable will be evaluated again
+to determine the next timestep, etc.  Thus the variable should return
+timestep values.  See the stagger() and logfreq() math functions for
+"equal-style variables"_variable.html, as examples of useful functions
+to use in this context.  Other similar math functions could easily be
+added as options for "equal-style variables"_variable.html.  When
+using the variable option with the {every} keyword, you also need to
+use the {first} option if you want an initial snapshot written to the
+dump file.  The {every} keyword cannot be used with the dump {dcd}
+style.
+
+For example, the following commands will
+write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
+
+variable	s equal logfreq(10,3,10)
+dump		1 all atom 100 tmp.dump
+dump_modify	1 every v_s first yes :pre
 
 The {first} keyword determines whether a dump snapshot is written on
 the very first timestep after the dump command is invoked.  This will

doc/variable.html

@@ -34,7 +34,8 @@
                      x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y
     math functions = sqrt(x), exp(x), ln(x), log(x),
                      sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
-                     ceil(x), floor(x), round(x), ramp(x,y)
+                     ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y),
+		     logfreq(x,y,z)
     group functions = count(group), mass(group), charge(group),
 		      xcm(group,dim), vcm(group,dim), fcm(group,dim),
 		      bound(group,xmin), gyration(group), ke(group),
@@ -257,7 +258,7 @@ references to other variables.
 <TR><TD >Number</TD><TD > 0.2, 100, 1.0e20, -15.4, etc</TD></TR>
 <TR><TD >Thermo keywords</TD><TD > vol, pe, ebond, etc</TD></TR>
 <TR><TD >Math operators</TD><TD > (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y</TD></TR>
-<TR><TD >Math functions</TD><TD > sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), ceil(x), floor(x), round(x), ramp(x,y)</TD></TR>
+<TR><TD >Math functions</TD><TD > sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z)</TD></TR>
 <TR><TD >Group functions</TD><TD > count(ID), mass(ID), charge(ID), xcm(ID,dim),                  vcm(ID,dim), fcm(ID,dim), bound(ID,dir), 		 gyration(ID), ke(ID), angmom(ID,dim), 		 inertia(ID,dimdim), omega(ID,dim)</TD></TR>
 <TR><TD >Region functions</TD><TD > count(ID,IDR), mass(ID,IDR), charge(ID,IDR), 		  xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), 		  bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), 		  angmom(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR)</TD></TR>
 <TR><TD >Atom values</TD><TD > mass[i], type[i], x[i], y[i], z[i],              vx[i], vy[i], vz[i], fx[i], fy[i], fz[i]</TD></TR>
@@ -343,7 +344,7 @@ to its argument.
 </P>
 <P>Ramp(x,y) uses the current timestep to generate a scalar value:
 </P>
-<PRE>value = x + (y-x) * (timestep - startstep) / (stopstep - startstep) 
+<PRE>value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) 
 </PRE>
 <P>which is a value that ramps linear between x and y over the course of
 a run.  The run begins on startstep and ends on stopstep.  Startstep
@@ -351,6 +352,25 @@ and stopstep can span 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>Stagger(x,y) requires x,y > 0 and x > y and uses the current timestep
+to generate a new timestep, in a staggered fashion, as the sequence
+x,x+y,2x,2x+y,3x,3x+y,etc.  For any current timestep, the next
+timestep in the sequence is returned.  Thus if stagger(1000,100) is
+used in a variable by the <A HREF = "dump_modify.html">dump_modify frequency</A>
+command, it will generate the sequence of output timesteps:
+</P>
+<PRE>100,1000,1100,2000,2100,3000,etc 
+</PRE>
+<P>Logfreq(x,y,z) requires x,y,z > 0 and y < z and uses the current
+timestep to generate a new timestep, in a logarithmic fashion, as the
+sequence x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc.
+For any current timestep, the next timestep in the sequence is
+returned.  Thus if logfreq(100,4,10) is used in a variable by the
+<A HREF = "dump_modify.html">dump_modify frequency</A> command, it will generate the
+sequence of output timesteps:
+</P>
+<PRE>100,200,300,400,1000,2000,3000,4000,10000,20000,etc 
+</PRE>
 <P>Group functions are specified as keywords followed by one or two
 parenthesized arguments.  The first argument is the group-ID.  The
 <I>dim</I> argument, if it exists, is <I>x</I> or <I>y</I> or <I>z</I>.  The <I>dir</I>

doc/variable.txt

@@ -29,7 +29,8 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st
                      x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y
     math functions = sqrt(x), exp(x), ln(x), log(x),
                      sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
-                     ceil(x), floor(x), round(x), ramp(x,y)
+                     ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y),
+		     logfreq(x,y,z)
     group functions = count(group), mass(group), charge(group),
 		      xcm(group,dim), vcm(group,dim), fcm(group,dim),
 		      bound(group,xmin), gyration(group), ke(group),
@@ -250,7 +251,7 @@ references to other variables.
 Number: 0.2, 100, 1.0e20, -15.4, etc
 Thermo keywords: vol, pe, ebond, etc
 Math operators: (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y
-Math functions: sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), ceil(x), floor(x), round(x), ramp(x,y)
+Math functions: sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z)
 Group functions: count(ID), mass(ID), charge(ID), xcm(ID,dim), \
                  vcm(ID,dim), fcm(ID,dim), bound(ID,dir), \
 		 gyration(ID), ke(ID), angmom(ID,dim), \
@@ -342,7 +343,7 @@ to its argument.
 
 Ramp(x,y) uses the current timestep to generate a scalar value:
 
-value = x + (y-x) * (timestep - startstep) / (stopstep - startstep) :pre
+value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) :pre
 
 which is a value that ramps linear between x and y over the course of
 a run.  The run begins on startstep and ends on stopstep.  Startstep
@@ -350,6 +351,25 @@ and stopstep can span 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.
 
+Stagger(x,y) requires x,y > 0 and x > y and uses the current timestep
+to generate a new timestep, in a staggered fashion, as the sequence
+x,x+y,2x,2x+y,3x,3x+y,etc.  For any current timestep, the next
+timestep in the sequence is returned.  Thus if stagger(1000,100) is
+used in a variable by the "dump_modify frequency"_dump_modify.html
+command, it will generate the sequence of output timesteps:
+
+100,1000,1100,2000,2100,3000,etc :pre
+
+Logfreq(x,y,z) requires x,y,z > 0 and y < z and uses the current
+timestep to generate a new timestep, in a logarithmic fashion, as the
+sequence x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc.
+For any current timestep, the next timestep in the sequence is
+returned.  Thus if logfreq(100,4,10) is used in a variable by the
+"dump_modify frequency"_dump_modify.html command, it will generate the
+sequence of output timesteps:
+
+100,200,300,400,1000,2000,3000,4000,10000,20000,etc :pre
+
 Group functions are specified as keywords followed by one or two
 parenthesized arguments.  The first argument is the group-ID.  The
 {dim} argument, if it exists, is {x} or {y} or {z}.  The {dir}