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

Merge branch 'develop' into fix-pair-dump-skip

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-09-12 18:19:12 -04:00
parent 73b44c3b18 23595aa851
commit 893586c8eb
372 changed files with 5404 additions and 2557 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Commands_all.rst
View File

@ -63,6 +63,7 @@ table above.
* :doc:`kspace_modify <kspace_modify>`
* :doc:`kspace_style <kspace_style>`
* :doc:`label <label>`
* :doc:`labelmap <labelmap>`
* :doc:`lattice <lattice>`
* :doc:`log <log>`
* :doc:`mass <mass>`

9
doc/src/Developer_utils.rst
View File

@ -175,6 +175,12 @@ and parsing files or arguments.
.. doxygenfunction:: is_double
:project: progguide
.. doxygenfunction:: is_id
:project: progguide
.. doxygenfunction:: is_type
:project: progguide
Potential file functions
^^^^^^^^^^^^^^^^^^^^^^^^
@ -205,6 +211,9 @@ Argument processing
.. doxygenfunction:: expand_args
:project: progguide
.. doxygenfunction:: expand_type
:project: progguide
Convenience functions
^^^^^^^^^^^^^^^^^^^^^

40
doc/src/Errors_messages.rst
View File

@ -5453,6 +5453,11 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
Mass command must set a type from 1-N where N is the number of atom
types.
*Invalid label2type() function syntax in variable formula*
The first argument must be a label map kind (atom, bond, angle,
dihedral, or improper) and the second argument must be a valid type
label that has been assigned to a numeric type.
*Invalid use of library file() function*
This function is called through the library interface. This
error should not occur. Contact the developers if it does.
@ -5585,9 +5590,18 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*LJ6 off not supported in pair_style buck/long/coul/long*
Self-explanatory.
*Label map is incomplete: all types must be assigned a unique type label*
For a given type-kind (atom types, bond types, etc.) to be written to
the data file, all associated types must be assigned a type label, and
each type label can be assigned to only one numeric type.
*Label wasn't found in input script*
Self-explanatory.
*Labelmap command before simulation box is defined*
The labelmap command cannot be used before a read_data,
read_restart, or create_box command.
*Lattice orient vectors are not orthogonal*
The three specified lattice orientation vectors must be mutually
orthogonal.
@ -5863,6 +5877,12 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Must not have multiple fixes change box parameter ...*
Self-explanatory.
*Must read Angle Type Labels before Angles*
An Angle Type Labels section of a data file must come before the Angles section.
*Must read Atom Type Labels before Atoms*
An Atom Type Labels section of a data file must come before the Atoms section.
*Must read Atoms before Angles*
The Atoms section of a data file must come before an Angles section.
@ -5893,6 +5913,15 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
The Atoms section of a data file must come before a Velocities
section.
*Must read Bond Type Labels before Bonds*
A Bond Type Labels section of a data file must come before the Bonds section.
*Must read Dihedral Type Labels before Dihedrals*
An Dihedral Type Labels section of a data file must come before the Dihedrals section.
*Must read Improper Type Labels before Impropers*
An Improper Type Labels section of a data file must come before the Impropers section.
*Must re-specify non-restarted pair style (xxx) after read_restart*
For pair styles, that do not store their settings in a restart file,
it must be defined with a new 'pair_style' command after read_restart.
@ -7849,6 +7878,10 @@ keyword to allow for additional bonds to be formed
Number of local atoms times number of columns must fit in a 32-bit
integer for dump.
*Topology type exceeds system topology type*
The number of bond, angle, etc types exceeds the system setting. See
the create_box or read_data command for how to specify these values.
*Tree structure in joint connections*
Fix poems cannot (yet) work with coupled bodies whose joints connect
the bodies in a tree structure.
@ -7873,6 +7906,13 @@ keyword to allow for additional bonds to be formed
*Two groups cannot be the same in fix spring couple*
Self-explanatory.
*The %s type label %s is already in use for type %s*
For a given type-kind (atom types, bond types, etc.), a given type
label can be assigned to only one numeric type.
*Type label string %s for %s type %s is invalid*
See the labelmap command documentation for valid type labels.
*Unable to initialize accelerator for use*
There was a problem initializing an accelerator for the gpu package

1
doc/src/Howto.rst
View File

@ -34,6 +34,7 @@ Settings howto
:maxdepth: 1
Howto_2d
Howto_type_labels
Howto_triclinic
Howto_thermostat
Howto_barostat

126
doc/src/Howto_type_labels.rst Normal file
View File

@ -0,0 +1,126 @@
Type labels
===========
.. versionadded:: TBD
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 :doc:`include command <include>` for different systems with different
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 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 :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
characters. When using the :doc:`labelmap command <labelmap>` 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:
.. code-block:: LAMMPS
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 :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 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
:doc:`read_restart <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.
.. code-block:: LAMMPS
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
:doc:`variable <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.
.. code-block:: LAMMPS
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
.. code-block:: LAMMPS
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 :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 multiple simulations or different systems.

4
doc/src/Packages_details.rst
View File

@ -932,6 +932,10 @@ EXTRA-MOLECULE package
Additional bond, angle, dihedral, and improper styles that are less commonly used.
**Install:**
To use this package, also the :ref:`MOLECULE <PKG-MOLECULE>` package needs to be installed.
**Supporting info:**
* src/EXTRA-MOLECULE: filenames -> commands

50
doc/src/angle_coeff.rst
View File

