diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst index 1d7d626e02..71fb3aee7b 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -33,6 +33,7 @@ Settings howto :maxdepth: 1 Howto_2d + Howto_type_labels Howto_triclinic Howto_thermostat Howto_barostat diff --git a/doc/src/Howto_type_labels.rst b/doc/src/Howto_type_labels.rst new file mode 100644 index 0000000000..3066b88078 --- /dev/null +++ b/doc/src/Howto_type_labels.rst @@ -0,0 +1,125 @@ +Type labels +=========== + +Each atom in LAMMPS has an associated atom type. Likewise each bond, +angle, dihedral, improper enumerated in a data file read by the +:doc:`read_data ` command has a bond type, angle type, etc. + +By default, type values are integers from 1 to Ntypes, wherever they +appear in LAMMPS input or output files. However, LAMMPS also has the +option to use alphanumeric strings, called type labels, for these +values in its input and output. + +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. + +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. + +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. + +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 '*'. + +As explained below, for certain command 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 +a C-H bond with a type label "[C][H]". + +There are two ways to define label maps. One is via the +:doc:`labelmap ` command, which has an optional *mapID* +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. + +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 +mapIDs cannot be written to either data or restart files by these +commands. + +---------- + +Use of type labels in LAMMPS input or output +"""""""""""""""""""""""""""""""""""""""""""" + +Any LAMMPS input script command which takes a numeric type as an +argument, can use the associated type label instead, with the optional +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. + +.. code-block:: LAMMPS + + bond_coeff 2 80.0 1.2 # numeric type + labelmap bond 2 [C][H] + bond_coeff [C][H] 80.0 1.2 # type label + +or + +.. code-block:: LAMMPS + + bond_coeff 2 80.0 1.2 # numeric type + labelmap bond 2 [C][H] mapID Map2 + bond_coeff Map2::[C][H] 80.0 1.2 # type label + +Support for type labels is a work-in-progress for LAMMPS as of +Nov 2021. If an input script command allows substituting for a +numeric type argument with a type label, it will be mentioned on that +command's doc page. If not yet supported, any input script command +that requires a numeric type can instead use a variable with a +labelmap function that converts a type label to a numeric type, as in +the last example above. See the :doc:`variable ` command +for details. + +For example, here is how the bond_coeff command could be used with a +type label if it did not yet support them, either with an explicit +variable command or an implicit variable used in the bond_coeff +command. + +.. code-block:: LAMMPS + + labelmap bond 2 [C][H] + variable bond2 equal blabel([C][H]) + bond_coeff ${bond2} 80.0 1.2 + +.. code-block:: LAMMPS + + labelmap bond 2 [C][H] + bond_coeff $(blabel([C][H])) 80.0 1.2 + +Support for output of type labels in dump files will be added to +LAMMPS soon (as of Nov 2021). + +---------- + +Commands that can use label types in interesting ways +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Provide a few details on these to spark user's interest? If not yet +implemented, just say this is planned, as of Nov 2021. + +fix bond/react +pair_style kim +other? diff --git a/doc/src/angle_coeff.rst b/doc/src/angle_coeff.rst index b1424266b5..cbe74a9aac 100644 --- a/doc/src/angle_coeff.rst +++ b/doc/src/angle_coeff.rst @@ -22,6 +22,9 @@ 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. + Description """"""""""" @@ -31,7 +34,11 @@ Angle coefficients can also be set in the data file read by the :doc:`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 N can be a :doc:`type label `. +be used, as in the first example above. Or N 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. + 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 N = the number of angle types, then an @@ -40,9 +47,10 @@ 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 using an :doc:`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: +Note that using an :doc:`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 @@ -50,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 ` 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 ` +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 .. parsed-literal:: diff --git a/doc/src/bond_coeff.rst b/doc/src/bond_coeff.rst index 6e3f4f96be..4f2d226dc1 100644 --- a/doc/src/bond_coeff.rst +++ b/doc/src/bond_coeff.rst @@ -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) + +JAKE add an example with 2 lines. First = labelmap command, second = +use the type label. Description """"""""""" @@ -31,8 +34,12 @@ 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 ` command or in a restart file. -N can be specified in one of several ways. An explicit numeric value can -be used, as in the first example above. Or N can be a :doc:`type label `. +N can be specified in one of several ways. An explicit numeric value +can be used, as in the first example above. Or N 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. + 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 N = the number of bond types, then an diff --git a/doc/src/dihedral_coeff.rst b/doc/src/dihedral_coeff.rst index 1e6dbc91ff..846973b7ed 100644 --- a/doc/src/dihedral_coeff.rst +++ b/doc/src/dihedral_coeff.rst @@ -22,6 +22,9 @@ 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. + Description """"""""""" @@ -31,7 +34,11 @@ Dihedral coefficients can also be set in the data file read by the :doc:`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 N can be a :doc:`type label `. +be used, as in the first example above. Or N 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. + 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 N = the number of dihedral types, then diff --git a/doc/src/improper_coeff.rst b/doc/src/improper_coeff.rst index f0f1d48f2c..980eda05c6 100644 --- a/doc/src/improper_coeff.rst +++ b/doc/src/improper_coeff.rst @@ -32,7 +32,11 @@ file read by the :doc:`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 N can be a :doc:`type label `. +be used, as in the first example above. Or N 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. + 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 N = the number of improper types, then diff --git a/doc/src/labelmap.rst b/doc/src/labelmap.rst index e0e289979a..87ec50e67b 100644 --- a/doc/src/labelmap.rst +++ b/doc/src/labelmap.rst @@ -8,16 +8,17 @@ Syntax .. code-block:: LAMMPS - labelmap interaction numeric-type type-label ... keyword values + labelmap type-kind numeric-type type-label ... keyword arg -* interaction = *atom* or *bond* or *angle* or *dihedral* or *improper* -* one or more numeric-type/type-label pairs may be appended -* keyword = *map/assign* +* type-kind = *atom* or *bond* or *angle* or *dihedral* or *improper* +* one or more numeric-type/type-label pairs may be specified +* zero or more keyword/arg pairs may be appended +* keyword = *mapID* .. parsed-literal:: - *map/assign* value = mapID - mapID = name of auxiliary label map + *mapID* arg = name + name = ID for the label map Examples """""""" @@ -26,78 +27,54 @@ 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) Description """"""""""" -Define or replace the alphanumeric type label associated with a -numeric atom, bond, angle, dihedral or improper type. Type labels are -strings that can be assigned to each interaction type. Pairing each -numeric type used by LAMMPS with a character-based type can be -helpful in a variety of situations. For example, type labels can make -various inputs more readable and compatible with other inputs (data -files, molecule templates, etc.), particularly if your model's force -field uses alphanumeric atom types. The default type label map can -also be defined by :doc:`data files ` using the relevant -Type Label sections. +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. -.. note:: +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 +labels can be used. - If substituting numeric types with type labels is currently - supported by a given command, this feature will be mentioned on - that command's doc page. Or, for input script commands, type labels - can be processed using :doc:`variable ` syntax using - labelmap functions. +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 '*'. -.. note:: +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 a given numeric +type, it will be overwritten. Type labels must be unique; assigning +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. - Type labels cannot start with a number. - -The label map of only one type of interaction (atom, bond, etc.) may -be modified by a given *labelmap* command. Any number of -numeric-type/type-label pairs may follow. If a type label already -exists for a given numeric type, it will be overwritten. Types labels -must be unique; assigning the same type label to multiple numeric -types is not permitted. There does not need to be a type label -associated with every numeric type; in this case, those types without -a label must be referenced by their numeric type. - -For certain features, it is necessary to be able to extract the -atom types that make up a given bond, angle, dihedral or improper. The -standard way to write multi-atom interaction types is to enclose the -constituent atom types in brackets. For example, a bond type between -atom type 'C' and 'H' is written as: - -.. code-block:: LAMMPS - - bond_style harmonic - bond_coeff [C][H] 80.0 1.2 - -In some circumstances, it may be helpful to define extra label maps in -addition to the default one. An auxiliary label map can be created and -populated using the *map/assign* keyword. Type labels of auxiliary -label maps can be referenced by prefixing the type label with the -mapID followed by "::". For example, a type label "C" assigned to a -label map named "Map2" can be created and referenced as follows: - -.. code-block:: LAMMPS - - labelmap bond 1 [C][H] map/assign Map2 - bond_coeff Map2::[C][H] 80.0 1.2 - -Auxiliary label maps are not written to restart or data files. Due to -the syntax for auxiliary maps, type labels cannot contain the -substring "::". The default label map has no prefix. +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. ---------- Restrictions """""""""""" -Type labels cannot contain the symbols '#' or '*'. This command must -come after the simulation box is defined by a :doc:`read_data `, -:doc:`read_restart `, or :doc:`create_box ` -command. +This command must come after the simulation box is defined by a +:doc:`read_data `, :doc:`read_restart `, or +:doc:`create_box ` command. Related commands """""""""""""""" @@ -108,4 +85,5 @@ Related commands Default """"""" -The option default is no type label map. +If the mapID keyword is not used, specified type labels are assigned +to the default map for the type-kind. diff --git a/doc/src/molecule.rst b/doc/src/molecule.rst index d56992aeed..1112c7fc38 100644 --- a/doc/src/molecule.rst +++ b/doc/src/molecule.rst @@ -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 ` command allows multiple-molecule templates -to define a system with more than one templated molecule. +contains multiple molecules. The :doc:`atom_style template +` 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 @@ -173,12 +174,15 @@ 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, etc. type can be listed either as a number (numeric type) -or as an alphanumeric :doc:`type label `. Type labels cannot -start with a number, and a label map must have previously been defined -by a :doc:`labelmap ` or :doc:`read_data ` -command. +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 +` 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. If a Bonds section is specified then the Special Bond Counts and Special Bonds sections can also be used, if desired, to explicitly @@ -186,25 +190,26 @@ 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 ` command for more details. One -reason to list the special bond info explicitly is for the -:doc:`thermalized Drude oscillator model ` which treats the -bonds between nuclear cores and Drude electrons in a different manner. +interactions between bonded atoms. See the :doc:`special_bonds +` command for more details. One reason to list the +special bond info explicitly is for the :doc:`thermalized Drude +oscillator model ` 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 ` command, the Coords - and Types sections are required. To add a rigid body via the :doc:`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 ` command, the Coords and + Types sections are required. To add a rigid body via the :doc:`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 ` 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 diff --git a/doc/src/pair_coeff.rst b/doc/src/pair_coeff.rst index 51bf8e0079..4f10ff2da2 100644 --- a/doc/src/pair_coeff.rst +++ b/doc/src/pair_coeff.rst @@ -36,9 +36,13 @@ by the :doc:`read_data ` command or in a restart file. 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 may be a :doc:`type label `. -LAMMPS sets the coefficients for the symmetric J,I interaction to the -same values. +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. 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 @@ -47,9 +51,11 @@ multiple pairs of atom types. This takes the form "\*" or "\*n" or 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. +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. 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 @@ -68,8 +74,8 @@ 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 +file, the line corresponding to the first example above would be +listed as .. parsed-literal:: diff --git a/doc/src/read_data.rst b/doc/src/read_data.rst index 18146378b7..d98995ad3f 100644 --- a/doc/src/read_data.rst +++ b/doc/src/read_data.rst @@ -477,7 +477,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 map +* *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 @@ -547,11 +547,13 @@ input script. ID = angle type (1-N) label = alphanumeric type label -See the *Atom Type Labels* section for more details about how angle -types are interpreted when reading one or more data files that contain -angle type label sections. See the :doc:`labelmap ` command -for a discussion about how to format angle type labels and use type -label maps. +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 ` doc page for the +allowed syntax of type labels and a general discussion of how type +labels can be used. ---------- @@ -599,8 +601,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 ` command or an Angle Type Labels section +earlier in the data file. 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. ---------- @@ -626,29 +635,13 @@ integers (1, not 1.0). ID = numeric atom type (1-N) label = alphanumeric type label -Type labels can be used to make data files more general, by defining -atom, bond, etc. types in terms of user-provided strings instead of -numbers. If a type label section exists for a given interaction -(atom, bond, angle, dihedral or improper), then all types must be -assigned a type label for that interaction. Type label sections must -come before any section that utilizes that type. Type labels can be -directly substituted for numeric types listed in the *Atoms*, *Bonds*, -etc. sections of data files. If numeric types are used, each -interaction type is first converted into its corresponding type label -before being read into LAMMPS. Data files assign all types to the -default label map; if the type label does not already exist, the type -label is created as a new type and assigned to the default label map. -The corresponding interaction coefficients listed in the data file are -associated to this type. There must be enough space in the per-type -data arrays to create new types; see the *extra/atom/types* keyword -for how to reserve extra space for new types, e.g., when reading -multiple data files. Note that, in this case, the numeric-to-label -mapping within a data file does not necessary correspond to that of -the simulation; once the default label map is fully defined, the -:doc:`write_data ` command can be used to print out the -default label map at a given point in a simulation. See the -:doc:`labelmap ` command for more discussion on how to use -type label maps. +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 ` doc page for the +allowed syntax of type labels and a general discussion of how type +labels can be used. ---------- @@ -773,6 +766,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 ` command or an Atom Type Labels section +earlier in the data file. 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. + 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 @@ -993,11 +993,13 @@ script. ID = bond type (1-N) label = alphanumeric type label -See the *Atom Type Labels* section for more details about how bond -types are interpreted when reading one or more data files that contain -bond type label sections. See the :doc:`labelmap ` command -for a discussion about how to format bond type labels and use type -label maps. +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 ` doc page for the +allowed syntax of type labels and a general discussion of how type +labels can be used. ---------- @@ -1054,8 +1056,15 @@ label maps. 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 ` command or a Bond Type Labels section +earlier in the data file. 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. ---------- @@ -1093,11 +1102,13 @@ Coefficients can also be set via the ID = dihedral type (1-N) label = alphanumeric type label -See the *Atom Type Labels* section for more details about how dihedral -types are interpreted when reading one or more data files that contain -dihedral type label sections. See the :doc:`labelmap ` -command for a discussion about how to format dihedral type labels and -use type label maps. +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 ` doc page for the +allowed syntax of type labels and a general discussion of how type +labels can be used. ---------- @@ -1119,8 +1130,15 @@ use type label maps. 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 ` command or a Dihedral Type Labels section +earlier in the data file. 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. ---------- @@ -1212,11 +1230,13 @@ Coefficients can also be set via the ID = improper type (1-N) label = alphanumeric type label -See the *Atom Type Labels* section for more details about how improper -types are interpreted when reading one or more data files that contain -improper type label sections. See the :doc:`labelmap ` -command for a discussion about how to format improper type labels and -use type label maps. +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 ` doc page for the +allowed syntax of type labels and a general discussion of how type +labels can be used. ---------- @@ -1238,11 +1258,19 @@ use type label maps. 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 `. See the doc pages for individual styles -for details. +angle used in the formula for each :doc:`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 ` command or a Improper Type Labels section +earlier in the data file. 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. ---------- diff --git a/doc/src/write_data.rst b/doc/src/write_data.rst index b7eb7cf94d..6200f62716 100644 --- a/doc/src/write_data.rst +++ b/doc/src/write_data.rst @@ -19,7 +19,7 @@ Syntax *nocoeff* = do not write out force field info *nofix* = do not write out extra sections read by fixes *nolabelmap* = do not write out the default label map - *types_style* value = *numeric* or *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 @@ -96,30 +96,36 @@ 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 ` command for details). For example, this -option excludes sections for user-created per-atom properties -from :doc:`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 +` command for details). For example, this option excludes +sections for user-created per-atom properties from :doc:`fix +property/atom `. -The *nolabelmap* keyword requests that the default label map should -not be written to the data file (see the Type Label sections of -:doc:`read_data ` command for details). By default, if the -default label map is fully defined for a given interaction, i.e. every -atom, bond, angle, dihedral or improper type has an associated type -label, then a type label section for that interaction is written to -the data file. The *types_style* keyword indicates how atom, bond, -etc. types are written in the Atoms, Bonds, etc. sections. If the -value is specified as *numeric*, then numeric types are used. If the -value is specified as *labels*, then interaction types are written as -type labels using the default label map. When using type labels, the -default label map (i.e., Type Label sections) must be written to the -data file. +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 +` 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. + +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 *pair* keyword lets you specify in what format the pair coefficient information is written into the data file. If the value