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). The orthogonal +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 @@ -818,16 +818,26 @@ the x box length is 10 and the xy tilt factor must be between -5 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. +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. +
+The 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.
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 constants -are the scalar lengths of the edge vectors a, b, and c 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: +gamma. Note that in this nomenclature, the a, b, and c lattice +constants are the scalar lengths of the edge vectors a, b, and c +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:
For triclinic (non-orthogonal) simulation boxes, if the 2nd dimension +of a tilt factor (e.g. y for xy) is periodic, then the periodicity is +enforced with the tilt factor offset. If the 1st dimension is +shrink-wrapped, then the shrink wrapping is applied to the tilted box +face, to encompass the atoms. E.g. for a positive xy tilt, the xlo +and xhi faces of the box are planes tilting in the +y direction as y +increases. These tilted planes are shrink-wrapped around the atoms to +determine the x extent of the box. +
+See Section_howto 12 of the doc pages +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. +
Restrictions:
This command cannot be used after the simulation box is defined by a diff --git a/doc/boundary.txt b/doc/boundary.txt index b265d07b83..cfdb43ce21 100644 --- a/doc/boundary.txt +++ b/doc/boundary.txt @@ -55,6 +55,20 @@ face has a value of 50.0 in the data file, the face will always be positioned at 50.0 or above, even if the maximum z-extent of all the atoms becomes less than 50.0. +For triclinic (non-orthogonal) simulation boxes, if the 2nd dimension +of a tilt factor (e.g. y for xy) is periodic, then the periodicity is +enforced with the tilt factor offset. If the 1st dimension is +shrink-wrapped, then the shrink wrapping is applied to the tilted box +face, to encompass the atoms. E.g. for a positive xy tilt, the xlo +and xhi faces of the box are planes tilting in the +y direction as y +increases. These tilted planes are shrink-wrapped around the atoms to +determine the x extent of the box. + +See "Section_howto 12"_Section_howto.html#howto_12 of the doc pages +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. + [Restrictions:] This command cannot be used after the simulation box is defined by a diff --git a/doc/fix_deform.html b/doc/fix_deform.html index ef1cb4c770..76b723d59c 100644 --- a/doc/fix_deform.html +++ b/doc/fix_deform.html @@ -99,13 +99,12 @@ continuously strained system. See the fix nvt/sllod and compute temp/deform commands for more details.
-Any parameter varied by this command must refer to a periodic -dimension - see the boundary command. For parameters -xy, xz, and yz, the 2nd dimension must be periodic, e.g. y for -xy. Dimensions not varied by this command can be periodic or -non-periodic. Dimensions corresponding to unspecified parameters can -also be controlled by a fix npt or fix nph -command. +
For the x, y, z parameters, the associated dimension cannot be +shrink-wrapped. For the xy, yz, xz parameters, the associated +2nd dimension cannot be shrink-wrapped. Dimensions not varied by this +command can be periodic or non-periodic. Dimensions corresponding to +unspecified parameters can also be controlled by a fix +npt or fix nph command.
The size and shape of the simulation box at the beginning of the simulation run were either specified by the @@ -433,16 +432,23 @@ example), then configurations with tilt = ..., -15, -5, 5, 15, 25, applied via the xy, xz, or yz parameters, the following algorithm is used. If prd is the associated parallel box length (10 in the example above), then if the tilt factor exceeds the accepted -range of -5 to 5 during the simulation, then the box is re-shaped to -the other limit (an equivalent box) and the simulation continues. -Thus for this example, if the initial xy tilt factor was 0.0 and "xy -final 100.0" was specified, then during the simulation the xy tilt -factor would increase from 0.0 to 5.0, the box would be re-shaped so -that the tilt factor becomes -5.0, the tilt factor would increase from --5.0 to 5.0, the box would be re-shaped again, etc. The re-shaping -would occur 10 times and the final tilt factor at the end of the -simulation would be 0.0. During each re-shaping event, atoms are -remapped into the new box in the appropriate manner. +range of -5 to 5 during the simulation, then the box is flipped to the +other limit (an equivalent box) and the simulation continues. Thus +for this example, if the initial xy tilt factor was 0.0 and "xy final +100.0" was specified, then during the simulation the xy tilt factor +would increase from 0.0 to 5.0, the box would be flipped so that the +tilt factor becomes -5.0, the tilt factor would increase from -5.0 to +5.0, the box would be flipped again, etc. The flip occurs 10 times +and the final tilt factor at the end of the simulation would be 0.0. +During each flip event, atoms are remapped into the new box in the +appropriate manner. +
+The 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.
Restrictions:
-Any box dimension varied by this fix must be periodic. +
You cannot apply x, y, or z deformations to a dimension that is +shrink-wrapped via the boundary comamnd. +
+You cannot apply xy, yz, or xz deformations to a 2nd dimension (y in +xy) that is shrink-wrapped via the boundary comamnd.
Related commands:
diff --git a/doc/fix_deform.txt b/doc/fix_deform.txt index 9944084e67..51baaea5a9 100644 --- a/doc/fix_deform.txt +++ b/doc/fix_deform.txt @@ -89,13 +89,12 @@ continuously strained system. See the "fix nvt/sllod"_fix_nvt_sllod.html and "compute temp/deform"_compute_temp_deform.html commands for more details. -Any parameter varied by this command must refer to a periodic -dimension - see the "boundary"_boundary.html command. For parameters -{xy}, {xz}, and {yz}, the 2nd dimension must be periodic, e.g. {y} for -{xy}. Dimensions not varied by this command can be periodic or -non-periodic. Dimensions corresponding to unspecified parameters can -also be controlled by a "fix npt"_fix_nh.html or "fix nph"_fix_nh.html -command. +For the {x}, {y}, {z} parameters, the associated dimension cannot be +shrink-wrapped. For the {xy}, {yz}, {xz} parameters, the associated +2nd dimension cannot be shrink-wrapped. Dimensions not varied by this +command can be periodic or non-periodic. Dimensions corresponding to +unspecified parameters can also be controlled by a "fix +npt"_fix_nh.html or "fix nph"_fix_nh.html command. The size and shape of the simulation box at the beginning of the simulation run were either specified by the @@ -423,16 +422,23 @@ To obey this constraint and allow for large shear deformations to be applied via the {xy}, {xz}, or {yz} parameters, the following algorithm is used. If {prd} is the associated parallel box length (10 in the example above), then if the tilt factor exceeds the accepted -range of -5 to 5 during the simulation, then the box is re-shaped to -the other limit (an equivalent box) and the simulation continues. -Thus for this example, if the initial xy tilt factor was 0.0 and "xy -final 100.0" was specified, then during the simulation the xy tilt -factor would increase from 0.0 to 5.0, the box would be re-shaped so -that the tilt factor becomes -5.0, the tilt factor would increase from --5.0 to 5.0, the box would be re-shaped again, etc. The re-shaping -would occur 10 times and the final tilt factor at the end of the -simulation would be 0.0. During each re-shaping event, atoms are -remapped into the new box in the appropriate manner. +range of -5 to 5 during the simulation, then the box is flipped to the +other limit (an equivalent box) and the simulation continues. Thus +for this example, if the initial xy tilt factor was 0.0 and "xy final +100.0" was specified, then during the simulation the xy tilt factor +would increase from 0.0 to 5.0, the box would be flipped so that the +tilt factor becomes -5.0, the tilt factor would increase from -5.0 to +5.0, the box would be flipped again, etc. The flip occurs 10 times +and the final tilt factor at the end of the simulation would be 0.0. +During each flip event, atoms are remapped into the new box in the +appropriate manner. + +The 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. :line @@ -509,7 +515,11 @@ This fix is not invoked during "energy minimization"_minimize.html. [Restrictions:] -Any box dimension varied by this fix must be periodic. +You cannot apply x, y, or z deformations to a dimension that is +shrink-wrapped via the "boundary"_boundary.html comamnd. + +You cannot apply xy, yz, or xz deformations to a 2nd dimension (y in +xy) that is shrink-wrapped via the "boundary"_boundary.html comamnd. [Related commands:] diff --git a/doc/fix_nh.html b/doc/fix_nh.html index afe49c95c2..3df653b8c8 100644 --- a/doc/fix_nh.html +++ b/doc/fix_nh.html @@ -275,16 +275,15 @@ specified values of the external stress tensor. A value of nstep means that every nstep timesteps, the reference dimensions are set to those of the current simulation domain. -The scaleyz, scalexz, and scalexy keywords control whether or -not the corresponding tilt factors are scaled with the -associated box dimensions -when barostatting triclinic periodic cells. -The default values yes will turn on scaling, which corresponds to -adjusting the linear dimensions of the cell while preserving its shape. -Choosing no ensures that the tilt factors are not scaled with the -box dimensions. See below for restrictions and default values in different -situations. In older versions of LAMMPS, scaling of tilt factors was not -performed. The old behavior can be recovered by setting all three +
The scaleyz, scalexz, and scalexy keywords control whether or +not the corresponding tilt factors are scaled with the associated box +dimensions when barostatting triclinic periodic cells. The default +values yes will turn on scaling, which corresponds to adjusting the +linear dimensions of the cell while preserving its shape. Choosing +no ensures that the tilt factors are not scaled with the box +dimensions. See below for restrictions and default values in different +situations. In older versions of LAMMPS, scaling of tilt factors was +not performed. The old behavior can be recovered by setting all three scale keywords to no.
IMPORTANT NOTE: Using a barostat coupled to tilt dimensions xy, xz, yz can sometimes result in arbitrarily large values of the tilt dimensions, i.e. a dramatically deformed simulation box. LAMMPS -allows the tilt factors to grow a little beyond the normal limit -of half the box length (0.6 times the box length), and then performs +allows the tilt factors to grow a little beyond the normal limit of +half the box length (0.6 times the box length), and then performs flipping or re-shaping to an equivalent periodic cell. The re-shaping -operation is described in more detail in the doc page for -fix deform. Both the barostat dynamics and -the atom trajectories are unaffected by this operation. However, -if a tilt factor is incremented by a large amount (1.5 times the -box length) on a single timestep, LAMMPS can not accomodate -this event and will terminate the simulation -with an error. This error typically -indicates that there is something badly wrong with how the simulation -was constructed, such as specifying values of Pstart that are -too far from the current stress value, or specifying a timestep that -is too large. Triclinic barostatting should be used with -care. This also is true for other barostat styles, although they tend -to be more forgiving of insults. In particular, it is important to -recognize that equilibrium liquids can not support a shear stress and -that equilibrium solids can not support shear stresses that exceed the yield stress. +operation is described in more detail in the doc page for fix +deform. Both the barostat dynamics and the atom +trajectories are unaffected by this operation. However, if a tilt +factor is incremented by a large amount (1.5 times the box length) on +a single timestep, LAMMPS can not accomodate this event and will +terminate the simulation with an error. This error typically indicates +that there is something badly wrong with how the simulation was +constructed, such as specifying values of Pstart that are too far +from the current stress value, or specifying a timestep that is too +large. Triclinic barostatting should be used with care. This also is +true for other barostat styles, although they tend to be more +forgiving of insults. In particular, it is important to recognize that +equilibrium liquids can not support a shear stress and that +equilibrium solids can not support shear stresses that exceed the +yield stress.
IMPORTANT NOTE: Unlike the fix temp/berendsen command which performs @@ -493,14 +492,15 @@ space measure of the underlying non-Hamiltonian equations of motion.
Restrictions:
-Non-periodic dimensions cannot be barostatted. Z, xz, and yz, -cannot be barostatted 2D simulations. Xy, xz, and yz can only -be barostatted if the simulation domain is triclinic and the 2nd -dimension in the keyword (y dimension in xy) is periodic. The -create_box, read data, and -read_restart commands specify whether the -simulation box is orthogonal or non-orthogonal (triclinic) and explain -the meaning of the xy,xz,yz tilt factors. +
X, y, z cannot be barostatted if the associated dimension is not +periodic. Xy, xz, and yz can only be barostatted if the +simulation domain is triclinic and the 2nd dimension in the keyword +(y dimension in xy) is periodic. Z, xz, and yz, cannot be +barostatted for 2D simulations. The create_box, +read data, and read_restart +commands specify whether the simulation box is orthogonal or +non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz +tilt factors.
For the temp keyword, the final Tstop cannot be 0.0 since it would make the external T = 0.0 at some timestep during the simulation which diff --git a/doc/fix_nh.txt b/doc/fix_nh.txt index 71d219f868..7d6d6e4bd4 100644 --- a/doc/fix_nh.txt +++ b/doc/fix_nh.txt @@ -265,16 +265,15 @@ specified values of the external stress tensor. A value of {nstep} means that every {nstep} timesteps, the reference dimensions are set to those of the current simulation domain. -The {scaleyz}, {scalexz}, and {scalexy} keywords control whether or -not the corresponding tilt factors are scaled with the -associated box dimensions -when barostatting triclinic periodic cells. -The default values {yes} will turn on scaling, which corresponds to -adjusting the linear dimensions of the cell while preserving its shape. -Choosing {no} ensures that the tilt factors are not scaled with the -box dimensions. See below for restrictions and default values in different -situations. In older versions of LAMMPS, scaling of tilt factors was not -performed. The old behavior can be recovered by setting all three +The {scaleyz}, {scalexz}, and {scalexy} keywords control whether or +not the corresponding tilt factors are scaled with the associated box +dimensions when barostatting triclinic periodic cells. The default +values {yes} will turn on scaling, which corresponds to adjusting the +linear dimensions of the cell while preserving its shape. Choosing +{no} ensures that the tilt factors are not scaled with the box +dimensions. See below for restrictions and default values in different +situations. In older versions of LAMMPS, scaling of tilt factors was +not performed. The old behavior can be recovered by setting all three scale keywords to {no}. :line @@ -282,24 +281,24 @@ scale keywords to {no}. IMPORTANT NOTE: Using a barostat coupled to tilt dimensions {xy}, {xz}, {yz} can sometimes result in arbitrarily large values of the tilt dimensions, i.e. a dramatically deformed simulation box. LAMMPS -allows the tilt factors to grow a little beyond the normal limit -of half the box length (0.6 times the box length), and then performs +allows the tilt factors to grow a little beyond the normal limit of +half the box length (0.6 times the box length), and then performs flipping or re-shaping to an equivalent periodic cell. The re-shaping -operation is described in more detail in the doc page for -"fix deform"_fix_deform.html. Both the barostat dynamics and -the atom trajectories are unaffected by this operation. However, -if a tilt factor is incremented by a large amount (1.5 times the -box length) on a single timestep, LAMMPS can not accomodate -this event and will terminate the simulation -with an error. This error typically -indicates that there is something badly wrong with how the simulation -was constructed, such as specifying values of {Pstart} that are -too far from the current stress value, or specifying a timestep that -is too large. Triclinic barostatting should be used with -care. This also is true for other barostat styles, although they tend -to be more forgiving of insults. In particular, it is important to -recognize that equilibrium liquids can not support a shear stress and -that equilibrium solids can not support shear stresses that exceed the yield stress. +operation is described in more detail in the doc page for "fix +deform"_fix_deform.html. Both the barostat dynamics and the atom +trajectories are unaffected by this operation. However, if a tilt +factor is incremented by a large amount (1.5 times the box length) on +a single timestep, LAMMPS can not accomodate this event and will +terminate the simulation with an error. This error typically indicates +that there is something badly wrong with how the simulation was +constructed, such as specifying values of {Pstart} that are too far +from the current stress value, or specifying a timestep that is too +large. Triclinic barostatting should be used with care. This also is +true for other barostat styles, although they tend to be more +forgiving of insults. In particular, it is important to recognize that +equilibrium liquids can not support a shear stress and that +equilibrium solids can not support shear stresses that exceed the +yield stress. IMPORTANT NOTE: Unlike the "fix temp/berendsen"_fix_temp_berendsen.html command which performs @@ -483,14 +482,15 @@ space measure of the underlying non-Hamiltonian equations of motion. [Restrictions:] -Non-periodic dimensions cannot be barostatted. {Z}, {xz}, and {yz}, -cannot be barostatted 2D simulations. {Xy}, {xz}, and {yz} can only -be barostatted if the simulation domain is triclinic and the 2nd -dimension in the keyword ({y} dimension in {xy}) is periodic. The -"create_box"_create_box.html, "read data"_read_data.html, and -"read_restart"_read_restart.html commands specify whether the -simulation box is orthogonal or non-orthogonal (triclinic) and explain -the meaning of the xy,xz,yz tilt factors. +{X}, {y}, {z} cannot be barostatted if the associated dimension is not +periodic. {Xy}, {xz}, and {yz} can only be barostatted if the +simulation domain is triclinic and the 2nd dimension in the keyword +({y} dimension in {xy}) is periodic. {Z}, {xz}, and {yz}, cannot be +barostatted for 2D simulations. The "create_box"_create_box.html, +"read data"_read_data.html, and "read_restart"_read_restart.html +commands specify whether the simulation box is orthogonal or +non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz +tilt factors. For the {temp} keyword, the final Tstop cannot be 0.0 since it would make the external T = 0.0 at some timestep during the simulation which