Merge pull request lammps#4145 from jrgissing/improve_type_label_support

Improve type label support

doc/src/compute_rdf.rst

@@ -13,8 +13,8 @@ Syntax
 * ID, group-ID are documented in :doc:`compute <compute>` command
 * rdf = style name of this compute command
 * Nbin = number of RDF bins
-* itypeN = central atom type for Nth RDF histogram (see asterisk form below)
-* jtypeN = distribution atom type for Nth RDF histogram (see asterisk form below)
+* itypeN = central atom type for Nth RDF histogram (integer, type label, or asterisk form)
+* jtypeN = distribution atom type for Nth RDF histogram (integer, type label, or asterisk form)
 * zero or more keyword/value pairs may be appended
 * keyword = *cutoff*
 
@@ -96,14 +96,16 @@ is computed for :math:`g(r)` between all atom types.  If one or more pairs are
 listed, then a separate histogram is generated for each
 *itype*,\ *jtype* pair.
 
-The *itypeN* and *jtypeN* settings can be specified in one of two
-ways.  An explicit numeric value can be used, as in the fourth example
-above.  Or a wild-card asterisk can be used to specify a range of atom
-types.  This takes the form "\*" or "\*n" or "m\*" or "m\*n".  If
-:math:`N` is the number of atom types, then an asterisk with no numeric values
-means all types from 1 to :math:`N`. A leading asterisk means all types from 1
-to n (inclusive).  A trailing asterisk means all types from m to :math:`N`
-(inclusive).  A middle asterisk means all types from m to n (inclusive).
+The *itypeN* and *jtypeN* settings can be specified in one of three
+ways.  One or both of the types in the I,J pair can be a
+:doc:`type label <Howto_type_labels>`.  Or an explicit numeric value can be
+used, as in the fourth example above. Or a wild-card asterisk can be used
+to specify a range of atom types.  This takes the form "\*" or "\*n" or
+"m\*" or "m\*n". If :math:`N` is the number of atom types, then an asterisk
+with no numeric values means all types from 1 to :math:`N`. A leading
+asterisk means all types from 1 to n (inclusive).  A trailing asterisk
+means all types from m to :math:`N` (inclusive).  A middle asterisk means
+all types from m to n (inclusive).
 
 If both *itypeN* and *jtypeN* are single values, as in the fourth example
 above, this means that a :math:`g(r)` is computed where atoms of type *itypeN*

doc/src/create_atoms.rst

@@ -10,7 +10,7 @@ Syntax
 
    create_atoms type style args keyword values ...
 
-* type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)
+* type = atom type (1-Ntypes or type label) of atoms to create (offset for molecule creation)
 * style = *box* or *region* or *single* or *mesh* or *random*
 
   .. parsed-literal::
@@ -37,7 +37,7 @@ Syntax
          seed = random # seed (positive integer)
        *basis* values = M itype
          M = which basis atom
-         itype = atom type (1-N) to assign to this basis atom
+         itype = atom type (1-Ntypes or type label) to assign to this basis atom
        *ratio* values = frac seed
          frac = fraction of lattice sites (0 to 1) to populate randomly
          seed = random # seed (positive integer)
@@ -74,6 +74,13 @@ Examples
 .. code-block:: LAMMPS
 
    create_atoms 1 box
+
+   labelmap atom 1 Pt
+   create_atoms Pt box
+
+   labelmap atom 1 C 2 Si
+   create_atoms C region regsphere basis Si C
+
    create_atoms 3 region regsphere basis 2 3
    create_atoms 3 region regsphere basis 2 3 ratio 0.5 74637
    create_atoms 3 single 0 0 5

doc/src/delete_bonds.rst

@@ -43,6 +43,9 @@ Examples
    delete_bonds all bond 0*3 special
    delete_bonds all stats
 
