diff --git a/doc/molecule.html b/doc/molecule.html index d2ff915697..3b312fbc5a 100644 --- a/doc/molecule.html +++ b/doc/molecule.html @@ -13,16 +13,32 @@

Syntax:

-
molecule ID file1 file2 ... 
+
molecule ID file1 file2 ... keyword values ... 
 

-
 
If a Bonds section is specified then the Special Bond Counts and
-Special Bonds sections must be also, since the latter is needed for
-LAMMPS to properly exclude or weight bonded pairwise interactions
-between bonded atoms.  See the special_bonds
-command for more details.
+Special Bonds sections must be also unless the optional auto keyword
+is defined.  This info is needed for LAMMPS to properly exclude or
+weight bonded pairwise interactions between bonded atoms.  See the
+special_bonds command for more details.  If the
+auto keyword is used, then LAMMPS will generate this information
+automatically for the molecule.
 

 
IMPORTANT NOTE: Whether a section is required depends on how the
 molecule template is used by other LAMMPS commands.  For example, to
diff --git a/doc/molecule.txt b/doc/molecule.txt
index 1d1e7545f2..cff68cb9db 100644
--- a/doc/molecule.txt
+++ b/doc/molecule.txt
@@ -10,16 +10,27 @@ molecule command :h3
 
 [Syntax:]
 
-molecule ID file1 file2 ... :pre
+molecule ID file1 file2 ... keyword values ... :pre
 
-ID = user-assigned name for the molecule template
-file1,file2,... = names of files containing molecule descriptions :ul
+ID = user-assigned name for the molecule template :ulb,l
+file1,file2,... = names of files containing molecule descriptions :l
+zero or more keyword/value pairs may be appended :l
+keyword = {offset} or {auto} :l
+  {offset} values = toff boff aoff doff ioff
+    toff = offset to add to atom type
+    boff = offset to add to bond type
+    aoff = offset to add to angle type
+    doff = offset to add to dihedral type
+    ioff = offset to add to improper type
+  {auto} value = none = generate special bond lists automatically :pre
+:ule
 
 [Examples:]
 
 molecule 1 mymol
 molecule 1 co2.txt h2o.txt
-molecule CO2 co2.txt :pre
+molecule CO2 co2.txt
+molecule 1 mymol offset 6 9 18 23 14 auto :pre
 
 [Description:]
 
@@ -46,6 +57,20 @@ contains multiple molecules.  The "atom_style
 template"_atom_style.html command allows multiple-molecule templates
 to define a system with more than one templated molecule.
 
+The optional {offset} keyword will add the specified offset values to
+the atom types, bond types, angle types, dihedral types, and improper
+types as they are read from the molecule file.  E.g. if {toff} = 2,
+and the file uses atom types 1,2,3, then each created molecule will
+have atom types 3,4,5.  This makes it easy to use the same molecule
+template file in different simulations.  Note that the same offsets
+are applied to the molecules in all specified files.  All five offset
+values are required, but individual values will be ignored if the
+molecule template does not define that attribute.
+
+The optional {auto} keyword can be used for molecules with bonds
+instead of listing neighbors within the molecular topology explicitly.
+More details are given below.
+
 IMPORTANT NOTE: When using the "atom_style template"_atom_style.html
 command with a molecule template that contains multiple molecules, you
 should insure the atom types, bond types, angle_types, etc in all the
@@ -56,7 +81,23 @@ with each other when a mixture system of H2O and CO2 molecules is
 defined, e.g.  by the "read_data"_read_data.html command.  Rather the
 H2O molecule should define atom types 1 and 2, and bond type 1.  And
 the CO2 molecule should define atom types 3 and 4 (or atom types 3 and
-2 if a single oxygen type is desired), and bond type 2.
+2 if a single oxygen type is desired), and bond type 2.  You can also
+use the {offset} keyword to shift all of these type values to new
+values for a particular simulation.
+
+IMPORTANT NOTE: This command can be used to define molecules with
+bonds, angles, dihedrals, imporopers, or special bond lists of
+neighbors within a molecular topology, so that you can later add the
+molecules to your simulation, via one or more of the commands listed
+above.  If such molecules do not already exist when LAMMPS creates the
+simulation box, via the "create_box"_create_box.html or
+"read_data"_read_data.html command, when you later add them you may
+overflow the pre-allocated data structures which store molecular
+topology information with each atom, and an error will be generated.
+Both the "create_box"_create_box.html command and the data files read
+by the "read_data"_read_data.html command have "extra" options which
+insure space is allocated for storing topology info for molecules that
+are added later.
 
 The format of an individual molecule file is similar to the data file
 read by the "read_data"_read_data.html commands, and is as follows.
@@ -116,10 +157,12 @@ These are the allowed section keywords for the body of the file.
 {Shake Flags, Shake Atoms, Shake Bond Types} = SHAKE info :ul
 
 If a Bonds section is specified then the Special Bond Counts and
-Special Bonds sections must be also, since the latter is needed for
-LAMMPS to properly exclude or weight bonded pairwise interactions
-between bonded atoms.  See the "special_bonds"_special_bonds.html
-command for more details.
+Special Bonds sections must be also unless the optional {auto} keyword
+is defined.  This info is needed for LAMMPS to properly exclude or
+weight bonded pairwise interactions between bonded atoms.  See the
+"special_bonds"_special_bonds.html command for more details.  If the
+{auto} keyword is used, then LAMMPS will generate this information
+automatically for the molecule.
 
 IMPORTANT NOTE: Whether a section is required depends on how the
 molecule template is used by other LAMMPS commands.  For example, to