254 lines
11 KiB
ReStructuredText
254 lines
11 KiB
ReStructuredText
.. index:: create_box
|
|
|
|
create_box command
|
|
==================
|
|
|
|
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 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*
|
|
|
|
.. parsed-literal::
|
|
|
|
*bond/types* value = # of bond types
|
|
*angle/types* value = # of angle types
|
|
*dihedral/types* value = # of dihedral types
|
|
*improper/types* value = # of improper types
|
|
*extra/bond/per/atom* value = # of bonds per atom
|
|
*extra/angle/per/atom* value = # of angles per atom
|
|
*extra/dihedral/per/atom* value = # of dihedrals per atom
|
|
*extra/improper/per/atom* value = # of impropers per atom
|
|
*extra/special/per/atom* value = # of special neighbors per atom
|
|
|
|
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 triclinic/general
|
|
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 triclinic/general
|
|
create box 1 NULL -5 5 -10 10 0 20
|
|
|
|
Description
|
|
"""""""""""
|
|
|
|
This command creates a simulation box. It also partitions the box into
|
|
a regular 3d grid of smaller sub-boxes, one per processor (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 <processors>` command. The partitioning can
|
|
later be changed by the :doc:`balance <balance>` or :doc:`fix balance
|
|
<fix_balance>` commands.
|
|
|
|
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. 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 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})`. In LAMMPS lingo, 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
See the :doc:`Howto triclinic <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 <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
|
|
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 <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
|
|
<region>` command) radically smaller/larger than the extent of the
|
|
atoms you eventually plan to create (e.g., via the
|
|
:doc:`create_atoms <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 <boundary>` command). When using "shrink-wrap"
|
|
boundary conditions (see the :doc:`boundary <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 in LAMMPS allow the box to
|
|
have 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
|
|
previously defined by the :doc:`lattice <lattice>` command.
|
|
|
|
The lattice must be of style *custom* and use its *triclinic/general*
|
|
option. This insures the lattice satisfies the restrictions listed
|
|
above. The *a1, *a2*, *a3* settings of the :doc:`lattice <lattice>`
|
|
command define the edge vectors of a unit cell of the general
|
|
triclinic lattice. This command uses them to define the three edge
|
|
vectors and origin of the general triclinic box as:
|
|
|
|
* **A** = (ahi-alo) * *a1*
|
|
* **B** = (bhi-blo) * *a2*
|
|
* **C** = (chi-clo) * *a3*
|
|
* origin = (alo*a1 + blo*a2 + clo*a3)
|
|
|
|
For 2d general triclinic boxes, clo = -0.5 and chi = 0.5 is required.
|
|
|
|
.. note::
|
|
|
|
LAMMPS allows specification of general triclinic simulation boxes
|
|
as a convenience for users who may be converting data from
|
|
solid-state crystallographic 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 (rotated) 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.
|
|
|
|
----------
|
|
|
|
The optional keywords can be used to create a system that allows for
|
|
bond (angle, dihedral, improper) interactions, or for molecules with
|
|
special 1--2, 1--3, or 1--4 neighbors to be added later. These
|
|
optional keywords serve the same purpose as the analogous keywords
|
|
that can be used in a data file which are recognized by the
|
|
:doc:`read_data <read_data>` command when it sets up a system.
|
|
|
|
Note that if these keywords are not used, then the create_box command
|
|
creates an atomic (non-molecular) simulation that does not allow bonds
|
|
between pairs of atoms to be defined, or a :doc:`bond potential
|
|
<bond_style>` to be specified, or for molecules with special neighbors
|
|
to be added to the system by commands such as :doc:`create_atoms mol
|
|
<create_atoms>`, :doc:`fix deposit <fix_deposit>` or :doc:`fix pour
|
|
<fix_pour>`.
|
|
|
|
As an example, see the examples/deposit/in.deposit.molecule script,
|
|
which deposits molecules onto a substrate. Initially there are no
|
|
molecules in the system, but they are added later by the :doc:`fix
|
|
deposit <fix_deposit>` command. The create_box command in the script
|
|
uses the bond/types and extra/bond/per/atom keywords to allow this.
|
|
If the added molecule contained more than one special bond (allowed by
|
|
default), an extra/special/per/atom keyword would also need to be
|
|
specified.
|
|
|
|
----------
|
|
|
|
Restrictions
|
|
""""""""""""
|
|
|
|
An :doc:`atom_style <atom_style>` and :doc:`region <region>` must have
|
|
been previously defined to use this command.
|
|
|
|
Related commands
|
|
""""""""""""""""
|
|
|
|
:doc:`read_data <read_data>`, :doc:`create_atoms <create_atoms>`,
|
|
:doc:`region <region>`
|
|
|
|
Default
|
|
"""""""
|
|
|
|
none
|