new doc page for fix set command with example

doc/src/fix.rst

@@ -395,6 +395,7 @@ accelerated styles exist.
 * :doc:`rigid/small <fix_rigid>` - constrain many small clusters of atoms to move as a rigid body with NVE integration
 * :doc:`rx <fix_rx>` - solve reaction kinetic ODEs for a defined reaction set
 * :doc:`saed/vtk <fix_saed_vtk>` - time-average the intensities from :doc:`compute saed <compute_saed>`
+* :doc:`set <fix_set>` - reset an atom property via an atom-style variable every N steps
 * :doc:`setforce <fix_setforce>` - set the force on each atom
 * :doc:`setforce/spin <fix_setforce>` - set magnetic precession vectors on each atom
 * :doc:`sgcmc <fix_sgcmc>` - fix for hybrid semi-grand canonical MD/MC simulations

doc/src/fix_set.rst

@@ -0,0 +1,154 @@
+.. index:: fix set
+
+fix set command
+===============
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   fix ID group-ID set Nfreq set-args
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* set = style name of this fix command
+* Nfreq = reset per-atom properties every this many timesteps
+* set-args = identical to args for the :doc:`set <set>` command
+  
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix 10 all set 1 group all i_dump v_new
+   fix 10 all set 1 group all i_dump v_turnoff
+
+Description
+"""""""""""
+
+Reset one or more properties of one or more atoms once every *Nfreq*
+stepes during a simulation.
+
+The args following *Nfreq* are identical to those allowed for the
+:doc:`set <set>` command, as in the examples above and below.
+
+Note that the group-ID setting for this command is ignored.  The
+syntax for the :doc:`set <set>` command allows selection of which
+atoms have their properties reset.
+
+This command can only be used to reset an atom property using a
+per-atom variable.  This option in allowed by many, but not all, of
+the keyword/value pairs supported by the :doc:`set <set>` command.
+The reason for this restriction is that if a per-atom variable is not
+used, this command will typically not change atom properties during
+the simulation.
+
+The :doc:`set <set>` command can be used with similar syntax to this
+command to reset atom properties once before or between simulations.
+
+----------
+
+Here is an example of input script commands which will output atoms
+into a dump file only when their x-velocity crosses a threshold value
+*vthresh* for the first time.  Their position and x-velocity will then
+be output every step for *twindow* timesteps.
+
+.. code-block:: LAMMPS
+
+   variable        vthresh equal 2             # threshold velocity
+   variable        twindow equal 10            # dump for this many steps
+   #
+   # define custom property i_dump to store timestep threshold is crossed
+   #
+   fix             2 all property/atom i_dump
+   set             group all i_dump -1
+   #
+   # fix set command checks for threshold crossings every step
+   # resets i_dump from -1 to current timestep when crossing occurs
+   #
+   variable        start atom "vx > v_vthresh && i_dump == -1"
+   variable        new atom ternary(v_start,step,i_dump)
+   fix             3 all set 1 group all i_dump v_new
+   #
+   # dump command with thresh which enforces twindow
+   #
+   dump            1 all custom 1 tmp.dump id x y vx i_dump 
+   variable        dumpflag atom "i_dump >= 0 && (step-i_dump) < v_twindow"
+   dump_modify     1 thresh v_dumpflag == 1
+   #
+   # run the simulation
+   # final dump with all atom IDs which crossed threshold on which timestep
+   #
+   run             1000
+   write_dump      all custom tmp.dump.final id i_dump modify thresh i_dump >= 0
+
+The tmp.dump.final file lists which atoms crossed the velocity
+threshold.  This command will print the *twindow* timesteps when a
+specific atom ID (104 in this case) was output in the tmp.dump file:
+
+.. code-block:: LAMMPS
+
+   % grep "^104 " tmp.dump
+   
+If these commands are used instead of the above, then an atom can
+cross the velocity threshold multiple times, and will be output for
+*twindow* timesteps each time.  However the write_dump command is no
+longer useful.
+
+.. code-block:: LAMMPS
+
+   variable        vthresh equal 2             # threshold velocity
+   variable        twindow equal 10            # dump for this many steps
+   #
+   # define custom property i_dump to store timestep threshold is crossed
+   #
+   fix             2 all property/atom i_dump
+   set             group all i_dump -1
+   #
+   # fix set command checks for threshold crossings every step
+   # resets i_dump from -1 to current timestep when crossing occurs
+   #
+   variable        start atom "vx > v_vthresh && i_dump == -1"
+   variable        turnon atom ternary(v_start,step,i_dump)
+   variable        stop atom "v_turnon >= 0 && (step-v_turnon) < v_twindow"
+   variable        turnoff atom ternary(v_stop,v_turnon,-1)
+   fix             3 all set 1 group all i_dump v_turnoff
+   #
+   # dump command with thresh which enforces twindow
+   #
+   dump            1 all custom 1 tmp.dump id x y vx i_dump 
+   variable        dumpflag atom "i_dump >= 0 && (step-i_dump) < v_twindow"
+   dump_modify     1 thresh v_dumpflag == 1
+   #
+   # run the simulation
+   #
+   run             1000
+   
+----------
+
+Restart, fix_modify, output, run start/stop, minimize info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+No information about this fix is written to :doc:`binary restart files
+<restart>`.  None of the :doc:`fix_modify <fix_modify>` options are
+relevant to this fix.  No global or per-atom quantities are stored by
+this fix for access by various :doc:`output commands <Howto_output>`.
+No parameter of this fix can be used with the *start/stop* keywords of
+the :doc:`run <run>` command.  This fix is not invoked during
+:doc:`energy minimization <minimize>`.
+
+Restrictions
+""""""""""""
+
+As noted above, 
+
+
+Related commands
+""""""""""""""""
+
+:doc:`set <set>`
+
+Default
+"""""""
+
+none

