From ac60b08b699f5a1ce4644e12a602cd7d9710a54e Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Mon, 13 Nov 2006 22:18:34 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@150
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/Section_commands.html |  31 +++---
 doc/Section_commands.txt  |  17 ++-
 doc/create_atoms.html     |  62 +++++++----
 doc/create_atoms.txt      |  58 +++++++----
 doc/displace_atoms.html   |  10 +-
 doc/displace_atoms.txt    |  10 +-
 doc/fix_indent.html       |   9 +-
 doc/fix_indent.txt        |   9 +-
 doc/fix_recenter.html     |   9 +-
 doc/fix_recenter.txt      |   9 +-
 doc/lattice.html          | 210 ++++++++++++++++++++++++++++++++------
 doc/lattice.txt           | 207 +++++++++++++++++++++++++++++++------
 doc/temperature.html      |   5 +-
 doc/temperature.txt       |   5 +-
 14 files changed, 492 insertions(+), 159 deletions(-)

diff --git a/doc/Section_commands.html b/doc/Section_commands.html
index 2363187b76..2373c72016 100644
--- a/doc/Section_commands.html
+++ b/doc/Section_commands.html
@@ -161,10 +161,10 @@ or restart file via the <A HREF = "read_data.html">read_data</A> or
 <A HREF = "read_restart.html">read_restart</A> commands.  These files can contain
 molecular topology information.  Or create atoms on a lattice (with no
 molecular topology), using these commands: <A HREF = "lattice.html">lattice</A>,
-<A HREF = "orient.html">orient</A>, <A HREF = "origin.html">origin</A>, <A HREF = "region.html">region</A>,
-<A HREF = "create_box.html">create_box</A>, <A HREF = "create_atoms.html">create_atoms</A>.  The
-entire set of atoms can be duplicated to make a larger simulation
-using the <A HREF = "replicate.html">replicate</A> command.
+<A HREF = "region.html">region</A>, <A HREF = "create_box.html">create_box</A>,
+<A HREF = "create_atoms.html">create_atoms</A>.  The entire set of atoms can be
+duplicated to make a larger simulation using the
+<A HREF = "replicate.html">replicate</A> command.
 </P>
 <P>(3) Settings
 </P>
@@ -222,9 +222,9 @@ in the command's documentation.
 <P>Atom definition:
 </P>
 <P><A HREF = "create_atoms.html">create_atoms</A>, <A HREF = "create_box.html">create_box</A>,
-<A HREF = "lattice.html">lattice</A>, <A HREF = "orient.html">orient</A>, <A HREF = "origin.html">origin</A>,
-<A HREF = "read_data.html">read_data</A>, <A HREF = "read_restart.html">read_restart</A>,
-<A HREF = "region.html">region</A>, <A HREF = "replicate.html">replicate</A>
+<A HREF = "lattice.html">lattice</A>, <A HREF = "read_data.html">read_data</A>,
+<A HREF = "read_restart.html">read_restart</A>, <A HREF = "region.html">region</A>,
+<A HREF = "replicate.html">replicate</A>
 </P>
 <P>Force fields:
 </P>
@@ -293,13 +293,12 @@ in the command's documentation.
 <TR ALIGN="center"><TD ><A HREF = "dump.html">dump</A></TD><TD ><A HREF = "dump_modify.html">dump_modify</A></TD><TD ><A HREF = "echo.html">echo</A></TD><TD ><A HREF = "fix.html">fix</A></TD><TD ><A HREF = "fix_modify.html">fix_modify</A></TD><TD ><A HREF = "group.html">group</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "improper_coeff.html">improper_coeff</A></TD><TD ><A HREF = "improper_style.html">improper_style</A></TD><TD ><A HREF = "include.html">include</A></TD><TD ><A HREF = "jump.html">jump</A></TD><TD ><A HREF = "kspace_modify.html">kspace_modify</A></TD><TD ><A HREF = "kspace_style.html">kspace_style</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "label.html">label</A></TD><TD ><A HREF = "lattice.html">lattice</A></TD><TD ><A HREF = "log.html">log</A></TD><TD ><A HREF = "mass.html">mass</A></TD><TD ><A HREF = "minimize.html">minimize</A></TD><TD ><A HREF = "min_modify.html">min_modify</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "min_style.html">min_style</A></TD><TD ><A HREF = "neigh_modify.html">neigh_modify</A></TD><TD ><A HREF = "neighbor.html">neighbor</A></TD><TD ><A HREF = "newton.html">newton</A></TD><TD ><A HREF = "next.html">next</A></TD><TD ><A HREF = "orient.html">orient</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "origin.html">origin</A></TD><TD ><A HREF = "pair_coeff.html">pair_coeff</A></TD><TD ><A HREF = "pair_modify.html">pair_modify</A></TD><TD ><A HREF = "pair_style.html">pair_style</A></TD><TD ><A HREF = "pair_write.html">pair_write</A></TD><TD ><A HREF = "print.html">print</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "processors.html">processors</A></TD><TD ><A HREF = "read_data.html">read_data</A></TD><TD ><A HREF = "read_restart.html">read_restart</A></TD><TD ><A HREF = "region.html">region</A></TD><TD ><A HREF = "replicate.html">replicate</A></TD><TD ><A HREF = "reset_timestep.html">reset_timestep</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "restart.html">restart</A></TD><TD ><A HREF = "run.html">run</A></TD><TD ><A HREF = "run_style.html">run_style</A></TD><TD ><A HREF = "set.html">set</A></TD><TD ><A HREF = "shell.html">shell</A></TD><TD ><A HREF = "special_bonds.html">special_bonds</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "temp_modify.html">temp_modify</A></TD><TD ><A HREF = "temper.html">temper</A></TD><TD ><A HREF = "temperature.html">temperature</A></TD><TD ><A HREF = "thermo.html">thermo</A></TD><TD ><A HREF = "thermo_modify.html">thermo_modify</A></TD><TD ><A HREF = "thermo_style.html">thermo_style</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "timestep.html">timestep</A></TD><TD ><A HREF = "undump.html">undump</A></TD><TD ><A HREF = "unfix.html">unfix</A></TD><TD ><A HREF = "units.html">units</A></TD><TD ><A HREF = "variable.html">variable</A></TD><TD ><A HREF = "velocity.html">velocity</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "write_restart.html">write_restart</A> 
