From eec46d66ec9851912b5d4356c0e9cfd141d18d3a Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Sat, 25 Jan 2014 23:06:52 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@11329
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/atom_style.html | 36 +++++++++++++++++++++++++++---------
 doc/atom_style.txt  | 36 +++++++++++++++++++++++++++---------
 doc/read_data.html  | 23 ++++++++++++++++++-----
 doc/read_data.txt   | 23 ++++++++++++++++++-----
 4 files changed, 90 insertions(+), 28 deletions(-)

diff --git a/doc/atom_style.html b/doc/atom_style.html
index fdadf243d5..49de9bf614 100644
--- a/doc/atom_style.html
+++ b/doc/atom_style.html
@@ -15,13 +15,15 @@
 </P>
 <PRE>atom_style style args 
 </PRE>
-<UL><LI>style = <I>angle</I> or <I>atomic</I> or <I>body</I> or <I>bond</I> or <I>charge</I> or <I>dipole</I> or         <I>electron</I> or <I>ellipsoid</I> or <I>full</I> or <I>line</I> or <I>meso</I> or 	<I>molecular</I> or <I>peri</I> or <I>sphere</I> or <I>tri</I> or <I>hybrid</I> 
+<UL><LI>style = <I>angle</I> or <I>atomic</I> or <I>body</I> or <I>bond</I> or <I>charge</I> or <I>dipole</I> or         <I>electron</I> or <I>ellipsoid</I> or <I>full</I> or <I>line</I> or <I>meso</I> or 	<I>molecular</I> or <I>peri</I> or <I>sphere</I> or <I>tri</I> or <I>template</I> or <I>hybrid</I> 
 </UL>
 <PRE>  args = none for any style except <I>body</I> and <I>hybrid</I>
   <I>body</I> args = bstyle bstyle-args
     bstyle = style of body particles
     bstyle-args = additional arguments specific to the bstyle
                   see the <A HREF = "body.html">body</A> doc page for details
+  <I>template</I> args = template-ID
+    template-ID = ID of molecule template specified in a separate <A HREF = "molecule.html">molecule</A> command
   <I>hybrid</I> args = list of one or more sub-styles, each with their args 
 </PRE>
 <P><B>Examples:</B>
@@ -31,7 +33,8 @@ atom_style bond
 atom_style full
 atom_style body nparticle 2 10
 atom_style hybrid charge bond
-atom_style hybrid charge body nparticle 2 5 
+atom_style hybrid charge body nparticle 2 5
+atom_style template myMols 
 </PRE>
 <P><B>Description:</B>
 </P>
@@ -73,6 +76,7 @@ quantities.
 <TR><TD ><I>molecular</I> </TD><TD > bonds, angles, dihedrals, impropers </TD><TD > uncharged molecules </TD></TR>
 <TR><TD ><I>peri</I> </TD><TD > mass, volume </TD><TD > mesocopic Peridynamic models </TD></TR>
 <TR><TD ><I>sphere</I> </TD><TD > diameter, mass, angular velocity </TD><TD > granular models </TD></TR>
+<TR><TD ><I>template</I> </TD><TD > template index, template atom </TD><TD > small molecules with fixed topology </TD></TR>
 <TR><TD ><I>tri</I> </TD><TD > corner points, angular momentum </TD><TD > rigid bodies </TD></TR>
 <TR><TD ><I>wavepacket</I> </TD><TD > charge, spin, eradius, etag, cs_re, cs_im </TD><TD > AWPMD 
 </TD></TR></TABLE></DIV>
@@ -92,9 +96,9 @@ output the custom values.
 14</A> for an overview of using finite-size
 particle models with LAMMPS.
 </P>
-<P>All of the styles assign mass to particles on a per-type basis, using
-the <A HREF = "mass.html">mass</A> command, except for the finite-size particle
-styles.  They assign mass to individual particles on a per-particle
+<P>All of the point-particle styles assign mass to particles on a
+per-type basis, using the <A HREF = "mass.html">mass</A> command, The finite-size
+particle styles assign mass to individual particles on a per-particle
 basis.
 </P>
 <P>For the <I>sphere</I> style, the particles are spheres and each stores a
@@ -133,6 +137,16 @@ end points of the line segment).
 stores a per-particle mass and size and orientation (i.e. the corner
 points of the triangle).
 </P>
