ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs update

Browse Source
This commit is contained in:
Jacob Gissinger
2021-12-06 17:47:47 -05:00
parent 2f851db756
commit 14e09b7a75
9 changed files with 89 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
doc/src/Howto_type_labels.rst
View File

@ -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 <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 <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
<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 <write_data>` command. They are also written to and
read from restart files, by the :doc:`write_restart <write_restart>`
and :doc:`read_restart <read_restart>` commands. Label maps with
If defined, the default label map can be written out to data files by
the :doc:`write_data <write_data>` command. They are also written to
and read from restart files, by the :doc:`write_restart <write_restart>`
and :doc:`read_restart <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 <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?

4
doc/src/angle_coeff.rst
View File

@ -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
"""""""""""

4
doc/src/bond_coeff.rst
View File

@ -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
"""""""""""

4
doc/src/dihedral_coeff.rst
View File

@ -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
"""""""""""

3
doc/src/improper_coeff.rst
View File

@ -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
"""""""""""

31
doc/src/labelmap.rst
View File

@ -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 <read_data>`
The default label maps can also be defined by the :doc:`read_data <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
<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.

2
doc/src/molecule.rst
View File

@ -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
<labelmap>` command or in data files read by the :doc:`read_data
<read_data>` command which have sections for Atom Type Labels, Bond
Type Labels, Angle Type Labels, etc. See the :doc:`Howto type labels

11
doc/src/pair_coeff.rst
View File

@ -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 <labelmap>` command
or in a section of a data file read by the :doc:`read_data
<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

32
doc/src/write_data.rst
View File

@ -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 <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
<labelmap>` command or in data files read by the :doc:`read_data
<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 <labelmap>`
command or in data files read by the :doc:`read_data <read_data>`
command which have sections for Atom Type Labels, Bond Type Labels,
Angle Type Labels, etc. See the :doc:`Howto type labels
<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