+<TR ALIGN="center"><TD ><A HREF = "min_style.html">min_style</A></TD><TD ><A HREF = "neigh_modify.html">neigh_modify</A></TD><TD ><A HREF = "neighbor.html">neighbor</A></TD><TD ><A HREF = "newton.html">newton</A></TD><TD ><A HREF = "next.html">next</A></TD><TD ><A HREF = "pair_coeff.html">pair_coeff</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "pair_modify.html">pair_modify</A></TD><TD ><A HREF = "pair_style.html">pair_style</A></TD><TD ><A HREF = "pair_write.html">pair_write</A></TD><TD ><A HREF = "print.html">print</A></TD><TD ><A HREF = "processors.html">processors</A></TD><TD ><A HREF = "read_data.html">read_data</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "read_restart.html">read_restart</A></TD><TD ><A HREF = "region.html">region</A></TD><TD ><A HREF = "replicate.html">replicate</A></TD><TD ><A HREF = "reset_timestep.html">reset_timestep</A></TD><TD ><A HREF = "restart.html">restart</A></TD><TD ><A HREF = "run.html">run</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "run_style.html">run_style</A></TD><TD ><A HREF = "set.html">set</A></TD><TD ><A HREF = "shell.html">shell</A></TD><TD ><A HREF = "special_bonds.html">special_bonds</A></TD><TD ><A HREF = "temp_modify.html">temp_modify</A></TD><TD ><A HREF = "temper.html">temper</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "temperature.html">temperature</A></TD><TD ><A HREF = "thermo.html">thermo</A></TD><TD ><A HREF = "thermo_modify.html">thermo_modify</A></TD><TD ><A HREF = "thermo_style.html">thermo_style</A></TD><TD ><A HREF = "timestep.html">timestep</A></TD><TD ><A HREF = "undump.html">undump</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "unfix.html">unfix</A></TD><TD ><A HREF = "units.html">units</A></TD><TD ><A HREF = "variable.html">variable</A></TD><TD ><A HREF = "velocity.html">velocity</A></TD><TD ><A HREF = "write_restart.html">write_restart</A> 
 </TD></TR></TABLE></DIV>
 
 <P>Fix styles.  See the <A HREF = "fix.html">fix</A> command for one-line descriptions
@@ -312,8 +311,8 @@ or click on the command itself for a full description:
 <TR ALIGN="center"><TD ><A HREF = "fix_nve.html">fix nve</A></TD><TD ><A HREF = "fix_nve_gran.html">fix nve/gran</A></TD><TD ><A HREF = "fix_nvt.html">fix nvt</A></TD><TD ><A HREF = "fix_orient_fcc.html">fix orient/fcc</A></TD><TD ><A HREF = "fix_planeforce.html">fix planeforce</A></TD><TD ><A HREF = "fix_poems.html">fix poems</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "fix_print.html">fix print</A></TD><TD ><A HREF = "fix_rdf.html">fix rdf</A></TD><TD ><A HREF = "fix_recenter.html">fix recenter</A></TD><TD ><A HREF = "fix_rigid.html">fix rigid</A></TD><TD ><A HREF = "fix_setforce.html">fix setforce</A></TD><TD ><A HREF = "fix_shake.html">fix shake</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "fix_spring.html">fix spring</A></TD><TD ><A HREF = "fix_spring_rg.html">fix spring/rg</A></TD><TD ><A HREF = "fix_spring_self.html">fix spring/self</A></TD><TD ><A HREF = "fix_temp_rescale.html">fix temp/rescale</A></TD><TD ><A HREF = "fix_tmd.html">fix tmd</A></TD><TD ><A HREF = "fix_uniaxial.html">fix uniaxial</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_vcm.html">fix vcm</A></TD><TD ><A HREF = "fix_viscous.html">fix viscous</A></TD><TD ><A HREF = "fix_volume_rescale.html">fix volume/rescale</A></TD><TD ><A HREF = "fix_wall_gran.html">fix wall/gran</A></TD><TD ><A HREF = "fix_wall_lj93.html">fix wall/lj93</A></TD><TD ><A HREF = "fix_wall_reflect.html">fix wall/reflect</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_wiggle.html">fix wiggle</A> 
+<TR ALIGN="center"><TD ><A HREF = "fix_vcm.html">fix vcm</A></TD><TD ><A HREF = "fix_viscous.html">fix viscous</A></TD><TD ><A HREF = "fix_volume_rescale.html">fix volume/rescale</A></TD><TD ><A HREF = "fix_wall_gran.html">fix wall/gran</A></TD><TD ><A HREF = "fix_wall_lj93.html">fix wall/lj93</A></TD><TD ><A HREF = "fix_wall_lj126.html">fix wall/lj126</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_wall_reflect.html">fix wall/reflect</A></TD><TD ><A HREF = "fix_wiggle.html">fix wiggle</A> 
 </TD></TR></TABLE></DIV>
 
 <P>Pair styles.  See the <A HREF = "pair_style.html">pair_style</A> command for an
diff --git a/doc/Section_commands.txt b/doc/Section_commands.txt
index e8c11a56fa..8716ce1191 100644
--- a/doc/Section_commands.txt
+++ b/doc/Section_commands.txt
@@ -158,10 +158,10 @@ or restart file via the "read_data"_read_data.html or
 "read_restart"_read_restart.html commands.  These files can contain
 molecular topology information.  Or create atoms on a lattice (with no
 molecular topology), using these commands: "lattice"_lattice.html,
-"orient"_orient.html, "origin"_origin.html, "region"_region.html,
-"create_box"_create_box.html, "create_atoms"_create_atoms.html.  The
-entire set of atoms can be duplicated to make a larger simulation
-using the "replicate"_replicate.html command.
+"region"_region.html, "create_box"_create_box.html,
+"create_atoms"_create_atoms.html.  The entire set of atoms can be
+duplicated to make a larger simulation using the
+"replicate"_replicate.html command.
 
 (3) Settings
 
@@ -219,9 +219,9 @@ Initialization:
 Atom definition:
 
 "create_atoms"_create_atoms.html, "create_box"_create_box.html,
-"lattice"_lattice.html, "orient"_orient.html, "origin"_origin.html,
-"read_data"_read_data.html, "read_restart"_read_restart.html,
-"region"_region.html, "replicate"_replicate.html
+"lattice"_lattice.html, "read_data"_read_data.html,
+"read_restart"_read_restart.html, "region"_region.html,
+"replicate"_replicate.html
 
 Force fields:
 
@@ -324,8 +324,6 @@ in the command's documentation.
 "neighbor"_neighbor.html,
 "newton"_newton.html,
 "next"_next.html,
-"orient"_orient.html,
-"origin"_origin.html,
 "pair_coeff"_pair_coeff.html,
 "pair_modify"_pair_modify.html,
 "pair_style"_pair_style.html,
@@ -401,6 +399,7 @@ or click on the command itself for a full description:
 "fix volume/rescale"_fix_volume_rescale.html,
 "fix wall/gran"_fix_wall_gran.html,
 "fix wall/lj93"_fix_wall_lj93.html,
+"fix wall/lj126"_fix_wall_lj126.html,
 "fix wall/reflect"_fix_wall_reflect.html,
 "fix wiggle"_fix_wiggle.html :tb(c=6,ea=c)
 
diff --git a/doc/create_atoms.html b/doc/create_atoms.html
index 88ca3daff8..8bf4df020b 100644
--- a/doc/create_atoms.html
+++ b/doc/create_atoms.html
@@ -13,41 +13,62 @@
 </H3>
 <P><B>Syntax:</B>
 </P>
