From 14e09b7a757ec4db4574c5740669d3d0d3600a67 Mon Sep 17 00:00:00 2001 From: Jacob Gissinger Date: Mon, 6 Dec 2021 17:47:47 -0500 Subject: [PATCH] docs update --- doc/src/Howto_type_labels.rst | 72 ++++++++++++++++++++--------------- doc/src/angle_coeff.rst | 4 +- doc/src/bond_coeff.rst | 4 +- doc/src/dihedral_coeff.rst | 4 +- doc/src/improper_coeff.rst | 3 ++ doc/src/labelmap.rst | 31 ++++++++------- doc/src/molecule.rst | 2 +- doc/src/pair_coeff.rst | 11 +++--- doc/src/write_data.rst | 32 ++++++++-------- 9 files changed, 89 insertions(+), 74 deletions(-) diff --git a/doc/src/Howto_type_labels.rst b/doc/src/Howto_type_labels.rst index 3066b88078..a50f69aad2 100644 --- a/doc/src/Howto_type_labels.rst +++ b/doc/src/Howto_type_labels.rst @@ -10,35 +10,35 @@ 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. -This 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), particularly if a force field uses alphanumeric atom types. -See a list of other commands below which can use label types in -interesting ways. +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. -A collection of one or more type labels for one category of types -(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 -map, each type label must be unique. It can be assigned to only one -numeric type. Not all numeric types need have a type label assigned. +A collection of type labels for all interaction types (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 map, each type +label must be unique. It can be assigned to only one numeric type. +Not all numeric types need have a type label assigned. -There can be mutliple label maps defined for a single type category, -e.g. atom types. There is a default label map which has no mapID. -Additional label maps each have a mapID, which is a string containing -only alphanumeric characters and underscores. +There can be multiple label maps defined. There is a default label +map which has no mapID. Additional label maps each have a mapID, +which is a string containing only alphanumeric characters and +underscores. Valid type labels can contain any alphanumeric character, but cannot -start with a number. They can also contain any of these characters: -square brackets "[" and "]", dash "-", underscore "_", JAKE what other -chars are allowed? Note that type labels cannot contain the symbols +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 symbols '#' or '*'. -As explained below, for certain command in LAMMPS, it is useful to +As explained below, for certain commands in LAMMPS, it is useful to define type labels so that the atom types that make up a given bond, angle, dihedral, or improper can be deduced from the type label. A standard way to do that is to define the type label for the bond by -enclosing the constituent atom types in square brackets. E.g. define +enclosing the constituent atom types in square brackets. E.g., define a C-H bond with a type label "[C][H]". There are two ways to define label maps. One is via the @@ -47,12 +47,13 @@ keyword to allow creation of type labels in either a default map or an additional map with a mapID. The other is via the :doc:`read_data ` command. A data file can have sections such as Atom Type Labels, Bond Type Lables, etc, which associate type labels with -numeric types. Only default label maps can be defined in this manner. +numeric types. Only the default label map can be defined in this +manner. -If defined, default label maps can be written out to data files by the -:doc:`write_data ` command. They are also written to and -read from restart files, by the :doc:`write_restart ` -and :doc:`read_restart ` commands. Label maps with +If defined, the default label map can be written out to data files by +the :doc:`write_data ` command. They are also written to +and read from restart files, by the :doc:`write_restart ` +and :doc:`read_restart ` commands. Label maps with mapIDs cannot be written to either data or restart files by these commands. @@ -67,8 +68,8 @@ mapID prepended, followed by a double colon "::". If a type label is not defined for a particular numeric type, only its numeric type can be used. -The first example uses a default label map for bond types. The second -uses a label map with mapID = Map2. +The first example uses the default label map for bond types. The +second uses a label map with mapID = Map2. .. code-block:: LAMMPS @@ -117,9 +118,20 @@ LAMMPS soon (as of Nov 2021). Commands that can use label types in interesting ways """"""""""""""""""""""""""""""""""""""""""""""""""""" -Provide a few details on these to spark user's interest? If not yet -implemented, just say this is planned, as of Nov 2021. +As of Nov 2021, efforts are underway to utilize type labels in various +commands. + +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. -fix bond/react pair_style kim other? diff --git a/doc/src/angle_coeff.rst b/doc/src/angle_coeff.rst index cbe74a9aac..40ed936db8 100644 --- a/doc/src/angle_coeff.rst +++ b/doc/src/angle_coeff.rst @@ -22,8 +22,8 @@ Examples angle_coeff * 5.0 angle_coeff 2*10 5.0 -JAKE add an example with 2 lines. First = labelmap command, second = -use the type label. + labelmap angle 1 [C][O][H] + angle_coeff [C][O][H] 300.0 107.0 Description """"""""""" diff --git a/doc/src/bond_coeff.rst b/doc/src/bond_coeff.rst index 4f2d226dc1..4992fba521 100644 --- a/doc/src/bond_coeff.rst +++ b/doc/src/bond_coeff.rst @@ -23,8 +23,8 @@ Examples bond_coeff 1*4 30.0 1.5 1.0 1.0 bond_coeff 1 harmonic 200.0 1.0 (for bond_style hybrid) -JAKE add an example with 2 lines. First = labelmap command, second = -use the type label. + labelmap bond 5 [C][H] + bond_coeff [C][H] 80.0 1.2 Description """"""""""" diff --git a/doc/src/dihedral_coeff.rst b/doc/src/dihedral_coeff.rst index 846973b7ed..e060abdc59 100644 --- a/doc/src/dihedral_coeff.rst +++ b/doc/src/dihedral_coeff.rst @@ -22,8 +22,8 @@ Examples dihedral_coeff * 80.0 1 3 0.5 dihedral_coeff 2* 80.0 1 3 0.5 -JAKE add an example with 2 lines. First = labelmap command, second = -use the type label. + labelmap dihedral 1 [C][C][O][H] + dihedral_coeff [C][C][O][H] 80.0 1 3 Description """"""""""" diff --git a/doc/src/improper_coeff.rst b/doc/src/improper_coeff.rst index 980eda05c6..aa1e5f60e8 100644 --- a/doc/src/improper_coeff.rst +++ b/doc/src/improper_coeff.rst @@ -22,6 +22,9 @@ Examples improper_coeff * 80.2 -1 2 improper_coeff *4 80.2 -1 2 + labelmap improper 1 [C][C][C][N] + improper_coeff [C][C][C][N] 300.0 0.0 + Description """"""""""" diff --git a/doc/src/labelmap.rst b/doc/src/labelmap.rst index 87ec50e67b..32b222fb3e 100644 --- a/doc/src/labelmap.rst +++ b/doc/src/labelmap.rst @@ -28,19 +28,18 @@ Examples labelmap atom 3 carbon labelmap bond 1 [c1][c2] 2 [c1][hc] labelmap bond 1 [c1][c2] 2 [c1][hc] mapID myMap - JAKE: give an example of a command using variable labelmap func (see below) + labelmap atom $(label(carbon)) C // change type label from 'carbon' to 'C' Description """"""""""" Define alphanumeric type labels to associate with one or more numeric atom, bond, angle, dihedral or improper types. A collection of type -labels for a particular type-kind (atom types, bond types, etc) is -stored as a label map. As explained below, this command also allows -definition of multiple label maps for the same type-kind by use of the -mapID keyword. +labels for all atom types, bond types, etc is stored as a label map. +As explained below, this command also allows definition of multiple +label maps by use of the mapID keyword. -Label maps can also be defined by the :doc:`read_data ` +The default label maps can also be defined by the :doc:`read_data ` command when it reads these sections in a data file: Atom Type Labels, Bond Type Lables, etc. See the :doc:`Howto type labels ` doc page for a general discussion of how type @@ -48,9 +47,9 @@ labels can be used. As explained on the Howto page, valid type labels can contain any alphanumeric character, but cannot start with a number. They can also -contain any of these characters: square brackets "[" and "]", dash -"-", underscore "_", JAKE what other chars are allowed? Note that -type labels cannot contain the symbols '#' or '*'. +contain standard characters such as square brackets "[" and "]", dash +"-", underscore "_", plus "+" and equals "=" signs. Note that type +labels cannot contain the symbols '#' or '*'. A *labelmap* command can only modify the label map for one type-kind (atom types, bond types, etc). Any number of numeric-type/type-label @@ -60,12 +59,12 @@ the same type label to multiple numeric types is not allowed. Note that there is no requirement that a type label be defined for every numeric type. -It may sometimes be useful to define multiple label maps for a single -type-kind. This can be done using the *mapID* keyword. The specified -*name* is the mapID assigned to the label map. The ID of a label map -can only contain alphanumeric characters and underscores. If the -*mapID* keyword is not used, the specified type labels are assigned to -the default label map for each type-kind, which has no mapID. +It may sometimes be useful to define multiple label maps. This can be +done using the *mapID* keyword. The specified *name* is the mapID +assigned to the label map. The ID of a label map can only contain +alphanumeric characters and underscores. If the *mapID* keyword is +not used, the specified type labels are assigned to the default label +map, which has no mapID. ---------- @@ -86,4 +85,4 @@ Default """"""" If the mapID keyword is not used, specified type labels are assigned -to the default map for the type-kind. +to the default map. diff --git a/doc/src/molecule.rst b/doc/src/molecule.rst index 1112c7fc38..edfcf0b92d 100644 --- a/doc/src/molecule.rst +++ b/doc/src/molecule.rst @@ -177,7 +177,7 @@ These are the allowed section keywords for the body of the file. For the Types, Bonds, Angles, Dihedrals, and Impropers sections, each atom/bond/angle/etc type can be specified either as a number (numeric type) or as an alphanumeric type label. The latter is only allowed if -type lables have been defined, either by the :doc:`labelmap +type labels have been defined, either by the :doc:`labelmap ` command or in data files read by the :doc:`read_data ` command which have sections for Atom Type Labels, Bond Type Labels, Angle Type Labels, etc. See the :doc:`Howto type labels diff --git a/doc/src/pair_coeff.rst b/doc/src/pair_coeff.rst index 4f10ff2da2..3a1a79aa8e 100644 --- a/doc/src/pair_coeff.rst +++ b/doc/src/pair_coeff.rst @@ -40,9 +40,8 @@ or both of the types in the I,J pair can be a type label, which is an alphanumeric string defined by the :doc:`labelmap ` command or in a section of a data file read by the :doc:`read_data ` command, and which converts internally to a numeric type. -In either case I <= J is required. Interally, LAMMPS will set -coefficients for the symmetric J,I interaction to the same values as -the I <= J interaction. +Interally, LAMMPS will set coefficients for the symmetric J,I +interaction to the same values as the I <= J interaction. For numeric values only, a wildcard asterisk can be used in place of or in conjunction with the I,J arguments to set the coefficients for @@ -53,9 +52,9 @@ asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive). For the asterisk syntax, only type pairs with I <= J are considered; if asterisks imply type pairs where -J < I, they are ignored (no error as with non-asterisk arguments). -Again interally, LAMMPS will set the coefficients for the symmetric -J,I interactions to the same values as the I <= J interactions. +J < I, they are ignored. Again internally, LAMMPS will set the +coefficients for the symmetric J,I interactions to the same values as +the I <= J interactions. Note that a pair_coeff command can override a previous setting for the same I,J pair. For example, these commands set the coeffs for all I,J diff --git a/doc/src/write_data.rst b/doc/src/write_data.rst index 6200f62716..0d1c4518e7 100644 --- a/doc/src/write_data.rst +++ b/doc/src/write_data.rst @@ -107,25 +107,27 @@ written to the data file (see the *fix* option of the :doc:`read_data sections for user-created per-atom properties from :doc:`fix property/atom `. -The *nolabelmap* and *types* keywords refer to label maps that may be -defined for number atom types, bond types, angle types, etc. Label -maps can be defined in two ways, either by the :doc:`labelmap -` command or in data files read by the :doc:`read_data -` command which have sections for Atom Type Labels, Bond -Type Labels, Angle Type Labels, etc. See the :doc:`Howto type labels +The *nolabelmap* and *types* keywords refer to type labels that may be +defined for numeric atom types, bond types, angle types, etc. Only +the default label map is written to data files. The default label map +can be defined in two ways, either by the :doc:`labelmap ` +command or in data files read by the :doc:`read_data ` +command which have sections for Atom Type Labels, Bond Type Labels, +Angle Type Labels, etc. See the :doc:`Howto type labels ` doc page for the allowed syntax of type labels and a general discussion of how type labels can be used. -Use of the *nolabelmap* keyword means that even if default type label -maps exist for Atoms, Bonds, Angles, etc, they are not written to the -data file. By default, they are written if they exist. +Use of the *nolabelmap* keyword means that even if the default type +label map exists for Atoms, Bonds, Angles, etc., type labels are not +written to the data file. By default, they are written if they exist. -The *types* keyword determins how atom types, bond types, angle types, -etc are written into these data file sections: Atoms, Bonds, Angles, -etc. The default is the *numeric* setting, even if type label maps -exist. If the *labels" setting is used, type labels will be written -to the data file, if the corresponding label map exists. Note that -when using *types labels*, the *nolabelmap* keyword cannot be used. +The *types* keyword determines how atom types, bond types, angle +types, etc are written into these data file sections: Atoms, Bonds, +Angles, etc. The default is the *numeric* setting, even if type label +maps exist. If the *labels* setting is used, type labels will be +written to the data file, if the corresponding label map exists. Note +that when using *types labels*, the *nolabelmap* keyword cannot be +used. The *pair* keyword lets you specify in what format the pair coefficient information is written into the data file. If the value