diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index 5e309c3ed0..fdde1f8e6c 100644 --- a/doc/src/Commands_all.rst +++ b/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 diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index cb61cbe17b..c5c2fb7cba 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -165,6 +165,7 @@ OPT. * :doc:`orient/fcc ` * :doc:`orient/eco ` * :doc:`pafi ` + * :doc:`pair ` * :doc:`phonon ` * :doc:`pimd ` * :doc:`planeforce ` diff --git a/doc/src/compute_pair.rst b/doc/src/compute_pair.rst index b43c4bd6d7..e399b61aba 100644 --- a/doc/src/compute_pair.rst +++ b/doc/src/compute_pair.rst @@ -93,7 +93,9 @@ Restrictions Related commands """""""""""""""" -:doc:`compute pe `, :doc:`compute bond ` +:doc:`compute pe `, :doc:`compute bond `, +:doc:`fix pair ` + Default """"""" diff --git a/doc/src/dump_modify.rst b/doc/src/dump_modify.rst index fd916beb4e..0dcb4f198f 100644 --- a/doc/src/dump_modify.rst +++ b/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 +`, 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 ` +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 ` option is turned on, which it is by default, to +parallel. This is the case even in serial if the :doc:`atom_modify +sort ` 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 diff --git a/doc/src/fix.rst b/doc/src/fix.rst index 2ec4437b39..acddb2f351 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -307,6 +307,7 @@ accelerated styles exist. * :doc:`orient/fcc ` - add grain boundary migration force for FCC * :doc:`orient/eco ` - add generalized grain boundary migration force * :doc:`pafi ` - constrained force averages on hyper-planes to compute free energies (PAFI) +* :doc:`pair ` - access per-atom info from pair styles * :doc:`phonon ` - calculate dynamical matrix from MD simulations * :doc:`pimd ` - Feynman path integral molecular dynamics * :doc:`planeforce ` - constrain atoms to move in a plane diff --git a/doc/src/fix_pair.rst b/doc/src/fix_pair.rst new file mode 100644 index 0000000000..c8734299d4 --- /dev/null +++ b/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 ` 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 ` command or by another :doc:`fix `, +:doc:`compute `, or :doc:`variable ` command. + +These are example use cases: + +* extract per-atom density from :doc:`pair_style eam ` to a dump file +* extract induced dipoles from :doc:`pair_style 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 ` 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 ` 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 +` 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 ` 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 ` 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 +`. None of the :doc:`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 `. 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 ` + +Default +""""""" + +none diff --git a/doc/src/pair_amoeba.rst b/doc/src/pair_amoeba.rst index a58eb2fabc..b41cb9815b 100644 --- a/doc/src/pair_amoeba.rst +++ b/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 ` command. This +allows the quantities to be output to files by the :doc:`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 ` command in order for these pair +styles to calculate it. + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/pair_eam.rst b/doc/src/pair_eam.rst index fd05d7189e..4ba926362f 100644 --- a/doc/src/pair_eam.rst +++ b/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 ` command. +This allows the quantities to be output to files by the :doc:`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 ` 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 ` shift, table, and tail options. -The eam pair styles do not write their information to :doc:`binary restart files `, 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 `, 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 ` 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 ` page for more info. +enabled if LAMMPS was built with that package. See the :doc:`Build +package ` page for more info. Related commands """""""""""""""" diff --git a/src/AMOEBA/pair_amoeba.cpp b/src/AMOEBA/pair_amoeba.cpp index 1d37b3c85b..8229684d29 100644 --- a/src/AMOEBA/pair_amoeba.cpp +++ b/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; diff --git a/src/MANYBODY/pair_eam.cpp b/src/MANYBODY/pair_eam.cpp index 031d41387b..2534386225 100644 --- a/src/MANYBODY/pair_eam.cpp +++ b/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; diff --git a/src/dump.cpp b/src/dump.cpp index 3062763d89..13e3bcdfcc 100644 --- a/src/dump.cpp +++ b/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 diff --git a/src/fix_pair.cpp b/src/fix_pair.cpp index 4171164cac..c4c81a4bda 100644 --- a/src/fix_pair.cpp +++ b/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 ------------------------------------------------------------------------- */ diff --git a/src/fix_pair.h b/src/fix_pair.h index 3e32b11544..a9927cf477 100644 --- a/src/fix_pair.h +++ b/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;