-<PRE>create_atoms type region-ID 
+<PRE>create_atoms type keyword values ... 
 </PRE>
-<UL><LI>type = atom type (1-N) of atoms to create on a lattice
-<LI>region-ID = ID of region each atom will belong to (optional) 
+<UL><LI>type = atom type (1-N) of atoms to create on a lattice 
+
+<LI>zero or more keyword/value pairs may be appended 
+
+<LI>keyword = <I>region</I> or <I>basis</I> 
+
+<PRE>  <I>region</I> value = region-ID
+    region-ID = atoms will only be created if contained in the region
+  <I>basis</I> values = M itype
+    M = which basis atom
+    itype = atom type (1-N) to assign to the basis atom 
+</PRE>
+
 </UL>
 <P><B>Examples:</B>
 </P>
-<PRE>create_atoms 1 regsphere
-create_atoms 3 
+<PRE>create_atoms 1
+create_atoms 3 region regsphere
+create_atoms 1 basis 2 5 
 </PRE>
 <P><B>Description:</B>
 </P>
 <P>This command creates atoms on a lattice as an alternative to reading
 in their coordinates via a <A HREF = "read_data.html">read_data</A> or
 <A HREF = "read_restart.html">read_restart</A> command.  A simulation box must
-already exist, which is created with the <A HREF = "create_box.html">create_box</A>
-command.
+already exist, which is typically created via the
+<A HREF = "create_box.html">create_box</A> command.
 </P>
 <P>Before using this command, a lattice must be defined using the
 <A HREF = "lattice.html">lattice</A> command.  If a region is not specified, the
 create_atoms command fills the entire simulation box with atoms on the
-lattice.  If a region is specified, then the geometric volume is
-filled that is inside the simulation box and is also consistent with
-the region volume.
+lattice.  If a region is specified (see the <A HREF = "region.html">region</A>
+command), then the geometric volume is filled that is inside the
+simulation box and is also consistent with the region volume.  Note
+that a region can be specified so that its "volume" is either inside
+or outside a geometric boundary.
 </P>
-<P>The <I>create_atoms</I> command can be used multiple times with different
-lattice orientations to create grain boundaries.  Used in conjunction
-with the <A HREF = "delete_atoms.html">delete_atoms</A> command, reasonably complex
-geometries can be created.  The <I>create_atoms</I> command can also be
-used to add atoms to a system previously read in from a data or
-restart file.  In all these cases, care should be taken to insure that
-new atoms do not overlap existing atoms inappropriately.
+<P>The <A HREF = "lattice.html">lattice</A> command specifies one or more basis atoms
+in each unit cell.  By default, when created, all basis atoms are
+assigned the argument <I>type</I> as their atom type.  The keyword <I>basis</I>
+can be used to override the default for one or more basis atoms and
+assign them a different atom type.
 </P>
-<P>Created atoms are assigned the specified atom type and a velocity of
-0.0.
+<P>By using the create_atoms command multiple times (interleaved with
+<A HREF = "lattice.html">lattice</A> commands specifying different orientations),
+grain boundaries can be created.  Using the create_atoms command in
+conjunction with the <A HREF = "delete_atoms.html">delete_atoms</A> command,
+reasonably complex geometries can be created.  The create_atoms
+command can also be used to add atoms to a system previously read in
+from a data or restart file.  In all these cases, care should be taken
+to insure that new atoms do not overlap existing atoms
+inappropriately.
+</P>
+<P>Created atoms are assigned a velocity of 0.0.
 </P>
 <P><B>Restrictions:</B>
 </P>
@@ -56,8 +77,7 @@ previously defined to use this command.
 </P>
 <P><B>Related commands:</B>
 </P>
-<P><A HREF = "lattice.html">lattice</A>, <A HREF = "orient.html">orient</A>, <A HREF = "origin.html">origin</A>,
-<A HREF = "region.html">region</A>, <A HREF = "create_box.html">create_box</A>,
+<P><A HREF = "lattice.html">lattice</A>, <A HREF = "region.html">region</A>, <A HREF = "create_box.html">create_box</A>,
 <A HREF = "read_data.html">read_data</A>, <A HREF = "read_restart.html">read_restart</A>
 </P>
 <P><B>Default:</B> none
diff --git a/doc/create_atoms.txt b/doc/create_atoms.txt
index 541857730c..520529199f 100644
--- a/doc/create_atoms.txt
+++ b/doc/create_atoms.txt
@@ -10,41 +10,58 @@ create_atoms command :h3
 
 [Syntax:]
 
-create_atoms type region-ID :pre
+create_atoms type keyword values ... :pre
 
-type = atom type (1-N) of atoms to create on a lattice
-region-ID = ID of region each atom will belong to (optional) :ul
+type = atom type (1-N) of atoms to create on a lattice :ulb,l
+zero or more keyword/value pairs may be appended :l
+keyword = {region} or {basis} :l
+  {region} value = region-ID
+    region-ID = atoms will only be created if contained in the region
+  {basis} values = M itype
+    M = which basis atom
+    itype = atom type (1-N) to assign to the basis atom :pre
+:ule
 
 [Examples:]
 
-create_atoms 1 regsphere
-create_atoms 3 :pre
+create_atoms 1
+create_atoms 3 region regsphere
+create_atoms 1 basis 2 5 :pre
 
 [Description:]
 
 This command creates atoms on a lattice as an alternative to reading
 in their coordinates via a "read_data"_read_data.html or
 "read_restart"_read_restart.html command.  A simulation box must
-already exist, which is created with the "create_box"_create_box.html
-command.
+already exist, which is typically created via the
+"create_box"_create_box.html command.
 
 Before using this command, a lattice must be defined using the
 "lattice"_lattice.html command.  If a region is not specified, the
 create_atoms command fills the entire simulation box with atoms on the
-lattice.  If a region is specified, then the geometric volume is
-filled that is inside the simulation box and is also consistent with
-the region volume.
+lattice.  If a region is specified (see the "region"_region.html
+command), then the geometric volume is filled that is inside the
+simulation box and is also consistent with the region volume.  Note
+that a region can be specified so that its "volume" is either inside
+or outside a geometric boundary.
 
-The {create_atoms} command can be used multiple times with different
-lattice orientations to create grain boundaries.  Used in conjunction
-with the "delete_atoms"_delete_atoms.html command, reasonably complex
-geometries can be created.  The {create_atoms} command can also be
-used to add atoms to a system previously read in from a data or
-restart file.  In all these cases, care should be taken to insure that
-new atoms do not overlap existing atoms inappropriately.
+The "lattice"_lattice.html command specifies one or more basis atoms
+in each unit cell.  By default, when created, all basis atoms are
+assigned the argument {type} as their atom type.  The keyword {basis}
+can be used to override the default for one or more basis atoms and
+assign them a different atom type.
 
