new fix pair and dump_modify skip commands

doc/src/Commands_all.rst

@@ -15,7 +15,9 @@
 General commands
 ================
 
-An alphabetic list of general LAMMPS commands.
+An alphabetic list of general LAMMPS commands.  Note that style
+commands with many variants, can be more easily accessed via the small
+table above.
 
 .. table_from_list::
    :columns: 5

doc/src/Commands_fix.rst

@@ -165,6 +165,7 @@ OPT.
    * :doc:`orient/fcc <fix_orient>`
    * :doc:`orient/eco <fix_orient_eco>`
    * :doc:`pafi <fix_pafi>`
+   * :doc:`pair <fix_pair>`
    * :doc:`phonon <fix_phonon>`
    * :doc:`pimd <fix_pimd>`
    * :doc:`planeforce <fix_planeforce>`

doc/src/compute_pair.rst

@@ -93,7 +93,9 @@ Restrictions
 Related commands
 """"""""""""""""
 
-:doc:`compute pe <compute_pe>`, :doc:`compute bond <compute_bond>`
+:doc:`compute pe <compute_pe>`, :doc:`compute bond <compute_bond>`,
+:doc:`fix pair <fix_pair>`
+
 
 Default
 """""""

doc/src/dump_modify.rst

@@ -17,7 +17,7 @@ Syntax
 * one or more keyword/value pairs may be appended
 
 * these keywords apply to various dump styles
-* keyword = *append* or *at* or *balance* or *buffer* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
+* keyword = *append* or *at* or *balance* or *buffer* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *skip* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
 
   .. parsed-literal::
 
@@ -65,6 +65,8 @@ Syntax
        *refresh* arg = c_ID = compute ID that supports a refresh operation
        *scale* arg = *yes* or *no*
        *sfactor* arg = coordinate scaling factor (> 0.0)
+       *skip* arg = v_name
+         v_name = variable with name which evaluates to non-zero (skip) or 0
        *sort* arg = *off* or *id* or N or -N
           off = no sorting of per-atom lines within a snapshot
           id = sort per-atom lines by atom ID
@@ -678,10 +680,28 @@ most effective when the typical magnitude of position data is between
 
 ----------
 
+The *skip* keyword can be used with all dump styles.  It allows a dump
+snapshot to be skipped (not written to the dump file), if a condition
+is met.  The condition is computed by an :doc:`equal-style variable
+<variable>`, which should be specified as v_name, where name is the
+variable name.  If the variable evaulation returns a non-zero value,
+then the dump snapshot is skipped.  If it returns zero, the dump
+proceeds as usual.  Note that :doc:`equal-style variable <variable>`
+can contain Boolean operators which effectively evaluate as a true
+(non-zero) or false (zero) result.
+
+The *skip* keyword can be useful for debugging purposes, e.g. to dump
+only on a particular timestep.  Or to limit output to conditions of
+interest, e.g. only when the force on some atom exceeds a threshold
+value.
+
+----------
+
 The *sort* keyword determines whether lines of per-atom output in a
 snapshot are sorted or not.  A sort value of *off* means they will
 typically be written in indeterminate order, either in serial or
-parallel.  This is the case even in serial if the :doc:`atom_modify sort <atom_modify>` option is turned on, which it is by default, to
+parallel.  This is the case even in serial if the :doc:`atom_modify
+sort <atom_modify>` option is turned on, which it is by default, to
 improve performance.  A sort value of *id* means sort the output by
 atom ID.  A sort value of N or -N means sort the output by the value
 in the Nth column of per-atom info in either ascending or descending

doc/src/fix.rst

@@ -307,6 +307,7 @@ accelerated styles exist.
 * :doc:`orient/fcc <fix_orient>` - add grain boundary migration force for FCC
 * :doc:`orient/eco <fix_orient_eco>` - add generalized grain boundary migration force
 * :doc:`pafi <fix_pafi>` - constrained force averages on hyper-planes to compute free energies (PAFI)
+* :doc:`pair <fix_pair>` - access per-atom info from pair styles
 * :doc:`phonon <fix_phonon>` - calculate dynamical matrix from MD simulations
 * :doc:`pimd <fix_pimd>` - Feynman path integral molecular dynamics
 * :doc:`planeforce <fix_planeforce>` - constrain atoms to move in a plane

doc/src/fix_pair.rst

@@ -0,0 +1,104 @@
+.. index:: fix pair
+
+fix pair command
+=======================
+
+Syntax
+""""""
+
+.. parsed-literal::
+
+   fix ID group-ID pair N pairstyle name flag ...
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* pair = style name of this fix command
+* N = invoke this fix once every N timesteps
+* pairstyle = name of pair style to extract info from (e.g. eam)
+* one or more name/flag pairs can be listed
+* name = name of quantity the pair style allows extraction of
+* flag = 1 if pair style needs to be triggered to produce data for name, 0 if not
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix request all pair 100 eam rho 0
+   fix request all pair 100 amoeba uind 0 uinp 0
+
+
+Description
+"""""""""""
+
+Extract per-atom quantities from a pair style and store them in this
+fix so they can be accessed by other LAMMPS commands, e.g. by a
+:doc:`dump <dump>` command or by another :doc:`fix <fix>`,
+:doc:`compute <compute>`, or :doc:`variable <variable>` command.
+
+These are example use cases:
+
+* extract per-atom density from :doc:`pair_style eam <pair_eam>` to a dump file
+* extract induced dipoles from :doc:`pair_style amoeba <pair_amoeba>` to a dump file
+* extract accuracy metrics from a machine-learned potential to trigger output when
+a condition is met (see the :doc:`dump_modify skip <dump_modify>` command)
+
+The *N* argument determines how often the fix is invoked.
+
+The *pairstyle* argument is the name of the pair style.  It can be a
+sub-style used in a :doc:`pair_style hybrid <pair_hybrid>` command.
+
+One or more *name/flag* pairs of arguments follow.  Each *name* is a
+per-atom quantity which the pair style must recognize as an extraction
+request.  See the doc pages for individual :doc:`pair_styles
+<pair_style>` to see what fix pair requests (if any) they support.
+
+The *flag* setting determines whether this fix will also request that
+the pair style compute the named quantity to be extracted.  If the
+quantity is always computed by the pair style, no request is needed;
+specify *flag* = 0.  If the quantity is not always computed (e.g. it
+is expensive to calculate), then specify *flag* = 1.  This fix will
+then request the quantity only on timesteps it is needed.  Again, see
+the doc pages for individual :doc:`pair_styles <pair_style>` to
+determine which fix pair requests (if any) need to be triggered with a
+*flag* = 1 setting.
+
+The per-atom data extracted from the pair style is stored by this fix
+as either a per-atom vector or array.  If there is only one *name*
+argument specified and the pair style computes a single value for each
+atom, then this fix stores it as a per-atom vector.  Otherwise a
+per-atom array is created, with its data in the order of the *name*
+arguments.
+
+For example, :doc:`pair_style amoeba <pair_amoeba>` allows extraction
+of two named quantities: "uind" and "uinp", both of which are
+3-vectors for each atom, i.e. dipole moments.  If this fix specifies
+"uind" and "uinp" (in that order), then a 6-column per-atom array will
+be created.  Columns 1-3 will store the "uind" values; columns 4-6
+will store the "uinp" values.
+
+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.
+
+As explained above, this fix produces a per-atom vector or array which
+can be accessed by various :doc:`output commands <Howto_output>`.  If
+an array is produced, the number of columns is the sum of the number
+of per-atom quantities produced by each *name* argument requested from
+the pair style.
+
+Restrictions
+""""""""""""
+none
+
+Related commands
+""""""""""""""""
+
+:doc:`compute pair <compute_pair>`
+
+Default
+"""""""
+
+none

doc/src/pair_amoeba.rst

@@ -156,6 +156,18 @@ settings.
 
 ----------
 
+The *amoeba* and *hippo* pair styles support extraction of two
+per-atom quantities by the :doc:`fix pair <fix_pair>` command.  This
+allows the quantities to be output to files by the :doc:`dump <dump>`
+or otherwise processed by other LAMMPS commamds.
+
+The names of the two quantites are "uind" and "uinp" for the induced
+dipole moments for each atom.  Neither quantity needs to be triggered
+by the :doc:`fix pair <fix_pair>` command in order for these pair
+styles to calculate it.
+
+----------
+
 Mixing, shift, table, tail correction, restart, rRESPA info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 

doc/src/pair_eam.rst

@@ -444,6 +444,18 @@ identical to the FS EAM files (see above).
 
 ----------
 
+The eam, eam/alloy, eam/fs, and eam/he pair styles support extraction
+of two per-atom quantities by the :doc:`fix pair <fix_pair>` command.
+This allows the quantities to be output to files by the :doc:`dump
+<dump>` or otherwise processed by other LAMMPS commamds.
+
+The names of the two quantites are "rho" and "fp" for the density and
+derivative of the embedding energy for each atom.  Neither quantity
+needs to be triggered by the :doc:`fix pair <fix_pair>` command in
+order for these pair styles to calculate it.
+
+----------
+
 .. include:: accel_styles.rst
 
 ----------
@@ -459,21 +471,26 @@ a pair_coeff command with I != J arguments for the eam styles.
 This pair style does not support the :doc:`pair_modify <pair_modify>`
 shift, table, and tail options.
 
-The eam pair styles do not write their information to :doc:`binary restart files <restart>`, since it is stored in tabulated potential files.
-Thus, you need to re-specify the pair_style and pair_coeff commands in
-an input script that reads a restart file.
+The eam pair styles do not write their information to :doc:`binary
+restart files <restart>`, since it is stored in tabulated potential
+files.  Thus, you need to re-specify the pair_style and pair_coeff
+commands in an input script that reads a restart file.
 
 The eam pair styles can only be used via the *pair* keyword of the
 :doc:`run_style respa <run_style>` command.  They do not support the
 *inner*, *middle*, *outer* keywords.
 
+
+
+
 ----------
 
 Restrictions
 """"""""""""
 
 All of these styles are part of the MANYBODY package.  They are only
-enabled if LAMMPS was built with that package.  See the :doc:`Build package <Build_package>` page for more info.
+enabled if LAMMPS was built with that package.  See the :doc:`Build
+package <Build_package>` page for more info.
 
 Related commands
 """"""""""""""""