+<P>The <I>template</I> style allows molecular topolgy (bonds,angles,etc) to be
+defined via a molecule template using the <A HREF = "molecule.txt">molecule</A>
+command.  The template stores one or more molecules with a single copy
+of the topology info (bonds,angles,etc) of each.  Individual atoms
+only store a template index and template atom to identify which
+molecule and which atom-within-the-molecule they represent.  Using the
+<I>template</I> style instead of the <I>bond</I>, <I>angle</I>, <I>molecular</I> styles
+can save memory for systems comprised of a large number of small
+molecules, all of a single type (or small number of types).
+</P>
 <P>For the <I>body</I> style, the particles are arbitrary bodies with internal
 attributes defined by the "style" of the bodies, which is specified by
 the <I>bstyle</I> argument.  Body particles can represent complex entities,
@@ -165,6 +179,10 @@ torque, you would need to use "atom_style hybrid sphere dipole".  When
 a hybrid style is used, atoms store and communicate the union of all
 quantities implied by the individual styles.
 </P>
+<P>When using the <I>hybrid</I> style, you cannot combine the <I>template</I> style
+with another molecular style that stores bond,angle,etc info on a
+per-atom basis.
+</P>
 <P>LAMMPS can be extended with new atom styles as well as new body
 styles; see <A HREF = "Section_modify.html">this section</A>.
 </P>
@@ -173,10 +191,10 @@ styles; see <A HREF = "Section_modify.html">this section</A>.
 <P>This command cannot be used after the simulation box is defined by a
 <A HREF = "read_data.html">read_data</A> or <A HREF = "create_box.html">create_box</A> command.
 </P>
-<P>The <I>angle</I>, <I>bond</I>, <I>full</I>, and <I>molecular</I> styles are part of the
-MOLECULAR package.  The <I>line</I> and <I>tri</I> styles are part of the
-ASPHERE pacakge.  The <I>body</I> style is part of the BODY package.  The
-<I>dipole</I> style is part of the DIPOLE package.  The <I>peri</I> style is
+<P>The <I>angle</I>, <I>bond</I>, <I>full</I>, <I>molecular</I>, and <I>template</I> styles are
+part of the MOLECULAR package.  The <I>line</I> and <I>tri</I> styles are part
+of the ASPHERE pacakge.  The <I>body</I> style is part of the BODY package.
+The <I>dipole</I> style is part of the DIPOLE package.  The <I>peri</I> style is
 part of the PERI package for Peridynamics.  The <I>electron</I> style is
 part of the USER-EFF package for <A HREF = "pair_eff.html">electronic force
 fields</A>.  The <I>meso</I> style is part of the USER-SPH
diff --git a/doc/atom_style.txt b/doc/atom_style.txt
index 44049ee8f1..3350c60744 100644
--- a/doc/atom_style.txt
+++ b/doc/atom_style.txt
@@ -14,12 +14,14 @@ atom_style style args :pre
 
 style = {angle} or {atomic} or {body} or {bond} or {charge} or {dipole} or \
         {electron} or {ellipsoid} or {full} or {line} or {meso} or \
-	{molecular} or {peri} or {sphere} or {tri} or {hybrid} :ul
+	{molecular} or {peri} or {sphere} or {tri} or {template} or {hybrid} :ul
   args = none for any style except {body} and {hybrid}
   {body} args = bstyle bstyle-args
     bstyle = style of body particles
     bstyle-args = additional arguments specific to the bstyle
                   see the "body"_body.html doc page for details
+  {template} args = template-ID
+    template-ID = ID of molecule template specified in a separate "molecule"_molecule.html command
   {hybrid} args = list of one or more sub-styles, each with their args :pre
 
 [Examples:]
@@ -29,7 +31,8 @@ atom_style bond
 atom_style full
 atom_style body nparticle 2 10
 atom_style hybrid charge bond
-atom_style hybrid charge body nparticle 2 5 :pre
+atom_style hybrid charge body nparticle 2 5
+atom_style template myMols :pre
 
 [Description:]
 
@@ -70,6 +73,7 @@ quantities.
 {molecular} | bonds, angles, dihedrals, impropers | uncharged molecules |
 {peri} | mass, volume | mesocopic Peridynamic models |
 {sphere} | diameter, mass, angular velocity | granular models |
+{template} | template index, template atom | small molecules with fixed topology |
 {tri} | corner points, angular momentum | rigid bodies |
 {wavepacket} | charge, spin, eradius, etag, cs_re, cs_im | AWPMD :tb(c=3,s=|)
 
@@ -88,9 +92,9 @@ All of the above styles define point particles, except the {sphere},
 14"_Section_howto.html#howto_14 for an overview of using finite-size
 particle models with LAMMPS.
 