+   labelmap atom 4 hc
+   delete_bonds all atom hc special
+
 Description
 """""""""""
 
@@ -59,19 +62,20 @@ For all styles, by default, an interaction is only turned off (or on)
 if all the atoms involved are in the specified group.  See the *any*
 keyword to change the behavior.
 
-Several of the styles (\ *atom*, *bond*, *angle*, *dihedral*,
-*improper*\ ) take a *type* as an argument.  The specified *type* should
-be an integer from 0 to :math:`N`, where :math:`N` is the number of relevant
+Several of the styles (\ *atom*, *bond*, *angle*, *dihedral*, *improper*\ )
+take a *type* as an argument.  The specified *type* can be a
+:doc:`type label <Howto_type_labels>`.  Otherwise, the type should be an
+integer from 0 to :math:`N`, where :math:`N` is the number of relevant
 types (atom types, bond types, etc.).  A value of 0 is only relevant for
-style *bond*\ ; see details below.  In all cases, a wildcard asterisk
+style *bond*\ ; see details below.  For numeric types, a wildcard asterisk
 can be used in place of or in conjunction with the *type* argument to
 specify a range of types.  This takes the form "\*" or "\*n" or "m\*" or
-"m\*n".  If :math:`N` is the number of types, then an asterisk with no numeric
-values means all types from 0 to :math:`N`.  A leading asterisk means all
-types from 0 to n (inclusive).  A trailing asterisk means all types
-from m to N (inclusive).  A middle asterisk means all types from m to
-n (inclusive).  Note that it is fine to include a type of 0 for
-non-bond styles; it will simply be ignored.
+"m\*n".  If :math:`N` is the number of types, then an asterisk with no
+numeric values means all types from 0 to :math:`N`.  A leading asterisk
+means all types from 0 to n (inclusive).  A trailing asterisk means all
+types from m to N (inclusive).  A middle asterisk means all types from m to
+n (inclusive).  Note that it is fine to include a type of 0 for non-bond
+styles; it will simply be ignored.
 
 For style *multi* all bond, angle, dihedral, and improper interactions
 of any type, involving atoms in the group, are turned off.

doc/src/dump.rst

@@ -114,6 +114,7 @@ Syntax
            proc = ID of processor that owns atom
            procp1 = ID+1 of processor that owns atom
            type = atom type
+           typelabel = atom :doc:`type label <Howto_type_labels>`
            element = name of atom element, as defined by :doc:`dump_modify <dump_modify>` command
            mass = atom mass
            x,y,z = unscaled atom coordinates
@@ -470,8 +471,9 @@ followed by one line per atom with the atom type and the :math:`x`-,
 :math:`y`-, and :math:`z`-coordinate of that atom.  You can use the
 :doc:`dump_modify element <dump_modify>` option to change the output
 from using the (numerical) atom type to an element name (or some other
-label). This will help many visualization programs to guess bonds and
-colors.
+label). This option will help many visualization programs to guess bonds
+and colors. You can use the :doc:`dump_modify types labels <dump_modify>`
+option to replace numeric atom types with :doc:`type labels <Howto_type_labels>`.
 
 .. versionadded:: 22Dec2022
 
@@ -774,21 +776,21 @@ command creates a per-atom array with six columns:
 
 Per-atom attributes used as arguments to the *custom* and *cfg* styles:
 
-The *id*, *mol*, *proc*, *procp1*, *type*, *element*, *mass*, *vx*,
-*vy*, *vz*, *fx*, *fy*, *fz*, *q* attributes are self-explanatory.
+The *id*, *mol*, *proc*, *procp1*, *type*, *typelabel*, *element*, *mass*,
+*vx*, *vy*, *vz*, *fx*, *fy*, *fz*, *q* attributes are self-explanatory.
 
-*Id* is the atom ID.  *Mol* is the molecule ID, included in the data
-file for molecular systems.  *Proc* is the ID of the processor (0 to
+*Id* is the atom ID.  *Mol* is the molecule ID, included in the data file
+for molecular systems.  *Proc* is the ID of the processor (0 to
 :math:`N_\text{procs}-1`) that currently owns the atom.  *Procp1* is the
 proc ID+1, which can be convenient in place of a *type* attribute (1 to
 :math:`N_\text{types}`) for coloring atoms in a visualization program.
-*Type* is the atom type (1 to :math:`N_\text{types}`).  *Element* is
-typically the chemical name of an element, which you must assign to each
-type via the :doc:`dump_modify element <dump_modify>` command.  More
-generally, it can be any string you wish to associated with an atom
-type.  *Mass* is the atom mass. The quantities *vx*, *vy*, *vz*, *fx*,
-*fy*, *fz*, and *q* are components of atom velocity and force and atomic
-charge.
+*Type* is the atom type (1 to :math:`N_\text{types}`).  *Typelabel* is the
+atom :doc:`type label <Howto_type_labels>`.  *Element* is typically the
+chemical name of an element, which you must assign to each type via the
+:doc:`dump_modify element <dump_modify>` command.  More generally, it can
+be any string you wish to associated with an atom type.  *Mass* is the atom
+mass.  The quantities *vx*, *vy*, *vz*, *fx*, *fy*, *fz*, and *q* are
+components of atom velocity and force and atomic charge.
 
 There are several options for outputting atom coordinates.  The *x*,
 *y*, and *z* attributes write atom coordinates "unscaled", in the

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 *colname* 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 *triclinic/general* or *units* or *unwrap*
+* keyword = *append* or *at* or *balance* or *buffer* or *colname* 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 *triclinic/general* or *types* or *units* or *unwrap*
 
   .. parsed-literal::
 
@@ -81,6 +81,7 @@ Syntax
          these 3 args can be replaced by the word "none" to turn off thresholding
        *time* arg = *yes* or *no*
        *triclinic/general* arg = *yes* or *no*
+       *types* value = *numeric* or *labels*
        *units* arg = *yes* or *no*
        *unwrap* arg = *yes* or *no*
 
@@ -849,6 +850,13 @@ The default setting is *no*\ .
 
 ----------
 
+The *types* keyword applies only to the dump xyz style. If this keyword is
+used with a value of *numeric*, then numeric atom types are printed in the
+xyz file (default). If the value *labels* is specified, then
+:doc:`type labels <Howto_type_labels>` are printed for atom types.
+
+----------
+
 The *triclinic/general* keyword only applies to the dump *atom* and
 *custom* styles.  It can only be used with a value of *yes* if the
 simulation box was created as a general triclinic box.  See the
@@ -960,11 +968,11 @@ The option defaults are
 * sort = id for dump styles *dcd*, *xtc*, and *xyz*
 * thresh = none
 * time = no
-* triclinic/general no
+* triclinic/general = no
+* types = numeric
 * units = no
 * unwrap = no
 
 * compression_level = 9 (gz variants)
 * compression_level = 0 (zstd variants)
 * checksum = yes (zstd variants)
-

doc/src/fix_adapt.rst

@@ -21,17 +21,17 @@ Syntax
        *pair* args = pstyle pparam I J v_name
          pstyle = pair style name (e.g., lj/cut)
          pparam = parameter to adapt over time
-         I,J = type pair(s) to set parameter for
+         I,J = type pair(s) to set parameter for (integer or type label)
          v_name = variable with name that calculates value of pparam
        *bond* args = bstyle bparam I v_name
          bstyle = bond style name (e.g., harmonic)
          bparam = parameter to adapt over time
-         I = type bond to set parameter for
+         I = type bond to set parameter for (integer or type label)
          v_name = variable with name that calculates value of bparam
        *angle* args = astyle aparam I v_name
          astyle = angle style name (e.g., harmonic)
          aparam = parameter to adapt over time
-         I = type angle to set parameter for
+         I = type angle to set parameter for (integer or type label)
          v_name = variable with name that calculates value of aparam
        *kspace* arg = v_name
          v_name = variable with name that calculates scale factor on :math:`k`-space terms
@@ -67,6 +67,9 @@ Examples
    variable ramp_up equal "ramp(0.01,0.5)"
    fix stretch all adapt 1 bond harmonic r0 1 v_ramp_up
 
+   labelmap atom 1 c1
+   fix 1 all adapt 1 pair soft a c1 c1 v_prefactor
+
 Description
 """""""""""
 