src/AMOEBA/pair_amoeba.cpp

@@ -2077,7 +2077,10 @@ void *PairAmoeba::extract(const char *str, int &dim)
   if (strcmp(str,"opbend_pentic") == 0) return (void *) &opbend_pentic;
   if (strcmp(str,"opbend_sextic") == 0) return (void *) &opbend_sextic;
 
-  // requests from FixPair
+  // peratom requests from FixPair
+  // return dim = # of quantites per atom
+  //   0 = per-atom vector
+  //   1 or more = # of columns in per-atom array
 
   if (strcmp(str,"uind") == 0) {
     dim = 3;

src/MANYBODY/pair_eam.cpp

@@ -934,7 +934,10 @@ void *PairEAM::extract(const char *str, int &dim)
   dim = 2;
   if (strcmp(str,"scale") == 0) return (void *) scale;
 
-  // requests from FixPair
+  // peratom requests from FixPair
+  // return dim = # of quantites per atom
+  //   0 = per-atom vector
+  //   1 or more = # of columns in per-atom array
 
   if (strcmp(str,"rho") == 0) {
     dim = 0;

src/dump.cpp

@@ -345,11 +345,6 @@ void Dump::write()
 
   if (delay_flag && update->ntimestep < delaystep) return;
 
-  // if file per timestep, open new file
-
-  if (multifile) openfile();
-  if (fp) clearerr(fp);
-
   // simulation box bounds
 
   if (domain->triclinic == 0) {
@@ -376,14 +371,20 @@ void Dump::write()
   nme = count();
 
   // if skip condition is defined and met, just return
-  // do it after count() b/c that invoked computes
-  // NOTE: for multifile, will have already opened file
+  // do this after count() b/c it invokes computes,
+  //   so caller can trigger future invocation of needed computes
 
   if (skipflag) {
     double value = input->variable->compute_equal(skipindex);
     if (value != 0.0) return;
   }
 
+  // if file per timestep, open new file
+  // do this after skip check, so no file is opened if skip occurs
+
+  if (multifile) openfile();
+  if (fp) clearerr(fp);
+
   // ntotal = total # of dump lines in snapshot
   // nmax = max # of dump lines on any proc
 

src/fix_pair.cpp

@@ -81,18 +81,19 @@ FixPair::FixPair(LAMMPS *lmp, int narg, char **arg) :
     }
   }
 
-  // extract all fields just to get number of per-atom values, ptrs may be NULL
+  // extract all fields just to get number of per-atom values
+  //   returned data ptr may be NULL, if pair style has not allocated field yet
+  //   check for recognized field cannot be done until post_force()
   // also check if triggername can be extracted as a scalar value
 
   triggerptr = new int*[nfield];
 
-  int columns,dim;
+  int dim;
   ncols = 0;
 
   for (int ifield = 0; ifield < nfield; ifield++) {
-    void *tmp = pstyle->extract(fieldname[ifield],columns);
-    //if (!tmp) 
-    //  error->all(FLERR,"Fix pair pair style cannot extract {}",fieldname[ifield]);
+    int columns = 0;         // set in case fieldname not recognized by pstyle
+    void *pvoid = pstyle->extract(fieldname[ifield],columns);
     if (columns) ncols += columns;
     else ncols++;
     if (trigger[ifield]) {
@@ -175,12 +176,26 @@ int FixPair::setmask()
 
 void FixPair::init()
 {
-  // make sure pair style still exists
+  // insure pair style still exists
 
   pstyle = force->pair_match(pairname,1,0);
   if (pstyle == nullptr) error->all(FLERR,"Fix pair pair style not found");
 }
 
+/* ---------------------------------------------------------------------- */
+
+void FixPair::setup(int vflag)
+{
+  post_force(vflag);
+}
+
+/* ---------------------------------------------------------------------- */
+
+void FixPair::setup_pre_force(int vflag)
+{
+  pre_force(vflag);
+}
+
 /* ----------------------------------------------------------------------
    trigger pair style computation on steps which are multiples of Nevery
 ------------------------------------------------------------------------- */

src/fix_pair.h

@@ -30,6 +30,8 @@ class FixPair : public Fix {
   ~FixPair() override;
   int setmask() override;
   void init() override;
+  void setup(int) override;
+  void setup_pre_force(int) override;
   void pre_force(int) override;
   void post_force(int) override;