-All of the styles assign mass to particles on a per-type basis, using
-the "mass"_mass.html command, except for the finite-size particle
-styles.  They assign mass to individual particles on a per-particle
+All of the point-particle styles assign mass to particles on a
+per-type basis, using the "mass"_mass.html command, The finite-size
+particle styles assign mass to individual particles on a per-particle
 basis.
 
 For the {sphere} style, the particles are spheres and each stores a
@@ -129,6 +133,16 @@ For the {tri} style, the particles are planar triangles and each
 stores a per-particle mass and size and orientation (i.e. the corner
 points of the triangle).
 
+The {template} style allows molecular topolgy (bonds,angles,etc) to be
+defined via a molecule template using the "molecule"_molecule.txt
+command.  The template stores one or more molecules with a single copy
+of the topology info (bonds,angles,etc) of each.  Individual atoms
+only store a template index and template atom to identify which
+molecule and which atom-within-the-molecule they represent.  Using the
+{template} style instead of the {bond}, {angle}, {molecular} styles
+can save memory for systems comprised of a large number of small
+molecules, all of a single type (or small number of types).
+
 For the {body} style, the particles are arbitrary bodies with internal
 attributes defined by the "style" of the bodies, which is specified by
 the {bstyle} argument.  Body particles can represent complex entities,
@@ -161,6 +175,10 @@ torque, you would need to use "atom_style hybrid sphere dipole".  When
 a hybrid style is used, atoms store and communicate the union of all
 quantities implied by the individual styles.
 
+When using the {hybrid} style, you cannot combine the {template} style
+with another molecular style that stores bond,angle,etc info on a
+per-atom basis.
+
 LAMMPS can be extended with new atom styles as well as new body
 styles; see "this section"_Section_modify.html.
 
@@ -169,10 +187,10 @@ styles; see "this section"_Section_modify.html.
 This command cannot be used after the simulation box is defined by a
 "read_data"_read_data.html or "create_box"_create_box.html command.
 
-The {angle}, {bond}, {full}, and {molecular} styles are part of the
-MOLECULAR package.  The {line} and {tri} styles are part of the
-ASPHERE pacakge.  The {body} style is part of the BODY package.  The
-{dipole} style is part of the DIPOLE package.  The {peri} style is
+The {angle}, {bond}, {full}, {molecular}, and {template} styles are
+part of the MOLECULAR package.  The {line} and {tri} styles are part
+of the ASPHERE pacakge.  The {body} style is part of the BODY package.
+The {dipole} style is part of the DIPOLE package.  The {peri} style is
 part of the PERI package for Peridynamics.  The {electron} style is
 part of the USER-EFF package for "electronic force
 fields"_pair_eff.html.  The {meso} style is part of the USER-SPH
diff --git a/doc/read_data.html b/doc/read_data.html
index 7db005e662..c743b3c895 100644
--- a/doc/read_data.html
+++ b/doc/read_data.html
@@ -343,6 +343,7 @@ of analysis.
 <TR><TD >molecular</TD><TD > atom-ID molecule-ID atom-type x y z</TD></TR>
 <TR><TD >peri</TD><TD > atom-ID atom-type volume density x y z</TD></TR>
 <TR><TD >sphere</TD><TD > atom-ID atom-type diameter density x y z</TD></TR>
+<TR><TD >template</TD><TD > atom-ID molecule-ID template-index template-atom atom-type x y z</TD></TR>
 <TR><TD >tri</TD><TD > atom-ID molecule-ID atom-type triangleflag density x y z</TD></TR>
 <TR><TD >wavepacket</TD><TD > atom-ID atom-type charge spin eradius etag cs_re cs_im x y z</TD></TR>
 <TR><TD >hybrid</TD><TD > atom-ID atom-type x y z sub-style1 sub-style2 ...  
@@ -359,6 +360,8 @@ of analysis.
 <LI>lineflag = 1 for line segment particles, 0 for point particles
 <LI>triangleflag = 1 for triangular particles, 0 for point particles
 <LI>bodyflag = 1 for body particles, 0 for point particles
+<LI>template-index = which molecule within the molecule template the atom is part of
+<LI>template-atom = which atom within a template molecule the atom is
 <LI>density = density of particle (mass/distance^3 or mass/distance^2 or mass/distance units, depending on dimensionality of particle)
 <LI>mass = mass of particle (mass units)
 <LI>volume = volume of particle (distance^3 units)
@@ -382,11 +385,11 @@ setting in the data file header.
 in dump files.  Normally, it is a unique value from 1 to Natoms for
 each atom.  Unique values larger than Natoms can be used, but they
 will cause extra memory to be allocated on each processor, if an atom
