From 79f6867d7e77e4c57815615d5150d42aee0056e5 Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Fri, 2 May 2025 16:13:01 -0600 Subject: [PATCH] new doc page for fix set command with example --- doc/src/fix.rst | 1 + doc/src/fix_set.rst | 154 ++++++++++++++++++++++++++++++++++++++++++++ doc/src/set.rst | 6 +- src/fix_set.cpp | 12 +++- src/set.cpp | 2 + 5 files changed, 172 insertions(+), 3 deletions(-) create mode 100644 doc/src/fix_set.rst diff --git a/doc/src/fix.rst b/doc/src/fix.rst index 3b1bc4a75c..22996a327a 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -395,6 +395,7 @@ accelerated styles exist. * :doc:`rigid/small ` - constrain many small clusters of atoms to move as a rigid body with NVE integration * :doc:`rx ` - solve reaction kinetic ODEs for a defined reaction set * :doc:`saed/vtk ` - time-average the intensities from :doc:`compute saed ` +* :doc:`set ` - reset an atom property via an atom-style variable every N steps * :doc:`setforce ` - set the force on each atom * :doc:`setforce/spin ` - set magnetic precession vectors on each atom * :doc:`sgcmc ` - fix for hybrid semi-grand canonical MD/MC simulations diff --git a/doc/src/fix_set.rst b/doc/src/fix_set.rst new file mode 100644 index 0000000000..0f1cf7fcb0 --- /dev/null +++ b/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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 +`. None of the :doc:`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 `. +No parameter of this fix can be used with the *start/stop* keywords of +the :doc:`run ` command. This fix is not invoked during +:doc:`energy minimization `. + +Restrictions +"""""""""""" + +As noted above, + + +Related commands +"""""""""""""""" + +:doc:`set ` + +Default +""""""" + +none diff --git a/doc/src/set.rst b/doc/src/set.rst index aecd2d2cb5..d2c865dfbb 100644 --- a/doc/src/set.rst +++ b/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 ` 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 `, :doc:`create_atoms `, -:doc:`read_data ` +:doc:`read_data `, :doc:`fix set ` Default """"""" diff --git a/src/fix_set.cpp b/src/fix_set.cpp index 5473cb35f5..a1b8a45655 100644 --- a/src/fix_set.cpp +++ b/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() diff --git a/src/set.cpp b/src/set.cpp index 951655879a..d07b1e4e2c 100644 --- a/src/set.cpp +++ b/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)