@ -10,7 +10,7 @@ Syntax
angle_coeff N args
* N = angle type (see asterisk form below)
* N = numeric angle type (see asterisk form below), or type label
* args = coefficients for one or more angle types
Examples
@ -22,6 +22,9 @@ Examples
angle_coeff * 5.0
angle_coeff 2*10 5.0
labelmap angle 1 hydroxyl
angle_coeff hydroxyl 300.0 107.0
Description
"""""""""""
@ -30,18 +33,24 @@ The number and meaning of the coefficients depends on the angle style.
Angle coefficients can also be set in the data file read by the
:doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the first example above. Or a wild-card asterisk can be
used to set the coefficients for multiple angle types. This takes the
form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of angle types,
then an asterisk with no numeric values means all types from 1 to N. A
leading 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).
:math:`N` can be specified in one of two ways. An explicit numeric
value can be used, as in the first example above. Or :math:`N` 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.
Note that using an :doc:`angle_coeff <angle_coeff>` command can override a previous setting
for the same angle type. For example, these commands set the coeffs
for all angle types, then overwrite the coeffs for just angle type 2:
For numeric values only, a wild-card asterisk can be used to set the
coefficients for multiple angle types. This takes the form "\*" or
"\*n" or "n\*" or "m\*n". If :math:`N` is the number of angle types,
then an asterisk with no numeric values means all types from 1 to
:math:`N`. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to :math:`N` (inclusive). A
middle asterisk means all types from m to n (inclusive).
Note that using an :doc:`angle_coeff <angle_coeff>` command can
override a previous setting for the same angle type. For example,
these commands set the coeffs for all angle types, then overwrite the
coeffs for just angle type 2:
.. code-block:: LAMMPS
@ -49,11 +58,11 @@ for all angle types, then overwrite the coeffs for just angle type 2:
angle_coeff 2 50.0 107.0
A line in a data file that specifies angle coefficients uses the exact
same format as the arguments of the :doc:`angle_coeff <angle_coeff>` command in an input
script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
under the "Angle Coeffs" section of a data file, the line that
corresponds to the first example above would be listed as
same format as the arguments of the :doc:`angle_coeff <angle_coeff>`
command in an input script, except that wild-card asterisks should not
be used since coefficients for all :math:`N` types must be listed in the
file. For example, under the "Angle Coeffs" section of a data file, the
line that corresponds to the first example above would be listed as
.. parsed-literal::
@ -61,15 +70,14 @@ corresponds to the first example above would be listed as
The :doc:`angle_style class2 <angle_class2>` is an exception to this
rule, in that an additional argument is used in the input script to
allow specification of the cross-term coefficients. See its
doc page for details.
allow specification of the cross-term coefficients. See its doc page
for details.
----------
The list of all angle styles defined in LAMMPS is given on the
:doc:`angle_style <angle_style>` doc page. They are also listed in more
compact form on the :ref:`Commands angle <angle>` doc
page.
compact form on the :ref:`Commands angle <angle>` doc page.
On either of those pages, click on the style to display the formula it
computes and its coefficients as specified by the associated

30
doc/src/bond_coeff.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_coeff N args
* N = bond type (see asterisk form below)
* N = numeric bond type (see asterisk form below), or type label
* args = coefficients for one or more bond types
Examples
@ -21,7 +21,10 @@ Examples
bond_coeff 5 80.0 1.2
bond_coeff * 30.0 1.5 1.0 1.0
bond_coeff 1*4 30.0 1.5 1.0 1.0
bond_coeff 1 harmonic 200.0 1.0
bond_coeff 1 harmonic 200.0 1.0 (for bond_style hybrid)
labelmap bond 5 carbonyl
bond_coeff carbonyl 80.0 1.2
Description
"""""""""""
@ -31,14 +34,19 @@ The number and meaning of the coefficients depends on the bond style.
Bond coefficients can also be set in the data file read by the
:doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the first example above. Or a wild-card asterisk can be
used to set the coefficients for multiple bond types. This takes the
form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of bond types,
then an asterisk with no numeric values means all types from 1 to N. A
:math:`N` can be specified in one of several ways. An explicit numeric
value can be used, as in the first example above. Or :math:`N` 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.
For numeric values only, a wild-card asterisk can be used to set the
coefficients for multiple bond types. This takes the form "\*" or "\*n"
or "n\*" or "m\*n". If :math:`N` is the number of bond types, then an
asterisk with no numeric values means all types from 1 to :math:`N`. A
leading 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).
asterisk means all types from n to :math:`N` (inclusive). A middle
asterisk means all types from m to n (inclusive).
Note that using a bond_coeff command can override a previous setting
for the same bond type. For example, these commands set the coeffs
@ -52,8 +60,8 @@ for all bond types, then overwrite the coeffs for just bond type 2:
A line in a data file that specifies bond coefficients uses the exact
same format as the arguments of the bond_coeff command in an input
script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
under the "Bond Coeffs" section of a data file, the line that
coefficients for all :math:`N` types must be listed in the file. For
example, under the "Bond Coeffs" section of a data file, the line that
corresponds to the first example above would be listed as
.. parsed-literal::

1
doc/src/commands_list.rst
View File

@ -56,6 +56,7 @@ Commands
kspace_modify
kspace_style
label
labelmap
lattice
log
mass

37
doc/src/dihedral_coeff.rst
View File

