doc/user/box.dox

   1 /*
   2 Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
   3 (HOOMD-blue) Open Source Software License Copyright 2009-2014 The Regents of
   4 the University of Michigan All rights reserved.
   5
   6 HOOMD-blue may contain modifications ("Contributions") provided, and to which
   7 copyright is held, by various Contributors who have granted The Regents of the
   8 University of Michigan the right to modify and/or distribute such Contributions.
   9
  10 You may redistribute, use, and create derivate works of HOOMD-blue, in source
  11 and binary forms, provided you abide by the following conditions:
  12
  13 * Redistributions of source code must retain the above copyright notice, this
  14 list of conditions, and the following disclaimer both in the code and
  15 prominently in any materials provided with the distribution.
  16
  17 * Redistributions in binary form must reproduce the above copyright notice, this
  18 list of conditions, and the following disclaimer in the documentation and/or
  19 other materials provided with the distribution.
  20
  21 * All publications and presentations based on HOOMD-blue, including any reports
  22 or published results obtained, in whole or in part, with HOOMD-blue, will
  23 acknowledge its use according to the terms posted at the time of submission on:
  24 http://codeblue.umich.edu/hoomd-blue/citations.html
  25
  26 * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
  27 http://codeblue.umich.edu/hoomd-blue/
  28
  29 * Apart from the above required attributions, neither the name of the copyright
  30 holder nor the names of HOOMD-blue's contributors may be used to endorse or
  31 promote products derived from this software without specific prior written
  32 permission.
  33
  34 Disclaimer
  35
  36 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
  37 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  38 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
  39 WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.
  40
  41 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  42 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  43 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  44 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  45 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  46 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  47 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48 */
  49
  50 /*! \page page_box Periodic boundary conditions
  51
  52 Table of contents:
  53  - \ref sec_triclinic_intro
  54  - \ref sec_triclinic_definition
  55  - \ref sec_triclinic_specify
  56  - \ref sec_triclinic_update
  57
  58 \section sec_triclinic_intro Introduction
  59
  60 All simulations executed in HOOMD-blue occur in a triclinic simulation box with periodic boundary conditions in all
  61 three directions. A triclinic box is defined by six values: the extents \f$L_x\f$, \f$L_y\f$ and \f$L_z\f$ of the box
  62 in the three directions, and three tilt factors \f$xy\f$, \f$xz\f$ and \f$yz\f$.
  63
  64 The parameter matrix \f$\mathbf{h}\f$ is defined in terms of the lattice vectors
  65 \f$ \vec a_1 \f$, \f$ \vec a_2 \f$ and \f$ \vec a_3 \f$:
  66 \f[ \mathbf{h} \equiv \left( \vec a_1, \vec a_2, \vec a_3 \right). \f]
  67 By convention, the first lattice vector
  68 \f$ \vec a_1 \f$ is parallel to the unit vector \f$ \vec e_x = (1,0,0) \f$. The tilt factor
  69 \f$ xy \f$ indicates how the second lattice vector \f$ \vec a_2\f$ is tilted with respect to the first one. It specifies
  70 many units along the x-direction correspond to one unit of the second lattice vector. Similarly, \f$ xz \f$ and
  71 \f$ yz \f$ indicate the tilt of the third lattice vector \f$ \vec a_3 \f$ with respect to the first and second lattice
  72 vector.
  73
  74 \section sec_triclinic_definition Definitions and formulas for the cell parameter matrix
  75 The full cell parameter matrix is
  76 \f{eqnarray*}{
  77 \mathbf{h}& =& \left(\begin{array}{ccc} L_x & xy L_y & xz L_z \\
  78                                         0   & L_y    & yz L_z \\
  79                                         0   & 0      & L_z    \\
  80                      \end{array}\right)
  81 \f}
  82
  83 The tilt factors \f$ xy \f$, \f$ xz \f$ and \f$ yz \f$ are dimensionless.
  84 The relationships between the tilt factors and the box angles \f$ \alpha \f$,
  85 \f$ \beta \f$ and \f$ \gamma \f$ are as follows:
  86 \f{eqnarray*}{
  87 \cos\gamma \equiv \cos(\angle\vec a_1, \vec a_2) &=& \frac{xy}{\sqrt{1+xy^2}}\\
  88 \cos\beta \equiv \cos(\angle\vec a_1, \vec a_3) &=& \frac{xz}{\sqrt{1+xz^2+yz^2}}\\
  89 \cos\alpha \equiv \cos(\angle\vec a_2, \vec a_3) &=& \frac{xy*xz + yz}{\sqrt{1+xy^2} \sqrt{1+xz^2+yz^2}} \\
  90 \f}
  91
  92 Given an arbitrarily oriented lattice with box vectors \f$ \vec v_1, \vec v_2, \vec v_3 \f$, the HOOMD-blue
  93 box parameters for the rotated box can be found as follows.
  94 \f{eqnarray*}{
  95 L_x &=& v_1\\
  96 a_{2x} &=& \frac{\vec v_1 \cdot \vec v_2}{v_1}\\
  97 L_y &=& \sqrt{v_2^2 - a_{2x}^2}\\
  98 xy &=& \frac{a_{2x}}{L_y}\\
  99 L_z &=& \vec v_3 \cdot \frac{\vec v_1 \times \vec v_2}{\left| \vec v_1 \times \vec v_2 \right|}\\
 100 a_{3x} &=& \frac{\vec v_1 \cdot \vec v_3}{v_1}\\
 101 xz &=& \frac{a_{3x}}{L_z}\\
 102 yz &=& \frac{\vec v_2 \cdot \vec v_3 - a_{2x}a_{3x}}{L_x L_z}\\
 103 \f}
 104
 105 Example:
 106 ~~~
 107 # boxMatrix contains an arbitrarily oriented right-handed box matrix.
 108 v[0] = boxMatrix[:,0]
 109 v[1] = boxMatrix[:,1]
 110 v[2] = boxMatrix[:,2]
 111 Lx = numpy.sqrt(numpy.dot(v[0], v[0]))
 112 a2x = numpy.dot(v[0], v[1]) / Lx
 113 Ly = numpy.sqrt(numpy.dot(v[1],v[1]) - a2x*a2x)
 114 xy = a2x / Ly
 115 v0xv1 = numpy.cross(v[0], v[1])
 116 v0xv1mag = numpy.sqrt(numpy.dot(v0xv1, v0xv1))
 117 Lz = numpy.dot(v[2], v0xv1) / v0xv1mag
 118 a3x = numpy.dot(v[0], v[2]) / Lx
 119 xz = a3x / Lz
 120 yz = (numpy.dot(v[1],v[2]) - a2x*a3x) / (Ly*Lz)
 121 ~~~
 122
 123 \section sec_triclinic_specify Initializing a system with a triclinic box
 124
 125 You can specify all parameters of a triclinic box in an \link page_xml_file_format XML file\endlink.
 126
 127 You can also pass a data.boxdim argument to the constructor of any initialization method. Here is an example for
 128 \link hoomd_script.init.create_random_polymers init.create_random_polymers\endlink
 129 ~~~
 130 init.create_random_polymers(box=data.boxdim(L=18, xy=0.1, xz=0.2, yz=0.3),
 131                             polymeres=[polymer2],
 132                             separation=dict(A=0.35, B=0.35));
 133 ~~~
 134 This creates a triclinic box with edges of length 18, and tilt factors
 135 \f$ xy =0.1 \f$, \f$ xz=0.2 \f$ and \f$ yz=0.3\f$.
 136
 137 You can also specify a 2D box to any of the initialization methods.
 138 ~~~
 139 init.create_random(N=1000, box=data.boxdim(xy=1.0, volume=2000, dimensions=2), min_dist=1.0)
 140 ~~~
 141
 142 \section sec_triclinic_update Change the simulation box
 143
 144 The triclinic unit cell can be updated in various ways.
 145
 146 \subsection triclinic_resize Resizing the box
 147
 148 The simulation box can be gradually resized during a simulation run using
 149 \link hoomd_script.update.box_resize update.box_resize \endlink.
 150
 151 To update the tilt factors continuously during the simulation (shearing
 152 the simulation box with **Lees-Edwards** boundary conditions), use:
 153 ~~~
 154 update.box_resize(xy = variant.linear_interp([(0,0), (1e6, 1)]))
 155 ~~~
 156 This command applies shear in the \f$ xy \f$-plane so that the angle between the *x*-
 157 and *y*-directions changes continuously from 0 to \f$45^\circ\f$ during \f$ 10^6 \f$ time steps.
 158
 159 \link hoomd_script.update.box_resize update.box_resize \endlink. Can change any or all of the six box parameters.
 160
 161 \subsection triclinic_npt NPT or NPH integration
 162
 163 In a constant pressure ensemble, the box is updated every time step, according to the anisotropic stresses in the
 164 system. This is supported by
 165
 166 - \link hoomd_script.integrate.npt integrate.npt\endlink
 167 - \link hoomd_script.integrate.nph integrate.nph\endlink
 168
 169 Anisotropic constant-pressure integration modes for <b>rigid bodies</b>
 170 are not yet available in HOOMD-blue, but the tilt factors and box lengths
 171 can still be set to any arbitrary value and are
 172 preserved during the course of the NPT or NPH integration when using:
 173
 174 - \link hoomd_script.integrate.npt_rigid integrate.npt_rigid\endlink
 175 - \link hoomd_script.integrate.nph_rigid integrate.nph_rigid\endlink
 176
 177 \subsection triclinic_other Other features
 178 All other features of HOOMD-blue work with triclinic symmetry, including
 179 \link page_mpi MPI\endlink simulations.
 180
 181 As for every rule, there is an exception.
 182 - \link hoomd_script.dump.bin dump.bin\endlink (deprecated) has not been updated to work with triclinic
 183   boxes.
 184 */