@@ -254,10 +257,12 @@ should be specified to indicate which type pairs to apply it to.  If a global
 parameter is specified, the :math:`I` and :math:`J` settings still need to be
 specified, but are ignored.
 
-Similar to the :doc:`pair_coeff command <pair_coeff>`, :math:`I` and :math:`J`
-can be specified in one of two ways.  Explicit numeric values can be used for
-each, as in the first example above.  :math:`I \le J` is required.  LAMMPS sets
-the coefficients for the symmetric :math:`J,I` interaction to the same values.
+Similar to the :doc:`pair_coeff command <pair_coeff>`, :math:`I` and
+:math:`J` can be specified in one of several ways.  Explicit numeric values
+can be used for each, as in the first example above.  Or, one or both of
+the types in the I,J pair can be a :doc:`type label <Howto_type_labels>`.
+LAMMPS sets the coefficients for the symmetric :math:`J,I` interaction to
+the same values.
 
 A wild-card asterisk can be used in place of or in conjunction with
 the :math:`I,J` arguments to set the coefficients for multiple pairs of atom
@@ -266,8 +271,9 @@ is the number of atom types, then an asterisk with no numeric values
 means all types from 1 to :math:`N`.  A leading asterisk means all types from
 1 to n (inclusive).  A trailing asterisk means all types from m to :math:`N`
 (inclusive).  A middle asterisk means all types from m to n
