diff --git a/doc/src/Howto_type_labels.rst b/doc/src/Howto_type_labels.rst index f04a53e630..77f5b216c0 100644 --- a/doc/src/Howto_type_labels.rst +++ b/doc/src/Howto_type_labels.rst @@ -1,44 +1,65 @@ Type labels =========== -Each atom in LAMMPS has an associated atom type. Likewise each bond, -angle, dihedral, improper enumerated in a data file read by the -:doc:`read_data ` command has a bond type, angle type, etc. +.. versionadded:: TBD -By default, type values are integers from 1 to Ntypes, wherever they -appear in LAMMPS input or output files. However, LAMMPS also has the -option to use alphanumeric strings, called type labels, for these -values in its input and output. +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. -Using labels instead of numeric types can be useful in various -scenarios. For example, type labels can make inputs more readable and -compatible with other inputs (e.g., data files, molecule template -files read by the :doc:`molecule ` command, etc.), -particularly if a force field uses alphanumeric atom types. See a list -of other commands below which can use label types in interesting ways. +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 +is created. -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. +A recent addition to LAMMPS is the option to use strings - referred +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 ` 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 ` or molecule template +files read by the :doc:`molecule ` command. See below for a list +of other commands below which can use label types in different ways. -Valid type labels can contain any alphanumeric character, but cannot -start with a number. They can also contain standard characters, such -as square brackets "[" and "]", underscore "_", dash "-", plus "+" and -equals "=" signs. Note that type labels cannot contain the comment -symbol '#'. +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. -There are two ways to define label maps. One is via the -:doc:`labelmap ` command. The other is via the -:doc:`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 label map can be written out to data -files by the :doc:`write_data ` command. This map is also -written to and read from restart files, by the :doc:`write_restart -` and :doc:`read_restart ` commands. +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 ` command and read back +with the :doc:`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 +characters. When using the :doc:`labelmap command ` 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: + +.. code-block:: LAMMPS + + labelmap angle 1 """ C1'-C2"-C3# """ + +This 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 +` command. The other is via the :doc:`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 +label map can be written out to data files by the :doc:`write_data +` command. This map is also written to and read from +restart files, by the :doc:`write_restart ` and +:doc:`read_restart ` commands. ---------- @@ -59,14 +80,16 @@ labels to redefine the pair coefficients. labelmap atom 1 C 2 H pair_coeff C H 1.0 1.0 # type labels -Support for type labels is a work-in-progress for LAMMPS as of -Nov 2021. If an input script command allows substituting for a -numeric type argument with a type label, it will be mentioned on that -command's doc page. If not yet supported, any input script command -that requires a numeric type can instead use a variable with a -labelmap function that converts a type label to a numeric type, as in -the last example above. See the :doc:`variable ` command -for details. +Adding support for type labels to various commands is an ongoing +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. +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 ` command for details. For example, here is how the pair_coeff command could be used with type labels if it did not yet support them, either with an explicit @@ -85,35 +108,15 @@ command. labelmap atom 1 C 2 H pair_coeff $(label(C)) $(label(H)) 80.0 1.2 -Support for output of type labels in dump files will be added to -LAMMPS soon (as of Nov 2021). - ---------- -Commands that can use label types in interesting ways -""""""""""""""""""""""""""""""""""""""""""""""""""""" - -As of Nov 2021, efforts are underway to utilize type labels in various -commands. +Commands that can use label types +""""""""""""""""""""""""""""""""" Any workflow that involves reading multiple data files, molecule -templates or a combination of the two will be greatly streamlined by -using type labels instead of numeric types, because types are -automatically synced between the files. For example, the creation of -simulation-ready reaction templates for :doc:`fix bond/react ` -is much simpler when using type labels, and results in templates that -can be used without modification in new simulations. Additional fix -bond/react features enabled by type labels are in progress, such as -using wildcards to further increase the portability of reaction -templates, as well as automatically inferring the types of newly -created bond, angle, etc. interactions. - -LAMMPS type labels will be used in a planned extension of OpenKIM to -support bonded force fields (FFs) (such as CHARMM, AMBER, IFF, etc.). -Users will be able to use a bonded FF, packaged as an OpenKIM -Simulator Model (SM), using the `kim init` command. The SM will -include all required interaction parameters (pair, bond, angle, -dihedral, improper) defined in terms of the standard atom types for -that FF. Molecular configurations can then be specified within a -LAMMPS script or read in from a data file by using type labels that -match the atom types for that FF. +templates or a combination of the two can be streamlined by using type +labels instead of numeric types, because types are automatically synced +between the files. The creation of simulation-ready reaction templates +for :doc:`fix bond/react ` is much simpler when using +type labels, and results in templates that can be used without +modification in multiple simulations or different systems.