more work on read_data and doc pages

This commit is contained in:
Steve Plimpton
2023-11-06 16:56:33 -07:00
parent de037f5bd8
commit 612a919e93
9 changed files with 113 additions and 128 deletions

View File

@ -1,29 +1,32 @@
2d simulations
==============
================
2d simulations
================
You must use the :doc:`dimension <dimension>` command to specify a 2d
simulation. The default is 3d.
Make the simulation box periodic in z via the :doc:`boundary <boundary>`
command. This is the default.
A 2d simulation box must be periodic in z as set by the :doc:`boundary
<boundary>` command. This is the default.
If using the :doc:`create_box <create_box>` command, you must define a
simulation box which straddes z = 0.0 in the z dimension since all the
atoms will have a z coordinate of zero. Typicaily the width of box in
the z dimension should be narrow, e.g. -0.5 to 0.5, but that is not
required. An example is:
simulation box which straddles z = 0.0 in the z dimension since all
the atoms will have a z coordinate of zero. Typicaily the width of
box in the z dimension should be narrow, e.g. -0.5 to 0.5, but that is
not required. Example are:
.. code-block:: LAMMPS
create_box 1 -10 10 0 10 -0.5 0.5
create_box 1 -10 10 0 10 -0.25 0.25
Likewise, If using the :doc:`read_data <read_data>` command to define
the simulation box and read in a file of atom coordinates, the default
"zlo zhi" values are -0.5 0.5 for 2d simulations. If the data file
includes that header keyword the zlo/zhi values must straddle z = 0.0.
The z coords for atoms listed in the file must be 0.0 (within epsilon
of zero is also allowed in case the data file was generated by another
program with finite precision).
Likewise, if using the :doc:`read_data <read_data>` command to define
the simulation box and read in a data file of atom coordinates, the
default "zlo zhi" values are -0.5 0.5 for 2d simulations. If the data
file includes that header keyword the zlo/zhi values must straddle z =
0.0. Also, the z coord for each atom listed in the file must be 0.0.
A value within epsilon of zero is also allowed in case the data file
was generated by another program with finite precision, in which case
the z coord for the atom will be set to 0.0.
Use the :doc:`fix enforce2d <fix_enforce2d>` command as the last fix
defined in the input script. It ensures that the z-components of

View File

