\(\renewcommand{\AA}{\text{Å}}\)

8.2.2. Type labels

New in version 15Sep2022.

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 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 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 include command for different systems with different numerical values assigned to types. This generality also applies to other inputs like data files read by read_data or molecule template files read by the molecule command. A discussion of the current type label support can be found in (Gissinger). See below for a list of other commands that can use type labels in different ways.

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 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 labelmap write command and read back with the 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 labelmap command in the 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:

labelmap angle 1 """ C1'-C2"-C3# """

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 labelmap command. The other is via the read_data command. A data file can have sections such as Atom Type Labels, Bond Type Labels, etc., which assign type labels to numeric types. The label map can be written out to data files by the write_data command. This map is also written to and read from restart files, by the write_restart and read_restart commands.

Use of type labels in LAMMPS input or output

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.

This example assigns labels to the atom types, and then uses the type labels to redefine the pair coefficients.

pair_coeff 1 2 1.0 1.0              # numeric types
labelmap atom 1 C 2 H
pair_coeff C H 1.0 1.0              # type labels

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 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 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 variable command or an implicit variable used in the pair_coeff command.

labelmap atom 1 C 2 H
variable atom1 equal label2type(atom,C)
variable atom2 equal label2type(atom,H)
pair_coeff ${atom1} ${atom2} 1.0 1.0

labelmap atom 1 C 2 H
pair_coeff $(label2type(atom,C)) $(label2type(atom,H)) 80.0 1.2

Commands that can use label types

Any workflow that involves reading multiple data files, molecule 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 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.

(Gissinger) J. R. Gissinger, I. Nikiforov, Y. Afshar, B. Waters, M. Choi, D. S. Karls, A. Stukowski, W. Im, H. Heinz, A. Kohlmeyer, and E. B. Tadmor, J Phys Chem B, 128, 3282-3297 (2024).