@ -10,7 +10,7 @@ Syntax
dihedral_coeff N args
* N = dihedral type (see asterisk form below)
* N = numeric dihedral type (see asterisk form below) or alphanumeric type label
* args = coefficients for one or more dihedral types
Examples
@ -22,26 +22,35 @@ Examples
dihedral_coeff * 80.0 1 3 0.5
dihedral_coeff 2* 80.0 1 3 0.5
labelmap dihedral 1 backbone
dihedral_coeff backbone 80.0 1 3
Description
"""""""""""
Specify the dihedral force field coefficients for one or more dihedral types.
The number and meaning of the coefficients depends on the dihedral style.
Dihedral coefficients can also be set in the data file read by the
:doc:`read_data <read_data>` command or in a restart file.
Specify the dihedral force field coefficients for one or more dihedral
types. The number and meaning of the coefficients depends on the
dihedral style. Dihedral coefficients can also be set in the data file
read by the :doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the first example above. Or a wild-card asterisk can be
used to set the coefficients for multiple dihedral types. This takes the
form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is the number of dihedral
types, then an asterisk with no numeric values means all types from 1 to
:math:`N`. A leading asterisk means all types from 1 to n (inclusive). A
trailing asterisk means all types from m to N (inclusive). A middle asterisk
means all types from m to n (inclusive).
:math:`N` can be specified in one of two ways. An explicit numeric
value can be used, as in the first example above. Or :math:`N` can be
an alphanumeric type label, which is a string defined by the
:doc:`labelmap <labelmap>` command or in a corresponding section of a
data file read by the :doc:`read_data <read_data>` command.
For numeric values only, a wild-card asterisk can be used to set the
coefficients for multiple dihedral types. This takes the form "\*" or
"\*n" or "n\*" or "m\*n". If :math:`N` is the number of dihedral types,
then an asterisk with no numeric values means all types from 1 to
:math:`N`. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to :math:`N` (inclusive). A
middle asterisk means all types from m to n (inclusive).
Note that using a dihedral_coeff command can override a previous setting
for the same dihedral type. For example, these commands set the coeffs
for all dihedral types, then overwrite the coeffs for just dihedral type 2:
for all dihedral types, then overwrite the coeffs for just dihedral type
2:
.. code-block:: LAMMPS

13
doc/src/dump_modify.rst
View File

@ -178,7 +178,6 @@ extra buffering.
----------
.. versionadded:: 4May2022
The *colname* keyword can be used to change the default header keyword
@ -401,10 +400,10 @@ the setting of this keyword is *yes*\ . If it is *no*, which is the
default, then it will not be written.
Note that if the argument to the :doc:`dump_modify every
<dump_modify>` or doc:`dump_modify every/time <dump_modify>` commands
is a variable and not a numeric value, then specifying *first yes* is
the only way to write a dump snapshot on the first timestep after the
dump command is invoked.
<dump_modify>` :doc:`dump_modify every/time <dump_modify>` commands is
a variable and not a numeric value, then specifying *first yes* is the
only way to write a dump snapshot on the first timestep after the dump
command is invoked.
----------
@ -503,7 +502,7 @@ current coordinate. Note that for dump style *custom* these various
values can be printed in the dump file by using the appropriate atom
attributes in the dump command itself.
Using this keyword will reset all custom header names set with
*dump_modify colname*.
*dump_modify colname* to their respective default values.
----------
@ -678,7 +677,7 @@ value of *yes* means atom coords are written in normalized units from
value of *no* means they are written in absolute distance units
(e.g., :math:`\mathrm{\mathring A}` or :math:`\sigma`).
Using this keyword will reset all custom header names set with
*dump_modify colname*.
*dump_modify colname* to their respective default values.
----------

41
doc/src/improper_coeff.rst
View File

@ -10,7 +10,7 @@ Syntax
improper_coeff N args
* N = improper type (see asterisk form below)
* N = numeric improper type (see asterisk form below), or type label
* args = coefficients for one or more improper types
Examples
@ -22,27 +22,34 @@ Examples
improper_coeff * 80.2 -1 2
improper_coeff *4 80.2 -1 2
labelmap improper 1 benzene
improper_coeff benzene 300.0 0.0
Description
"""""""""""
Specify the improper force field coefficients for one or more improper
types. The number and meaning of the coefficients depends on the
improper style. Improper coefficients can also be set in the data
file read by the :doc:`read_data <read_data>` command or in a restart
file.
improper style. Improper coefficients can also be set in the data file
read by the :doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the first example above. Or a wild-card asterisk can be
used to set the coefficients for multiple improper types. This takes
the form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of improper
types, then an asterisk with no numeric values means all types from 1
to N. A leading 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).
:math:`N` can be specified in one of two ways. An explicit numeric
value can be used, as in the first example above. Or :math:`N` 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.
For numeric values only, a wild-card asterisk can be used to set the
coefficients for multiple improper types. This takes the form "\*" or
"\*n" or "n\*" or "m\*n". If :math:`N` = the number of improper types,
then an asterisk with no numeric values means all types from 1 to
:math:`N`. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to :math:`N` (inclusive). A
middle asterisk means all types from m to n (inclusive).
Note that using an improper_coeff command can override a previous
setting for the same improper type. For example, these commands set
the coeffs for all improper types, then overwrite the coeffs for just
setting for the same improper type. For example, these commands set the
coeffs for all improper types, then overwrite the coeffs for just
improper type 2:
.. code-block:: LAMMPS
@ -53,9 +60,9 @@ improper type 2:
A line in a data file that specifies improper coefficients uses the
exact same format as the arguments of the improper_coeff command in an
input script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
under the "Improper Coeffs" section of a data file, the line that
corresponds to the first example above would be listed as
coefficients for all :math:`N` types must be listed in the file. For
example, under the "Improper Coeffs" section of a data file, the line
that corresponds to the first example above would be listed as
.. parsed-literal::

100
doc/src/labelmap.rst Normal file
View File

