diff --git a/doc/src/create_box.rst b/doc/src/create_box.rst index f930ecea83..b5ac4ac907 100644 --- a/doc/src/create_box.rst +++ b/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 ` 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. -Thus a :doc:`region ` command must first be used to define a -geometric domain. It also partitions the simulation box into a -regular 3d grid of rectangular bricks, one per processor, based on the -number of processors being used and the settings of the -:doc:`processors ` command. The partitioning can later be -changed by the :doc:`balance ` or :doc:`fix balance ` commands. +This command creates a simulation box. It also partitions the box into +a regular 3d grid of smaller sub-boxes, one per procssor (MPI task). +The geometry of the partitioning is based on the size and shape of the +simulation box, the number of processors being used and the settings +of the :doc:`processors ` command. The partitioning can +later be changed by the :doc:`balance ` or :doc:`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 ` +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 ` 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 ` command, the -parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by three -edge vectors starting from the origin given by -:math:`\vec a = (x_\text{hi}-x_\text{lo},0,0)`; -:math:`\vec b = (xy,y_\text{hi}-y_\text{lo},0)`; and -:math:`\vec c = (xz,yz,z_\text{hi}-z_\text{lo})`. -The parameters *xy*\ , *xz*\ , and *yz* can be 0.0 or -positive or negative values and are called "tilt factors" because they -are the amount of displacement applied to faces of an originally -orthogonal box to transform it into the parallelepiped. +parallelepiped has an "origin" at (xlo,ylo,zlo) and three edge vectors +starting from the origin given by :math:`\vec a = +(x_\text{hi}-x_\text{lo},0,0)`; :math:`\vec b = +(xy,y_\text{hi}-y_\text{lo},0)`; and :math:`\vec c = +(xz,yz,z_\text{hi}-z_\text{lo})`. This is a restricted triclinic box +because the three edge vectors cannot be defined in arbitrary +(general) directions. The parameters *xy*\ , *xz*\ , and *yz* can be +0.0 or positive or negative values and are called "tilt factors" +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 -tilt factors :math:`(xy,xz,yz)` that do not skew the box more 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` -box length is 10 and the :math:`xy` tilt factor must be between -:math:`-5` and :math:`5`. Similarly, both :math:`xz` and :math:`yz` -must be between :math:`-(x_\text{hi}-x_\text{lo})/2` and +Typically a *prism* region used with the create_box command should +have tilt factors :math:`(xy,xz,yz)` that do not skew the box more +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` box length is 10 and the :math:`xy` tilt factor must be +between :math:`-5` and :math:`5`. Similarly, both :math:`xz` 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), -then configurations with tilt :math:`= \dots, -15`, :math:`-5`, -:math:`5`, :math:`15`, :math:`25, \dots` are all geometrically -equivalent. Simulations with large tilt factors will run inefficiently, -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. +limitation, since if the maximum tilt factor is 5 (as in this +example), then configurations with tilt :math:`= \dots, -15`, +:math:`-5`, :math:`5`, :math:`15`, :math:`25, \dots` are all +geometrically equivalent. -See the :doc:`Howto triclinic ` page for a -geometric description of triclinic boxes, as defined by LAMMPS, and -how to transform these parameters to and from other commonly used -triclinic representations. +LAMMPS will issue a warning if the tilt factors of the created box do +not meet this criterion. This is because simulations with large tilt +factors may run inefficiently, since they require more ghost atoms and +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 -in the dimension that the tilt is applied to, which is given by the second -dimension of the tilt factor (e.g., :math:`y` for :math:`xy` tilt). This is so -that pairs of atoms interacting across that boundary will have one of them -shifted by the tilt factor. Periodicity is set by the -:doc:`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. +See the :doc:`Howto triclinic ` page for geometric +descriptions of triclinic boxes and tilt factors, as well as how to +transform the restricted triclinic parameters to and from other +commonly used triclinic representations. + +When a prism region is used, the simulation domain should normally be +periodic in the dimension that the tilt is applied to, which is given +by the second dimension of the tilt factor (e.g., :math:`y` for +:math:`xy` tilt). This is so that pairs of atoms interacting across +that boundary will have one of them shifted by the tilt factor. +Periodicity is set by the :doc:`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 ` command), the simulation box must be set up to -be triclinic, even if the tilt factors are initially 0.0. You can -also change an orthogonal box to a triclinic box or vice versa by +:doc:`fix deform ` command), the simulation box must be +created as triclinic, even if the tilt factors are initially 0.0. You +can also change an orthogonal box to a triclinic box or vice versa by using the :doc:`change box ` command with its *ortho* and *triclinic* options. .. note:: - If the system is non-periodic (in a dimension), then you should - not make the lo/hi box dimensions (as defined in your - :doc:`region ` command) radically smaller/larger than the extent - of the atoms you eventually plan to create (e.g., via the - :doc:`create_atoms ` command). For example, if your atoms - extend from 0 to 50, you should not specify the box bounds as :math:`-10000` - and :math:`10000`. This is because as described above, LAMMPS uses the - specified box size to lay out the 3d grid of processors. A huge - (mostly empty) box will be sub-optimal for performance when using - "fixed" boundary conditions (see the :doc:`boundary ` - command). When using "shrink-wrap" boundary conditions (see the - :doc:`boundary ` command), a huge (mostly empty) box may cause - a parallel simulation to lose atoms the first time that LAMMPS - shrink-wraps the box around the atoms. + If the system is non-periodic (in a dimension), then you should not + make the lo/hi box dimensions (as defined in your :doc:`region + ` command) radically smaller/larger than the extent of the + atoms you eventually plan to create (e.g., via the + :doc:`create_atoms ` command). For example, if your + atoms extend from 0 to 50, you should not specify the box bounds as + :math:`-10000` and :math:`10000`. This is because as described + above, LAMMPS uses the specified box size to lay out the 3d grid of + processors. A huge (mostly empty) box will be sub-optimal for + performance when using "fixed" boundary conditions (see the + :doc:`boundary ` command). When using "shrink-wrap" + boundary conditions (see the :doc:`boundary ` command), a + huge (mostly empty) box may cause a parallel simulation to lose + 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 ` 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 ` 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 ` +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 ` 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 + ` command are converted from general to restricted + triclinic form when the two commands are invoked. The + ` doc page also discusses other LAMMPS commands + which can input/output general triclinic representations of the + simulation box and per-atom data. ---------- diff --git a/doc/src/lattice.rst b/doc/src/lattice.rst index 7dc9c579e5..277f648515 100644 --- a/doc/src/lattice.rst +++ b/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, -where bx,by,bz are the 3 values specified for the *basis* keyword. +the unit cell's 3 edge vectors, i.e. x = bx a1 + by a2 + bz a3, where +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. ---------- diff --git a/doc/src/read_data.rst b/doc/src/read_data.rst index d26d0ab577..56c92355a8 100644 --- a/doc/src/read_data.rst +++ b/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 -such that (**A** x **B**) points in the direction of **C**. A +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. 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 diff --git a/doc/src/write_restart.rst b/doc/src/write_restart.rst index a35adffe56..6205f24faf 100644 --- a/doc/src/write_restart.rst +++ b/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 ` 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 ` to convert a restart file to a data file. +another machine. In this case, you can use the :doc:`-r command-line +switch ` 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 - were specified during the initial run is not stored, which means the - new input script must specify any fixes you want to use. Even when - restart information is stored in the file, as it is for some fixes, - commands may need to be re-specified in the new input script, in order - to re-use that information. Details are usually given in the - documentation of the respective command. Also, see the - :doc:`read_restart ` command for general information about - what is stored in a restart file. + simulation is stored in the file. For example, the list of fixes + that were specified during the initial run is not stored, which + means the new input script must specify any fixes you want to use. + Even when restart information is stored in the file, as it is for + some fixes, commands may need to be re-specified in the new input + script, in order to re-use that information. Details are usually + given in the documentation of the respective command. Also, see the + :doc:`read_restart ` command for general information + about what is stored in a restart file. ---------- diff --git a/src/create_box.cpp b/src/create_box.cpp index 8cf6065962..4df23d286f 100644 --- a/src/create_box.cpp +++ b/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);