diff --git a/doc/lattice.html b/doc/lattice.html
index e3dd79db8a..2e75e2157d 100644
--- a/doc/lattice.html
+++ b/doc/lattice.html
@@ -82,6 +82,15 @@ are the edge vectors of the unit cell. This is the nomenclature for
unit cell they determine does not have to be a "primitive cell" of
minimum volume.
+Note that the lattice command can be used multiple times in an input
+script. Each time it is invoked, the lattice attributes are
+re-defined and are used for all subsequent commands (that use lattice
+attributes). For example, a sequence of lattice,
+region, and create_atoms commands
+can be repeated multiple times to build a poly-crystalline model with
+different geometric regions populated with atoms in different lattice
+orientations.
+
A lattice of style none does not define a unit cell and basis set,
@@ -168,61 +177,73 @@ mapping it into the simulation box. The dim argument is one of the
the crystallographic direction in the lattice that you want to orient
along that axis, specified as integers. E.g. "orient x 2 1 0" means
the x-axis in the simulation box will be the [210] lattice
-direction. The 3 lattice directions you specify must be mutually
+direction, and similarly for y and z. The 3 lattice directions you
+specify do not have to be unit vectors, but they must be mutually
orthogonal and obey the right-hand rule, i.e. (X cross Y) points in
-the Z direction. Note that this description is really only valid for
-orthogonal lattices. If you are using the more general lattice style
-custom with non-orthogonal a1,a2,a3 vectors, then think of the 3
-orient options as creating a 3x3 rotation matrix which is applied to
-a1,a2,a3 to rotate the original unit cell to a new orientation in the
-simulation box.
+the Z direction.
+
+IMPORTANT NOTE: The preceding paragraph describing lattice directions
+is only valid for orthogonal cubic unit cells (or square in 2d). If
+you are using a hcp or hex lattice or the more general lattice
+style custom with non-orthogonal a1,a2,a3 vectors, then you should
+think of the 3 orient vectors as creating a 3x3 rotation matrix
+which is applied to a1,a2,a3 to rotate the original unit cell to a new
+orientation in the simulation box.
Several LAMMPS commands have the option to use distance units that are
-inferred from "lattice spacing" in the x,y,z box directions. E.g. the
-region command can create a block of size 10x20x20,
-where 10 means 10 lattice spacings in the x direction.
+inferred from "lattice spacings" in the x,y,z box directions.
+E.g. the region command can create a block of size
+10x20x20, where 10 means 10 lattice spacings in the x direction.
-The spacing option sets the 3 lattice spacings directly. All must
-be non-zero (use 1.0 for dz in a 2d simulation). The specified values
-are multiplied by the multiplicative factor described above that is
-associated with the scale factor. Thus a spacing of 1.0 means one
-unit cell independent of the scale factor. This option can be useful
-if the spacings LAMMPS computes are inconvenient to use in subsequent
-commands, which can be the case for non-orthogonal or rotated
-lattices.
+
IMPORTANT NOTE: Though they are called lattice spacings, all the
+commands that have a "units lattice" option, simply use the 3 values
+as scale factors on the distance units defined by the
+units command. Thus if you do not like the lattice
+spacings computed by LAMMPS (e.g. for a non-orthogonal or rotated unit
+cell), you can define the 3 values to be whatever you wish, via the
+spacing option.
If the spacing option is not specified, the lattice spacings are
computed by LAMMPS in the following way. A unit cell of the lattice
-is mapped into the simulation box (scaled, shifted, rotated), so that
-it now has (perhaps) a modified size and orientation. The lattice
-spacing in X is defined as the difference between the min/max extent
-of the x coordinates of the 8 corner points of the modified unit cell.
-Similarly, the Y and Z lattice spacings are defined as the difference
-in the min/max of the y and z coordinates.
+is mapped into the simulation box (scaled and rotated), so that it now
+has (perhaps) a modified size and orientation. The lattice spacing in
+X is defined as the difference between the min/max extent of the x
+coordinates of the 8 corner points of the modified unit cell (4 in
+2d). Similarly, the Y and Z lattice spacings are defined as the
+difference in the min/max of the y and z coordinates.
-Note that if the unit cell is orthogonal with axis-aligned edges (not
-rotated via the orient keyword), then the lattice spacings in each
+
Note that if the unit cell is orthogonal with axis-aligned edges (no
+rotation via the orient keyword), then the lattice spacings in each
dimension are simply the scale factor (described above) multiplied by
the length of a1,a2,a3. Thus a hex style lattice with a scale
factor of 3.0 Angstroms, would have a lattice spacing of 3.0 in x and
3*sqrt(3.0) in y.
IMPORTANT NOTE: For non-orthogonal unit cells and/or when a rotation
-is applied via the orient keyword, then the lattice spacings may be
-less intuitive. In particular, in these cases, there is no guarantee
-that the lattice spacing is an integer multiple of the periodicity of
-the lattice in that direction. Thus, if you create an orthogonal
-periodic simulation box whose size in a dimension is a multiple of the
-lattice spacing, and then fill it with atoms via the
-create_atoms command, you will NOT necessarily
-create a periodic system. I.e. atoms may overlap incorrectly at the
-faces of the simulation box.
+is applied via the orient keyword, then the lattice spacings
+computed by LAMMPS are typically less intuitive. In particular, in
+these cases, there is no guarantee that a particular lattice spacing
+is an integer multiple of the periodicity of the lattice in that
+direction. Thus, if you create an orthogonal periodic simulation box
+whose size in a dimension is a multiple of the lattice spacing, and
+then fill it with atoms via the create_atoms
+command, you will NOT necessarily create a periodic system.
+I.e. atoms may overlap incorrectly at the faces of the simulation box.
-Regardless of these issues, the values of the lattice spacings LAMMPS
-calculates are printed out, so their effect in commands that use the
-spacings should be decipherable.
+
The spacing option sets the 3 lattice spacings directly. All must
+be non-zero (use 1.0 for dz in a 2d simulation). The specified values
+are multiplied by the multiplicative factor described above that is
+associated with the scale factor. Thus a spacing of 1.0 means one
+unit cell edge length independent of the scale factor. As mentioned
+above, this option can be useful if the spacings LAMMPS computes are
+inconvenient to use in subsequent commands, which can be the case for
+non-orthogonal or rotated lattices.
+
+Note that whenever the lattice command is used, the values of the
+lattice spacings LAMMPS calculates are printed out. Thus their effect
+in commands that use the spacings should be decipherable.
diff --git a/doc/lattice.txt b/doc/lattice.txt
index 38f38ae58b..776998f27b 100644
--- a/doc/lattice.txt
+++ b/doc/lattice.txt
@@ -74,6 +74,15 @@ are the edge vectors of the unit cell. This is the nomenclature for
unit cell they determine does not have to be a "primitive cell" of
minimum volume.
+Note that the lattice command can be used multiple times in an input
+script. Each time it is invoked, the lattice attributes are
+re-defined and are used for all subsequent commands (that use lattice
+attributes). For example, a sequence of lattice,
+"region"_region.html, and "create_atoms"_create_atoms.html commands
+can be repeated multiple times to build a poly-crystalline model with
+different geometric regions populated with atoms in different lattice
+orientations.
+
:line
A lattice of style {none} does not define a unit cell and basis set,
@@ -160,61 +169,73 @@ mapping it into the simulation box. The {dim} argument is one of the
the crystallographic direction in the lattice that you want to orient
along that axis, specified as integers. E.g. "orient x 2 1 0" means
the x-axis in the simulation box will be the \[210\] lattice
-direction. The 3 lattice directions you specify must be mutually
+direction, and similarly for y and z. The 3 lattice directions you
+specify do not have to be unit vectors, but they must be mutually
orthogonal and obey the right-hand rule, i.e. (X cross Y) points in
-the Z direction. Note that this description is really only valid for
-orthogonal lattices. If you are using the more general lattice style
-{custom} with non-orthogonal a1,a2,a3 vectors, then think of the 3
-{orient} options as creating a 3x3 rotation matrix which is applied to
-a1,a2,a3 to rotate the original unit cell to a new orientation in the
-simulation box.
+the Z direction.
+
+IMPORTANT NOTE: The preceding paragraph describing lattice directions
+is only valid for orthogonal cubic unit cells (or square in 2d). If
+you are using a {hcp} or {hex} lattice or the more general lattice
+style {custom} with non-orthogonal a1,a2,a3 vectors, then you should
+think of the 3 {orient} vectors as creating a 3x3 rotation matrix
+which is applied to a1,a2,a3 to rotate the original unit cell to a new
+orientation in the simulation box.
:line
Several LAMMPS commands have the option to use distance units that are
-inferred from "lattice spacing" in the x,y,z box directions. E.g. the
-"region"_region.html command can create a block of size 10x20x20,
-where 10 means 10 lattice spacings in the x direction.
+inferred from "lattice spacings" in the x,y,z box directions.
+E.g. the "region"_region.html command can create a block of size
+10x20x20, where 10 means 10 lattice spacings in the x direction.
-The {spacing} option sets the 3 lattice spacings directly. All must
-be non-zero (use 1.0 for dz in a 2d simulation). The specified values
-are multiplied by the multiplicative factor described above that is
-associated with the scale factor. Thus a spacing of 1.0 means one
-unit cell independent of the scale factor. This option can be useful
-if the spacings LAMMPS computes are inconvenient to use in subsequent
-commands, which can be the case for non-orthogonal or rotated
-lattices.
+IMPORTANT NOTE: Though they are called lattice spacings, all the
+commands that have a "units lattice" option, simply use the 3 values
+as scale factors on the distance units defined by the
+"units"_units.html command. Thus if you do not like the lattice
+spacings computed by LAMMPS (e.g. for a non-orthogonal or rotated unit
+cell), you can define the 3 values to be whatever you wish, via the
+{spacing} option.
If the {spacing} option is not specified, the lattice spacings are
computed by LAMMPS in the following way. A unit cell of the lattice
-is mapped into the simulation box (scaled, shifted, rotated), so that
-it now has (perhaps) a modified size and orientation. The lattice
-spacing in X is defined as the difference between the min/max extent
-of the x coordinates of the 8 corner points of the modified unit cell.
-Similarly, the Y and Z lattice spacings are defined as the difference
-in the min/max of the y and z coordinates.
+is mapped into the simulation box (scaled and rotated), so that it now
+has (perhaps) a modified size and orientation. The lattice spacing in
+X is defined as the difference between the min/max extent of the x
+coordinates of the 8 corner points of the modified unit cell (4 in
+2d). Similarly, the Y and Z lattice spacings are defined as the
+difference in the min/max of the y and z coordinates.
-Note that if the unit cell is orthogonal with axis-aligned edges (not
-rotated via the {orient} keyword), then the lattice spacings in each
+Note that if the unit cell is orthogonal with axis-aligned edges (no
+rotation via the {orient} keyword), then the lattice spacings in each
dimension are simply the scale factor (described above) multiplied by
the length of a1,a2,a3. Thus a {hex} style lattice with a scale
factor of 3.0 Angstroms, would have a lattice spacing of 3.0 in x and
3*sqrt(3.0) in y.
IMPORTANT NOTE: For non-orthogonal unit cells and/or when a rotation
-is applied via the {orient} keyword, then the lattice spacings may be
-less intuitive. In particular, in these cases, there is no guarantee
-that the lattice spacing is an integer multiple of the periodicity of
-the lattice in that direction. Thus, if you create an orthogonal
-periodic simulation box whose size in a dimension is a multiple of the
-lattice spacing, and then fill it with atoms via the
-"create_atoms"_create_atoms.html command, you will NOT necessarily
-create a periodic system. I.e. atoms may overlap incorrectly at the
-faces of the simulation box.
+is applied via the {orient} keyword, then the lattice spacings
+computed by LAMMPS are typically less intuitive. In particular, in
+these cases, there is no guarantee that a particular lattice spacing
+is an integer multiple of the periodicity of the lattice in that
+direction. Thus, if you create an orthogonal periodic simulation box
+whose size in a dimension is a multiple of the lattice spacing, and
+then fill it with atoms via the "create_atoms"_create_atoms.html
+command, you will NOT necessarily create a periodic system.
+I.e. atoms may overlap incorrectly at the faces of the simulation box.
-Regardless of these issues, the values of the lattice spacings LAMMPS
-calculates are printed out, so their effect in commands that use the
-spacings should be decipherable.
+The {spacing} option sets the 3 lattice spacings directly. All must
+be non-zero (use 1.0 for dz in a 2d simulation). The specified values
+are multiplied by the multiplicative factor described above that is
+associated with the scale factor. Thus a spacing of 1.0 means one
+unit cell edge length independent of the scale factor. As mentioned
+above, this option can be useful if the spacings LAMMPS computes are
+inconvenient to use in subsequent commands, which can be the case for
+non-orthogonal or rotated lattices.
+
+Note that whenever the lattice command is used, the values of the
+lattice spacings LAMMPS calculates are printed out. Thus their effect
+in commands that use the spacings should be decipherable.
:line