more doc page updates for general tri

doc/src/create_box.rst

@@ -9,9 +9,11 @@ Syntax
 .. code-block:: LAMMPS
 
    create_box N region-ID keyword value ...
+   create_box N NULL alo ahi blo bhi clo chi keyword value ...
 
 * N = # of atom types to use in this simulation
-* region-ID = ID of region to use as simulation domain
+* region-ID = ID of region to use as simulation domain or NULL for general triclinic box
+* alo,ahi,blo,bhi,clo,chi = multipliers on a1,a2,a3 vectors defined by :doc"`lattice <lattice>` command (only when region-ID = NULL)
 * zero or more keyword/value pairs may be appended
 * keyword = *bond/types* or *angle/types* or *dihedral/types* or *improper/types* or *extra/bond/per/atom* or *extra/angle/per/atom* or *extra/dihedral/per/atom* or *extra/improper/per/atom* or *extra/special/per/atom*
 
@@ -32,95 +34,183 @@ Examples
 
 .. code-block:: LAMMPS
 
+   # orthogonal or restricted triclinic box using regionID = mybox
    create_box 2 mybox
    create_box 2 mybox bond/types 2 extra/bond/per/atom 1
 
+.. code-block:: LAMMPS
+
+   # 2d general triclinic box using primitive cell for 2d hex lattice
+   lattice       custom 1.0 a1 1.0 0.0 0.0 a2 0.5 0.86602540378 0.0 &
+                 a3 0.0 0.0 1.0 basis 0.0 0.0 0.0
+   create_box    1 NULL 0 5 0 5 -0.5 0.5
+
+.. code-block:: LAMMPS
+ 
+   # 3d general triclinic box using primitive cell for 3d fcc lattice
+   lattice custom 1.0 a2 0.0 0.5 0.5 a1 0.5 0.0 0.5 a3 0.5 0.5 0.0 basis 0.0 0.0 0.0
+   create box 1 NULL -5 5 -10 10 0 20
+   
 Description
 """""""""""
 
-This command creates a simulation box based on the specified region.
+This command creates a simulation box. It also partitions the box into
-Thus a :doc:`region <region>` command must first be used to define a
+a regular 3d grid of smaller sub-boxes, one per procssor (MPI task).
-geometric domain.  It also partitions the simulation box into a
+The geometry of the partitioning is based on the size and shape of the
-regular 3d grid of rectangular bricks, one per processor, based on the
+simulation box, the number of processors being used and the settings
-number of processors being used and the settings of the
+of the :doc:`processors <processors>` command.  The partitioning can
-:doc:`processors <processors>` command.  The partitioning can later be
+later be changed by the :doc:`balance <balance>` or :doc:`fix balance
-changed by the :doc:`balance <balance>` or :doc:`fix balance <fix_balance>` commands.
+<fix_balance>` commands.
 
-The argument N is the number of atom types that will be used in the
+Simulation boxes in LAMMPS can be either orthogonal or triclinic in
+shape.  Orthogonal boxes are a brick in 3d (rectangle in 2d) with 6
+faces that are each perpendicular to one of the standard xyz
+coordinate axes.  Triclinic boxes are a parallelepiped in 3d
+(parallelogram in 2d) with opposite pairs of faces parallel to each
+other.  LAMMPS supports two forms of triclinic boxes, restricted and
+general, which differ in how the box is oriented with respect to the
+xyz coordinate axes.  See the :doc:`Howto triclinic <Howto_triclinic>`
+for a detailed description of all 3 kinds of simulation boxes.
+
+The argument *N* is the number of atom types that will be used in the
 simulation.
 
+Orthogonal and restricted triclinic boxes are created by specifying a
+region ID previously defined by the :doc:`region <region>` command.
+General triclinic boxes are discussed below.
+
 If the region is not of style *prism*, then LAMMPS encloses the region
 (block, sphere, etc.) with an axis-aligned orthogonal bounding box
-which becomes the simulation domain.
+which becomes the simulation domain.  For a 2d simulation, the zlo and
+zhi values of the simulation box must straddle zero.
 
 If the region is of style *prism*, LAMMPS creates a non-orthogonal
 simulation domain shaped as a parallelepiped with triclinic symmetry.
 As defined by the :doc:`region prism <region>` command, the
-parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by three
+parallelepiped has an "origin" at (xlo,ylo,zlo) and three edge vectors
-edge vectors starting from the origin given by
+starting from the origin given by :math:`\vec a =
-:math:`\vec a = (x_\text{hi}-x_\text{lo},0,0)`;
+(x_\text{hi}-x_\text{lo},0,0)`; :math:`\vec b =
-:math:`\vec b = (xy,y_\text{hi}-y_\text{lo},0)`; and
+(xy,y_\text{hi}-y_\text{lo},0)`; and :math:`\vec c =
-:math:`\vec c = (xz,yz,z_\text{hi}-z_\text{lo})`.
+(xz,yz,z_\text{hi}-z_\text{lo})`.  This is a restricted triclinic box
-The parameters *xy*\ , *xz*\ , and *yz* can be 0.0 or
+because the three edge vectors cannot be defined in arbitrary
-positive or negative values and are called "tilt factors" because they
+(general) directions.  The parameters *xy*\ , *xz*\ , and *yz* can be
-are the amount of displacement applied to faces of an originally
+0.0 or positive or negative values and are called "tilt factors"
-orthogonal box to transform it into the parallelepiped.
+because they are the amount of displacement applied to faces of an
+originally orthogonal box to transform it into the parallelepiped.
+For a 2d simulation, the zlo and zhi values of the simulation box must
+straddle zero.
 
-By default, a *prism* region used with the create_box command must have
+Typically a *prism* region used with the create_box command should
-tilt factors :math:`(xy,xz,yz)` that do not skew the box more than half
+have tilt factors :math:`(xy,xz,yz)` that do not skew the box more
-the distance of the parallel box length.  For example, if
+than half the distance of the parallel box length.  For example, if
-:math:`x_\text{lo} = 2` and :math:`x_\text{hi} = 12`, then the :math:`x`
+:math:`x_\text{lo} = 2` and :math:`x_\text{hi} = 12`, then the
-box length is 10 and the :math:`xy` tilt factor must be between
+:math:`x` box length is 10 and the :math:`xy` tilt factor must be
-:math:`-5` and :math:`5`.  Similarly, both :math:`xz` and :math:`yz`
+between :math:`-5` and :math:`5`.  Similarly, both :math:`xz` and
-must be between :math:`-(x_\text{hi}-x_\text{lo})/2` and
+:math:`yz` must be between :math:`-(x_\text{hi}-x_\text{lo})/2` and
 :math:`+(y_\text{hi}-y_\text{lo})/2`.  Note that this is not a
-limitation, since if the maximum tilt factor is 5 (as in this example),
+limitation, since if the maximum tilt factor is 5 (as in this
-then configurations with tilt :math:`= \dots, -15`, :math:`-5`,
+example), then configurations with tilt :math:`= \dots, -15`,
-:math:`5`, :math:`15`, :math:`25, \dots` are all geometrically
+:math:`-5`, :math:`5`, :math:`15`, :math:`25, \dots` are all
-equivalent.  Simulations with large tilt factors will run inefficiently,
+geometrically equivalent.
-since they require more ghost atoms and thus more communication.  With
-very large tilt factors, LAMMPS will eventually produce incorrect
-trajectories and stop with errors due to lost atoms or similar.
 
-See the :doc:`Howto triclinic <Howto_triclinic>` page for a
+LAMMPS will issue a warning if the tilt factors of the created box do
-geometric description of triclinic boxes, as defined by LAMMPS, and
+not meet this criterion.  This is because simulations with large tilt
-how to transform these parameters to and from other commonly used
+factors may run inefficiently, since they require more ghost atoms and
-triclinic representations.
+thus more communication.  With very large tilt factors, LAMMPS may
+eventually produce incorrect trajectories and stop with errors due to
+lost atoms or similar issues.
 
-When a prism region is used, the simulation domain should normally be periodic
+See the :doc:`Howto triclinic <Howto_triclinic>` page for geometric
-in the dimension that the tilt is applied to, which is given by the second
+descriptions of triclinic boxes and tilt factors, as well as how to
-dimension of the tilt factor (e.g., :math:`y` for :math:`xy` tilt).  This is so
+transform the restricted triclinic parameters to and from other
-that pairs of atoms interacting across that boundary will have one of them
+commonly used triclinic representations.
-shifted by the tilt factor.  Periodicity is set by the
+
-:doc:`boundary <boundary>` command.  For example, if the :math:`xy` tilt factor
+When a prism region is used, the simulation domain should normally be
-is non-zero, then the :math:`y` dimension should be periodic.  Similarly, the
+periodic in the dimension that the tilt is applied to, which is given
-:math:`z` dimension should be periodic if :math:`xz` or :math:`yz` is non-zero.
+by the second dimension of the tilt factor (e.g., :math:`y` for
-LAMMPS does not require this periodicity, but you may lose atoms if this is not
+:math:`xy` tilt).  This is so that pairs of atoms interacting across
-the case.
+that boundary will have one of them shifted by the tilt factor.
+Periodicity is set by the :doc:`boundary <boundary>` command.  For
+example, if the :math:`xy` tilt factor is non-zero, then the :math:`y`
+dimension should be periodic.  Similarly, the :math:`z` dimension
+should be periodic if :math:`xz` or :math:`yz` is non-zero.  LAMMPS
+does not require this periodicity, but you may lose atoms if this is
+not the case.
 
 Note that if your simulation will tilt the box (e.g., via the
-:doc:`fix deform <fix_deform>` command), the simulation box must be set up to
+:doc:`fix deform <fix_deform>` command), the simulation box must be
-be triclinic, even if the tilt factors are initially 0.0.  You can
+created as triclinic, even if the tilt factors are initially 0.0.  You
-also change an orthogonal box to a triclinic box or vice versa by
+can also change an orthogonal box to a triclinic box or vice versa by
 using the :doc:`change box <change_box>` command with its *ortho* and
 *triclinic* options.
 
 .. note::
 
-   If the system is non-periodic (in a dimension), then you should
+   If the system is non-periodic (in a dimension), then you should not
-   not make the lo/hi box dimensions (as defined in your
+   make the lo/hi box dimensions (as defined in your :doc:`region
-   :doc:`region <region>` command) radically smaller/larger than the extent
+   <region>` command) radically smaller/larger than the extent of the
-   of the atoms you eventually plan to create (e.g., via the
+   atoms you eventually plan to create (e.g., via the
-   :doc:`create_atoms <create_atoms>` command).  For example, if your atoms
+   :doc:`create_atoms <create_atoms>` command).  For example, if your
-   extend from 0 to 50, you should not specify the box bounds as :math:`-10000`
+   atoms extend from 0 to 50, you should not specify the box bounds as
-   and :math:`10000`. This is because as described above, LAMMPS uses the
+   :math:`-10000` and :math:`10000`. This is because as described
-   specified box size to lay out the 3d grid of processors.  A huge
+   above, LAMMPS uses the specified box size to lay out the 3d grid of
-   (mostly empty) box will be sub-optimal for performance when using
+   processors.  A huge (mostly empty) box will be sub-optimal for
-   "fixed" boundary conditions (see the :doc:`boundary <boundary>`
+   performance when using "fixed" boundary conditions (see the
-   command).  When using "shrink-wrap" boundary conditions (see the
+   :doc:`boundary <boundary>` command).  When using "shrink-wrap"
-   :doc:`boundary <boundary>` command), a huge (mostly empty) box may cause
+   boundary conditions (see the :doc:`boundary <boundary>` command), a
-   a parallel simulation to lose atoms the first time that LAMMPS
+   huge (mostly empty) box may cause a parallel simulation to lose
-   shrink-wraps the box around the atoms.
+   atoms the first time that LAMMPS shrink-wraps the box around the
+   atoms.
+
+----------
+
+As noted above, general triclinic boxes allow for arbitrary edge
+vectors **A**, **B**, **C*.  The only restrictions are that the three
+vectors be distinct, non-zero, and not co-planar.  They must also
+define a right-handed system such that (**A** x **B**) points in the
+direction of **C**.  Note that a left-handed system can be converted
+to a right-handed system by simply swapping the order of any pair of
+the **A**, **B**, **C** vectors.
+
+To create a general triclinic boxes, the region is specified as NULL
+and the next 6 parameters (alo,ahi,blo,bhi,clo,chi) define the three
+edge vectors **A**, **B**, **C** using additional information
+previousl set by the :doc:`lattice <lattice>` command.
+
+The lattice must be of style *custom* with a default orientation (no
+use of the *orient* keyword to change the default values).  The *a1,
+*a2*, *a3* settings of the :doc:`lattice <lattice>` command define the
+edge vectors of a unit cell of the lattice.  The three edge vectors of
+the general triclinic box are defined as
+
+* **A** = (ahi-alo) * *a1*
+* **B** = (bhi-blo) * *a2*
+* **C** = (chi-clo) * *a3*
+
+The origin of the general triclinic box is at (alo*a1 + blo*a2 +
+clo*a3) with an additional offset due to the *origin* setting of the
+lattice command (zero vector by default).
+
+For 2d simulations, **C** = (0,0,1) is required, and the z-component
+of the simulation box origin must be -0.5.  The easy way to do this is
+to specify clo = -0.5 and chi = 0.5 with the :doc:`lattice <lattice>`
+command default of a3 = (0,0,1).
+
+.. note::
+
+   LAMMPS allows specification of general triclinic simulation boxes
+   as a convenience for users who may be converting data from
+   solid-state crystallograhic representations or from DFT codes for
+   input to LAMMPS.  However, as explained on the
+   :doc:`Howto_triclinic <Howto_triclinic>` doc page, internally,
+   LAMMPS only uses restricted triclinic simulation boxes.  This means
+   the box defined by this command and per-atom information
+   (e.g. coordinates, velocities) defined by the :doc:`create_atoms
+   <create_atoms>` command are converted from general to restricted
+   triclinic form when the two commands are invoked.  The
+   <Howto_triclinic>` doc page also discusses other LAMMPS commands
+   which can input/output general triclinic representations of the
+   simulation box and per-atom data.
 
 ----------
 

doc/src/lattice.rst

@@ -131,8 +131,10 @@ 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).  The position vector
 x of a basis atom within the unit cell is thus a linear combination of
-the unit cell's 3 edge vectors, i.e. x = bx a1 + by a2 + bz a3,
+the unit cell's 3 edge vectors, i.e. x = bx a1 + by a2 + bz a3, where
-where bx,by,bz are the 3 values specified for the *basis* keyword.
+bx,by,bz are the 3 values specified for the *basis* keyword.  For 2d
+simulations, the fractional z coordinate for any basis atom must be
+0.0.
 
 ----------
 

doc/src/read_data.rst

@@ -449,8 +449,8 @@ origin* keywords are used.  The *xlo xhi*, *ylo yhi*, *zlo zhi*, and
 *xy xz yz* keywords are not used.  The first 3 keywords define the 3
 edge vectors **A**, **B**, **C** of a general triclinic box.  They can
 be arbitrary vectors so long as they are distinct, non-zero, and not
-co-planar.  They must also define a right-handed system requirement
+co-planar.  They must also define a right-handed system such that
-such that (**A** x **B**) points in the direction of **C**.  A
+(**A** x **B**) points in the direction of **C**.  Note that a
 left-handed system can be converted to a right-handed system by simply
 swapping the order of any pair of the **A**, **B**, **C** vectors.
 The origin of the box (origin of the 3 edge vectors) is set by the
@@ -818,6 +818,8 @@ of analysis.
      - atom-ID atom-type bodyflag mass x y z
    * - bond
      - atom-ID molecule-ID atom-type x y z
+   * - bpm/sphere
+     - atom-ID molecule-ID atom-type diameter density x y z
    * - charge
      - atom-ID atom-type q x y z
    * - dielectric
@@ -848,8 +850,6 @@ of analysis.
      - atom-ID atom-type rho esph cv x y z
    * - sphere
      - atom-ID atom-type diameter density x y z
-   * - bpm/sphere
-     - atom-ID molecule-ID atom-type diameter density x y z
    * - spin
      - atom-ID atom-type x y z spx spy spz sp
    * - tdpd

doc/src/write_restart.rst

@@ -55,21 +55,22 @@ alter the number of files written.
 Restart files can be read by a :doc:`read_restart <read_restart>`
 command to restart a simulation from a particular state.  Because the
 file is binary (to enable exact restarts), it may not be readable on
-another machine.  In this case, you can use the :doc:`-r command-line switch <Run_options>` to convert a restart file to a data file.
+another machine.  In this case, you can use the :doc:`-r command-line
+switch <Run_options>` to convert a restart file to a data file.
 
 .. note::
 
    Although the purpose of restart files is to enable restarting a
    simulation from where it left off, not all information about a
-   simulation is stored in the file.  For example, the list of fixes that
+   simulation is stored in the file.  For example, the list of fixes
-   were specified during the initial run is not stored, which means the
+   that were specified during the initial run is not stored, which
-   new input script must specify any fixes you want to use.  Even when
+   means the new input script must specify any fixes you want to use.
-   restart information is stored in the file, as it is for some fixes,
+   Even when restart information is stored in the file, as it is for
-   commands may need to be re-specified in the new input script, in order
+   some fixes, commands may need to be re-specified in the new input
-   to re-use that information. Details are usually given in the
+   script, in order to re-use that information. Details are usually
-   documentation of the respective command. Also, see the
+   given in the documentation of the respective command. Also, see the
-   :doc:`read_restart <read_restart>` command for general information about
+   :doc:`read_restart <read_restart>` command for general information
-   what is stored in a restart file.
+   about what is stored in a restart file.
 
 ----------
 

src/create_box.cpp

@@ -121,11 +121,6 @@ void CreateBox::command(int narg, char **arg)
     double chi = utils::numeric(FLERR, arg[iarg + 5], false, lmp);
     iarg += 6;
     
-    if (domain->dimension == 2) {
-      if (clo >= 0.0 || clo <= 0.0)
-        error->all(FLERR,"Create_box region clo/chi for 2d simulation must straddle 0.0");
-    }
-    
     // use lattice2box() to generate origin and ABC vectors
     // origin = abc lo
     // ABC vectors = hi in one dim - origin
@@ -157,6 +152,12 @@ void CreateBox::command(int narg, char **arg)
     cvec[1] = py - origin[1];
     cvec[2] = pz - origin[2];
 
+    if (domain->dimension == 2) {
+      if (cvec[0] != 0.0 || cvec[1] != 0.0 || cvec[2] != 1.0 || origin[2] != -0.5)
+        error->all(FLERR,"Create_box C vector and/or origin is invalid "
+                   "for 2d simulation with general triclinic box");
+    }
+
     // define general triclinic box within Domain
     
     domain->define_general_triclinic(avec,bvec,cvec,origin);