doc/src/set.rst

@@ -200,6 +200,10 @@ their properties reset.  The remaining keywords specify which
 properties to reset and what the new values are.  Some strings like
 *type* or *mol* can be used as a style and/or a keyword.
 
+The :doc:`fix set <fix_set>` command can be used with similar syntax
+to this command to reset atom properties once every *N* steps during a
+simulation using via atom-style variables.
+
 ----------
 
 This section describes how to select which atoms to change
@@ -658,7 +662,7 @@ Related commands
 """"""""""""""""
 
 :doc:`create_box <create_box>`, :doc:`create_atoms <create_atoms>`,
-:doc:`read_data <read_data>`
+:doc:`read_data <read_data>`, :doc:`fix set <fix_set>`
 
 Default
 """""""

src/fix_set.cpp

@@ -37,8 +37,16 @@ FixSet::FixSet(LAMMPS *lmp, int narg, char **arg) : Fix(lmp, narg, arg)
 
   // pass remaining args to Set class
   // only keywords which use per-atom variables are currently allowed
+  // NOTE: could also allow when set style = region, since atoms may move in/out of regions
   
   set->process_args(FIXSET,narg-4,&arg[4]);
+
+  // NOTE: not sure if either of these options for fix set are needed or could be problematic
+  // could add ghost yes keyword/value to trigger
+  //   ghost comm, e.g. if atom types are reset
+  //   this could require an extract() method in Set to query what value(s) to comm
+  // could add reneigh yes keyword/value to trigger
+  //   full reneighbor on next step, e.g. if xyz coords are reset
 }
 
 /* ---------------------------------------------------------------------- */
@@ -59,7 +67,7 @@ int FixSet::setmask()
 
 /* ----------------------------------------------------------------------
    use the Set instance to update per-atom properties
-   NOTE: could return count of updated atoms from Set and use it as a fix output
+   NOTE: could return count of updated atoms from Set for use as fix output
 ---------------------------------------------------------------------- */
 
 void FixSet::end_of_step()

src/set.cpp

@@ -999,6 +999,8 @@ void Set::topology(int keyword, Action *action)
 // separate two operations so can be called by either set or fix set command
 // ----------------------------------------------------------------------
 
+/* ---------------------------------------------------------------------- */
+
 void Set::process_angle(int &iarg, int narg, char **arg, Action *action)
 {
   if (atom->avec->angles_allow == 0)