-Created atoms are assigned the specified atom type and a velocity of
-0.0.
+By using the create_atoms command multiple times (interleaved with
+"lattice"_lattice.html commands specifying different orientations),
+grain boundaries can be created.  Using the create_atoms command in
+conjunction with the "delete_atoms"_delete_atoms.html command,
+reasonably complex geometries can be created.  The create_atoms
+command can also be used to add atoms to a system previously read in
+from a data or restart file.  In all these cases, care should be taken
+to insure that new atoms do not overlap existing atoms
+inappropriately.
+
+Created atoms are assigned a velocity of 0.0.
 
 [Restrictions:]
 
@@ -53,8 +70,7 @@ previously defined to use this command.
 
 [Related commands:]
 
-"lattice"_lattice.html, "orient"_orient.html, "origin"_origin.html,
-"region"_region.html, "create_box"_create_box.html,
+"lattice"_lattice.html, "region"_region.html, "create_box"_create_box.html,
 "read_data"_read_data.html, "read_restart"_read_restart.html
 
 [Default:] none
diff --git a/doc/displace_atoms.html b/doc/displace_atoms.html
index d9c98529fa..cc04a354c7 100644
--- a/doc/displace_atoms.html
+++ b/doc/displace_atoms.html
@@ -58,9 +58,9 @@ those bounds will be moved the minimum (0.0) or maximum (5.0) amount.
 <P>Distance units for the displacement are determined by the setting of
 <I>box</I> or <I>lattice</I> for the <I>units</I> keyword.  <I>Box</I> means distance
 units as defined by the <A HREF = "units.html">units</A> command - e.g. Angstroms
-for <I>real</I> units.  <I>Lattice</I> means to use lattice spacings as defined
-by the <A HREF = "lattice.html">lattice</A> command.  The default is to use lattice
-units.
+for <I>real</I> units.  <I>Lattice</I> means distance units are in lattice
+spacings.  The <A HREF = "lattice.html">lattice</A> command must have been
+previously used to define the lattice spacing.
 </P>
 <P>Care should be taken not to move atoms on top of other atoms.  After
 the move, atoms are remapped to the periodic simulation box.  In
@@ -76,7 +76,9 @@ once they have been displaced.  This means that your system must be
 ready to perform a simulation before using this command (force fields
 setup, atom masses set, etc).
 </P>
-<P><B>Related commands:</B> none
+<P><B>Related commands:</B>
+</P>
+<P><A HREF = "lattice.html">lattice</A>
 </P>
 <P><B>Default:</B>
 </P>
diff --git a/doc/displace_atoms.txt b/doc/displace_atoms.txt
index 820949c022..ad12477dff 100644
--- a/doc/displace_atoms.txt
+++ b/doc/displace_atoms.txt
@@ -50,9 +50,9 @@ those bounds will be moved the minimum (0.0) or maximum (5.0) amount.
 Distance units for the displacement are determined by the setting of
 {box} or {lattice} for the {units} keyword.  {Box} means distance
 units as defined by the "units"_units.html command - e.g. Angstroms
-for {real} units.  {Lattice} means to use lattice spacings as defined
-by the "lattice"_lattice.html command.  The default is to use lattice
-units.
+for {real} units.  {Lattice} means distance units are in lattice
+spacings.  The "lattice"_lattice.html command must have been
+previously used to define the lattice spacing.
 
 Care should be taken not to move atoms on top of other atoms.  After
 the move, atoms are remapped to the periodic simulation box.  In
@@ -68,7 +68,9 @@ once they have been displaced.  This means that your system must be
 ready to perform a simulation before using this command (force fields
 setup, atom masses set, etc).
 
-[Related commands:] none
+[Related commands:]
+
+"lattice"_lattice.html
 
 [Default:]
 
diff --git a/doc/fix_indent.html b/doc/fix_indent.html
index 05f6fe1975..752cfab63c 100644
--- a/doc/fix_indent.html
+++ b/doc/fix_indent.html
@@ -94,10 +94,11 @@ each run.
 to define the indenter.  A <I>box</I> value selects standard distance units
 as defined by the <A HREF = "units.html">units</A> command, e.g. Angstroms for units
 = real or metal.  A <I>lattice</I> value means the distance units are in
-cubic lattice spacings.  The <A HREF = "lattice.html">lattice</A> command must first
-be used to define a lattice.  Note that the units choice affects not
-only the indenter's physical geometry, but also its velocity and force
-constant since they are defined in terms of distance as well.
+lattice spacings.  The <A HREF = "lattice.html">lattice</A> command must have been
+previously used to define the lattice spacing.  Note that the units
+choice affects not only the indenter's physical geometry, but also its
+velocity and force constant since they are defined in terms of
+distance as well.
 </P>
 <P>This fix supports the <A HREF = "fix_modify.html">fix_modify</A> options for
 <I>thermo</I> and <I>energy</I>.  The former will print the contribution the fix
diff --git a/doc/fix_indent.txt b/doc/fix_indent.txt
index 51b9d3b644..b272ec4eee 100644
--- a/doc/fix_indent.txt
+++ b/doc/fix_indent.txt
@@ -85,10 +85,11 @@ The {units} keyword determines the meaning of the distance units used
 to define the indenter.  A {box} value selects standard distance units
 as defined by the "units"_units.html command, e.g. Angstroms for units
 = real or metal.  A {lattice} value means the distance units are in
-cubic lattice spacings.  The "lattice"_lattice.html command must first
-be used to define a lattice.  Note that the units choice affects not
-only the indenter's physical geometry, but also its velocity and force
-constant since they are defined in terms of distance as well.
+lattice spacings.  The "lattice"_lattice.html command must have been
+previously used to define the lattice spacing.  Note that the units
+choice affects not only the indenter's physical geometry, but also its
+velocity and force constant since they are defined in terms of
+distance as well.
 
 This fix supports the "fix_modify"_fix_modify.html options for
 {thermo} and {energy}.  The former will print the contribution the fix
diff --git a/doc/fix_recenter.html b/doc/fix_recenter.html
index ea346fc23f..6e4f4ebd97 100644
--- a/doc/fix_recenter.html
+++ b/doc/fix_recenter.html
@@ -65,10 +65,11 @@ could be shifted.
 </P>
 <P>If the <I>units</I> keyword is set to <I>box</I>, then the distance units of
 x,y,z are defined by the <A HREF = "units.html">units</A> command - e.g. Angstroms
-for <I>real</I> units.  <I>Lattice</I> means to use lattice spacings as defined
-by the <A HREF = "lattice.html">lattice</A> command.  <I>Fraction</I> means a fractional
-distance between the lo/hi box boundaries, e.g. 0.5 = middle of the
-box.  The default is to use lattice units.
+for <I>real</I> units.  A <I>lattice</I> value means the distance units are in
+lattice spacings.  The <A HREF = "lattice.html">lattice</A> command must have been
+previously used to define the lattice spacing.  A <I>fraction</I> value
+means a fractional distance between the lo/hi box boundaries, e.g. 0.5
+= middle of the box.  The default is to use lattice units.
 </P>
 <P>Note that the <A HREF = "velocity.html">velocity</A> command can be used to create
 velocities with zero aggregate linear and/or angular momentum.