@ -0,0 +1,100 @@
.. index:: labelmap
labelmap command
==================
Syntax
""""""
.. code-block:: LAMMPS
labelmap option args
* *option* = *atom* or *bond* or *angle* or *dihedral* or *improper* or *clear* or *write*
.. parsed-literal::
*clear* = no args
*write* arg = filename
*atom* or *bond* or *angle* or *dihedral* or *improper*
args = list of one or more numeric-type/type-label pairs
Examples
""""""""
.. code-block:: LAMMPS
labelmap atom 3 carbon 4 'c3"' 5 "c1'" 6 "c#"
labelmap bond 1 carbonyl 2 nitrile 3 """ c1'-c2" """
labelmap atom $(label2type(atom,carbon)) C # change type label from 'carbon' to 'C'
labelmap clear
labelmap write mymap.include
Description
"""""""""""
.. versionadded:: TBD
Define alphanumeric type labels to associate with one or more numeric
atom, bond, angle, dihedral or improper types. A collection of type
labels for all atom types, bond types, etc. is stored as a label map.
The label map 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 Labels, etc. See the :doc:`Howto type labels
<Howto_type_labels>` doc page for a general discussion of how type
labels can be used.
Valid type labels can contain any alphanumeric character, but must not
start with a number, a '#', or a '*' character. They can contain other
standard ASCII characters such as angular or square brackets '<' and '>'
or '[' and ']', parenthesis '(' and ')', dash '-', underscore '_', plus
'+' and equals '=' signs and more. They must not contain blanks or any
other whitespace. Note that type labels must be put in single or double
quotation marks if they contain the '#' character or if they contain a
double (") or single quotation mark ('). If the label contains both
a single and a double quotation mark, then triple quotation (""") must
be used. When enclosing a type label with quotation marks, the
LAMMPS input parser may require adding leading or trailing blanks
around the type label so it can identify the enclosing quotation
marks. Those blanks will be removed when defining the label.
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
pairs may follow. If a type label already exists for the same numeric
type, it will be overwritten. Type labels must be unique; assigning the
same type label to multiple numeric types within the same type-kind is
not allowed. When reading and writing data files, it is required that
there is a label defined for *every* numeric type within a given
type-kind in order to write out the type label section for that
type-kind.
The *clear* option resets the labelmap and thus discards all previous
settings.
The *write* option takes a filename as argument and writes the current
label mappings to a file as labelmap commands, so the file can be copied
into a new LAMMPS input file or read in using the :doc:`include
<include>` command.
----------
Restrictions
""""""""""""
This command must come after the simulation box is defined by a
:doc:`read_data <read_data>`, :doc:`read_restart <read_restart>`, or
:doc:`create_box <create_box>` command.
Labelmaps are currently not supported when using the KOKKOS package.
Related commands
""""""""""""""""
:doc:`read_data <read_data>`, :doc:`write_data <write_data>`,
:doc:`molecule <molecule>`, :doc:`fix bond/react <fix_bond_react>`
Default
"""""""
none

21
doc/src/mass.rst
View File

@ -10,7 +10,7 @@ Syntax
mass I value
* I = atom type (see asterisk form below)
* I = atom type (see asterisk form below), or type label
* value = mass
Examples
@ -22,6 +22,9 @@ Examples
mass * 62.5
mass 2* 62.5
labelmap atom 1 C
mass C 12.01
Description
"""""""""""
@ -30,12 +33,16 @@ values can also be set in the :doc:`read_data <read_data>` data file
using the "Masses" keyword. See the :doc:`units <units>` command for
what mass units to use.
The I index can be specified in one of two ways. An explicit numeric
value can be used, as in the first example above. Or a wild-card
asterisk can be used to set the mass for multiple atom types. This
takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of
atom types, then an asterisk with no numeric values means all types
from 1 to N. A leading asterisk means all types from 1 to n
The I index can be specified in one of several ways. An explicit
numeric value can be used, as in the first example above. Or I 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. Or a wild-card asterisk can be used to
set the mass for multiple atom types. This takes the form "\*" or
"\*n" or "n\*" or "m\*n", where m and n are numbers. If N = the
number of atom types, then an asterisk with no numeric values means
all types from 1 to N. A leading 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).

100
doc/src/molecule.rst
View File

