Merge pull request #3761 from lammps/count-types

New compute count/type command

doc/src/Commands_compute.rst

@@ -46,6 +46,7 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`com/chunk <compute_com_chunk>`
    * :doc:`contact/atom <compute_contact_atom>`
    * :doc:`coord/atom (k) <compute_coord_atom>`
+   * :doc:`count/type <compute_count_type>`
    * :doc:`damage/atom <compute_damage_atom>`
    * :doc:`dihedral <compute_dihedral>`
    * :doc:`dihedral/local <compute_dihedral_local>`

doc/src/Howto_broken_bonds.rst

@@ -1,48 +1,56 @@
 Broken Bonds
 ============
 
-Typically, bond interactions persist for the duration of a simulation in
-LAMMPS. However, there are some exceptions that allow for bonds to
-break, including the :doc:`quartic bond style <bond_quartic>` and the
-bond styles in the :doc:`BPM package <Howto_bpm>` which contains the
-:doc:`bpm/spring <bond_bpm_spring>` and :doc:`bpm/rotational
-<bond_bpm_rotational>` bond styles. In these cases, a bond can be broken
-if it is stretched beyond a user-defined threshold.  LAMMPS accomplishes
-this by setting the bond type to 0, such that the bond force is no
-longer computed.
+Typically, molecular bond interactions persist for the duration of a
+simulation in LAMMPS.  However, some commands break bonds dynamically,
+including the following:
 
-Users are normally able to weight the contribution of pair forces to atoms
-that are bonded using the :doc:`special_bonds command <special_bonds>`.
-When bonds break, this is not always the case. For the quartic bond style,
-pair forces are always turned off between bonded particles. LAMMPS does
-this via a computational sleight-of-hand. It subtracts the pairwise
-interaction as part of the bond computation. When the bond breaks, the
-subtraction stops.  For this to work, the pairwise interaction must always
-be computed by the :doc:`pair_style <pair_style>` command, whether the bond
-is broken or not.  This means that :doc:`special_bonds <special_bonds>` must
-be set to 1,1,1. After the bond breaks, the pairwise interaction between the
-two atoms is turned on, since they are no longer bonded.
+* :doc:`bond_style quartic <bond_quartic>`
+* :doc:`fix bond/break <fix_bond_break>`
+* :doc:`fix bond/react <fix_bond_react>`
+* :doc:`BPM package <Howto_bpm>` bond styles
 
-In the BPM package, one can either turn off all pair interactions between
-bonded particles or leave them on, overlaying pair forces on top of bond
-forces. To remove pair forces, the special bond list is dynamically
-updated. More details can be found on the :doc:`Howto BPM <Howto_bpm>`
-page.
+A bond can break if it is stretched beyond a user-defined threshold or
+more generally if other criteria are met.
 
-Bonds can also be broken by fixes which change bond topology, including
-:doc:`fix bond/break <fix_bond_break>` and
-:doc:`fix bond/react <fix_bond_react>`. These fixes will automatically
-trigger a rebuild of the neighbor list and update special bond data structures
-when bonds are broken.
+For the quartic bond style, when a bond is broken its bond type is set
+to 0 to effectively break it and pairwise forces between the two atoms
+in the broken bond are "turned on".  Angles, dihedrals, etc cannot be
+defined for a system when :doc:`bond_style quartic <bond_quartic>` is
+used.
 