diff --git a/doc/fix_recenter.txt b/doc/fix_recenter.txt
index 5f3306c72c..8aa0e52654 100644
--- a/doc/fix_recenter.txt
+++ b/doc/fix_recenter.txt
@@ -57,10 +57,11 @@ could be shifted.
 
 If the {units} keyword is set to {box}, then the distance units of
 x,y,z are defined by the "units"_units.html command - e.g. Angstroms
-for {real} units.  {Lattice} means to use lattice spacings as defined
-by the "lattice"_lattice.html command.  {Fraction} means a fractional
-distance between the lo/hi box boundaries, e.g. 0.5 = middle of the
-box.  The default is to use lattice units.
+for {real} units.  A {lattice} value means the distance units are in
+lattice spacings.  The "lattice"_lattice.html command must have been
+previously used to define the lattice spacing.  A {fraction} value
+means a fractional distance between the lo/hi box boundaries, e.g. 0.5
+= middle of the box.  The default is to use lattice units.
 
 Note that the "velocity"_velocity.html command can be used to create
 velocities with zero aggregate linear and/or angular momentum.
diff --git a/doc/lattice.html b/doc/lattice.html
index a3428f01d3..806b22d01f 100644
--- a/doc/lattice.html
+++ b/doc/lattice.html
@@ -13,14 +13,31 @@
 </H3>
 <P><B>Syntax:</B>
 </P>
-<PRE>lattice style value 
+<PRE>lattice style scale keyword values ... 
 </PRE>
-<UL><LI>style = <I>none</I> or <I>sc</I> or <I>bcc</I> or <I>fcc</I> or <I>sq</I> or <I>sq2</I> or <I>hex</I> or <I>diamond</I> 
+<UL><LI>style = <I>none</I> or <I>sc</I> or <I>bcc</I> or <I>fcc</I> or <I>diamond</I> or         <I>sq</I> or <I>sq2</I> or <I>hex</I> or <I>user</I> 
 
-<PRE>  <I>none</I> value = none
+<LI>scale = scale factor between lattice and simulation box 
+
+<PRE>  for style <I>none</I>:
+    scale is not specified (nor any optional args)
   for all other styles:
-    value = reduced density (for LJ units)
-    value = cubic lattice constant in Angstroms (for real or metal units) 
+    scale = reduced density rho* (for LJ units)
+    scale = lattice constant in Angstroms (for real or metal units) 
+</PRE>
+<LI>zero or more keyword/value pairs may be appended 
+
+<LI>keyword = <I>origin</I> or <I>orient</I> or <I>a1</I> or <I>a2</I> or <I>a3</I> or <I>basis</I> 
+
+<PRE>  <I>origin</I> values = x y z
+    x,y,z = fractions of a unit cell (0 <= x,y,z < 1)
+  <I>orient</I> values = dim i j k
+    dim = <I>x</I> or <I>y</I> or <I>z</I>
+    i,j,k = integer lattice directions
+  <I>a1</I>,<I>a2</I>,<I>a3</I> values = x y z
+    x,y,z = primitive vector components that define unit cell
+  <I>basis</I> values = x y z
+    x,y,z = fractional coords of a basis atom (0 <= x,y,z < 1) 
 </PRE>
 
 </UL>
@@ -28,47 +45,176 @@
 </P>
 <PRE>lattice fcc 3.52
 lattice hex 0.85
+lattice sq 0.8 origin 0.0 0.5 0.0 orient x 1 1 0 orient y -1 1 0
+lattice user 3.52 a1 1.0 0.0 0.0 a2 0.5 1.0 0.0 a3 0.0 0.0 0.5 &
+                  basis 0.0 0.0 0.0 basis 0.5 0.5 0.5
 lattice none 
 </PRE>
 <P><B>Description:</B>
 </P>
-<P>Define a lattice type and lattice constant.  This is required before
-using a commands that (optionally) use the lattice, such as
-<A HREF = "create_atoms.html">create_atoms</A> or <A HREF = "region.html">region</A>.  The lattice
-type must be consistent with the dimension of the simulation - see the
-<A HREF = "dimension.html">dimension</A> command.  Styles <I>sc</I> or <I>bcc</I> or <I>fcc</I> or
-<I>diamond</I> are for 3d problems.  Styles <I>sq</I> or <I>sq2</I> or <I>hex</I> are for
-2d problems.  Lattices of style <I>fcc</I>, <I>bcc</I>, <I>hex</I>, or <I>diamond</I> are
-described in any solid-state physics text.  A <I>sc</I> lattice is simple
-cubic, with atoms at the corners of a cube.  A <I>sq</I> lattice is square
-with atoms at the corners of a square.  A <I>sq2</I> lattice is a <I>sq</I>
-lattice with an additional atom at the center of the square.
+<P>Define a lattice for use by other commands.  In LAMMPS, a lattice is
+simply a set of points in space, determined by a unit cell with basis
+atoms, that is replicated infinitely in all dimensions.  The arguments
+of the lattice command can be used to define a wide variety of
+crystallographic lattices.
 </P>
-<P>For unit style <I>real</I> or <I>metal</I>, the specified value is the cubic
-lattice constant in Angstroms.  For unit style <I>lj</I>, the value is the
-reduced density (rho*) which LAMMPS converts into a cubic lattice
-constant.  For 3d problems, the relationship "rho* = rho sigma^3" is
-used for the conversion, where rho = N/V with V = the volume of the
-cubic cell and N = 4 for <I>fcc</I>, 2 for <I>bcc</I>, 1 for <I>sc</I>, and 8 for
-<I>diamond</I> lattices.  For 2d problems, the relationship "rho* = rho
-sigma^2" is used for the conversion, where N = 2 for <I>sq2</I> or <I>hex</I>
-and 1 for <I>sq</I>.  In the hex case, the unit cell is actually
-rectangular; it is extended by a factor of sqrt(3) in the y-dimension.
+<P>A lattice is used by LAMMPS in two ways.  First, the
+<A HREF = "create_atoms.hmtl">create_atoms</A> command creates atoms on the lattice
+points inside the simulation box.  Note that the
+<A HREF = "create_atoms.html">create_atoms</A> command allows different atom types
+to be assigned to different basis atoms of the lattice.  Second, the
+lattice spacing in the x,y,z dimensions implied by the lattice, can be
+used by other commands as distance units (e.g. <A HREF = "region.html">region</A>
+and <A HREF = "velocity.html">velocity</A>), which are often convenient when the
+underlying problem geometry is atoms on a lattice.
 </P>
