Triclinic (non-orthogonal) simulation boxes
===========================================

By default, LAMMPS uses an orthogonal simulation box to encompass the
particles.  The orthogonal box has its "origin" at (xlo,ylo,zlo) and
extends to (xhi,yhi,zhi).  Conceptually it is defined by 3 edge
vectors starting from the origin given by **A** = (xhi-xlo,0,0); **B**
= (0,yhi-ylo,0); **C** = (0,0,zhi-zlo).  The :doc:`boundary
<boundary>` command sets the boundary conditions for the 6 faces of
the box (periodic, non-periodic, etc).  The 6 parameters
(xlo,xhi,ylo,yhi,zlo,zhi) are defined at the time the simulation box
is created by one of these commands:

* :doc:`create_box <create_box>`
* :doc:`read_data <read_data>`
* :doc:`read_restart <read_restart>`
* :doc:`read_dump <read_dump>`

Internally, LAMMPS defines box size parameters lx,ly,lz where lx =
xhi-xlo, and similarly in the y and z dimensions.  The 6 parameters, as
well as lx,ly,lz, can be output via the :doc:`thermo_style custom
<thermo_style>` command.  See the :doc:`Howto 2d <Howto_2d>` doc page
for info on how zlo and zhi are defined for 2d simulations.

----------

Triclinic simulation boxes
""""""""""""""""""""""""""

LAMMPS also allows simulations to be performed using triclinic
(non-orthogonal) simulation boxes shaped as a 3d parallelepiped with
triclinic symmetry.  For 2d simulations a triclinic simulation box is
effectively a parallelogram; see the :doc:`Howto 2d <Howto_2d>` doc
page for details.

One use of triclinic simulation boxes is to model solid-state crystals
with triclinic symmetry.  The :doc:`lattice <lattice>` command can be
used with non-orthogonal basis vectors to define a lattice that will
tile a triclinic simulation box via the :doc:`create_atoms
<create_atoms>` command.

A second use is to run Parrinello-Rahman dynamics via the :doc:`fix
npt <fix_nh>` command, which will adjust the xy, xz, yz tilt factors
to compensate for off-diagonal components of the pressure tensor.  The
analog for an :doc:`energy minimization <minimize>` is the :doc:`fix
box/relax <fix_box_relax>` command.

A third use is to shear a bulk solid to study the response of the
material.  The :doc:`fix deform <fix_deform>` command can be used for
this purpose.  It allows dynamic control of the xy, xz, yz tilt
factors as a simulation runs.  This is discussed in the :doc:`Howto
NEMD <Howto_nemd>` doc page on non-equilibrium MD (NEMD) simulations.