-Note that when bonds are dumped to a file via the :doc:`dump local <dump>` command, bonds with type 0 are not included.  The
-:doc:`delete_bonds <delete_bonds>` command can also be used to query the
-status of broken bonds or permanently delete them, e.g.:
+Similarly, bond styles in the BPM package are also incompatible with
+angles, dihedrals, etc. and when a bond breaks its type is set to zero.
+However, in the BPM package one can either turn off all pair interactions
+between bonded particles or leave them on, overlaying pair forces on
+top of bond forces. To remove pair forces, the special bond list is
+dynamically updated.  More details can be found on the :doc:`Howto BPM
+<Howto_bpm>` page.
+
+The :doc:`fix bond/break <fix_bond_break>` and :doc:`fix bond/react
+<fix_bond_react>` commands allow breaking of bonds within a molecular
+topology with may also define angles, dihedrals, etc.  These commands
+update internal topology data structures to remove broken bonds, as
+well as the appropriate angle, dihederal, etc interactions which
+include the bond.  They also trigger a rebuild of the neighbor list
+when this occurs, to turn on the appropriate pairwise forces.
+
+Note that when bonds are dumped to a file via the :doc:`dump local
+<dump>` command, bonds with type 0 are not included.
+
+The :doc:`delete_bonds <delete_bonds>` command can be used to query
+the status of broken bonds with type = 0 or permanently delete them,
+e.g.:
 
 .. code-block:: LAMMPS
 
    delete_bonds all stats
    delete_bonds all bond 0 remove
 
-The compute :doc:`nbond/atom <compute_nbond_atom>` can also be used
-to tally the current number of bonds per atom, excluding broken bonds.
+The compute :doc:`count/type <compute_count_type>` command tallies the
+current number of bonds (or angles, etc) for each bond (angle, etc)
+type.  It also tallies broken bonds with type = 0.
+
+The compute :doc:`nbond/atom <compute_nbond_atom>` command tallies the
+current number of bonds each atom is part of, excluding broken bonds
+with type = 0.

doc/src/bond_style.rst

@@ -32,13 +32,13 @@ Set the formula(s) LAMMPS uses to compute bond interactions between
 pairs of atoms.  In LAMMPS, a bond differs from a pairwise
 interaction, which are set via the :doc:`pair_style <pair_style>`
 command.  Bonds are defined between specified pairs of atoms and
-remain in force for the duration of the simulation (unless the bond
-breaks which is possible in some bond potentials).  The list of bonded
-atoms is read in by a :doc:`read_data <read_data>` or
-:doc:`read_restart <read_restart>` command from a data or restart file.
-By contrast, pair potentials are typically defined between all pairs
-of atoms within a cutoff distance and the set of active interactions
-changes over time.
+remain in force for the duration of the simulation (unless new bonds
+are created or existing bonds break, which is possible in some fixes
+and bond potentials).  The list of bonded atoms is read in by a
+:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
+command from a data or restart file.  By contrast, pair potentials are
+typically defined between all pairs of atoms within a cutoff distance
+and the set of active interactions changes over time.
 
 Hybrid models where bonds are computed using different bond potentials
 can be setup using the *hybrid* bond style.

doc/src/compute.rst

@@ -200,6 +200,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
 * :doc:`com/chunk <compute_com_chunk>` - center of mass for each chunk
 * :doc:`contact/atom <compute_contact_atom>` - contact count for each spherical particle
 * :doc:`coord/atom <compute_coord_atom>` - coordination number for each atom
+* :doc:`count/type <compute_count_type>` - count of atoms or bonds by type
 * :doc:`damage/atom <compute_damage_atom>` - Peridynamic damage for each atom
 * :doc:`dihedral <compute_dihedral>` - energy of each dihedral sub-style
 * :doc:`dihedral/local <compute_dihedral_local>` - angle of each dihedral

doc/src/compute_count_type.rst