@ -70,8 +70,9 @@ and underscores.
A single template can contain multiple molecules, listed one per file.
Some of the commands listed above currently use only the first
molecule in the template, and will issue a warning if the template
contains multiple molecules. The :doc:`atom_style template <atom_style>` command allows multiple-molecule templates
to define a system with more than one templated molecule.
contains multiple molecules. The :doc:`atom_style template
<atom_style>` command allows multiple-molecule templates to define a
system with more than one templated molecule.
Each filename can be followed by optional keywords which are applied
only to the molecule in the file as used in this template. This is to
@ -88,6 +89,12 @@ molecule file. E.g. if *toff* = 2, and the file uses atom types
individual values will be ignored if the molecule template does not
use that attribute (e.g. no bonds).
.. note::
Offsets are **ignored** on lines using type labels, as the type
labels will determine the actual types directly depending on the
current :doc:`labelmap <labelmap>` settings.
The *scale* keyword scales the size of the molecule. This can be
useful for modeling polydisperse granular rigid bodies. The scale
factor is applied to each of these properties in the molecule file, if
@ -118,14 +125,18 @@ The format of an individual molecule file is similar but
(not identical) to the data file read by the :doc:`read_data <read_data>`
commands, and is as follows.
A molecule file has a header and a body. The header appears first.
The first line of the header is always skipped; it typically contains
a description of the file. Then lines are read one at a time. Lines
can have a trailing comment starting with '#' that is ignored. If the
line is blank (only white-space after comment is deleted), it is
A molecule file has a header and a body. The header appears first. The
first line of the header and thus of the molecule file is *always* skipped;
it typically contains a description of the file or a comment from the software
that created the file.
Then lines are read one line at a time. Lines can have a trailing
comment starting with '#' that is ignored. There *must* be at least one
blank between any valid content and the comment. If the line is blank
(i.e. contains only white-space after comments are deleted), it is
skipped. If the line contains a header keyword, the corresponding
value(s) is read from the line. If it does not contain a header
keyword, the line begins the body of the file.
value(s) is/are read from the line. A line that is *not* blank and does
*not* contains a header keyword begins the body of the file.
The body of the file contains zero or more sections. The first line
of a section has only a keyword. The next line is skipped. The
@ -173,31 +184,43 @@ These are the allowed section keywords for the body of the file.
* *Special Bond Counts, Special Bonds* = special neighbor info
* *Shake Flags, Shake Atoms, Shake Bond Types* = SHAKE info
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 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
<Howto_type_labels>` doc page for the allowed syntax of type labels
and a general discussion of how type labels can be used.
When using type labels, any values specified as *offset* are ignored.
If a Bonds section is specified then the Special Bond Counts and
Special Bonds sections can also be used, if desired, to explicitly
list the 1-2, 1-3, 1-4 neighbors within the molecule topology (see
details below). This is optional since if these sections are not
included, LAMMPS will auto-generate this information. Note that
LAMMPS uses this info to properly exclude or weight bonded pairwise
interactions between bonded atoms. See the
:doc:`special_bonds <special_bonds>` command for more details. One
reason to list the special bond info explicitly is for the
:doc:`thermalized Drude oscillator model <Howto_drude>` which treats the
bonds between nuclear cores and Drude electrons in a different manner.
interactions between bonded atoms. See the :doc:`special_bonds
<special_bonds>` command for more details. One reason to list the
special bond info explicitly is for the :doc:`thermalized Drude
oscillator model <Howto_drude>` which treats the bonds between nuclear
cores and Drude electrons in a different manner.
.. note::
Whether a section is required depends on how the molecule
template is used by other LAMMPS commands. For example, to add a
molecule via the :doc:`fix deposit <fix_deposit>` command, the Coords
and Types sections are required. To add a rigid body via the :doc:`fix pour <fix_pour>` command, the Bonds (Angles, etc) sections are not
Whether a section is required depends on how the molecule template
is used by other LAMMPS commands. For example, to add a molecule
via the :doc:`fix deposit <fix_deposit>` command, the Coords and
Types sections are required. To add a rigid body via the :doc:`fix
pour <fix_pour>` command, the Bonds (Angles, etc) sections are not
required, since the molecule will be treated as a rigid body. Some
sections are optional. For example, the :doc:`fix pour <fix_pour>`
command can be used to add "molecules" which are clusters of
finite-size granular particles. If the Diameters section is not
specified, each particle in the molecule will have a default diameter
of 1.0. See the doc pages for LAMMPS commands that use molecule
templates for more details.
specified, each particle in the molecule will have a default
diameter of 1.0. See the doc pages for LAMMPS commands that use
molecule templates for more details.
Each section is listed below in alphabetic order. The format of each
section is described including the number of lines it must contain and
@ -222,7 +245,7 @@ order.
* one line per atom
* line syntax: ID type
* type = atom type of atom
* type = atom type of atom (1-Natomtype, or type label)
----------
@ -289,7 +312,7 @@ included, the default mass for each atom is derived from its volume
* one line per bond
* line syntax: ID type atom1 atom2
* type = bond type (1-Nbondtype)
* type = bond type (1-Nbondtype, or type label)
* atom1,atom2 = IDs of atoms in bond
The IDs for the two atoms in each bond should be values
@ -301,7 +324,7 @@ from 1 to Natoms, where Natoms = # of atoms in the molecule.
* one line per angle
* line syntax: ID type atom1 atom2 atom3
* type = angle type (1-Nangletype)
* type = angle type (1-Nangletype, or type label)
* atom1,atom2,atom3 = IDs of atoms in angle
The IDs for the three atoms in each angle should be values from 1 to
@ -315,7 +338,7 @@ which the angle is computed) is the atom2 in the list.
* one line per dihedral
* line syntax: ID type atom1 atom2 atom3 atom4
* type = dihedral type (1-Ndihedraltype)
* type = dihedral type (1-Ndihedraltype, or type label)
* atom1,atom2,atom3,atom4 = IDs of atoms in dihedral
The IDs for the four atoms in each dihedral should be values from 1 to
@ -328,7 +351,7 @@ ordered linearly within the dihedral.
* one line per improper
* line syntax: ID type atom1 atom2 atom3 atom4
* type = improper type (1-Nimpropertype)
* type = improper type (1-Nimpropertype, or type label)
* atom1,atom2,atom3,atom4 = IDs of atoms in improper
The IDs for the four atoms in each improper should be values from 1 to
@ -447,11 +470,15 @@ This section is only needed when molecules created using the template
will be constrained by SHAKE via the "fix shake" command. The other
two Shake sections must also appear in the file.
The a,b,c values are bond types (from 1 to Nbondtypes) for all bonds
in the SHAKE cluster that this atom belongs to. The number of values
that must appear is determined by the shake flag for the atom (see the
Shake Flags section above). All atoms in a particular cluster should
list their a,b,c values identically.
The a,b,c values are bond types for all bonds in the SHAKE cluster that
this atom belongs to. Bond types may be either numbers (from 1 to Nbondtypes)
or bond type labels as defined by the :doc:`labelmap <labelmap>` command
or a "Bond Type Labels" section of a data file.
The number of values that must appear is determined by the shake flag
for the atom (see the Shake Flags section above). All atoms in a
particular cluster should list their a,b,c values identically.
If flag = 0, no a,b,c values are listed on the line, just the
(ignored) ID.
@ -459,8 +486,9 @@ If flag = 0, no a,b,c values are listed on the line, just the
If flag = 1, a,b,c are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), b = bondtype of the bond between the central atom and
the second non-central atom (value c in the Shake Atoms section), and c =
the angle type (1 to Nangletypes) of the angle between the 3 atoms.
the second non-central atom (value c in the Shake Atoms section), and c
= the angle type (1 to Nangletypes, or angle type label) of the angle
between the 3 atoms.
If flag = 2, only a is listed, where a = bondtype of the bond between
the 2 atoms in the cluster.
@ -473,9 +501,9 @@ and the second non-central atom (value c in the Shake Atoms section).
If flag = 4, a,b,c are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), b = bondtype of the bond between the central atom and
the second non-central atom (value c in the Shake Atoms section), and c =
bondtype of the bond between the central atom and the third non-central
atom (value d in the Shake Atoms section).
the second non-central atom (value c in the Shake Atoms section), and c
= bondtype of the bond between the central atom and the third
non-central atom (value d in the Shake Atoms section).
See the :doc:`fix shake <fix_shake>` page for a further description
of SHAKE clusters.

49
doc/src/pair_coeff.rst
View File

@ -10,7 +10,7 @@ Syntax
pair_coeff I J args
* I,J = atom types (see asterisk form below)
* I,J = numeric atom types (see asterisk form below), or type labels
* args = coefficients for one or more pairs of atom types
Examples
@ -26,6 +26,10 @@ Examples
pair_coeff * 3 morse.table ENTRY1
pair_coeff 1 2 lj/cut 1.0 1.0 2.5 # (for pair_style hybrid)
labelmap atom 1 C
labelmap atom 2 H
pair_coeff C H 1.0 1.0 2.5
Description
"""""""""""
@ -34,20 +38,27 @@ atom types. The number and meaning of the coefficients depends on the
pair style. Pair coefficients can also be set in the data file read
by the :doc:`read_data <read_data>` command or in a restart file.
I and J can be specified in one of two ways. Explicit numeric values
can be used for each, as in the first example above. I <= J is
required. LAMMPS sets the coefficients for the symmetric J,I
interaction to the same values.
I and J can be specified in one of several ways. Explicit numeric
values can be used for each, as in the first example above. Or, one
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.
Internally, LAMMPS will set coefficients for the symmetric J,I
interaction to the same values as the I,J interaction.
A wildcard asterisk can be used in place of or in conjunction with the
I,J arguments to set the coefficients for multiple pairs of atom
types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = the
number of atom types, then an asterisk with no numeric values means all
types from 1 to N. A leading 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). Note that only type pairs with I <= J are considered; if
asterisks imply type pairs where J < I, they are ignored.
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
multiple pairs of atom types. This takes the form "\*" or "\*n" or
"n\*" or "m\*n". If :math:`N` is the number of atom types, then an
asterisk with no numeric values means all types from 1 to :math:`N`. A
leading asterisk means all types from 1 to n (inclusive). A trailing
asterisk means all types from n to :math:`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. 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
@ -63,11 +74,11 @@ same format as the arguments of the pair_coeff command in an input
script, with the exception of the I,J type arguments. In each line of
the "Pair Coeffs" section of a data file, only a single type I is
specified, which sets the coefficients for type I interacting with
type I. This is because the section has exactly N lines, where N =
the number of atom types. For this reason, the wild-card asterisk
should also not be used as part of the I argument. Thus in a data
file, the line corresponding to the first example above would be listed
as
type I. This is because the section has exactly :math:`N` lines, where
:math:`N` is the number of atom types. For this reason, the wild-card
asterisk should also not be used as part of the I argument. Thus in a
data file, the line corresponding to the first example above would be
listed as
.. parsed-literal::

