For example, assume that the 3 vectors A,B,C are the edge -vectors of a general parallelepiped, where there is no restriction -on A,B,C other than they form a complete right-handed basis i.e. -A x B . C > 0. -The equivalent LAMMPS a,b,c are a linear rotation of A, B, and -C and can be computed as follows: +vectors of a general parallelepiped, where there is no restriction on +A,B,C other than they form a complete right-handed basis i.e. +A x B . C > 0. The equivalent LAMMPS a,b,c are a linear +rotation of A, B, and C and can be computed as follows:
To avoid extremely tilted boxes (which would be computationally -inefficient), no tilt factor can skew the box more than half the -distance of the parallel box length, which is the 1st dimension in the -tilt factor (x for xz). 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 geometrically all -equivalent. If the box tilt exceeds this limit during a dynamics run -(e.g. via the fix deform command), then the box is -"flipped" to an equivalent shape with a tilt factor within the bounds, -so the run can continue. See the fix deform doc -page for further details. +inefficient), LAMMPS normally requires that no tilt factor can skew +the box more than half the distance of the parallel box length, which +is the 1st dimension in the tilt factor (x for xz). This is required +both when the simulation box is created, e.g. via the +create_box or read_data commands, +as well as when the box shape changes dynamically during a simulation, +e.g. via the fix deform or fix npt +commands.
-The one exception to this rule is if the 1st dimension in the tilt +
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 geometrically all equivalent. If the box tilt exceeds this +limit during a dynamics run (e.g. via the fix deform +command), then the box is "flipped" to an equivalent shape with a tilt +factor within the bounds, so the run can continue. See the fix +deform doc page for further details. +
+One exception to this rule is if the 1st dimension in the tilt factor (x for xy) is non-periodic. In that case, the limits on the tilt factor are not enforced, since flipping the box in that dimension does not change the atom positions due to non-periodicity. In this mode, if you tilt the system to extreme angles, the simulation will simply become inefficient, due to the highly skewed simulation box.
+The limitation on not creating a simulation box with a tilt factor +skewing the box more than half the distance of the parallel box length +can be overridden via the box command. Setting the tilt +keyword to large allows any tilt factors to be specified. +
+Box flips that may occur using the fix deform or +fix npt commands can be turned off using the flip no +option with either of the commands. +
+Note that if a simulation box has a large tilt factor, LAMMPS will run +less efficiently, due to the large volume of communication needed to +acquire ghost atoms around a processor's irregular-shaped sub-domain. +For extreme values of tilt, LAMMPS may also lose atoms and generate an +error. +
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, and c lattice diff --git a/doc/Section_howto.txt b/doc/Section_howto.txt index 8c22a42931..fb94ceeaf8 100644 --- a/doc/Section_howto.txt +++ b/doc/Section_howto.txt @@ -780,24 +780,22 @@ 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. In LAMMPS the -triclinic simulation box edge vectors [a], [b], and [c] cannot be -arbitrary vectors. As indicated, [a] must lie on the positive x axis. -[b] must lie in the xy plane, with strictly positive y component. [c] may -have any orientation with strictly positive z component. -The requirement that [a], [b], and [c] have strictly positive x, y, -and z components, respectively, ensures -that [a], [b], and [c] form a complete right-handed basis. -These restrictions impose -no loss of generality, since it is possible to rotate/invert -any set of 3 crystal basis vectors so that they conform to the restrictions. +transform it into the parallelepiped. In LAMMPS the triclinic +simulation box edge vectors [a], [b], and [c] cannot be arbitrary +vectors. As indicated, [a] must lie on the positive x axis. [b] must +lie in the xy plane, with strictly positive y component. [c] may have +any orientation with strictly positive z component. The requirement +that [a], [b], and [c] have strictly positive x, y, and z components, +respectively, ensures that [a], [b], and [c] form a complete +right-handed basis. These restrictions impose no loss of generality, +since it is possible to rotate/invert any set of 3 crystal basis +vectors so that they conform to the restrictions. For example, assume that the 3 vectors [A],[B],[C] are the edge -vectors of a general parallelepiped, where there is no restriction -on [A],[B],[C] other than they form a complete right-handed basis i.e. -[A] x [B] . [C] > 0. -The equivalent LAMMPS [a],[b],[c] are a linear rotation of [A], [B], and -[C] and can be computed as follows: +vectors of a general parallelepiped, where there is no restriction on +[A],[B],[C] other than they form a complete right-handed basis i.e. +[A] x [B] . [C] > 0. The equivalent LAMMPS [a],[b],[c] are a linear +rotation of [A], [B], and [C] and can be computed as follows: :c,image(Eqs/transform.jpg) @@ -859,27 +857,48 @@ The 9 parameters, as well as lx,ly,lz, can be output via the "thermo_style custom"_thermo_style.html command. To avoid extremely tilted boxes (which would be computationally -inefficient), no tilt factor can skew the box more than half the -distance of the parallel box length, which is the 1st dimension in the -tilt factor (x for xz). 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 geometrically all -equivalent. If the box tilt exceeds this limit during a dynamics run -(e.g. via the "fix deform"_fix_deform.html command), then the box is -"flipped" to an equivalent shape with a tilt factor within the bounds, -so the run can continue. See the "fix deform"_fix_deform.html doc -page for further details. +inefficient), LAMMPS normally requires that no tilt factor can skew +the box more than half the distance of the parallel box length, which +is the 1st dimension in the tilt factor (x for xz). This is required +both when the simulation box is created, e.g. via the +"create_box"_create_box.html or "read_data"_read_data.html commands, +as well as when the box shape changes dynamically during a simulation, +e.g. via the "fix deform"_fix_deform.html or "fix npt"_fix_nh.html +commands. -The one exception to this rule is if the 1st dimension in the tilt +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 geometrically all equivalent. If the box tilt exceeds this +limit during a dynamics run (e.g. via the "fix deform"_fix_deform.html +command), then the box is "flipped" to an equivalent shape with a tilt +factor within the bounds, so the run can continue. See the "fix +deform"_fix_deform.html doc page for further details. + +One exception to this rule is if the 1st dimension in the tilt factor (x for xy) is non-periodic. In that case, the limits on the tilt factor are not enforced, since flipping the box in that dimension does not change the atom positions due to non-periodicity. In this mode, if you tilt the system to extreme angles, the simulation will simply become inefficient, due to the highly skewed simulation box. +The limitation on not creating a simulation box with a tilt factor +skewing the box more than half the distance of the parallel box length +can be overridden via the "box"_box.html command. Setting the {tilt} +keyword to {large} allows any tilt factors to be specified. + +Box flips that may occur using the "fix deform"_fix_deform.html or +"fix npt"_fix_nh.html commands can be turned off using the {flip no} +option with either of the commands. + +Note that if a simulation box has a large tilt factor, LAMMPS will run +less efficiently, due to the large volume of communication needed to +acquire ghost atoms around a processor's irregular-shaped sub-domain. +For extreme values of tilt, LAMMPS may also lose atoms and generate an +error. + 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, and c lattice diff --git a/doc/box.html b/doc/box.html new file mode 100644 index 0000000000..162087c7ff --- /dev/null +++ b/doc/box.html @@ -0,0 +1,69 @@ + +
Syntax: +
+box keyword value ... ++
tilt value = small or large ++ +
Examples: +
+box tilt large +box tilt small ++
Description: +
+Set attributes of the simulation box. +
+For triclinic (non-orthogonal) simulation boxes, the tilt keyword +allows simulation domains to be created with arbitrary tilt factors, +e.g. via the create_box or +read_data commands. Tilt factors determine how +skewed the triclinic box is; see this +section of the manual for a discussion of +triclinic boxes in LAMMPS. +
+LAMMPS normally requires that no tilt factor can skew the box more +than half the distance of the parallel box length, which is the 1st +dimension in the tilt factor (x for xz). If tilt is set to +small, which is the default, then an error will be +generated if a box is created which exceeds this limit. If tilt +is set to large, then no limit is enforced. You can create +a box with any tilt factors you wish. +
+Note that if a simulation box has a large tilt factor, LAMMPS will run +less efficiently, due to the large volume of communication needed to +acquire ghost atoms around a processor's irregular-shaped sub-domain. +For extreme values of tilt, LAMMPS may also lose atoms and generate an +error. +
+Restrictions: +
+This command cannot be used after the simulation box is defined by a +read_data or create_box command or +read_restart command. +
+Related commands: none +
+Default: +
+The default value is tilt = small. +
+ diff --git a/doc/box.txt b/doc/box.txt new file mode 100644 index 0000000000..a6207ae993 --- /dev/null +++ b/doc/box.txt @@ -0,0 +1,61 @@ +"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +box command :h3 + +[Syntax:] + +box keyword value ... :pre + +one or more keyword/value pairs may be appended :ulb,l +keyword = {tilt} :l + {tilt} value = {small} or {large} :pre +:ule + +[Examples:] + +box tilt large +box tilt small :pre + +[Description:] + +Set attributes of the simulation box. + +For triclinic (non-orthogonal) simulation boxes, the {tilt} keyword +allows simulation domains to be created with arbitrary tilt factors, +e.g. via the "create_box"_create_box.html or +"read_data"_read_data.html commands. Tilt factors determine how +skewed the triclinic box is; see "this +section"_Section_howto.html#howto_12 of the manual for a discussion of +triclinic boxes in LAMMPS. + +LAMMPS normally requires that no tilt factor can skew the box more +than half the distance of the parallel box length, which is the 1st +dimension in the tilt factor (x for xz). If {tilt} is set to +{small}, which is the default, then an error will be +generated if a box is created which exceeds this limit. If {tilt} +is set to {large}, then no limit is enforced. You can create +a box with any tilt factors you wish. + +Note that if a simulation box has a large tilt factor, LAMMPS will run +less efficiently, due to the large volume of communication needed to +acquire ghost atoms around a processor's irregular-shaped sub-domain. +For extreme values of tilt, LAMMPS may also lose atoms and generate an +error. + +[Restrictions:] + +This command cannot be used after the simulation box is defined by a +"read_data"_read_data.html or "create_box"_create_box.html command or +"read_restart"_read_restart.html command. + +[Related commands:] none + +[Default:] + +The default value is tilt = small. diff --git a/doc/change_box.html b/doc/change_box.html index 898afe960d..059444bc1a 100644 --- a/doc/change_box.html +++ b/doc/change_box.html @@ -42,7 +42,7 @@ s is non-periodic and shrink-wrapped m is non-periodic and shrink-wrapped with a minimum value ortho args = none = change box to orthogonal - (triclinic args = none = change box to triclinic + triclinic args = none = change box to triclinic set args = none = store state of current box remap args = none = remap atom coords from last saved state to current box diff --git a/doc/change_box.txt b/doc/change_box.txt index 1a492a2c39..4dc41b9938 100644 --- a/doc/change_box.txt +++ b/doc/change_box.txt @@ -37,7 +37,7 @@ parameter = {x} or {y} or {z} or {xy} or {xz} or {yz} or {boundary} or {ortho} o {s} is non-periodic and shrink-wrapped {m} is non-periodic and shrink-wrapped with a minimum value {ortho} args = none = change box to orthogonal - (triclinic} args = none = change box to triclinic + {triclinic} args = none = change box to triclinic {set} args = none = store state of current box {remap} args = none = remap atom coords from last saved state to current box :pre diff --git a/doc/fix_box_relax.html b/doc/fix_box_relax.html index 4d74d1f328..d6884195dd 100644 --- a/doc/fix_box_relax.html +++ b/doc/fix_box_relax.html @@ -110,16 +110,17 @@ displaced by the same amount, different on each iteration.IMPORTANT NOTE: Appling an external pressure to tilt dimensions xy, xz, yz can sometimes result in arbitrarily large values of the -tilt dimensions, i.e. a dramatically deformed simulation box. This +tilt factors, i.e. a dramatically deformed simulation box. This typically indicates that there is something badly wrong with how the simulation was constructed. The two most common sources of this error are applying a shear stress to a liquid system or specifying an external shear stress tensor that exceeds the yield stress of the -solid. In either case the minimization is either not going to -converge at all, or converge to a bogus conformation. Note that -LAMMPS will not throw an error when the tilt value becomes extreme, -but the final box may be unsuitable for running dynamics on, unless -fix deform is used first to remap the box to a valid tilt value. +solid. In either case the minimization may converge to a bogus +conformation or not converge at all. Also note that if the box shape +tilts to an extreme shape, LAMMPS will run less efficiently, due to +the large volume of communication needed to acquire ghost atoms around +a processor's irregular-shaped sub-domain. For extreme values of +tilt, LAMMPS may also lose atoms and generate an error.
remap value = x or v or none
x = remap coords of atoms in group into deforming box
v = remap velocities of all atoms when they cross periodic boundaries
none = no remapping of x or v
+ flip value = yes or no
+ allow or dis-allow box flips when the skew ratio exceeds +/- 0.5
units value = lattice or box
lattice = distances are defined in lattice units
box = distances are defined in simulation box units
@@ -420,8 +422,11 @@ fix 2 all deform 1 xy variable v_displace v_rate remap v
All of the tilt styles change the xy, xz, yz tilt factors during a
simulation. In LAMMPS, tilt factors (xy,xz,yz) for triclinic boxes
-are always bounded by half the distance of the parallel box length.
-For example, if xlo = 2 and xhi = 12, then the x box length is 10 and
+are normally bounded by half the distance of the parallel box length.
+See the discussion of the flip keyword below, to allow this bound to
+be exceeded, if desired.
+
+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
@@ -497,6 +502,17 @@ rigid particles, you can either thermostat them independently or
include a background fluid and thermostat the fluid via fix
nvt/sllod.
+The flip keyword allows the tilt factors for a triclinic box to
+exceed half the distance of the parallel box length, as discussed
+above. If the flip value is set to yes, the bound is enforced by
+flipping the box when it is exceeded. If the flip value is set to
+no, the tilt will continue to change without flipping. Note that if
+you apply large deformations, this means the box shape can tilt
+dramatically LAMMPS will run less efficiently, due to the large volume
+of communication needed to acquire ghost atoms around a processor's
+irregular-shaped sub-domain. For extreme values of tilt, LAMMPS may
+also lose atoms and generate an error.
+
The units keyword determines the meaning of the distance units used
to define various arguments. A box value selects standard distance
units as defined by the units command, e.g. Angstroms for
@@ -537,6 +553,6 @@ xy) that is shrink-wrapped via the boundary comamn
Default:
-The option defaults are remap = x and units = lattice.
+
The option defaults are remap = x, flip = yes, and units = lattice.