-(inclusive).  Note that only type pairs with :math:`I \le J` are considered; if
-asterisks imply type pairs where :math:`J < I`, they are ignored.
+(inclusive).  For the asterisk syntax, note that only type pairs with
+:math:`I \le J` are considered; if asterisks imply type pairs where
+:math:`J < I`, they are ignored.
 
 IMPORTANT NOTE: If :doc:`pair_style hybrid or hybrid/overlay
 <pair_hybrid>` is being used, then the *pstyle* will be a sub-style

doc/src/fix_adapt_fep.rst

@@ -21,13 +21,13 @@ Syntax
        *pair* args = pstyle pparam I J v_name
          pstyle = pair style name (e.g., lj/cut)
          pparam = parameter to adapt over time
-         I,J = type pair(s) to set parameter for
+         I,J = type pair(s) to set parameter for (integer or type label)
          v_name = variable with name that calculates value of pparam
        *kspace* arg = v_name
          v_name = variable with name that calculates scale factor on K-space terms
        *atom* args = aparam v_name
          aparam = parameter to adapt over time
-         I = type(s) to set parameter for
+         I = type(s) to set parameter for (integer or type label)
          v_name = variable with name that calculates value of aparam
 
 * zero or more keyword/value pairs may be appended
@@ -56,6 +56,9 @@ Examples
    fix 1 all adapt/fep 1 pair lj/cut epsilon * * v_scale1 coul/cut scale 3 3 v_scale2 scale yes reset yes
    fix 1 all adapt/fep 10 atom diameter 1 v_size
 
+   labelmap atom 1 c1
+   fix 1 all adapt/fep 1 pair soft a c1 c1 v_prefactor
+
 
 Example input scripts available: examples/PACKAGES/fep
 
@@ -218,10 +221,12 @@ be specified to indicate which type pairs to apply it to.  If a global
 parameter is specified, the *I* and *J* settings still need to be
 specified, but are ignored.
 
-Similar to the :doc:`pair_coeff command <pair_coeff>`, I and J can be
-specified in one of two ways.  Explicit numeric values can be used for
-each, as in the first example above.  :math:`I \le J` is required.  LAMMPS sets
-the coefficients for the symmetric J,I interaction to the same values.
+Similar to the :doc:`pair_coeff command <pair_coeff>`, :math:`I` and
+:math:`J` can be specified in one of several ways.  Explicit numeric values
+can be used for each, as in the first example above.  Or, one or both of
+the types in the I,J pair can be a :doc:`type label <Howto_type_labels>`.
+LAMMPS sets the coefficients for the symmetric :math:`J,I` interaction to
+the same values.
 
 A wild-card asterisk can be used in place of or in conjunction with
 the :math:`I,J` arguments to set the coefficients for multiple pairs of atom