-<P>The command "lattice none" can be used to turn off the lattice
-setting.  Any command that attempts to use a lattice constant will
-then generate an error.
+<P>The lattice style must be consistent with the dimension of the
+simulation - see the <A HREF = "dimension.html">dimension</A> command.  Styles <I>sc</I>
+or <I>bcc</I> or <I>fcc</I> or <I>diamond</I> are for 3d problems.  Styles <I>sq</I> or
+<I>sq2</I> or <I>hex</I> are for 2d problems.  Style <I>user</I> can be used for
+either 2d or 3d problems.
 </P>
-<P><B>Restrictions:</B> none
+<P>A lattice consists of a unit cell, a set of basis atoms within that
+cell, and a set of transformation parameters (scale, origin, orient)
+that map the unit cell into the simulation box.  The vectors a1,a2,a3
+are the edge vectors of the unit cell.  This is the nomenclature for
+"primitive" vectors in solid-state crytallography, but in LAMMPS the
+unit cell they determine does not have to be a "primitive cell" of
+minimum volume.
+</P>
+<HR>
+
+<P>Lattices of style <I>sc</I>, <I>fcc</I>, <I>bcc</I>, and <I>diamond</I> are 3d lattices
+that define a cubic unit cell with edge length = 1.0.  This means a1 =
+1.0 0.0 0.0, a2 = 0.0 1.0 0.0, and a3 = 0.0 0.0 1.0.  The placement of
+the basis atoms within the unit cell are described in any solid-state
+physics text.  A <I>sc</I> lattice has 1 basis atom at the
+lower-left-bottom corner of the cube.  A <I>bcc</I> lattice has 2 basis
+atoms, one at the corner and one at the center of the cube.  A <I>fcc</I>
+lattice has 4 basis atoms, one at the corner and 3 at the cube face
+centers.  A <I>diamond</I> lattice has 8 basis atoms.
+</P>
+<P>Lattices of style <I>sq</I> and <I>sq2</I> are 2d lattices that define a square
+unit cell with edge length = 1.0.  This means a1 = 1.0 0.0 0.0 and a2
+= 0.0 1.0 0.0.  A <I>sq</I> lattice has 1 basis atom at the lower-left
+corner of the square.  A <I>sq2</I> lattice has 2 basis atoms, one at the
+corner and one at the center of the square.  A <I>hex</I> style is also a
+2d lattice, but the unit cell is rectangular, with a1 = 1.0 0.0 0.0
+and a2 = 0.0 sqrt(3.0) 0.0.  It has 2 basis atoms, one at the corner
+and one at the center of the rectangle.
+</P>
+<P>A lattice of style <I>user</I> allows you to specify a1, a2, a3, and a list
+of basis atoms to put in the unit cell.  By default, a1,a2,a3 are 3
+orthogonal unit vectors (edges of a unit cube).  But you can specify
+them to be of any length and non-orthogonal to each other, so that
+they describe a tilted parallelepiped.  Via the <I>basis</I> keyword you
+add atoms, one at a time, to the unit cell.  Its arguments are
+fractional coordinates (0.0 <= x,y,z < 1.0), so that a value of 0.5
+means a position half-way across the unit cell in that dimension.
+</P>
+<HR>
+
+<P>This sub-section discusses the arguments that determine how the
+idealized unit cell is transformed into a lattice of points within the
+simulation box with desired spacings.
+</P>
+<P>The <I>scale</I> argument determines how the size of the unit cell will be
+scaled when mapping it into the simulation box.  I.e. it determines a
+multiplicative factor to apply to the unit cell, to convert it to a
+lattice of the desired size and distance units in the simulation box.
+The meaning of the <I>scale</I> argument depends on the <A HREF = "unit.html">units</A>
+being used in your simulation.
+</P>
+<P>For unit style <I>real</I> or <I>metal</I>, the scale argument is in Angstroms.
+For example, if the unit cell is a unit cube with edge length 1.0,
+setting scale = 3.52 would create a cubic lattice with a spacing of
+3.52 Angstroms.
+</P>
+<P>For unit style <I>lj</I>, the scale argument is the Lennard-Jones reduced
+density, typically written as rho*.  LAMMPS converts this value into
+the multiplicative factor via the formula "factor^dim = rho/rho*",
+where rho = N/V with V = the volume of the lattice unit cell and N =
+the number of basis atoms in the unit cell (described below), and dim
+= 2 or 3 for the dimensionality of the simulation.  Effectively, this
+means that if LJ particles of size sigma = 1.0 are used in the
+simulation, the lattice of particles will be at the desired reduced
+density.
+</P>
+<P>The <I>origin</I> option specifies how the unit cell will be shifted or
+translated when mapping it into the simulation box.  The x,y,z values
+are fractional values (0.0 <= x,y,z < 1.0) meaning shift the lattice
+by a fraction of the lattice spacing in each dimension.  The meaning
+of "lattice spacing" is discussed below.
+</P>
+<P>The <I>orient</I> option specifies how the unit cell will be rotated when
+mapping it into the simulation box.  The <I>dim</I> argument is one of the
+3 coordinate axes in the simulation box.  The other 3 arguments are
+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
+orthogonal and obey the right-hand rule, i.e. (X cross Y) points in
+the Z direction.
+</P>
+<HR>
+
+<P>Several LAMMPS commands have the option to use distance units that are
+inferred from "lattice spacings" in the x,y,z directions.  E.g. the
+<A HREF = "region.html">region</A> command can create a block of size 10x20x20,
+where 10 means 10 lattice spacings in the x direction.
+</P>
+<P>These 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 shape 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 min/max of the y and z coordinates.
+</P>
+<P>Note that if the unit cell has axis-aligned edges (a1,a2,a3) and is
+not rotated (via the <I>orient</I> keyword), then the lattice spacings in
+each dimension are simply the scale factor (descibed above) multiplied
+by the length of a1,a2,a3.  Thus a <I>hex</I> 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.
+</P>
+<P>For unit cells with a more general shape or when a rotation is
+applied, the lattice spacing is less intuitive.  But regardless, the
+values of the computed lattice spacings are printed by LAMMPS, so
+their effect in commands that use the spacings should be decipherable.
+</P>
+<HR>
+
+<P>The command "lattice none" can be used to turn off a previous lattice
+definition.  Any command that attempts to use the lattice directly
+(<A HREF = "create_atoms.html">create_atoms</A>) or associated lattice spacings will
+then generate an error.  No additional arguments need be used with
+"lattice none".
+</P>
+<HR>
+
+<P><B>Restrictions:</B>
+</P>
+<P>The <I>a1,a2,a3,basis</I> keywords can only be used with style <I>user</I>.
+</P>
+<P>For lattices oriented at an angle or with a non-orthognal unit cell,
+care must be taken when using the <A HREF = "region.html">region</A> and
+<A HREF = "create_atoms.html">create_atoms</A> commands to create a periodic system.
+If the box size is not chosen appropriately, the system may not
+actually be periodic, and atoms may overlap incorretly at the faces of
+the simulation box.
 </P>
 <P><B>Related commands:</B>
 </P>
