corrections, suggestions to labelmap howto

doc/src/Howto_type_labels.rst

@@ -3,14 +3,15 @@ Type labels
 
 .. versionadded:: TBD
 
-Each atom in LAMMPS has an associated numeric atom type; likewise bonds,
-angles, dihedrals, and impropers have a bond type, angle type, and so
-on.  The primary use of these types are to map potential parameters to
-the interactions of the atom, bond, angle, dihedral, and improper.
+Each atom in LAMMPS has an associated numeric atom type. Similarly,
+each bond, angle, dihedral, and improper is assigned a bond type,
+angle type, and so on.  The primary use of these types is to map
+potential (force field) parameters to the interactions of the atom,
+bond, angle, dihedral, and improper.
 
-By default, type values are entered as integers from 1 to Ntypes,
-wherever they appear in LAMMPS input or output files. The number of
-these types are parameters that are "locked in" when the simulation box
+By default, type values are entered as integers from 1 to Ntypes
+wherever they appear in LAMMPS input or output files.  The total number
+Ntypes for each interaction is "locked in" when the simulation box
 is created.
 
 A recent addition to LAMMPS is the option to use strings - referred
@@ -18,44 +19,47 @@ to as type labels - as an alternative.  Using type labels instead of
 numeric types can be advantageous in various scenarios.  For example,
 type labels can make inputs more readable and generic (i.e. usable through
 the :doc:`include command <include>` for different systems with different
-counts and numeric assignment of types. This also applies to other inputs
-like data files read by :doc:`read_data <read_data>` or molecule template
-files read by the :doc:`molecule <molecule>` command.  See below for a list
-of other commands below which can use label types in different ways.
+numerical values assigned to types.  This generality also applies to
+other inputs like data files read by :doc:`read_data <read_data>` or
+molecule template files read by the :doc:`molecule <molecule>`
+command.  See below for a list of other commands that can use
+type labels in different ways.
 
-LAMMPS will *internally* continue to use the numeric types.  This means
-that all restrictions, e.g. locking in their counts when creating the
-simulation box, or that potential parameters for each type must be provided
-(even if not used by any interactions) still apply.
+LAMMPS will *internally* continue to use numeric types, which means
+that many previous restrictions still apply.  For example, the total
+number of types is locked in when creating the simulation box, and
+potential parameters for each type must be provided even if not used
+by any interactions.
 
 A collection of type labels for all type-kinds (atom types, bond types,
 etc.) is stored as a "label map" which is simply a list of numeric types
-and associated type labels.  Within a type-kind, each type label must be
-unique.  It can be assigned to only one numeric type. To read and write
-type labels to data files for a given type-kind, *all* associated
-numeric types need have a type label assigned.  Partial maps can be
-saved with the :doc:`labelmap write <labelmap>` command and read back
-with the :doc:`include <include>` command.
+and their associated type labels.  Within a type-kind, each type label
+must be unique.  It can be assigned to only one numeric type.  To read
+and write type labels to data files for a given type-kind, *all*
+associated numeric types need have a type label assigned.  Partial
+maps can be saved with the :doc:`labelmap write <labelmap>` command
+and read back with the :doc:`include <include>` command.
 
 Valid type labels can contain most ASCII characters, but cannot start
-with a number, a '#', or a '*'.  Also labels must not contain whitespace
+with a number, a '#', or a '*'.  Also, labels must not contain whitespace
 characters.  When using the :doc:`labelmap command <labelmap>` in the
-LAMMPS input, certain characters like the single (') or double (") quote
-or the '#' character require quoting with double, single, triple (""")
-quotes.  Triple quotes are the most generic but they require to have a
-leading and training blank.  When defining type labels the blanks will
-be ignored. Example:
+LAMMPS input, if certain characters appear in the type label, such as
+the single (') or double (") quote or the '#' character, the label
+must be put in either double, single, or triple (""") quotes.  Triple
+quotes allow for the most generic type label strings, but they require
+to have a leading and trailing blank space.  When defining type labels
+the blanks will be ignored. Example:
 
 .. code-block:: LAMMPS
 
    labelmap angle 1 """ C1'-C2"-C3# """
 
-This will map the string ```C1'-C2"-C3#``` to the angle type 1.
+This command will map the string ```C1'-C2"-C3#``` to the angle type 1.
 
 There are two ways to define label maps.  One is via the :doc:`labelmap
 <labelmap>` command.  The other is via the :doc:`read_data <read_data>`
 command.  A data file can have sections such as *Atom Type Labels*, *Bond
-Type Labels*, etc, which associate type labels with numeric types.  The
+Type Labels*, etc., which assign type labels to numeric types.  The
 label map can be written out to data files by the :doc:`write_data
 <write_data>` command.  This map is also written to and read from
 restart files, by the :doc:`write_restart <write_restart>` and
@@ -66,8 +70,8 @@ restart files, by the :doc:`write_restart <write_restart>` and
 Use of type labels in LAMMPS input or output
 """"""""""""""""""""""""""""""""""""""""""""
 
-Any LAMMPS input script command which takes a numeric type as an
-argument, can use the associated type label instead.  If a type label
+Many LAMMPS input script commands that take a numeric type as an
+argument can use the associated type label instead.  If a type label
 is not defined for a particular numeric type, only its numeric type
 can be used.
 
@@ -85,8 +89,8 @@ project.  If an input script command (or a section in a file read by a
 command) allows substituting a type label for a numeric type argument,
 it will be explicitly mentioned in that command's documentation page.
 
-As a temporary measure input script command can take advantage of
-variables and how they may be expanded during processing of the input.
+As a temporary measure, input script commands can take advantage of
+variables and how they can be expanded during processing of the input.
 The variables can use functions that will translate type label strings
 to their respective number as defined in the current label map.  See the
 :doc:`variable <variable>` command for details.
@@ -99,14 +103,14 @@ command.
 .. code-block:: LAMMPS
 
    labelmap atom 1 C 2 H
-   variable atom1 equal label(C)
-   variable atom2 equal label(H)
+   variable atom1 equal label2type(atom,C)
+   variable atom2 equal label2type(atom,H)
    pair_coeff ${atom1} ${atom2} 1.0 1.0
 
 .. code-block:: LAMMPS
 
    labelmap atom 1 C 2 H
-   pair_coeff $(label(C)) $(label(H)) 80.0 1.2
+   pair_coeff $(label2type(atom,C)) $(label2type(atom,H)) 80.0 1.2
 
 ----------