ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

more doc page updates for general tri

Browse Source
This commit is contained in:
Steve Plimpton
2023-11-16 16:35:16 -07:00
parent fc5803188f
commit 4057ee3d62
5 changed files with 179 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
doc/src/create_box.rst
View File

@ -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.
Thus a :doc:`region <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 <processors>` command. The partitioning can later be
changed by the :doc:`balance <balance>` or :doc:`fix balance <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 <processors>` command. The partitioning can
later be changed by the :doc:`balance <balance>` or :doc:`fix balance
<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
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 <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 <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 <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 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 <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.
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 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.
----------

6
doc/src/lattice.rst
View File

@ -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.
----------

8
doc/src/read_data.rst
View File

@ -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

21
doc/src/write_restart.rst
View File

@ -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
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 <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 <read_restart>` command for general information
about what is stored in a restart file.
----------

11
src/create_box.cpp
View File

@ -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);