-<P><A HREF = "dimension.html">dimension</A>, <A HREF = "orient.html">orient</A>,
-<A HREF = "origin.html">origin</A>, <A HREF = "create_atoms.html">create_atoms</A>,
+<P><A HREF = "dimension.html">dimension</A>, <A HREF = "create_atoms.html">create_atoms</A>,
 <A HREF = "region.html">region</A>
 </P>
 <P><B>Default:</B>
 </P>
 <PRE>lattice none 
 </PRE>
+<P>For other lattice styles, the option defaults are origin = 0.0 0.0
+0.0, orient = x 1 0 0, orient = y 0 1 0, orient = z 0 0 1, a1 = 1.0
+0.0 0.0, a2 = 0.0 1.0 0.0, and a3 = 0.0 0.0 1.0.
+</P>
 </HTML>
diff --git a/doc/lattice.txt b/doc/lattice.txt
index 3664927a8b..a707777679 100644
--- a/doc/lattice.txt
+++ b/doc/lattice.txt
@@ -10,58 +10,201 @@ lattice command :h3
 
 [Syntax:]
 
-lattice style value :pre
+lattice style scale keyword values ... :pre
 
-style = {none} or {sc} or {bcc} or {fcc} or {sq} or {sq2} or {hex} or {diamond} :ulb,l
-  {none} value = none
+style = {none} or {sc} or {bcc} or {fcc} or {diamond} or \
+        {sq} or {sq2} or {hex} or {user} :ulb,l
+scale = scale factor between lattice and simulation box :l
+  for style {none}:
+    scale is not specified (nor any optional args)
   for all other styles:
-    value = reduced density (for LJ units)
-    value = cubic lattice constant in Angstroms (for real or metal units) :pre
+    scale = reduced density rho* (for LJ units)
+    scale = lattice constant in Angstroms (for real or metal units) :pre
+zero or more keyword/value pairs may be appended :l
+keyword = {origin} or {orient} or {a1} or {a2} or {a3} or {basis} :l
+  {origin} values = x y z
+    x,y,z = fractions of a unit cell (0 <= x,y,z < 1)
+  {orient} values = dim i j k
+    dim = {x} or {y} or {z}
+    i,j,k = integer lattice directions
+  {a1},{a2},{a3} values = x y z
+    x,y,z = primitive vector components that define unit cell
+  {basis} values = x y z
+    x,y,z = fractional coords of a basis atom (0 <= x,y,z < 1) :pre
 :ule
 
 [Examples:]
 
 lattice fcc 3.52
 lattice hex 0.85
+lattice sq 0.8 origin 0.0 0.5 0.0 orient x 1 1 0 orient y -1 1 0
+lattice user 3.52 a1 1.0 0.0 0.0 a2 0.5 1.0 0.0 a3 0.0 0.0 0.5 &
+                  basis 0.0 0.0 0.0 basis 0.5 0.5 0.5
 lattice none :pre
 
 [Description:]
 
-Define a lattice type and lattice constant.  This is required before
-using a commands that (optionally) use the lattice, such as
-"create_atoms"_create_atoms.html or "region"_region.html.  The lattice
-type must be consistent with the dimension of the simulation - see the
-"dimension"_dimension.html command.  Styles {sc} or {bcc} or {fcc} or
-{diamond} are for 3d problems.  Styles {sq} or {sq2} or {hex} are for
-2d problems.  Lattices of style {fcc}, {bcc}, {hex}, or {diamond} are
-described in any solid-state physics text.  A {sc} lattice is simple
-cubic, with atoms at the corners of a cube.  A {sq} lattice is square
-with atoms at the corners of a square.  A {sq2} lattice is a {sq}
-lattice with an additional atom at the center of the square.
+Define a lattice for use by other commands.  In LAMMPS, a lattice is
+simply a set of points in space, determined by a unit cell with basis
+atoms, that is replicated infinitely in all dimensions.  The arguments
+of the lattice command can be used to define a wide variety of
+crystallographic lattices.
 
-For unit style {real} or {metal}, the specified value is the cubic
-lattice constant in Angstroms.  For unit style {lj}, the value is the
-reduced density (rho*) which LAMMPS converts into a cubic lattice
-constant.  For 3d problems, the relationship "rho* = rho sigma^3" is
-used for the conversion, where rho = N/V with V = the volume of the
-cubic cell and N = 4 for {fcc}, 2 for {bcc}, 1 for {sc}, and 8 for
-{diamond} lattices.  For 2d problems, the relationship "rho* = rho
-sigma^2" is used for the conversion, where N = 2 for {sq2} or {hex}
-and 1 for {sq}.  In the hex case, the unit cell is actually
-rectangular; it is extended by a factor of sqrt(3) in the y-dimension.
+A lattice is used by LAMMPS in two ways.  First, the
+"create_atoms"_create_atoms.hmtl command creates atoms on the lattice
+points inside the simulation box.  Note that the
+"create_atoms"_create_atoms.html command allows different atom types
+to be assigned to different basis atoms of the lattice.  Second, the
+lattice spacing in the x,y,z dimensions implied by the lattice, can be
+used by other commands as distance units (e.g. "region"_region.html
+and "velocity"_velocity.html), which are often convenient when the
+underlying problem geometry is atoms on a lattice.
 
-The command "lattice none" can be used to turn off the lattice
-setting.  Any command that attempts to use a lattice constant will
-then generate an error.
+The lattice style must be consistent with the dimension of the
+simulation - see the "dimension"_dimension.html command.  Styles {sc}
+or {bcc} or {fcc} or {diamond} are for 3d problems.  Styles {sq} or
+{sq2} or {hex} are for 2d problems.  Style {user} can be used for
+either 2d or 3d problems.
 