-map array is used (see the <A HREF = "atom_modify.html">atom_modify</A> command).
-If an atom map array is not used (e.g. an atomic system with no
-bonds), and velocities are not assigned in the data file, and you
-don't care if unique atom IDs appear in dump files, then the atom-IDs
-can all be set to 0.
+map array is used, but not if an atom map hash is used; see the
+<A HREF = "atom_modify.html">atom_modify</A> command for details.  If an atom map is
+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.
 </P>
 <P>The molecule ID is a 2nd identifier attached to an atom.  Normally, it
 is a number from 1 to N, identifying which molecule the atom belongs
@@ -403,6 +406,16 @@ Additional attributes must be defined for each ellipsoid, line,
 triangle, or body in the corresponding <I>Ellipsoids</I>, <I>Lines</I>,
 <I>Triangles</I>, or <I>Bodies</I> section.
 </P>
+<P>The <I>template-index</I> and <I>template-atom</I> are only defined used by
+<A HREF = "atom_style.html">atom_style template</A>.  In this case the
+<A HREF = "molecule.html">molecule</A> command is used to define a molecule template
+which contains one or more molecules.  If an atom belongs to one of
+those molecules, its <I>template-index</I> and <I>template-atom</I> are both set
+to positive integers; if not the values are both 0.  The
+<I>template-index</I> is which molecule (1 to Nmols) the atom belongs to.
+The <I>template-atom</I> is which atom (1 to Natoms) within the molecule
+the atom is.
+</P>
 <P>Some pair styles and fixes and computes that operate on finite-size
 particles allow for a mixture of finite-size and point particles.  See
 the doc pages of individual commands for details.
diff --git a/doc/read_data.txt b/doc/read_data.txt
index 8d8aaef3ac..7402acfb48 100644
--- a/doc/read_data.txt
+++ b/doc/read_data.txt
@@ -320,6 +320,7 @@ meso: atom-ID atom-type rho e cv x y z
 molecular: atom-ID molecule-ID atom-type x y z
 peri: atom-ID atom-type volume density x y z
 sphere: atom-ID atom-type diameter density x y z
+template: atom-ID molecule-ID template-index template-atom atom-type x y z
 tri: atom-ID molecule-ID atom-type triangleflag density x y z
 wavepacket: atom-ID atom-type charge spin eradius etag cs_re cs_im x y z
 hybrid: atom-ID atom-type x y z sub-style1 sub-style2 ...  :tb(s=:)
@@ -335,6 +336,8 @@ ellipsoidflag = 1 for ellipsoidal particles, 0 for point particles
 lineflag = 1 for line segment particles, 0 for point particles
 triangleflag = 1 for triangular particles, 0 for point particles
 bodyflag = 1 for body particles, 0 for point particles
+template-index = which molecule within the molecule template the atom is part of
+template-atom = which atom within a template molecule the atom is
 density = density of particle (mass/distance^3 or mass/distance^2 or mass/distance units, depending on dimensionality of particle)
 mass = mass of particle (mass units)
 volume = volume of particle (distance^3 units)
@@ -358,11 +361,11 @@ The atom-ID is used to identify the atom throughout the simulation and
 in dump files.  Normally, it is a unique value from 1 to Natoms for
 each atom.  Unique values larger than Natoms can be used, but they
 will cause extra memory to be allocated on each processor, if an atom
-map array is used (see the "atom_modify"_atom_modify.html command).
-If an atom map array is not used (e.g. an atomic system with no
-bonds), and velocities are not assigned in the data file, and you
-don't care if unique atom IDs appear in dump files, then the atom-IDs
-can all be set to 0.
+map array is used, but not if an atom map hash is used; see the
+"atom_modify"_atom_modify.html command for details.  If an atom map is
+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 molecule ID is a 2nd identifier attached to an atom.  Normally, it
 is a number from 1 to N, identifying which molecule the atom belongs
@@ -379,6 +382,16 @@ Additional attributes must be defined for each ellipsoid, line,
 triangle, or body in the corresponding {Ellipsoids}, {Lines},
 {Triangles}, or {Bodies} section.
 
+The {template-index} and {template-atom} are only defined used by
+"atom_style template"_atom_style.html.  In this case the
+"molecule"_molecule.html command is used to define a molecule template
+which contains one or more molecules.  If an atom belongs to one of
+those molecules, its {template-index} and {template-atom} are both set
+to positive integers; if not the values are both 0.  The
+{template-index} is which molecule (1 to Nmols) the atom belongs to.
+The {template-atom} is which atom (1 to Natoms) within the molecule
+the atom is.
+
 Some pair styles and fixes and computes that operate on finite-size
 particles allow for a mixture of finite-size and point particles.  See
 the doc pages of individual commands for details.