@@ -0,0 +1,130 @@
+.. index:: compute count/type
+
+compute count/type command
+====================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   compute ID group-ID count/type mode
+
+* ID, group-ID are documented in :doc:`compute <compute>` command
+* count/type = style name of this compute command
+* mode = {atom} or {bond} or {angle} or {dihedral} or {improper}
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   compute 1 all count/type atom
+   compute 1 flowmols count/type bond
+
+Description
+"""""""""""
+
+.. versionadded:: TBD
+
+Define a computation that counts the current number of atoms for each
+atom type.  Or the number of bonds (angles, dihedrals, impropers) for
+each bond (angle, dihedral, improper) type.
+
+The former can be useful if atoms are added to or deleted from the
+system in random ways, e.g. via the :doc:`fix deposit <fix_deposit>`,
+:doc:`fix pour <fix_pour>`, or :doc:`fix evaporate <fix_evaporate>`
+commands.  The latter can be useful in reactive simulations where
+molecular bonds are broken or created, as well as angles, dihedrals,
+impropers.
+
+Note that for this command, bonds (angles, etc) are the topological
+kind enumerated in a data file, initially read by the :doc:`read_data
+<read_data>` command or defined by the :doc:`molecule <molecule>`
+command.  They do not refer to implicit bonds defined on-the-fly by
+bond-order or reactive pair styles based on the current conformation
+of small clusters of atoms.
+
+These commands can turn off topological bonds (angles, etc) by setting
+their bond (angle, etc) types to negative values.  This command
+includes the turned-off bonds (angles, etc) in the count for each
+type:
+
+* :doc:`fix shake <fix_shake>`
+* :doc:`delete_bonds <delete_bonds>`
+
+These commands can create and/or break topological bonds (angles,
+etc).  In the case of breaking, they remove the bond (angle, etc) from
+the system, so that they no longer exist (:doc:`bond_style quartic
+<bond_quartic>` and :doc:`BPM bond styles <Howto_bpm>` are exceptions,
+see the discussion below).  Thus they are not included in the counts
+for each type:
+
+* :doc:`delete_bonds remove <delete_bonds>`
+* :doc:`bond_style quartic <bond_quartic>`
+* :doc:`fix bond/react <fix_bond_react>`
+* :doc:`fix bond/create <fix_bond_create>`
+* :doc:`fix bond/break <fix_bond_break>`
+* :doc:`BPM package <Howto_bpm>` bond styles
+
+----------
+
+If the {mode} setting is {atom} then the count of atoms for each atom
+type is tallied.  Only atoms in the specified group are counted.
+
+If the {mode} setting is {bond} then the count of bonds for each bond
+type is tallied.  Only bonds with both atoms in the specified group
+are counted.
+
+For {mode} = {bond}, broken bonds with a bond type of zero are also
+counted.  The :doc:`bond_style quartic <bond_quartic>` and :doc:`BPM
+bond styles <Howto_bpm>` break bonds by doing this.  See the :doc:`
+Howto broken bonds <Howto_broken_bonds>` doc page for more details.
+Note that the group setting is ignored for broken bonds; all broken
+bonds in the system are counted.
+
+If the {mode} setting is {angle} then the count of angles for each
+angle type is tallied.  Only angles with all 3 atoms in the specified
+group are counted.
+
+If the {mode} setting is {dihedral} then the count of dihedrals for
+each dihedral type is tallied.  Only dihedrals with all 4 atoms in the
+specified group are counted.
+
+If the {mode} setting is {improper} then the count of impropers for
+each improper type is tallied.  Only impropers with all 4 atoms in the
+specified group are counted.
+
+----------
+
+Output info
+"""""""""""
+
+This compute calculates a global vector of counts.  If the mode is
+{atom} or {bond} or {angle} or {dihedral} or {improper}, then the
+vector length is the number of atom types or bond types or angle types
+or dihedral types or improper types, respectively.
+
+If the mode is {bond} this compute also calculates a global scalar
+which is the number of broken bonds with type = 0, as explained above.
+
+These values can be used by any command that uses global scalar or
+vector values from a compute as input.  See the :doc:`Howto output
+<Howto_output>` page for an overview of LAMMPS output options.
+
+The scalar and vector values calculated by this compute are "extensive".
+
+Restrictions
+""""""""""""
+
+none
+
+Related commands
+""""""""""""""""
+
+none
+
+Default
+"""""""
+
+none