-[Restrictions:] none
+A lattice consists of a unit cell, a set of basis atoms within that
+cell, and a set of transformation parameters (scale, origin, orient)
+that map the unit cell into the simulation box.  The vectors a1,a2,a3
+are the edge vectors of the unit cell.  This is the nomenclature for
+"primitive" vectors in solid-state crytallography, but in LAMMPS the
+unit cell they determine does not have to be a "primitive cell" of
+minimum volume.
+
+:line
+
+Lattices of style {sc}, {fcc}, {bcc}, and {diamond} are 3d lattices
+that define a cubic unit cell with edge length = 1.0.  This means a1 =
+1.0 0.0 0.0, a2 = 0.0 1.0 0.0, and a3 = 0.0 0.0 1.0.  The placement of
+the basis atoms within the unit cell are described in any solid-state
+physics text.  A {sc} lattice has 1 basis atom at the
+lower-left-bottom corner of the cube.  A {bcc} lattice has 2 basis
+atoms, one at the corner and one at the center of the cube.  A {fcc}
+lattice has 4 basis atoms, one at the corner and 3 at the cube face
+centers.  A {diamond} lattice has 8 basis atoms.
+
+Lattices of style {sq} and {sq2} are 2d lattices that define a square
+unit cell with edge length = 1.0.  This means a1 = 1.0 0.0 0.0 and a2
+= 0.0 1.0 0.0.  A {sq} lattice has 1 basis atom at the lower-left
+corner of the square.  A {sq2} lattice has 2 basis atoms, one at the
+corner and one at the center of the square.  A {hex} style is also a
+2d lattice, but the unit cell is rectangular, with a1 = 1.0 0.0 0.0
+and a2 = 0.0 sqrt(3.0) 0.0.  It has 2 basis atoms, one at the corner
+and one at the center of the rectangle.
+
+A lattice of style {user} allows you to specify a1, a2, a3, and a list
+of basis atoms to put in the unit cell.  By default, a1,a2,a3 are 3
+orthogonal unit vectors (edges of a unit cube).  But you can specify
+them to be of any length and non-orthogonal to each other, so that
+they describe a tilted parallelepiped.  Via the {basis} keyword you
+add atoms, one at a time, to the unit cell.  Its arguments are
+fractional coordinates (0.0 <= x,y,z < 1.0), so that a value of 0.5
+means a position half-way across the unit cell in that dimension.
+
+:line
+
+This sub-section discusses the arguments that determine how the
+idealized unit cell is transformed into a lattice of points within the
+simulation box with desired spacings.
+
+The {scale} argument determines how the size of the unit cell will be
+scaled when mapping it into the simulation box.  I.e. it determines a
+multiplicative factor to apply to the unit cell, to convert it to a
+lattice of the desired size and distance units in the simulation box.
+The meaning of the {scale} argument depends on the "units"_unit.html
+being used in your simulation.
+
+For unit style {real} or {metal}, the scale argument is in Angstroms.
+For example, if the unit cell is a unit cube with edge length 1.0,
+setting scale = 3.52 would create a cubic lattice with a spacing of
+3.52 Angstroms.
+
+For unit style {lj}, the scale argument is the Lennard-Jones reduced
+density, typically written as rho*.  LAMMPS converts this value into
+the multiplicative factor via the formula "factor^dim = rho/rho*",
+where rho = N/V with V = the volume of the lattice unit cell and N =
+the number of basis atoms in the unit cell (described below), and dim
+= 2 or 3 for the dimensionality of the simulation.  Effectively, this
+means that if LJ particles of size sigma = 1.0 are used in the
+simulation, the lattice of particles will be at the desired reduced
+density.
+
+The {origin} option specifies how the unit cell will be shifted or
+translated when mapping it into the simulation box.  The x,y,z values
+are fractional values (0.0 <= x,y,z < 1.0) meaning shift the lattice
+by a fraction of the lattice spacing in each dimension.  The meaning
+of "lattice spacing" is discussed below.
+
+The {orient} option specifies how the unit cell will be rotated when
+mapping it into the simulation box.  The {dim} argument is one of the
+3 coordinate axes in the simulation box.  The other 3 arguments are
+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
+orthogonal and obey the right-hand rule, i.e. (X cross Y) points in
+the Z direction.
+
+:line
+
+Several LAMMPS commands have the option to use distance units that are
+inferred from "lattice spacings" in the x,y,z 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.
+
+These 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 shape 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 min/max of the y and z coordinates.
+
+Note that if the unit cell has axis-aligned edges (a1,a2,a3) and is
+not rotated (via the {orient} keyword), then the lattice spacings in
+each dimension are simply the scale factor (descibed 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.
+
+For unit cells with a more general shape or when a rotation is
+applied, the lattice spacing is less intuitive.  But regardless, the
+values of the computed lattice spacings are printed by LAMMPS, so
+their effect in commands that use the spacings should be decipherable.
+
+:line
+
+The command "lattice none" can be used to turn off a previous lattice
+definition.  Any command that attempts to use the lattice directly
+("create_atoms"_create_atoms.html) or associated lattice spacings will
+then generate an error.  No additional arguments need be used with
+"lattice none".
+
+:line
+
+[Restrictions:]
+
+The {a1,a2,a3,basis} keywords can only be used with style {user}.
+
+For lattices oriented at an angle or with a non-orthognal unit cell,
+care must be taken when using the "region"_region.html and
+"create_atoms"_create_atoms.html commands to create a periodic system.
+If the box size is not chosen appropriately, the system may not
+actually be periodic, and atoms may overlap incorretly at the faces of
+the simulation box.
 
 [Related commands:]
 
-"dimension"_dimension.html, "orient"_orient.html,
-"origin"_origin.html, "create_atoms"_create_atoms.html,
+"dimension"_dimension.html, "create_atoms"_create_atoms.html,
 "region"_region.html
 
 [Default:]
 
 lattice none :pre
+
+For other lattice styles, the option defaults are origin = 0.0 0.0
+0.0, orient = x 1 0 0, orient = y 0 1 0, orient = z 0 0 1, a1 = 1.0
+0.0 0.0, a2 = 0.0 1.0 0.0, and a3 = 0.0 0.0 1.0.
diff --git a/doc/temperature.html b/doc/temperature.html
index 247aefcbbc..61d2dc6dde 100644
--- a/doc/temperature.html
+++ b/doc/temperature.html
@@ -97,8 +97,9 @@ for coordinates (c1,c2) and velocities (vlo,vhi) defined for the
 <I>ramp</I> style.  A <I>box</I> value selects standard distance units as
 defined by the <A HREF = "units.html">units</A> command, e.g. Angstroms for units =
 real or metal.  A <I>lattice</I> value means the distance units are in
-cubic lattice spacings; e.g. lattice spacings / tau.  The
-<A HREF = "lattice.html">lattice</A> command must first be used to define a lattice.
+lattice spacings; e.g. velocity = lattice spacings / tau.  The
+<A HREF = "lattice.html">lattice</A> command must have been previously used to
+define the lattice spacing.
 </P>
 <P>LAMMPS defines a temperature with ID = <I>default</I> which computes a
 <I>full</I> style on the <I>all</I> group of atoms.  This is the temperature
diff --git a/doc/temperature.txt b/doc/temperature.txt
index 7a00a51f43..b6f8cd44a4 100644
--- a/doc/temperature.txt
+++ b/doc/temperature.txt
@@ -87,8 +87,9 @@ for coordinates (c1,c2) and velocities (vlo,vhi) defined for the
 {ramp} style.  A {box} value selects standard distance units as
 defined by the "units"_units.html command, e.g. Angstroms for units =
 real or metal.  A {lattice} value means the distance units are in
-cubic lattice spacings; e.g. lattice spacings / tau.  The
-"lattice"_lattice.html command must first be used to define a lattice.
+lattice spacings; e.g. velocity = lattice spacings / tau.  The
+"lattice"_lattice.html command must have been previously used to
+define the lattice spacing.
 
 LAMMPS defines a temperature with ID = {default} which computes a
 {full} style on the {all} group of atoms.  This is the temperature