@ -48,13 +48,17 @@ 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 next section
on non-equilibrium MD (NEMD) simulations.
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 now be arbitrary vectors, so
long as they are non-zero, distinct, and not co-planar.
(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 two 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
@ -64,46 +68,45 @@ 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. Note that a
general triclinic box can either be *right-handed* if (**A** x **B**)
points in the direction of **C**, or it can be *left-handed* if (**A**
x **B**) points opposite to **C**.
**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 form: **A** = (xhi-xlo,0,0), **B** =
(xy,yhi-ylo,0), **C** = (xz,yz,zhi-zlo). So there are 9 parameters in
total. The restricted form of edge vectors requires that **A** is
along the x-axis, **B** is in the xy plane with a y-component in
the +y direction, and **C** has a z-component in the +z direction.
Note that a restricted triclinic box is always *right-handed* so
that (**A** x **B**) points in the direction of **C**.
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 originally orthogonal box to change it
into a restricted triclinic parallelepiped.
applied to edges of faces of an orthogonal box to change it into a
restricted triclinic parallelepiped.
.. note::
Any general triclinic box (i.e. solid-state crystal basis vectors)
can be rotated in 3d around its origin (and reflected across a
plane if necessary to flip from a left-handed coordinate system to
right-handed) 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.
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 both
restricted and general triclinic simulation boxes. Thus you can check
the restricted triclinic box parameters LAMMPS generates to
rotate/reflect a general triclinic box to restricted triclinic form.
the restricted triclinic box parameters LAMMPS generates to rotate a
general triclinic box to restricted triclinic form.
For restricted triclinic boxes there are 9 thermo keywords for
For restricted triclinic boxes these are the 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. For both
orthogonal and restricted triclinic boxes, the thermo keywords
lx/ly/lz refer to the box sizes, namely lx = xhi - xlo, etc.
general triclinic boxes these are the 12 thermo keywords for
(xlo,ylo,zhi) and the components of the **A**, **B**, **C** edge
vectors. For both orthogonal and restricted triclinic boxes, the
thermo keywords lx/ly/lz refer to the box sizes, namely lx = xhi -
xlo, etc. Lx,ly,lz are the box edge vector lengths for orthogonal and
restricted/general triclinic simulation boxes.
The remainder of this doc page explains (a) how LAMMPS operates with
general triclinic simulation boxes, (b) mathematical transformations
@ -124,7 +127,7 @@ 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
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
@ -139,31 +142,39 @@ This means 4 things which are important to understand:
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 restriced triclinic (and vice versa) is a rotation +
optional reflection from one set of coordinate axes to another. For
orthogonal and restricted triclinic systems, the coordinate axes are
the standard x,y,z axes. For a general triclinic system, those
coordinate axes are rotated in 3d. The optional reflection flips
the axes from right-handed to left-handed if necessary. The 3
rotated/reflected axes remain mutually orthogonal. For all 3 kinds
of systems (orthogonal, restricted, general), per-atom quantities
(e.g. coords, velocities) are input/output as values consistent with
the corresponding coordinate axes.
* Other LAMMPS commands such as the :doc:`boundary <boundary>` or
:doc:`region <region>` or :doc:`velocity <velocity>` or :doc:`set
<set>` commands, operate on restricted triclinic systems even if a
general triclinic system was defined initially. For an example, see
the paragraph below the folliowing list.
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. I.e. a velocity vector that 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 this rule
affects when the 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
preceeding 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 **A**, **B**, **C** edge vectors of 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 <dump_modify>` - switch a dump file between restrictied and general triclinic format
* :doc:`dump_modify <dump_modify>` - toggle a dump file between restrictied and general triclinic format
* :doc:`thermo_style <thermo_style>` - output the pressure tensor in
general triclinic format
* :doc:`thermo_modify <thermo_modify>` - toggle thermo-style output
@ -171,42 +182,15 @@ This is the list of commands which have general triclinic options:
* :doc:`read_restart <read_restart>` - read a restart file for a general tricliinc system
* :doc:`write_restart <read_restart>` - write a restart file for a general tricliinc system
As an example, consider the velocity of each atom in a general
triclinic system. In a general triclinic data file, each atom will
have coordinates inside a general triclinic box with arbitrary edge
vectors **A**, **B**, **C**. If the file has a "Velocities" section
then the velocity vector of each atom should be in a direction
consistent with the orientation of the general triclnic coordinate
axes.
When LAMMPS internally converts the general triclinic system to
restricted triclinic, the coordinates of all atoms are transformed
(rotation + optional reflection) to be inside the new restricted
triclinic box. Likewise the velocity vectors are transformed.
If the :doc:`velocity <velocity>` command is used to set an x-velocity
component, it will use the coordinate axes of the restricted box.
If the atoms and their velocities are output via the :doc:`write_data
<write_data>` or :doc:`dump custom <dump>` commands, the coordinates
will be transformed (inverse rotation + optional reflection) to be
inside the general triclinic box. Likewise the velocity vector for
each atom will be transformed from restricted to general triclinic.
Any other vector quantities associated with atoms (magnetic moments,
spins, etc) are transformed in a similar manner back-and-forth between
general and restricted box orientations.
----------
Transformation from general to restricted triclinic boxes
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Let **A**,\ **B**,\ **C** be the edge vectors of a general triclinic
simulation box. Assume that **A** x **B** . **C** > 0. The
equivalent LAMMPS **a**,\ **b**,\ **c** for a restricted triclinic box
are a linear rotation of **A**, **B**, and **C** and can be computed
as follows:
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::
@ -228,15 +212,10 @@ symbol (\^) indicates the corresponding unit vector. :math:`\beta` and
:math:`\gamma` are angles between the **A**, **B**, **C** vectors
as described below.
If **A** x **B** . **C** < 0 the above equations are not valid for
**c**\ . In this case, it is necessary to first apply an
inversion. This can be achieved by interchanging two of the **A**,
**B**, **C** vectors or by changing the sign of one of them.
For consistency, the same rotation/inversion 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
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 resetricted
triclinic basis. The transformation is given by the following
equation:
@ -335,9 +314,9 @@ 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 enforce
a shift in coordinates due to periodic boundary conditions across the
y or z boundaries. See the doc page for the :doc:`boundary
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.

View File

@ -83,10 +83,10 @@ See the :doc:`Howto triclinic <Howto_triclinic>` page for a
description of both general and restricted triclinic boxes and how to
define them. General triclinic boxes (arbitrary edge vectors **A**,
**B**, and **C**) are converted internally to restricted triclinic
boxes with tilt factors (xy,xz,yz) added to skew an otherwise
orthogonal box.
boxes with tilt factors (xy,xz,yz) which skew an otherwise orthogonal
box.
The boundary <boundary> command settings expalined above for the 6
The boundary <boundary> command settings explained above for the 6
faces of an orthogonal box also apply in similar manner to the 6 faces
of a restricted triclinix box (and thus to the corresponding 6 faces
of a general triclinic box), with the following context.

View File

@ -1038,7 +1038,7 @@ void Atom::deallocate_topology()
/* ----------------------------------------------------------------------
unpack N lines from Atom section of data file
call style-specific routine to parse line
call atom-style specific method to parse each line
triclinic_general = 1 if data file defines a general triclinic box
------------------------------------------------------------------------- */
@ -1217,6 +1217,8 @@ void Atom::data_atoms(int n, char *buf, tagint id_offset, tagint mol_offset,
if (coord[0] >= sublo[0] && coord[0] < subhi[0] &&
coord[1] >= sublo[1] && coord[1] < subhi[1] &&
coord[2] >= sublo[2] && coord[2] < subhi[2]) {
// atom-style specific method parses single line
avec->data_atom(xdata,imagedata,values,typestr);
typestr = utils::utf8_subst(typestr);

View File

@ -1659,7 +1659,6 @@ void AtomVec::data_atom(double *coord, imageint imagetmp, const std::vector<std:
{
int m, n, datatype, cols;
void *pdata;
double vector[3];
int nlocal = atom->nlocal;
if (nlocal == nmax) grow(0);
@ -2227,7 +2226,8 @@ void AtomVec::write_improper(FILE *fp, int n, tagint **buf, int index)
/* ----------------------------------------------------------------------
convert info input by read_data from general to restricted triclinic
parent class only operates on data from Velocities section of data file
atom coords are converted in Atom::data_atoms()
parent class operates on data from Velocities section of data file
child classes operate on all other data: Atoms, Ellipsoids, Lines, Triangles, etc
------------------------------------------------------------------------- */
@ -2256,6 +2256,7 @@ void AtomVec::read_data_general_to_restricted(int nlocal_previous, int nlocal)
/* ----------------------------------------------------------------------
convert info output by write_data from restricted to general triclinic
create "hold" copy of original restricted data to restore after data file is written
parent class only operates on x and data from Velocities section of data file
child classes operate on all other data: Atoms, Ellipsoids, Lines, Triangles, etc
------------------------------------------------------------------------- */

View File

@ -292,12 +292,13 @@ void Domain::set_global_box()
}
// update general triclinic box if defined
// reset ABC edge vectors from restricted triclinic box
// boxlo = lower left corner of general triclinic box
// reset general tri ABC edge vectors from restricted tri box
if (triclinic_general) {
double aprime[3],bprime[3],cprime[3];
// A'B'C' = edge vectors of restricted triclinic box
aprime[0] = boxhi[0] - boxlo[0];
aprime[1] = aprime[2] = 0.0;
bprime[0] = xy;

View File

@ -40,7 +40,7 @@ class Domain : protected Pointers {
// 3 = shrink-wrap non-per w/ min
int triclinic; // 0 = orthog box, 1 = triclinic (restricted or general)
int triclinic_general; // 1 if mapping to/from general triclinic is stored, 0 if not
int triclinic_general; // 1 if general <-> restricted tri mapping is stored, 0 if not
// orthogonal box
@ -50,7 +50,7 @@ class Domain : protected Pointers {
double prd_half[3]; // array form of half dimensions
// restricted triclinic box
// xyzprd,xyzprd_half and prd,prd_half = same as if not tilted
// xyz prd,xyz prd_half and prd,prd_half = same as if not tilted
double prd_lamda[3]; // lamda box = (1,1,1)
double prd_half_lamda[3]; // lamda half box = (0.5,0.5,0.5)

View File

@ -576,7 +576,7 @@ void ReadData::command(int narg, char **arg)
if (!triclinic_general) {
// orthongal box
// orthogonal or restricted triclinic box
domain->boxlo[0] = boxlo[0];
domain->boxhi[0] = boxhi[0];
@ -605,8 +605,6 @@ void ReadData::command(int narg, char **arg)
// change simulation box to be union of existing box and new box + shift
// only done if firstpass and not first data file
// for restricted triclinic, new tilt factors not allowed
// for general triclinic, different new box and shift not allowed
if (firstpass && addflag != NONE) {
@ -670,7 +668,7 @@ void ReadData::command(int narg, char **arg)
int flag_all;
MPI_Allreduce(&iflag, &flag_all, 1, MPI_INT, MPI_SUM, world);
if ((flag_all > 0) && (comm->me == 0))
error->warning(FLERR, "Non-zero image flags with growing box leads to bad coordinates");
error->warning(FLERR, "Non-zero image flags with growing box can produce bad coordinates");
}
}
@ -689,6 +687,7 @@ void ReadData::command(int narg, char **arg)
lmap = new LabelMap(lmp, ntypes, nbondtypes, nangletypes, ndihedraltypes, nimpropertypes);
}
// -------------------------------------------------------------------------------------
// rest of data file is Sections
// read in any order, except where error checks
// customize for new sections
@ -1391,10 +1390,9 @@ void ReadData::header(int firstpass)
if (addflag == NONE) atom->nimpropertypes = nimpropertypes + extra_improper_types;
// these settings only used by first data file
// also, these are obsolescent. we parse them to maintain backward
// compatibility, but the recommended way is to set them via keywords
// in the LAMMPS input file. In case these flags are set in both,
// the input and the data file, we use the larger of the two.
// NOTEL these are now obsolete, we parse them to maintain backward compatibility
// the recommended way is to set them via command keywords in the input script
// if these flags are set both ways, the larger of the two values is used
} else if (strstr(line, "extra bond per atom")) {
if (addflag == NONE) extra_flag_value = utils::inumeric(FLERR, words[0], false, lmp);

View File

@ -59,15 +59,16 @@ class ReadData : public Command {
class LabelMap *lmap;
// box info
// box info read from file
int triclinic, triclinic_general;
int xloxhi_flag, yloyhi_flag, zlozhi_flag, tilt_flag;
int avec_flag, bvec_flag, cvec_flag, abc_origin_flag;
double boxlo[3], boxhi[3];
double xy, xz, yz;
double avec[3], bvec[3], cvec[3];
double abc_origin[3];
int triclinic, triclinic_general;
int xloxhi_flag, yloyhi_flag, zlozhi_flag, tilt_flag;
int avec_flag, bvec_flag, cvec_flag, abc_origin_flag;
// optional args