+By default, LAMMPS uses an orthogonal simulation box to encompass the particles. The boundary command sets the boundary -conditions of the box (periodic, non-periodic, etc). If the box size -is xprd by yprd by zprd then the 3 mutually orthogonal edge vectors of -an orthogonal simulation box are a = (xprd,0,0), b = (0,yprd,0), and c -= (0,0,zprd). +conditions of the box (periodic, non-periodic, etc). The orthogonal +box has its "origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors +starting from the origin given by A = (xhi-xlo,0,0); B = +(0,yhi-ylo,0); C = (0,0,zhi-zlo). The 6 parameters +(xlo,xhi,ylo,yhi,zlo,zhi) are defined at the time the simluation box +is created, e.g. by the create_box or +read_data or read_restart +commands. Additionally, LAMMPS defines box size parameters lx,ly,lz +where lx = xhi-xlo, and similarly in the y and z dimensions. The 6 +parameters, as well as lx,ly,lz, can be output via the thermo_style +custom command.
-LAMMPS also allows non-orthogonal simulation boxes (triclinic -symmetry) to be defined with 3 additional "tilt" parameters which -change the edge vectors of the simulation box to be a = (xprd,0,0), b -= (xy,yprd,0), and c = (xz,yz,zprd). The xy, xz, and yz parameters -can be positive or negative. The simulation box must be periodic in -both dimensions associated with a tilt factor. For example, if xz != -0.0, then the x and z dimensions must be periodic. +
LAMMPS also allows simulations to be perfored in non-orthogonal +simulation boxes shaped as a parallelepiped with triclinic symmetry. +The parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by +3 edge vectors starting from the origin given by A = (xhi-xlo,0,0); B += (xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). Xy,xz,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. Note that in +LAMMPS the triclinic simulation box edge vectors A,B,C cannot be +arbitrary vectors. As indicated, A must be aligned with the x axis, B +must be in the xy plane, and C is arbitrary. However, this is not a +restriction since it is possible to rotate any set of 3 crystal basis +vectors so that they meet this restriction. +
+The 9 parameters (xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) are defined at the +time the simluation box is created. This happens in one of 3 ways. +If the create_box command is used with a region of +style prism, then a triclinic box is setup. See the +region command for details. If the +read_data command is used to define the simulation +box, and the header of the data file contains a line with the "xy xz +yz" keyword, then a triclinic box is setup. See the +read_data command for details. Finally, if the +read_restart command reads a restart file which +was written from a simulation using a triclinic box, then a triclinic +box will be setup for the restarted simulation. +
+Note that you can define a triclinic box with all 3 tilt factors = +0.0, so that it is initially orthogonal. This is necessary if the box +will become non-orthogonal, e.g. due to the fix npt or +fix deform commands. Alternatively, you can use the +change_box command to convert a simulation box from +orthogonal to triclinic and vice versa. +
+As with orthogonal boxes, LAMMPS defines triclinic box size parameters +lx,ly,lz where lx = xhi-xlo, and similarly in the y and z dimensions. +The 9 parameters, as well as lx,ly,lz, can be output via the +thermo_style custom command.
To avoid extremely tilted boxes (which would be computationally inefficient), no tilt factor can skew the box more than half the @@ -749,43 +787,62 @@ the x box length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then configurations -with tilt = ..., -15, -5, 5, 15, 25, ... are all equivalent. +with tilt = ..., -15, -5, 5, 15, 25, ... are geometrically all +equivalent.
-You tell LAMMPS to use a non-orthogonal box when the simulation box is -defined. This happens in one of 3 ways. If the -create_box command is used with a region of style -prism, then a non-orthogonal domain is setup. See the -region command for details. If the -read_data command is used to define the simulation -box, and the header of the data file contains a line with the "xy xz -yz" keyword, then a non-orthogonal domain is setup. See the -read_data command for details. Finally, if the -read_restart command reads a restart file which -was written from a simulation using a triclinic box, then a -non-orthogonal box will be enabled for the restarted simulation. +
Triclinic crystal structures are often defined using three lattice +constants a, b, and c, and three angles alpha, beta and +gamma. Note that in this nomenclature, the a,b,c lattice constants +are the scalar lengths of the 3 A,B,C edge vectors defined above. The +relationship between these 6 quantities (a,b,c,alpha,beta,gamma) and +the LAMMPS box sizes (lx,ly,lz) = (xhi-xlo,yhi-ylo,zhi-zlo) and tilt +factors (xy,xz,yz) is as follows:
-Note that you can define a non-orthogonal box with all 3 tilt factors -= 0.0, so that it is initially orthogonal. This is necessary if the -box will become non-orthogonal. Alternatively, you can use the -change_box command to convert a simulation box from -orthogonal to non-orthogonal and vice versa. +
+As discussed on the dump command doc page, when the BOX +BOUNDS for a snapshot is written to a dump file for a triclinic box, +an orthogonal bounding box which encloses the triclinic simulation box +is output, along with the 3 tilt factors (xy, xz, yz) of the triclinic +box, formatted as follows:
-One use of non-orthogonal boxes is to model solid-state crystals with -triclinic symmetry. The lattice command can be used -with non-orthogonal basis vectors to define a lattice that will tile a -non-orthogonal simulation box via the create_atoms -command. Note that while the box edge vectors a,b,c cannot be -arbitrary vectors (e.g. a must be aligned with the x axis), it is -possible to rotate any crystal's basis vectors so that they meet these -restrictions. +
ITEM: BOX BOUNDS xy xz yz +xlo_bound xhi_bound xy +ylo_bound yhi_bound xz +zlo_bound zhi_bound yz ++
This bounding box is convenient for many visualization programs and is +calculated from the 9 triclinic box parameters +(xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) as follows:
-A second use of non-orthogonal boxes is to shear a bulk solid to study -the response of the material. The fix deform -command can be used for this purpose. It allows dynamic control of -the xy, xz, and yz tilt factors as a simulation runs. +
xlo_bound = xlo + MIN(0.0,xy,xz,xy+xz) +xhi_bound = xhi + MAX(0.0,xy,xz,xy+xz) +ylo_bound = ylo + MIN(0.0,yz) +yhi_bound = yhi + MAX(0.0,yz) +zlo_bound = zlo +zhi_bound = zhi ++
These formulas can be inverted if you need to convert the bounding box +back into the triclinic box parameters, e.g. xlo = xlo_bound - +MIN(0.0,xy,xz,xy+xz).
-Another use of non-orthogonal boxes is to perform non-equilibrium MD -(NEMD) simulations, as discussed in the next section. +
One use of triclinic simulation boxes is to model solid-state crystals +with triclinic symmetry. The lattice command can be +used with non-orthogonal basis vectors to define a lattice that will +tile a triclinic simulation box via the +create_atoms command. +
+A second use is to run Parinello-Rahman dyanamics via the fix +npt command, which will adjust the xy, xz, yz tilt +factors to compensate for off-diagonal components of the pressure +tensor. The analalog for an energy minimization is +the fix box/relax command. +
+A third use is to shear a bulk solid to study the response of the +material. The 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.
If the region is not of style prism, then LAMMPS encloses the region -(block, sphere, etc) with an axis-aligned (orthogonal) box which -becomes the simulation domain. +(block, sphere, etc) with an axis-aligned orthogonal bounding box +which becomes the simulation domain.
If the region is of style prism, LAMMPS creates a non-orthogonal simulation domain shaped as a parallelepiped with triclinic symmetry. -See the region prism command for a description of how -the shape of the parallelepiped is defined. The parallelepiped has -its "origin" at (xlo,ylo,zlo) and 3 edge vectors starting from its -origin given by a = (xhi-xlo,0,0); b = (xy,yhi-ylo,0); c = -(xz,yz,zhi-zlo). +As defined by the region prism command, the +parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by 3 +edge vectors starting from the origin given by A = (xhi-xlo,0,0); B = +(xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). Xy,xz,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 parallelipiped.
-A prism region used with the create_box command must have tilt factors -(xy,xz,yz) that do not skew the box more than half the distance of the -parallel box length. For example, if xlo = 2 and xhi = 12, then the x -box length is 10 and the xy tilt factor must be between -5 and 5. -Similarly, both xz and yz must be between -(xhi-xlo)/2 and -+(yhi-ylo)/2. Note that this is not a limitation, since if the -maximum tilt factor is 5 (as in this example), then configurations -with tilt = ..., -15, -5, 5, 15, 25, ... are all equivalent. +
A prism region used with the create_box command must have tilt +factors (xy,xz,yz) that do not skew the box more than half the +distance of the parallel box length. For example, if xlo = 2 and xhi += 12, then the x box length is 10 and the xy tilt factor must be +between -5 and 5. Similarly, both xz and yz must be between +-(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, +since if the maximum tilt factor is 5 (as in this example), then +configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all +geometrically equivalent. +
+See this section of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, and +how to transform these parameters into other commonly used triclinic +representations.
When a prism region is used, the simulation domain must be periodic in any dimensions with a non-zero tilt factor, as defined by the boundary command. I.e. if the xy tilt factor is non-zero, then both the x and y dimensions must be periodic. Similarly, x and z must be periodic if xz is non-zero and y and z must -be periodic if yz is non-zero. +be periodic if yz is non-zero. Also note that if your simulation will +tilt the box, e.g. via the fix deform command, the +simulation box must be defined as triclinic, even if the tilt factors +are initially 0.0.
IMPORTANT NOTE: If the system is non-periodic (in a dimension), then you should not make the lo/hi box dimensions (as defined in your diff --git a/doc/create_box.txt b/doc/create_box.txt index ccd9470d87..7259dca492 100644 --- a/doc/create_box.txt +++ b/doc/create_box.txt @@ -29,32 +29,43 @@ The argument N is the number of atom types that will be used in the simulation. If the region is not of style {prism}, then LAMMPS encloses the region -(block, sphere, etc) with an axis-aligned (orthogonal) box which -becomes the simulation domain. +(block, sphere, etc) with an axis-aligned orthogonal bounding box +which becomes the simulation domain. If the region is of style {prism}, LAMMPS creates a non-orthogonal simulation domain shaped as a parallelepiped with triclinic symmetry. -See the "region prism"_region.html command for a description of how -the shape of the parallelepiped is defined. The parallelepiped has -its "origin" at (xlo,ylo,zlo) and 3 edge vectors starting from its -origin given by a = (xhi-xlo,0,0); b = (xy,yhi-ylo,0); c = -(xz,yz,zhi-zlo). +As defined by the "region prism"_region.html command, the +parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by 3 +edge vectors starting from the origin given by A = (xhi-xlo,0,0); B = +(xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). {Xy,xz,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 parallelipiped. -A prism region used with the create_box command must have tilt factors -(xy,xz,yz) that do not skew the box more than half the distance of the -parallel box length. For example, if xlo = 2 and xhi = 12, then the x -box length is 10 and the xy tilt factor must be between -5 and 5. -Similarly, both xz and yz must be between -(xhi-xlo)/2 and -+(yhi-ylo)/2. Note that this is not a limitation, since if the -maximum tilt factor is 5 (as in this example), then configurations -with tilt = ..., -15, -5, 5, 15, 25, ... are all equivalent. +A {prism} region used with the create_box command must have tilt +factors (xy,xz,yz) that do not skew the box more than half the +distance of the parallel box length. For example, if xlo = 2 and xhi += 12, then the x box length is 10 and the xy tilt factor must be +between -5 and 5. Similarly, both xz and yz must be between +-(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, +since if the maximum tilt factor is 5 (as in this example), then +configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all +geometrically equivalent. + +See "this section"_Section_howto.html#4_12 of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, and +how to transform these parameters into other commonly used triclinic +representations. When a prism region is used, the simulation domain must be periodic in any dimensions with a non-zero tilt factor, as defined by the "boundary"_boundary.html command. I.e. if the xy tilt factor is non-zero, then both the x and y dimensions must be periodic. Similarly, x and z must be periodic if xz is non-zero and y and z must -be periodic if yz is non-zero. +be periodic if yz is non-zero. Also note that if your simulation will +tilt the box, e.g. via the "fix deform"_fix_deform.html command, the +simulation box must be defined as triclinic, even if the tilt factors +are initially 0.0. IMPORTANT NOTE: If the system is non-periodic (in a dimension), then you should not make the lo/hi box dimensions (as defined in your diff --git a/doc/dump.html b/doc/dump.html index 8ae659b10e..3ca213b8b5 100644 --- a/doc/dump.html +++ b/doc/dump.html @@ -140,7 +140,7 @@ this format. self-describing in the following sense.
The dimensions of the simulation box are included in each snapshot. -For orthogonal simulation boxes this is formatted as: +For an orthogonal simulation box this information is is formatted as:
ITEM: BOX BOUNDS xlo xhi @@ -150,37 +150,24 @@ zlo zhiwhere xlo,xhi are the maximum extents of the simulation box in the x-dimension, and similarly for y and z.
-For triclinic simulation boxes (non-orthogonal), the tilt factors are -also included, as a 3rd value on each line: +
For triclinic simulation boxes (non-orthogonal), an orthogonal +bounding box which encloses the triclinic simulation box is output, +along with the 3 tilt factors (xy, xz, yz) of the triclinic box, +formatted as follows:
ITEM: BOX BOUNDS xy xz yz xlo_bound xhi_bound xy ylo_bound yhi_bound xz zlo_bound zhi_bound yz-See the region prism or read_data -commands for a description of tilt factors in LAMMPS, and their -relationship to other nomenclatures for triclinic geometries, -e.g. using 3 lattice constants a, b, and c, and 3 angles -alpha, beta and gamma. +
This bounding box is convenient for many visualization programs.
-IMPORTANT NOTE: As the notation above indicates, for triclinic -simulation boxes, the 6 box bounds written to the dump file -(xlo_bound,xhi_bound,ylo_bound,yhi_bound,zlo_bound,zhi_bound) are NOT -equivalent to the 6 extents (xlo,xhi,ylo,yhi,zlo,zhi) in the -orthogoonal case. Instead they are the extent in each dimension of -the smallest orthogonal "bounding box" that encapsulates the entire -tricilinc simulation box, including the effects of any tilt. This -bounding box is convenient for many visualization programs and is -calculated as follows: +
See this section of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, simple +formulas for how the 6 bounding box extents (xlo_bound,xhi_bound,etc) +are calculated from the triclinic parameters, and how to transform +those parameters into other commonly used triclinic representations.
-xlo_bound = MIN(xlo,xlo+xy,xlo+xz,xlo+xy+xz) -xhi_bound = MAX(xhi,xhi+xy,xhi+xz,xhi+xy+xz) -ylo_bound = MIN(ylo,ylo+yz) -yhi_bound = MAX(yhi,yhi+yz) -zlo_bound = zlo -zhi_bound = zhi -The "ITEM: ATOMS" line in each snapshot lists column descriptors for the per-atom lines that follow. For example, the descriptors would be "id type xs ys zs" for the default atom style, and would be the atom diff --git a/doc/dump.txt b/doc/dump.txt index d0c052b01c..f29ce44667 100644 --- a/doc/dump.txt +++ b/doc/dump.txt @@ -130,7 +130,7 @@ For post-processing purposes the {atom} and {custom} text files are self-describing in the following sense. The dimensions of the simulation box are included in each snapshot. -For orthogonal simulation boxes this is formatted as: +For an orthogonal simulation box this information is is formatted as: ITEM: BOX BOUNDS xlo xhi @@ -140,36 +140,23 @@ zlo zhi :pre where xlo,xhi are the maximum extents of the simulation box in the x-dimension, and similarly for y and z. -For triclinic simulation boxes (non-orthogonal), the tilt factors are -also included, as a 3rd value on each line: +For triclinic simulation boxes (non-orthogonal), an orthogonal +bounding box which encloses the triclinic simulation box is output, +along with the 3 tilt factors (xy, xz, yz) of the triclinic box, +formatted as follows: ITEM: BOX BOUNDS xy xz yz xlo_bound xhi_bound xy ylo_bound yhi_bound xz zlo_bound zhi_bound yz :pre -See the "region prism"_region.html or "read_data"_read_data.html -commands for a description of tilt factors in LAMMPS, and their -relationship to other nomenclatures for triclinic geometries, -e.g. using 3 lattice constants {a}, {b}, and {c}, and 3 angles -{alpha}, {beta} and {gamma}. +This bounding box is convenient for many visualization programs. -IMPORTANT NOTE: As the notation above indicates, for triclinic -simulation boxes, the 6 box bounds written to the dump file -(xlo_bound,xhi_bound,ylo_bound,yhi_bound,zlo_bound,zhi_bound) are NOT -equivalent to the 6 extents (xlo,xhi,ylo,yhi,zlo,zhi) in the -orthogoonal case. Instead they are the extent in each dimension of -the smallest orthogonal "bounding box" that encapsulates the entire -tricilinc simulation box, including the effects of any tilt. This -bounding box is convenient for many visualization programs and is -calculated as follows: - -xlo_bound = MIN(xlo,xlo+xy,xlo+xz,xlo+xy+xz) -xhi_bound = MAX(xhi,xhi+xy,xhi+xz,xhi+xy+xz) -ylo_bound = MIN(ylo,ylo+yz) -yhi_bound = MAX(yhi,yhi+yz) -zlo_bound = zlo -zhi_bound = zhi :pre +See "this section"_Section_howto.html#4_12 of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, simple +formulas for how the 6 bounding box extents (xlo_bound,xhi_bound,etc) +are calculated from the triclinic parameters, and how to transform +those parameters into other commonly used triclinic representations. The "ITEM: ATOMS" line in each snapshot lists column descriptors for the per-atom lines that follow. For example, the descriptors would be diff --git a/doc/read_data.html b/doc/read_data.html index ffe8bfdf7c..3c0ff192d5 100644 --- a/doc/read_data.html +++ b/doc/read_data.html @@ -82,7 +82,7 @@ is different than the default.
The initial simulation box size is determined by the lo/hi settings. In any dimension, the system may be periodic or non-periodic; see the @@ -91,38 +91,37 @@ In any dimension, the system may be periodic or non-periodic; see the
If the xy xz yz line does not appear, LAMMPS will set up an axis-aligned (orthogonal) simulation box. If the line does appear, LAMMPS creates a non-orthogonal simulation domain shaped as a -parallelepiped with triclinic symmetry. See the region -prism command for a description of how the extent of the -parallelepiped is defined. The parallelepiped has its "origin" at -(xlo,ylo,zlo) and 3 edge vectors starting from the origin given by a = -(xhi-xlo,0,0); b = (xy,yhi-ylo,0); c = (xz,yz,zhi-zlo). Note that if -your simulation will tilt the box, e.g. via the fix -deform command, the simulation box must be triclinic, -even if the tilt factors are initially 0.0. +parallelepiped with triclinic symmetry. The parallelepiped has its +"origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors starting +from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C = +(xz,yz,zhi-zlo). Xy,xz,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.
The tilt factors (xy,xz,yz) can not skew the box more than half the -distance of the parallel box length. For example, if xlo = 2 and xhi -= 12, then the x box length is 10 and the xy tilt factor must be -between -5 and 5. Similarly, both xz and yz must be between --(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, -since if the maximum tilt factor is 5 (as in this example), then -configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all -equivalent. +distance of the corresponding parallel box length. For example, if +xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt +factor must be between -5 and 5. Similarly, both xz and yz must be +between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a +limitation, since if the maximum tilt factor is 5 (as in this +example), then configurations with tilt = ..., -15, -5, 5, 15, 25, +... are all geometrically equivalent.
-Crystal structures are often defined using three lattice constants -a, b, and c, and three angles alpha, beta and gamma. The -relationships between these quantities and the LAMMPS box dimensions -(lx,ly,lz) = (xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) are -as follows: +
See this section of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, and +how to transform these parameters into other commonly used triclinic +representations.
-
-When a triclinic system is used, the simulation domain must be periodic in any dimensions with a non-zero tilt factor, as defined by the boundary command. I.e. if the xy tilt factor is non-zero, then both the x and y dimensions must be periodic. Similarly, x and z must be periodic if xz is non-zero and y and z must -be periodic if yz is non-zero. +be periodic if yz is non-zero. Also note that if your simulation will +tilt the box, e.g. via the fix deform command, the +simulation box must be defined as triclinic, even if the tilt factors +are initially 0.0.
For 2d simulations, the zlo zhi values should be set to bound the z coords for atoms that appear in the file; the default of -0.5 0.5 is diff --git a/doc/read_data.txt b/doc/read_data.txt index d8292ee7ec..8f226ed90f 100644 --- a/doc/read_data.txt +++ b/doc/read_data.txt @@ -79,7 +79,7 @@ is different than the default. {xlo xhi} = simulation box boundaries in x dimension {ylo yhi} = simulation box boundaries in y dimension {zlo zhi} = simulation box boundaries in z dimension -{xy xz yz} = simulation box tilt factors for triclinic domain :ul +{xy xz yz} = simulation box tilt factors for triclinic system :ul The initial simulation box size is determined by the lo/hi settings. In any dimension, the system may be periodic or non-periodic; see the @@ -88,38 +88,37 @@ In any dimension, the system may be periodic or non-periodic; see the If the {xy xz yz} line does not appear, LAMMPS will set up an axis-aligned (orthogonal) simulation box. If the line does appear, LAMMPS creates a non-orthogonal simulation domain shaped as a -parallelepiped with triclinic symmetry. See the "region -prism"_region.html command for a description of how the extent of the -parallelepiped is defined. The parallelepiped has its "origin" at -(xlo,ylo,zlo) and 3 edge vectors starting from the origin given by a = -(xhi-xlo,0,0); b = (xy,yhi-ylo,0); c = (xz,yz,zhi-zlo). Note that if -your simulation will tilt the box, e.g. via the "fix -deform"_fix_deform.html command, the simulation box must be triclinic, -even if the tilt factors are initially 0.0. +parallelepiped with triclinic symmetry. The parallelepiped has its +"origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors starting +from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C = +(xz,yz,zhi-zlo). {Xy,xz,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. The tilt factors (xy,xz,yz) can not skew the box more than half the -distance of the parallel box length. For example, if xlo = 2 and xhi -= 12, then the x box length is 10 and the xy tilt factor must be -between -5 and 5. Similarly, both xz and yz must be between --(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, -since if the maximum tilt factor is 5 (as in this example), then -configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all -equivalent. +distance of the corresponding parallel box length. For example, if +xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt +factor must be between -5 and 5. Similarly, both xz and yz must be +between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a +limitation, since if the maximum tilt factor is 5 (as in this +example), then configurations with tilt = ..., -15, -5, 5, 15, 25, +... are all geometrically equivalent. -Crystal structures are often defined using three lattice constants -{a}, {b}, and {c}, and three angles {alpha}, {beta} and {gamma}. The -relationships between these quantities and the LAMMPS box dimensions -(lx,ly,lz) = (xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) are -as follows: - -:c,image(Eqs/box.jpg) +See "this section"_Section_howto.html#4_12 of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, and +how to transform these parameters into other commonly used triclinic +representations. When a triclinic system is used, the simulation domain must be periodic in any dimensions with a non-zero tilt factor, as defined by the "boundary"_boundary.html command. I.e. if the xy tilt factor is non-zero, then both the x and y dimensions must be periodic. Similarly, x and z must be periodic if xz is non-zero and y and z must -be periodic if yz is non-zero. +be periodic if yz is non-zero. Also note that if your simulation will +tilt the box, e.g. via the "fix deform"_fix_deform.html command, the +simulation box must be defined as triclinic, even if the tilt factors +are initially 0.0. For 2d simulations, the {zlo zhi} values should be set to bound the z coords for atoms that appear in the file; the default of -0.5 0.5 is diff --git a/doc/region.html b/doc/region.html index 37f5dc1374..80eaaf532c 100644 --- a/doc/region.html +++ b/doc/region.html @@ -151,35 +151,29 @@ half-space in the direction of the normal vector; see the discussion of the side option below.
For style prism, a parallelepiped is defined (it's too hard to spell -parallelepiped in an input script!). Think of the parallelepiped as -initially an axis-aligned orthogonal box with the same xyz lo/hi -parameters as region style block would define. Then, while holding -the (xlo,ylo,zlo) corner point fixed, the box is "skewed" or "tilted" -in 3 directions. First, for the lower xy face of the box, the xy -factor is how far the upper y edge is shifted in the x direction. The -lower xy face is now a parallelogram. A plus or minus value for xy -can be specified; 0.0 means no tilt. Then, the upper xy face of the -box is translated in the x and y directions by xz and yz. This -results in a parallelepiped whose "origin" is at (xlo,ylo,zlo) with 3 -edge vectors starting from its origin given by a = (xhi-xlo,0,0); b = -(xy,yhi-ylo,0); c = (xz,yz,zhi-zlo). +parallelepiped in an input script!). The parallelepiped has its +"origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors starting +from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C = +(xz,yz,zhi-zlo). Xy,xz,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.
-Crystal structures are often defined using three lattice constants -a, b, and c, and three angles alpha, beta and gamma. The -relationships between these quantities and a prism with (lx,ly,lz) = -(xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) are as follows: -
-
-A prism region used with the create_box command must -have tilt factors (xy,xz,yz) that do not skew the box more than half -the distance of the parallel box length. For example, if xlo = 2 and +
A prism region that will be used with the create_box +command to define a triclinic simulation box must have tilt factors +(xy,xz,yz) that do not skew the box more than half the distance of +corresponding the parallel box length. For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all -equivalent. +geometrically equivalent. +
+See this section of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, and +how to transform these parameters into other commonly used triclinic +representations.
The union style creates a region consisting of the volume of all the listed regions combined. The intersect style creates a region diff --git a/doc/region.txt b/doc/region.txt index fc4fa1ce57..598de688d5 100644 --- a/doc/region.txt +++ b/doc/region.txt @@ -142,35 +142,29 @@ half-space in the direction of the normal vector; see the discussion of the {side} option below. For style {prism}, a parallelepiped is defined (it's too hard to spell -parallelepiped in an input script!). Think of the parallelepiped as -initially an axis-aligned orthogonal box with the same xyz lo/hi -parameters as region style {block} would define. Then, while holding -the (xlo,ylo,zlo) corner point fixed, the box is "skewed" or "tilted" -in 3 directions. First, for the lower xy face of the box, the {xy} -factor is how far the upper y edge is shifted in the x direction. The -lower xy face is now a parallelogram. A plus or minus value for {xy} -can be specified; 0.0 means no tilt. Then, the upper xy face of the -box is translated in the x and y directions by {xz} and {yz}. This -results in a parallelepiped whose "origin" is at (xlo,ylo,zlo) with 3 -edge vectors starting from its origin given by a = (xhi-xlo,0,0); b = -(xy,yhi-ylo,0); c = (xz,yz,zhi-zlo). +parallelepiped in an input script!). The parallelepiped has its +"origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors starting +from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C = +(xz,yz,zhi-zlo). {Xy,xz,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. -Crystal structures are often defined using three lattice constants -{a}, {b}, and {c}, and three angles {alpha}, {beta} and {gamma}. The -relationships between these quantities and a prism with (lx,ly,lz) = -(xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) are as follows: - -:c,image(Eqs/box.jpg) - -A prism region used with the "create_box"_create_box.html command must -have tilt factors (xy,xz,yz) that do not skew the box more than half -the distance of the parallel box length. For example, if xlo = 2 and +A prism region that will be used with the "create_box"_create_box.html +command to define a triclinic simulation box must have tilt factors +(xy,xz,yz) that do not skew the box more than half the distance of +corresponding the parallel box length. For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all -equivalent. +geometrically equivalent. + +See "this section"_Section_howto.html#4_12 of the doc pages for a +geometric description of triclinic boxes, as defined by LAMMPS, and +how to transform these parameters into other commonly used triclinic +representations. The {union} style creates a region consisting of the volume of all the listed regions combined. The {intersect} style creates a region