2
doc/src/pair_dipole.rst
View File

@ -249,7 +249,7 @@ Style *lj/long/dipole/long* has the same functionality as style
*lj/cut/dipole/long*, except it also has an option to compute 12/6
Lennard-Jones interactions for use with a long-range dispersion kspace
style. This is done by setting its *flag_lj* argument to *long*. For
long-range LJ interactions, the doc:`kspace_style ewald/disp
long-range LJ interactions, the :doc:`kspace_style ewald/disp
<kspace_style>` command must be used.
----------

4
doc/src/pair_style.rst
View File

@ -81,12 +81,12 @@ only the global settings in that command are reset. Any previous
doc:`pair_coeff <pair_coeff>` and :doc:`pair_modify <pair_modify>`
command settings are preserved. The only exception is that if the
global cutoff in the pair_style command is changed, it will override
the corresponding cutoff in any of the previous doc:`pair_modify
the corresponding cutoff in any of the previous :doc:`pair_modify
<pair_coeff>` commands.
Two pair styles which do not follow this rule are the pair_style
*table* and *hybrid* commands. A new pair_style command for these
styles will wipe out all previously specified doc:`pair_coeff
styles will wipe out all previously specified :doc:`pair_coeff
<pair_coeff>` and :doc:`pair_modify <pair_modify>` settings, including
for the sub-styles of the *hybrid* command.

225
doc/src/read_data.rst
View File

@ -164,6 +164,12 @@ other types already exist. All five offset values must be specified,
but individual values will be ignored if the data file does not use
that attribute (e.g. no bonds).
.. note::
Offsets are **ignored** on lines using type labels, as the type
labels will determine the actual types directly depending on the
current :doc:`labelmap <labelmap>` settings.
The *shift* keyword can be used to specify an (Sx, Sy, Sz)
displacement applied to the coordinates of each atom. Sz must be 0.0
for a 2d simulation. This is a mechanism for adding structured
@ -227,22 +233,27 @@ The file will be read line by line, but there is a limit of 254
characters per line and characters beyond that limit will be ignored.
A data file has a header and a body. The header appears first. The
first line of the header is always skipped; it typically contains a
description of the file. Then lines are read one at a time. Lines
can have a trailing comment starting with '#' that is ignored. If the
line is blank (only white-space after comment is deleted), it is
skipped. If the line contains a header keyword, the corresponding
value(s) is read from the line. If it does not contain a header
keyword, the line begins the body of the file.
first line of the header and thus of the data file is *always* skipped;
it typically contains a description of the file or a comment from the
software that created the file.
The body of the file contains zero or more sections. The first line
of a section has only a keyword. This line can have a trailing
comment starting with '#' that is either ignored or can be used to
check for a style match, as described below. The next line is
skipped. The remaining lines of the section contain values. The
number of lines depends on the section keyword as described below.
Zero or more blank lines can be used between sections. Sections can
appear in any order, with a few exceptions as noted below.
Then lines are read one line at a time. Lines can have a trailing
comment starting with '#' that is ignored. There *must* be at least one
blank between any valid content and the comment. If a line is blank
(i.e. contains only white-space after comments are deleted), it is
skipped. If the line contains a header keyword, the corresponding
value(s) is/are read from the line. A line that is *not* blank and does
*not* contain a header keyword begins the body of the file.
The body of the file contains zero or more sections. The first line of
a section has only a keyword. This line can have a trailing comment
starting with '#' that is either ignored or can be used to check for a
style match, as described below. There must be a blank between the
keyword and any comment. The *next* line is *always* skipped. The
remaining lines of the section contain values. The number of lines
depends on the section keyword as described below. Zero or more blank
lines can be used *between* sections. Sections can appear in any order,
with a few exceptions as noted below.
The keyword *fix* can be used one or more times. Each usage specifies
a fix that will be used to process a specific portion of the data
@ -477,6 +488,7 @@ These are the section keywords for the body of the file.
* *Atoms, Velocities, Masses, Ellipsoids, Lines, Triangles, Bodies* = atom-property sections
* *Bonds, Angles, Dihedrals, Impropers* = molecular topology sections
* *Atom Type Labels, Bond Type Labels, Angle Type Labels, Dihedral Type Labels, Improper Type Labels* = type label maps
* *Pair Coeffs, PairIJ Coeffs, Bond Coeffs, Angle Coeffs, Dihedral Coeffs, Improper Coeffs* = force field sections
* *BondBond Coeffs, BondAngle Coeffs, MiddleBondTorsion Coeffs, EndBondTorsion Coeffs, AngleTorsion Coeffs, AngleAngleTorsion Coeffs, BondBond13 Coeffs, AngleAngle Coeffs* = class 2 force field sections
@ -503,7 +515,8 @@ section is described including the number of lines it must contain and
rules (if any) for where it can appear in the data file.
Any individual line in the various sections can have a trailing
comment starting with "#" for annotation purposes. E.g. in the
comment starting with "#" for annotation purposes. There must be at least
one blank between valid content and the comment. E.g. in the
Atoms section:
.. parsed-literal::
@ -536,6 +549,26 @@ input script.
----------
*Angle Type Labels* section:
* one line per angle type
* line syntax: ID label
.. parsed-literal::
ID = angle type (1-N)
label = alphanumeric type label
Define alphanumeric type labels for each numeric angle type. These
can be used in the Angles section in place of a numeric type, but only
if the this section appears before the Angles section.
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.
----------
*AngleAngle Coeffs* section:
* one line per improper type
@ -568,7 +601,7 @@ input script.
.. parsed-literal::
ID = number of angle (1-Nangles)
type = angle type (1-Nangletype)
type = angle type (1-Nangletype, or type label)
atom1,atom2,atom3 = IDs of 1st,2nd,3rd atom in angle
example:
@ -580,8 +613,15 @@ example:
The 3 atoms are ordered linearly within the angle. Thus the central
atom (around which the angle is computed) is the atom2 in the list.
E.g. H,O,H for a water molecule. The *Angles* section must appear
after the *Atoms* section. All values in this section must be
integers (1, not 1.0).
after the *Atoms* section.
All values in this section must be integers (1, not 1.0). However,
the type can be a numeric value or an alphanumeric label. The latter
is only allowed if the type label has been defined by the
:doc:`labelmap <labelmap>` command or an Angle Type Labels section
earlier in the data file. 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.
----------
@ -597,6 +637,26 @@ integers (1, not 1.0).
----------
*Atom Type Labels* section:
* one line per atom type
* line syntax: ID label
.. parsed-literal::
ID = numeric atom type (1-N)
label = alphanumeric type label
Define alphanumeric type labels for each numeric atom type. These
can be used in the Atoms section in place of a numeric type, but only
if the Atom Type Labels section appears before the Atoms section.
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.
----------
*Atoms* section:
* one line per atom
@ -670,7 +730,7 @@ of analysis.
The per-atom values have these meanings and units, listed alphabetically:
* atom-ID = integer ID of atom
* atom-type = type of atom (1-Ntype)
* atom-type = type of atom (1-Ntype, or type label)
* bodyflag = 1 for body particles, 0 for point particles
* bond_nt = bond NT factor for MESONT particles (?? units)
* buckling = buckling factor for MESONT particles (?? units)
@ -722,6 +782,13 @@ not used (e.g. an atomic system with no bonds), and you don't care if
unique atom IDs appear in dump files, then the atom-IDs can all be set
to 0.
The atom-type can be a numeric value or an alphanumeric label. The
latter is only allowed if the type label has been defined by the
:doc:`labelmap <labelmap>` command or an Atom Type Labels section
earlier in the data file. 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.
The molecule ID is a second identifier attached to an atom. Normally, it
is a number from 1 to N, identifying which molecule the atom belongs
to. It can be 0 if it is a non-bonded atom or if you don't care to
@ -932,6 +999,26 @@ script.
----------
*Bond Type Labels* section:
* one line per bond type
* line syntax: ID label
.. parsed-literal::
ID = bond type (1-N)
label = alphanumeric type label
Define alphanumeric type labels for each numeric bond type. These can
be used in the Bonds section in place of a numeric type, but only if
the this section appears before the Angles section.
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.
----------
*BondAngle Coeffs* section:
* one line per angle type
@ -976,7 +1063,7 @@ script.
.. parsed-literal::
ID = bond number (1-Nbonds)
type = bond type (1-Nbondtype)
type = bond type (1-Nbondtype, or type label)
atom1,atom2 = IDs of 1st,2nd atom in bond
* example:
@ -985,8 +1072,15 @@ script.
12 3 17 29
The *Bonds* section must appear after the *Atoms* section. All values
in this section must be integers (1, not 1.0).
The *Bonds* section must appear after the *Atoms* section.
All values in this section must be integers (1, not 1.0). However,
the type can be a numeric value or an alphanumeric label. The latter
is only allowed if the type label has been defined by the
:doc:`labelmap <labelmap>` command or a Bond Type Labels section
earlier in the data file. 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.
----------
@ -1014,6 +1108,26 @@ Coefficients can also be set via the
----------
*Dihedral Type Labels* section:
* one line per dihedral type
* line syntax: ID label
.. parsed-literal::
ID = dihedral type (1-N)
label = alphanumeric type label
Define alphanumeric type labels for each numeric dihedral type. These
can be used in the Dihedrals section in place of a numeric type, but
only if the this section appears before the Dihedrals section.
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.
----------
*Dihedrals* section:
* one line per dihedral
@ -1022,7 +1136,7 @@ Coefficients can also be set via the
.. parsed-literal::
ID = number of dihedral (1-Ndihedrals)
type = dihedral type (1-Ndihedraltype)
type = dihedral type (1-Ndihedraltype, or type label)
atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atom in dihedral
* example:
@ -1032,8 +1146,15 @@ Coefficients can also be set via the
12 4 17 29 30 21
The 4 atoms are ordered linearly within the dihedral. The *Dihedrals*
section must appear after the *Atoms* section. All values in this
section must be integers (1, not 1.0).
section must appear after the *Atoms* section.
All values in this section must be integers (1, not 1.0). However,
the type can be a numeric value or an alphanumeric label. The latter
is only allowed if the type label has been defined by the
:doc:`labelmap <labelmap>` command or a Dihedral Type Labels section
earlier in the data file. 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.
----------
@ -1115,6 +1236,26 @@ Coefficients can also be set via the
----------
*Improper Type Labels* section:
* one line per improper type
* line syntax: ID label
.. parsed-literal::
ID = improper type (1-N)
label = alphanumeric type label
Define alphanumeric type labels for each numeric improper type. These
can be used in the Impropers section in place of a numeric type, but
only if the this section appears before the Impropers section.
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.
----------
*Impropers* section:
* one line per improper
@ -1123,7 +1264,7 @@ Coefficients can also be set via the
.. parsed-literal::
ID = number of improper (1-Nimpropers)
type = improper type (1-Nimpropertype)
type = improper type (1-Nimpropertype, or type label)
atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atom in improper
* example:
@ -1133,11 +1274,19 @@ Coefficients can also be set via the
12 3 17 29 13 100
The ordering of the 4 atoms determines the definition of the improper
angle used in the formula for each :doc:`improper style <improper_style>`. See the doc pages for individual styles
for details.
angle used in the formula for each :doc:`improper style
<improper_style>`. See the doc pages for individual styles for
details.
The *Impropers* section must appear after the *Atoms* section. All
values in this section must be integers (1, not 1.0).
The *Impropers* section must appear after the *Atoms* section.
All values in this section must be integers (1, not 1.0). However,
the type can be a numeric value or an alphanumeric label. The latter
is only allowed if the type label has been defined by the
:doc:`labelmap <labelmap>` command or a Improper Type Labels section
earlier in the data file. 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.
----------
@ -1181,7 +1330,7 @@ The *Lines* section must appear after the *Atoms* section.
.. parsed-literal::
ID = atom type (1-N)
ID = atom type (1-N or atom type label)
mass = mass value
* example:
@ -1195,6 +1344,13 @@ This defines the mass of each atom type. This can also be set via the
used for atom styles that define a mass for individual atoms -
e.g. :doc:`atom_style sphere <atom_style>`.
Using type labels instead of atom type numbers is only allowed if the
type label has been defined by the :doc:`labelmap <labelmap>` command or
a Atom Type Labels section earlier in the data file. 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.
----------
*MiddleBondTorsion Coeffs* section:
@ -1363,11 +1519,14 @@ To read gzipped data files, you must compile LAMMPS with the
-DLAMMPS_GZIP option. See the :doc:`Build settings <Build_settings>`
doc page for details.
Labelmaps are currently not supported when using the KOKKOS package.
Related commands
""""""""""""""""
:doc:`read_dump <read_dump>`, :doc:`read_restart <read_restart>`,
:doc:`create_atoms <create_atoms>`, :doc:`write_data <write_data>`
:doc:`create_atoms <create_atoms>`, :doc:`write_data <write_data>`,
:doc:`labelmap <labelmap>`
Default
"""""""

10
doc/src/variable.rst
View File

@ -66,7 +66,7 @@ Syntax
bound(group,dir,region), gyration(group,region), ke(group,reigon),
angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label)
feature functions = is_active(category,feature), is_available(category,feature), is_defined(category,id)
atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i]
atom vector = id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q
@ -505,7 +505,7 @@ references, and references to other variables.
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Region functions | count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x) |
| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), label2type(kind,label) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Atom values | id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i] |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -962,6 +962,12 @@ types, bond types and so on. For the full list of available keywords
*name* and their meaning, see the documentation for extract_setting()
via the link in this paragraph.
The label2type() function converts type labels into numeric types, using label
maps created by the :doc:`labelmap <labelmap>` or :doc:`read_data <read_data>`
commands. The first argument is the label map kind (atom, bond, angle,
dihedral, or improper) and the second argument is the label. The function
returns the corresponding numeric type.
----------
Feature Functions

47
doc/src/write_data.rst
View File

@ -12,12 +12,14 @@ Syntax
* file = name of data file to write out
* zero or more keyword/value pairs may be appended
* keyword = *pair* or *nocoeff*
* keyword = *pair* or *nocoeff* or *nofix* or *nolabelmap*
.. parsed-literal::
*nocoeff* = do not write out force field info
*nofix* = do not write out extra sections read by fixes
*nolabelmap* = do not write out type labels
*types* value = *numeric* or *labels*
*pair* value = *ii* or *ij*
*ii* = write one line of pair coefficient info per atom type
*ij* = write one line of pair coefficient info per IJ atom type pair
@ -94,16 +96,39 @@ data file is read.
----------
The *nocoeff* keyword requests that no force field parameters should
be written to the data file. This can be very helpful, if one wants
to make significant changes to the force field or if the parameters
are read in separately anyway, e.g. from an include file.
Use of the *nocoeff* keyword means no force field parameters are
written to the data file. This can be helpful, for example, if you
want to make significant changes to the force field or if the force
field parameters are read in separately, e.g. from an include file.
The *nofix* keyword requests that no extra sections read by fixes
should be written to the data file (see the *fix* option of the
:doc:`read_data <read_data>` command for details). For example, this
option excludes sections for user-created per-atom properties
from :doc:`fix property/atom <fix_property_atom>`.
Use of the *nofix* keyword means no extra sections read by fixes are
written to the data file (see the *fix* option of the :doc:`read_data
<read_data>` command for details). For example, this option excludes
sections for user-created per-atom properties from :doc:`fix
property/atom <fix_property_atom>`.
The *nolabelmap* and *types* keywords refer to type labels that may be
defined for numeric atom types, bond types, angle types, etc. The
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 type labels exist
for a given type-kind (Atoms, Bonds, Angles, etc.), type labels are
not written to the data file. By default, they are written if they
exist. A type label must be defined for every numeric type (within a
given type-kind) to be written to the data file.
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
@ -144,4 +169,4 @@ Related commands
Default
"""""""
The option defaults are pair = ii.
The option defaults are pair = ii and types_style = numeric.