@@ -230,8 +235,9 @@ the number of atom types, then an asterisk with no numeric values means
 all types from 1 to :math:`N`.  A leading asterisk means all types from 1 to n
 (inclusive).  A trailing asterisk means all types from m to :math:`N`
 (inclusive).  A middle asterisk means all types from m to n
-(inclusive).  Note that only type pairs with :math:`I \le J` are considered; if
-asterisks imply type pairs where :math:`J < I`, they are ignored.
+(inclusive).  For the asterisk syntax, note that only type pairs with
+:math:`I \le J` are considered; if asterisks imply type pairs where
+:math:`J < I`, they are ignored.
 
 IMPROTANT NOTE: If :doc:`pair_style hybrid or hybrid/overlay <pair_hybrid>` is
 being used, then the *pstyle* will be a sub-style name.  You must specify

doc/src/fix_atom_swap.rst

@@ -21,7 +21,7 @@ Syntax
 
   .. parsed-literal::
 
-       *types* values = two or more atom types
+       *types* values = two or more atom types (1-Ntypes or type label)
        *mu* values = chemical potential of swap types (energy units)
        *ke* value = *no* or *yes*
          *no* = no conservation of kinetic energy after atom swaps

doc/src/fix_bond_break.rst

@@ -13,7 +13,7 @@ Syntax
 * ID, group-ID are documented in :doc:`fix <fix>` command
 * bond/break = style name of this fix command
 * Nevery = attempt bond breaking every this many steps
-* bondtype = type of bonds to break
+* bondtype = type of bonds to break (integer or type label)
 * Rmax = bond longer than Rmax can break (distance units)
 * zero or more keyword/value pairs may be appended
 * keyword = *prob*

doc/src/fix_bond_create.rst

@@ -17,29 +17,29 @@ Syntax
 * ID, group-ID are documented in :doc:`fix <fix>` command
 * bond/create = style name of this fix command
 * Nevery = attempt bond creation every this many steps
-* itype,jtype = atoms of itype can bond to atoms of jtype
+* itype,jtype = atoms of itype can bond to atoms of jtype (1-Ntypes or type label)
 * Rmin = 2 atoms separated by less than Rmin can bond (distance units)
-* bondtype = type of created bonds
+* bondtype = type of created bonds (integer or type label)
 * zero or more keyword/value pairs may be appended to args
 * keyword = *iparam* or *jparam* or *prob* or *atype* or *dtype* or *itype* or *aconstrain*
 
   .. parsed-literal::
 
        *iparam* values = maxbond, newtype
          maxbond = max # of bonds of bondtype the itype atom can have
-         newtype = change the itype atom to this type when maxbonds exist
+         newtype = change the itype atom to this type when maxbonds exist (1-Ntypes or type label)
        *jparam* values = maxbond, newtype
          maxbond = max # of bonds of bondtype the jtype atom can have
-         newtype = change the jtype atom to this type when maxbonds exist
+         newtype = change the jtype atom to this type when maxbonds exist (1-Ntypes or type label)
        *prob* values = fraction seed
          fraction = create a bond with this probability if otherwise eligible
          seed = random number seed (positive integer)
        *atype* value = angletype
-         angletype = type of created angles
+         angletype = type of created angles (integer or type label)
        *dtype* value = dihedraltype
-         dihedraltype = type of created dihedrals
+         dihedraltype = type of created dihedrals (integer or type label)
        *itype* value = impropertype
-         impropertype = type of created impropers
+         impropertype = type of created impropers (integer or type label)
        *aconstrain* value = amin amax
          amin = minimal angle at which new bonds can be created
          amax = maximal angle at which new bonds can be created
@@ -54,6 +54,10 @@ Examples
    fix 5 all bond/create 1 3 3 0.8 1 prob 0.5 85784 iparam 2 3 atype 1 dtype 2
    fix 5 all bond/create/angle 10 1 2 1.122 1 aconstrain 120 180 prob 1 4928459 iparam 2 1 jparam 2 2
 
+   labelmap atom 1 c1 2 n2
+   labelmap bond 1 c1-n2
+   fix 5 all bond/create 10 c1 n2 0.8 c1-n2
+
 Description
 """""""""""