Conceptually, a triclinic parallelepiped is defined with an "origin"
at (xlo,ylo,zhi) and 3 edge vectors **A** = (ax,ay,az), **B** =
(bx,by,bz), **C** = (cx,cy,cz) which can be arbitrary vectors, so long
as they are non-zero, distinct, and not co-planar.  In addition, they
must define a right-handed system, such that (**A** cross **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 4 commands listed above for defining orthogonal simulation boxes
have triclinic options which allow for specification of the origin and
edge vectors **A**, **B**, **C**.  For each command, this can be done
in one of two ways, for what LAMMPS calls a *general* triclinic box or
a *restricted* triclinic box.

A *general* triclinic box is specified by an origin (xlo, ylo, zlo)
and arbitrary edge vectors **A** = (ax,ay,az), **B** = (bx,by,bz), and
**C** = (cx,cy,cz).  So there are 12 parameters in total.

A *restricted* triclinic box also has an origin (xlo,ylo,zlo), but its
edge vectors are of the following restricted form: **A** =
(xhi-xlo,0,0), **B** = (xy,yhi-ylo,0), **C** = (xz,yz,zhi-zlo).  So
there are 9 parameters in total.  Note that the restricted form
requires **A** to be along the x-axis, **B** to be in the xy plane
with a y-component in the +y direction, and **C** to have its
z-component in the +z direction.  Note that a restricted triclinic box
is *right-handed* by construction since (**A** cross **B**) points in
the direction of **C**.

The *xy,xz,yz* values can be zero or positive or negative.  They are
called "tilt factors" because they are the amount of displacement
applied to edges of faces of an orthogonal box to change it into a
restricted triclinic parallelepiped.

.. note::

   Any right-handed general triclinic box (i.e. solid-state crystal
   basis vectors) can be rotated in 3d around its origin in order to
   conform to the LAMMPS definition of a restricted triclinic box.
   See the discussion in the next sub-section about general triclinic
   simulation boxes in LAMMPS.

Note that the :doc:`thermo_style custom <thermo_style>` command has
keywords for outputting the various parameters that define the size
and shape of orthogonal, restricted triclinic, and general triclinic
simulation boxes.

For orthogonal boxes there 6 thermo keywords (xlo,ylo,zlo) and
(xhi,yhi,zhi).

For restricted triclinic boxes there are 9 thermo keywords for
(xlo,ylo,zlo), (xhi,yhi,zhi), and the (xy,xz,yz) tilt factors.

For general triclinic boxes there are 12 thermo keywords for
(xlo,ylo,zhi) and the components of the **A**, **B**, **C** edge
vectors, namely (avecx,avecy,avecz), (bvecx,bvecy,bvecz), and
(cvecx,cvecy,cvecz),

The remainder of this doc page explains (a) how LAMMPS operates with
general triclinic simulation boxes, (b) mathematical transformations
between general and restricted triclinic boxes which may be useful
when creating LAMMPS inputs or interpreting outputs for triclinic
simulations, and (c) how LAMMPS uses tilt factors for restricted
triclinic simulation boxes.

----------

General triclinic simulation boxes in LAMMPS
""""""""""""""""""""""""""""""""""""""""""""

LAMMPS allows specification of general triclinic simulation boxes with
their atoms as a convenience for users who may be converting data from
solid-state crystallographic representations or from DFT codes for
input to LAMMPS.  Likewise it allows output of dump files, data files,
and thermodynamic data (e.g. pressure tensor) in a general triclinic
format.

However internally, LAMMPS only uses restricted triclinic simulation
boxes.  This is for parallel efficiency and to formulate partitioning
of the simulation box across processors, neighbor list building, and
inter-processor communication of per-atom data with methods similar to
those used for orthogonal boxes.

This means 4 things which are important to understand:

* Input of a general triclinic system is immediately converted to a
  restricted triclinic system.
* If output of per-atom data for a general triclinic system is
  requested (e.g. for atom coordinates in a dump file),
  conversion from a restricted to general triclinic system is done at
  the time of output.
* The conversion of the simulation box and per-atom data from general
  triclinic to restricted triclinic (and vice versa) is a 3d rotation
  operation around an origin, which is the lower left corner of the
  simulation box.  This means an input data file for a general
  triclinic system should specify all per-atom quantities consistent
  with the general triclinic box and its orientation relative to the
  standard x,y,z coordinate axes.  For example, atom coordinates
  should be inside the general triclinic simulation box defined by the
  edge vectors **A**, **B**, **C** and its origin.  Likewise per-atom
  velocities should be in directions consistent with the general
  triclinic box orientation.  E.g. a velocity vector which will be in
  the +x direction once LAMMPS converts from a general to restricted
  triclinic box, should be specified in the data file in the direction
  of the **A** edge vector.  See the :doc:`read_data <read_data>` doc
  page for info on all the per-atom vector quantities to which this
  rule applies when a data file for a general triclinic box is input.
* If commands such as :doc:`write_data <write_data>` or :doc:`dump
  custom <dump>` are used to output general triclinic information, it
  is effectively the inverse of the operation described in the
  preceding bullet.
* Other LAMMPS commands such as :doc:`region <region>` or
  :doc:`velocity <velocity>` or :doc:`set <set>`, operate on a
  restricted triclinic system even if a general triclinic system was
  defined initially.

This is the list of commands which have general triclinic options:

* :doc:`create_box <create_box>` - define a general triclinic box
* :doc:`create_atoms <create_atoms>` - add atoms to a general triclinic box
* :doc:`lattice <lattice>` - define a custom lattice consistent with the **A**, **B**, **C** edge vectors of a general triclinic box
* :doc:`read_data <read_data>` - read a data file for a general triclinic system
* :doc:`write_data <write_data>` - write a data file for a general triclinic system
* :doc:`dump atom, dump custom <dump>` - output dump snapshots in general triclinic format
* :doc:`dump_modify triclinic/general <dump_modify>` - select general triclinic format for dump output
* :doc:`thermo_style <thermo_style>` - output the pressure tensor in
  general triclinic format
* :doc:`thermo_modify triclinic/general <thermo_modify>` - select general triclinic format for thermo output
* :doc:`read_restart <read_restart>` - read a restart file for a general triclinic system
* :doc:`write_restart <read_restart>` - write a restart file for a general triclinic system

----------

Transformation from general to restricted triclinic boxes
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Let **A**,\ **B**,\ **C** be the right-handed edge vectors of a
general triclinic simulation box.  The equivalent LAMMPS **a**,\
**b**,\ **c** for a restricted triclinic box are a 3d rotation of
**A**, **B**, and **C** and can be computed as follows:

.. math::

  \begin{pmatrix} \mathbf{a}  & \mathbf{b}  & \mathbf{c} \end{pmatrix} = &
  \begin{pmatrix}
    a_x & b_x & c_x \\
    0   & b_y & c_y \\
    0   & 0   & c_z \\
  \end{pmatrix} \\
  a_x = & A \\
  b_x = & \mathbf{B} \cdot \mathbf{\hat{A}} \quad = \quad B \cos{\gamma} \\
  b_y = & |\mathbf{\hat{A}} \times \mathbf{B}| \quad = \quad B \sin{\gamma} \quad =  \quad  \sqrt{B^2 - {b_x}^2} \\
  c_x = & \mathbf{C} \cdot \mathbf{\hat{A}} \quad = \quad C \cos{\beta} \\
  c_y = & \mathbf{C} \cdot \widehat{(\mathbf{A} \times \mathbf{B})} \times \mathbf{\hat{A}} \quad = \quad \frac{\mathbf{B} \cdot \mathbf{C} - b_x c_x}{b_y} \\
  c_z = & |\mathbf{C} \cdot \widehat{(\mathbf{A} \times \mathbf{B})}|\quad = \quad \sqrt{C^2 - {c_x}^2 - {c_y}^2}

where A = \| **A** \| indicates the scalar length of **A**\ . The hat
symbol (\^) indicates the corresponding unit vector. :math:`\beta` and
:math:`\gamma` are angles between the **A**, **B**, **C** vectors
as described below.

For consistency, the same rotation applied to the triclinic box edge
vectors can also be applied to atom positions, velocities, and other
vector quantities.  This can be conveniently achieved by first
converting to fractional coordinates in the general triclinic
coordinates and then converting to coordinates in the restricted
triclinic basis.  The transformation is given by the following equation:

.. math::

  \mathbf{x} = & \begin{pmatrix} \mathbf{a}  & \mathbf{b}  & \mathbf{c} \end{pmatrix} \cdot \frac{1}{V}
    \begin{pmatrix}
      \mathbf{B \times C}  \\
      \mathbf{C \times A}  \\
      \mathbf{A \times B}
    \end{pmatrix} \cdot \mathbf{X}

where *V* is the volume of the box (same in either basis), **X** is
the fractional vector in the general triclinic basis and **x** is the
resulting vector in the restricted triclinic basis.

----------

Crystallographic general triclinic representation of a simulation box
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

General triclinic crystal structures are often defined using three
lattice constants *a*, *b*, and *c*, and three angles :math:`\alpha`,
:math:`\beta`, and :math:`\gamma`. Note that in this nomenclature, the
a, b, and c lattice constants are the scalar lengths of the edge
vectors **a**, **b**, and **c** defined above.  The relationship
between these 6 quantities (a, b, c, :math:`\alpha`, :math:`\beta`,
:math:`\gamma`) and the LAMMPS restricted triclinic box sizes
(lx,ly,lz) = (xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) is
as follows:

.. math::

  a   = & \mathrm{lx} \\
  b^2 = &  \mathrm{ly}^2 + \mathrm{xy}^2 \\
  c^2 = &  \mathrm{lz}^2 + \mathrm{xz}^2 + \mathrm{yz}^2 \\
  \cos{\alpha} = & \frac{\mathrm{xy}*\mathrm{xz} + \mathrm{ly}*\mathrm{yz}}{b*c} \\
  \cos{\beta}  = & \frac{\mathrm{xz}}{c} \\
  \cos{\gamma} = & \frac{\mathrm{xy}}{b} \\

The inverse relationship can be written as follows:

.. math::

  \mathrm{lx}   = & a \\
  \mathrm{xy}   = & b \cos{\gamma}  \\
  \mathrm{xz}   = & c \cos{\beta}\\
  \mathrm{ly}^2 = & b^2 - \mathrm{xy}^2 \\
  \mathrm{yz}   = & \frac{b*c \cos{\alpha} - \mathrm{xy}*\mathrm{xz}}{\mathrm{ly}} \\
  \mathrm{lz}^2 = & c^2 - \mathrm{xz}^2 - \mathrm{yz}^2 \\

The values of *a*, *b*, *c*, :math:`\alpha` , :math:`\beta`, and
:math:`\gamma` can be printed out or accessed by computes using the
:doc:`thermo_style custom <thermo_style>` keywords *cella*, *cellb*,
*cellc*, *cellalpha*, *cellbeta*, *cellgamma*, respectively.

----------

Output of restricted and general triclinic boxes in a dump file
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

As discussed on the :doc:`dump <dump>` command doc page, when the BOX
BOUNDS for a snapshot is written to a dump file for a restricted
triclinic box, an orthogonal bounding box which encloses the triclinic
simulation box is output, along with the 3 tilt factors (xy, xz, yz) of
the restricted triclinic box, formatted as follows:

.. parsed-literal::

   ITEM: BOX BOUNDS xy xz yz
   xlo_bound xhi_bound xy
   ylo_bound yhi_bound xz
   zlo_bound zhi_bound yz

This bounding box is convenient for many visualization programs and is
calculated from the 9 restricted triclinic box parameters
(xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) as follows:

.. parsed-literal::

   xlo_bound = xlo + MIN(0.0,xy,xz,xy+xz)
   xhi_bound = xhi + MAX(0.0,xy,xz,xy+xz)
   ylo_bound = ylo + MIN(0.0,yz)
   yhi_bound = yhi + MAX(0.0,yz)
   zlo_bound = zlo
   zhi_bound = zhi

These formulas can be inverted if you need to convert the bounding box
back into the restricted triclinic box parameters, e.g. xlo =
xlo_bound - MIN(0.0,xy,xz,xy+xz).

----------

Periodicity and tilt factors for triclinic simulation boxes
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

There is no requirement that a triclinic box be periodic in any
dimension, though it typically should be in y or z if you wish to
enforce a shift in coordinates due to periodic boundary conditions
across the y or z boundaries.  See the doc page for the :doc:`boundary
<boundary>` command for an explanation of shifted coordinates for
restricted triclinic boxes which are periodic.

Some commands that work with triclinic boxes, e.g. the :doc:`fix
deform <fix_deform>` and :doc:`fix npt <fix_nh>` commands, require
periodicity or non-shrink-wrap boundary conditions in specific
dimensions.  See the command doc pages for details.

A restricted triclinic box can be defined with all 3 tilt factors =
0.0, so that it is initially orthogonal.  This is necessary if the box
will become non-orthogonal, e.g. due to use of the :doc:`fix npt
<fix_nh>` or :doc:`fix deform <fix_deform>` commands.  Alternatively,
you can use the :doc:`change_box <change_box>` command to convert a
simulation box from orthogonal to restricted triclinic and vice versa.

.. note::

   Highly tilted restricted triclinic simulation boxes can be
   computationally inefficient.  This is due to the large volume of
   communication needed to acquire ghost atoms around a processor's
   irregular-shaped subdomain.  For extreme values of tilt, LAMMPS may
   also lose atoms and generate an error.

LAMMPS will issue a warning if you define a restricted triclinic box
with a tilt factor which skews the box more than half the distance of
the parallel box length, which is the first dimension in the tilt
factor (e.g. x for xz).

For example, if xlo = 2 and xhi = 12, then the x box length is 10 and
the xy tilt factor should be between -5 and 5 to avoid the warning.
Similarly, both xz and yz should be between -(xhi-xlo)/2 and
+(yhi-ylo)/2.  Note that these are not limitations, since if the
maximum tilt factor is 5 (as in this example), then simulations boxes
and atom configurations with tilt = ..., -15, -5, 5, 15, 25, ... are
all geometrically equivalent.

If the box tilt exceeds this limit during a dynamics run (e.g. due to
the :doc:`fix deform <fix_deform>` command), then by default the box
is "flipped" to an equivalent shape with a tilt factor within the
warning bounds, and the run continues.  See the :doc:`fix deform
<fix_deform>` page for further details.  Box flips that would normally
occur using the :doc:`fix deform <fix_deform>` or :doc:`fix npt
<fix_nh>` commands can be suppressed using the *flip no* option with
either of the commands.

One exception to box flipping is if the first dimension in the tilt
factor (e.g. x for xy) is non-periodic.  In that case, the limits on
the tilt factor are not enforced, since flipping the box in that
dimension would not change the atom positions due to non-periodicity.
In this mode, if the system tilts to large angles, the simulation will
simply become inefficient, due to the highly skewed simulation box.
