From a3c28800f4657db0c78232cd1766e7d4187d8744 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Mon, 6 Feb 2012 16:58:56 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@7703 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/Section_commands.html | 24 +-- doc/Section_commands.txt | 3 +- doc/Section_howto.html | 4 +- doc/Section_howto.txt | 4 +- doc/boundary.html | 5 +- doc/boundary.txt | 5 +- doc/change_box.html | 297 ++++++++++++++++++++++++++++++++++---- doc/change_box.txt | 293 +++++++++++++++++++++++++++++++++---- doc/displace_atoms.html | 36 ++--- doc/displace_atoms.txt | 36 ++--- doc/displace_box.html | 191 ------------------------ doc/displace_box.txt | 181 ----------------------- doc/fix_deform.html | 2 +- doc/fix_deform.txt | 2 +- 14 files changed, 597 insertions(+), 486 deletions(-) delete mode 100644 doc/displace_box.html delete mode 100644 doc/displace_box.txt diff --git a/doc/Section_commands.html b/doc/Section_commands.html index 2fa418e8ca..7c1a07a6e7 100644 --- a/doc/Section_commands.html +++ b/doc/Section_commands.html @@ -290,7 +290,7 @@ in the command's documentation.

delete_atoms, delete_bonds, displace_atoms, -displace_box, minimize, +change_box, minimize, neb prd, run, temper

Miscellaneous: @@ -317,17 +317,17 @@ in the command's documentation. angle_coeffangle_styleatom_modifyatom_stylebond_coeffbond_style boundarychange_boxclearcommunicatecomputecompute_modify create_atomscreate_boxdelete_atomsdelete_bondsdielectricdihedral_coeff -dihedral_styledimensiondisplace_atomsdisplace_boxdumpdump image -dump_modifyechofixfix_modifygroupif -improper_coeffimproper_styleincludejumpkspace_modifykspace_style -labellatticelogmassminimizemin_modify -min_stylenebneigh_modifyneighbornewtonnext -packagepair_coeffpair_modifypair_stylepair_writepartition -prdprintprocessorsquitread_dataread_restart -regionreplicatereset_timesteprestartrunrun_style -setshellspecial_bondssuffixtadtemper -thermothermo_modifythermo_styletimestepuncomputeundump -unfixunitsvariablevelocitywrite_restart +dihedral_styledimensiondisplace_atomsdumpdump imagedump_modify +echofixfix_modifygroupifimproper_coeff +improper_styleincludejumpkspace_modifykspace_stylelabel +latticelogmassminimizemin_modifymin_style +nebneigh_modifyneighbornewtonnextpackage +pair_coeffpair_modifypair_stylepair_writepartitionprd +printprocessorsquitread_dataread_restartregion +replicatereset_timesteprestartrunrun_styleset +shellspecial_bondssuffixtadtemperthermo +thermo_modifythermo_styletimestepuncomputeundumpunfix +unitsvariablevelocitywrite_restart


diff --git a/doc/Section_commands.txt b/doc/Section_commands.txt index 773a5ed031..08d67735b0 100644 --- a/doc/Section_commands.txt +++ b/doc/Section_commands.txt @@ -286,7 +286,7 @@ Actions: "delete_atoms"_delete_atoms.html, "delete_bonds"_delete_bonds.html, "displace_atoms"_displace_atoms.html, -"displace_box"_displace_box.html, "minimize"_minimize.html, +"change_box"_change_box.html, "minimize"_minimize.html, "neb"_neb.html "prd"_prd.html, "run"_run.html, "temper"_temper.html Miscellaneous: @@ -330,7 +330,6 @@ in the command's documentation. "dihedral_style"_dihedral_style.html, "dimension"_dimension.html, "displace_atoms"_displace_atoms.html, -"displace_box"_displace_box.html, "dump"_dump.html, "dump image"_dump_image.html, "dump_modify"_dump_modify.html, diff --git a/doc/Section_howto.html b/doc/Section_howto.html index 221685fea3..041124e229 100644 --- a/doc/Section_howto.html +++ b/doc/Section_howto.html @@ -1660,8 +1660,8 @@ derivative w.r.t. e_i, it follows that C_ij is also symmetric, with at most 7*6/2 = 21 distinct elements.

At zero temperature, it is easy to estimate these derivatives by -deforming the cell in one of the six directions using the command -displace_box and measuring the change in the +deforming the simulation box in one of the six directions using the +change_box command and measuring the change in the stress tensor. A general-purpose script that does this is given in the examples/elastic directory described in this section. diff --git a/doc/Section_howto.txt b/doc/Section_howto.txt index b19befe7f2..1f14a0a51b 100644 --- a/doc/Section_howto.txt +++ b/doc/Section_howto.txt @@ -1647,8 +1647,8 @@ derivative w.r.t. e_i, it follows that C_ij is also symmetric, with at most 7*6/2 = 21 distinct elements. At zero temperature, it is easy to estimate these derivatives by -deforming the cell in one of the six directions using the command -"displace_box"_displace_box.html and measuring the change in the +deforming the simulation box in one of the six directions using the +"change_box"_change_box.html command and measuring the change in the stress tensor. A general-purpose script that does this is given in the examples/elastic directory described in "this section"_Section_example.html. diff --git a/doc/boundary.html b/doc/boundary.html index 38544ed2d8..602a3d4f0d 100644 --- a/doc/boundary.html +++ b/doc/boundary.html @@ -77,7 +77,10 @@ triclinic representations.

Restrictions:

This command cannot be used after the simulation box is defined by a -read_data or create_box command. +read_data or create_box command or +read_restart command. See the +change_box command for how to change the simulation +box boundaries after it has been defined.

For 2d simulations, the z dimension must be periodic.

diff --git a/doc/boundary.txt b/doc/boundary.txt index cfdb43ce21..ec559d7f2f 100644 --- a/doc/boundary.txt +++ b/doc/boundary.txt @@ -72,7 +72,10 @@ triclinic representations. [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. +"read_data"_read_data.html or "create_box"_create_box.html command or +"read_restart"_read_restart.html command. See the +"change_box"_change_box.html command for how to change the simulation +box boundaries after it has been defined. For 2d simulations, the z dimension must be periodic. diff --git a/doc/change_box.html b/doc/change_box.html index e258ec2337..b504671ee9 100644 --- a/doc/change_box.html +++ b/doc/change_box.html @@ -13,51 +13,292 @@

Syntax:

-
change_box style 
+
change_box group-ID parameter args ... keyword args ... 
 
-
  • style = ortho or triclinic +
    • group-ID = ID of group of atoms to (optionally) displace -
        ortho = convert simulation box from non-orthogonal (triclinic) to orthogonal
      -  triclinic = convert simulation box from orthogonal to non-orthogonal (triclinic) 
      +
    • one or more parameter/arg pairs may be appended + +
      parameter = x or y or z or xy or xz or yz or boundary or ortho or triclinic or set or remap
      +  x, y, z args = style value(s)
      +    style = final or delta or scale or volume
      +      final values = lo hi
      +        lo hi = box boundaries after displacement (distance units)
      +      delta values = dlo dhi
      +        dlo dhi = change in box boundaries after displacement (distance units)
      +      scale values = factor
      +        factor = multiplicative factor for change in box length after displacement
      +      volume value = none = adjust this dim to preserve volume of system
      +  xy, xz, yz args = style value
      +    style = final or delta
      +      final value = tilt
      +        tilt = tilt factor after displacement (distance units)
      +      delta value = dtilt
      +        dtilt = change in tilt factor after displacement (distance units)
      +  boundary args = x y z
      +    x,y,z = p or s or f or m, one or two letters
      +    p is periodic
      +    f is non-periodic and fixed
      +    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
      +  set args = none = store state of current box
      +  remap args = none = remap atom coords from last saved state to current box 
       
      +
    • zero or more keyword/value pairs may be appended + +
    • keyword = units + +
        units value = lattice or box
      +    lattice = distances are defined in lattice units
      +    box = distances are defined in simulation box units 
      +
      + +

    Examples:

    -
    change_box ortho
    -change_box triclinic 
    +
    change_box all xy final -2.0 z final 0.0 5.0 boundary p p f remap units box
    +change_box all x scale 1.1 y volume z volume remap 
     

    Description:

    -

    By default LAMMPS runs a simulation in an orthogonal, axis-aligned -simulation box. LAMMPS can also run simulations in non-orthogonal -(triclinic) simulation boxes. A box is -defined as either orthogonal or non-orthogonal when it is created via -the create_box, read_data, or -read_restart commands. +

    Change the volume and/or shape and/or boundary conditions for the +simulation box. Orthogonal simulation boxes have 3 adjustable size +parameters (x,y,z). Triclinic (non-orthogonal) simulation boxes have +6 adjustable size/shape parameters (x,y,z,xy,xz,yz). Any or all of +them can be adjusted independently by this command. Thus it can be +used to expand or contract a box, or to apply a shear strain to a +non-orthogonal box. It can also be used to change the boundary +conditions for the simulation box, similar to the +boundary command.

    -

    This command allows you to toggle the existing simulation box from -orthogonal to non-orthogonal and vice versa. For example, an initial +

    The size and shape of the initial simulation box are specified by the +create_box or read_data or +read_restart command used to setup the simulation. +The size and shape may be altered by subsequent runs, e.g. by use of +the fix npt or fix deform commands. +The create_box, read data, and +read_restart commands also determine whether the +simulation box is orthogonal or triclinic and their doc pages explain +the meaning of the xy,xz,yz tilt factors. +

    +

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

    +

    The keywords used in this command are applied sequentially to the +simulation box and the atoms in it, in the order specified. +

    +

    Before the sequence of keywords are invoked, the current box +size/shape are stored, in case a remap keyword is used to map the +atom coordinates from the previous box size/shape to the current one. +

    +

    After all the keywords have been processed, any shrink-wrap boundary +conditions are invoked (see the boundary command) +which may change simulation box boundaries, and atoms are migrated to +new owning processors. +

    +

    IMPORTANT NOTE: It is possible to lose atoms with this command. +E.g. by changing the box without remapping the atoms, and having atoms +end up outside of non-periodic boundaries. It is also possible when +remapping atoms to put them (nearly) on top of each other which will +lead to bad dynamics. E.g. by converting a boundary from non-periodic +to periodic. +

    +

    IMPORTANT NOTE: The simulation box size/shape can be changed by +arbitrarily large amounts by this command. This is not a problem, +except that the mapping of processors to the simulation box is not +changed from its initial 3d configuration; see the +processors command. Thus, if the box size/shape +changes dramatically, the mapping of processors to the simulation box +may not end up as optimal as the initial mapping attempted to be. +

    +
    + +

    For the x, y, and z parameters, this is the meaning of their +styles and values. +

    +

    For style final, the final lo and hi box boundaries of a dimension +are specified. The values can be in lattice or box distance units. +See the discussion of the units keyword below. +

    +

    For style delta, plus or minus changes in the lo/hi box boundaries +of a dimension are specified. The values can be in lattice or box +distance units. See the discussion of the units keyword below. +

    +

    For style scale, a multiplicative factor to apply to the box length +of a dimension is specified. For example, if the initial box length +is 10, and the factor is 1.1, then the final box length will be 11. A +factor less than 1.0 means compression. +

    +

    The volume style changes the specified dimension in such a way that +the overall box volume remains constant with respect to the operation +performed by the preceding keyword. The volume style can only be +used following a keyword that changed the volume, which is any of the +x, y, z keywords. If the preceding keyword "key" had a volume +style, then both it and the current keyword apply to the keyword +preceding "key". I.e. this sequence of keywords is allowed: +

    +
    change_box all x scale 1.1 y volume z volume 
    +
    +

    The volume style changes the associated dimension so that the +overall box volume is unchanged relative to its value before the +preceding keyword was invoked. +

    +

    If "x scale 1.1 z volume" is used, then the z box length will +shrink by the same 1.1 factor the x box length was increased by. +

    +

    If "x scale 1.1 y volume z volume" is used, then the y,z box lengths +will each shrink by sqrt(1.1) to keep the volume constant. In this +case, the y,z box lengths shrink so as to keep their relative aspect +ratio constant. +

    +

    If "x scale 1.1 z volume y scale 1.1 z volume" is used, then +the final box will be a factor of 10% larger in x and y, and a +factor of 21% smaller in z, so as to keep the volume constant. +

    +

    IMPORTANT NOTE: For solids or liquids, when one dimension of the box +is expanded, it may be physically undesirable to hold the other 2 box +lengths constant since that implies a density change. For solids, +adjusting the other dimensions via the volume style may make +physical sense (just as for a liquid), but may not be correct for +materials and potentials whose Poisson ratio is not 0.5. +

    +

    For the scale and volume styles, the box length is expanded or +compressed around its mid point. +

    +
    + +

    For the xy, xz, and yz parameters, this is the meaning of their +styles and values. Note that changing the tilt factors of a triclinic +box does not change its volume. +

    +

    For style final, the final tilt factor is specified. The value +can be in lattice or box distance units. See the discussion of the +units keyword below. +

    +

    For style delta, a plus or minus change in the tilt factor is +specified. The value can be in lattice or box distance units. See +the discussion of the units keyword below. +

    +

    All of these styles change the xy, xz, yz tilt factors. In LAMMPS, +tilt factors (xy,xz,yz) for triclinic boxes are required to be no 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. Any tilt factor specified by this command +must be within these limits. +

    +
    + +

    The boundary keyword takes arguments that have exactly the same +meaning as they do for the boundary command. In each +dimension, a single letter assigns the same style to both the lower +and upper face of the box. Two letters assigns the first style to the +lower face and the second style to the upper face. +

    +

    The style p means the box is periodic; the other styles mean +non-periodic. For style f, the position of the face is fixed. For +style s, the position of the face is set so as to encompass the +atoms in that dimension (shrink-wrapping), no matter how far they +move. For style m, shrink-wrapping occurs, but is bounded by the +current box edge in that dimension, so that the box will become no +smaller. See the boundary command for more +explanation of these style options. +

    +

    Note that the "boundary" command itself can only be used before the +simulation box is defined via a read_data or +create_box or read_restart +command. This command allows the boundary conditions to be changed +later in your input script. Also note that the +read_restart will change boundary conditions to +match what is stored in the restart file. So if you wish to change +them, you should use the change_box command after the read_restart +command. +

    +
    + +

    The ortho and triclinic keywords convert the simulation box to be +orthogonal or triclinic (non-orthongonal). See this +section for a discussion of how non-orthongal +boxes are represented in LAMMPS. +

    +

    The simulation box is defined as either orthogonal or triclinic when +it is created via the create_box, +read_data, or read_restart +commands. +

    +

    These keywords allow you to toggle the existing simulation box from +orthogonal to triclinic and vice versa. For example, an initial equilibration simulation can be run in an orthogonal box, the box can -be toggled to non-orthogonal, and then a non-equilibrium MD (NEMD) +be toggled to triclinic, and then a non-equilibrium MD (NEMD) simulation can be run with deformation via the fix deform command.

    -

    Note that if the simulation box is currently non-orthogonal and has -non-zero tilt in xy, yz, or xz, then it cannot be converted to an -orthogonal box. +

    If the simulation box is currently triclinic and has non-zero tilt in +xy, yz, or xz, then it cannot be converted to an orthogonal box.

    +
    + +

    The set keyword saves the current box size/shape. This can be +useful if you wish to use the remap keyword more than once or if you +wish it to be applied to an intermediate box size/shape in a sequence +of keyword operations. Note that the box size/shape is saved before +any of the keywords are processed, i.e. the box size/shape at the time +the create_box command is encountered in the input script. +

    +

    The remap keyword remaps atom coordinates from the last saved box +size/shape to the current box state. For example, if you stretch the +box in the x dimension or tilt it in the xy plane via the x and xy +keywords, then the remap commmand will dilate or tilt the atoms to +conform to the new box size/shape, as if the atoms moved with the box +as it deformed. +

    +

    Note that this operation is performed without regard to periodic +boundaries. Any shrink-wrapping of non-periodic boundaries (see the +boundary command occurs after all keywords, including +this one, have been processed. +

    +

    Only atoms in the specified group are remapped. +

    +

    IMPORTANT NOTE: If you do not explicitly specify the remap keyword, +atom coordinates will not be changed even though the box size/shape +changes. This may be the behavior you desire, but can also cause +atoms to be lost. +

    +
    + +

    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 +units = real or metal. A lattice value means the distance units are +in lattice spacings. The lattice command must have +been previously used to define the lattice spacing. +

    +
    +

    Restrictions:

    -

    At the point in the input script when this command is issued, no -dumps can be active, nor can a fix -ave/spatial or fix deform be -active. This is because these commands test whether the simulation -box is orthogonal when they are first issued. Note that these -commands can appear in your script before a change_box command is -issued, so long as an undump or unfix -command is also used to turn them off. +

    If you use the ortho or triclinic keywords, then at the point in +the input script when this command is issued, no dumps can +be active, nor can a fix ave/spatial or fix +deform be active. This is because these commands +test whether the simulation box is orthogonal when they are first +issued. Note that these commands can be used in your script before a +change_box command is issued, so long as an undump or +unfix command is also used to turn them off.

    -

    Related commands: none +

    Related commands:

    -

    Default: none +

    fix deform, boundary +

    +

    Default: +

    +

    The option default is units = lattice.

    diff --git a/doc/change_box.txt b/doc/change_box.txt index 78c2c757d9..1b16b42dce 100644 --- a/doc/change_box.txt +++ b/doc/change_box.txt @@ -10,48 +10,285 @@ change_box command :h3 [Syntax:] -change_box style :pre +change_box group-ID parameter args ... keyword args ... :pre -style = {ortho} or {triclinic} :l - {ortho} = convert simulation box from non-orthogonal (triclinic) to orthogonal - {triclinic} = convert simulation box from orthogonal to non-orthogonal (triclinic) :pre +group-ID = ID of group of atoms to (optionally) displace :ulb,l +one or more parameter/arg pairs may be appended :l +parameter = {x} or {y} or {z} or {xy} or {xz} or {yz} or {boundary} or {ortho} or {triclinic} or {set} or {remap} + {x}, {y}, {z} args = style value(s) + style = {final} or {delta} or {scale} or {volume} + {final} values = lo hi + lo hi = box boundaries after displacement (distance units) + {delta} values = dlo dhi + dlo dhi = change in box boundaries after displacement (distance units) + {scale} values = factor + factor = multiplicative factor for change in box length after displacement + {volume} value = none = adjust this dim to preserve volume of system + {xy}, {xz}, {yz} args = style value + style = {final} or {delta} + {final} value = tilt + tilt = tilt factor after displacement (distance units) + {delta} value = dtilt + dtilt = change in tilt factor after displacement (distance units) + {boundary} args = x y z + x,y,z = {p} or {s} or {f} or {m}, one or two letters + {p} is periodic + {f} is non-periodic and fixed + {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 + {set} args = none = store state of current box + {remap} args = none = remap atom coords from last saved state to current box :pre + +zero or more keyword/value pairs may be appended :l +keyword = {units} :l + {units} value = {lattice} or {box} + lattice = distances are defined in lattice units + box = distances are defined in simulation box units :pre +:ule [Examples:] -change_box ortho -change_box triclinic :pre +change_box all xy final -2.0 z final 0.0 5.0 boundary p p f remap units box +change_box all x scale 1.1 y volume z volume remap :pre [Description:] -By default LAMMPS runs a simulation in an orthogonal, axis-aligned -simulation box. LAMMPS can also run simulations in "non-orthogonal -(triclinic) simulation boxes"_Section_howto.html#howto_12. A box is -defined as either orthogonal or non-orthogonal when it is created via -the "create_box"_create_box.html, "read_data"_read_data.html, or -"read_restart"_read_restart.html commands. +Change the volume and/or shape and/or boundary conditions for the +simulation box. Orthogonal simulation boxes have 3 adjustable size +parameters (x,y,z). Triclinic (non-orthogonal) simulation boxes have +6 adjustable size/shape parameters (x,y,z,xy,xz,yz). Any or all of +them can be adjusted independently by this command. Thus it can be +used to expand or contract a box, or to apply a shear strain to a +non-orthogonal box. It can also be used to change the boundary +conditions for the simulation box, similar to the +"boundary"_boundary.html command. -This command allows you to toggle the existing simulation box from -orthogonal to non-orthogonal and vice versa. For example, an initial +The size and shape of the initial simulation box are specified by the +"create_box"_create_box.html or "read_data"_read_data.html or +"read_restart"_read_restart.html command used to setup the simulation. +The size and shape may be altered by subsequent runs, e.g. by use of +the "fix npt"_fix_nh.html or "fix deform"_fix_deform.html commands. +The "create_box"_create_box.html, "read data"_read_data.html, and +"read_restart"_read_restart.html commands also determine whether the +simulation box is orthogonal or triclinic and their doc pages explain +the meaning of the xy,xz,yz tilt factors. + +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. + +The keywords used in this command are applied sequentially to the +simulation box and the atoms in it, in the order specified. + +Before the sequence of keywords are invoked, the current box +size/shape are stored, in case a {remap} keyword is used to map the +atom coordinates from the previous box size/shape to the current one. + +After all the keywords have been processed, any shrink-wrap boundary +conditions are invoked (see the "boundary"_boundary.html command) +which may change simulation box boundaries, and atoms are migrated to +new owning processors. + +IMPORTANT NOTE: It is possible to lose atoms with this command. +E.g. by changing the box without remapping the atoms, and having atoms +end up outside of non-periodic boundaries. It is also possible when +remapping atoms to put them (nearly) on top of each other which will +lead to bad dynamics. E.g. by converting a boundary from non-periodic +to periodic. + +IMPORTANT NOTE: The simulation box size/shape can be changed by +arbitrarily large amounts by this command. This is not a problem, +except that the mapping of processors to the simulation box is not +changed from its initial 3d configuration; see the +"processors"_processors.html command. Thus, if the box size/shape +changes dramatically, the mapping of processors to the simulation box +may not end up as optimal as the initial mapping attempted to be. + +:line + +For the {x}, {y}, and {z} parameters, this is the meaning of their +styles and values. + +For style {final}, the final lo and hi box boundaries of a dimension +are specified. The values can be in lattice or box distance units. +See the discussion of the units keyword below. + +For style {delta}, plus or minus changes in the lo/hi box boundaries +of a dimension are specified. The values can be in lattice or box +distance units. See the discussion of the units keyword below. + +For style {scale}, a multiplicative factor to apply to the box length +of a dimension is specified. For example, if the initial box length +is 10, and the factor is 1.1, then the final box length will be 11. A +factor less than 1.0 means compression. + +The {volume} style changes the specified dimension in such a way that +the overall box volume remains constant with respect to the operation +performed by the preceding keyword. The {volume} style can only be +used following a keyword that changed the volume, which is any of the +{x}, {y}, {z} keywords. If the preceding keyword "key" had a {volume} +style, then both it and the current keyword apply to the keyword +preceding "key". I.e. this sequence of keywords is allowed: + +change_box all x scale 1.1 y volume z volume :pre + +The {volume} style changes the associated dimension so that the +overall box volume is unchanged relative to its value before the +preceding keyword was invoked. + +If "x scale 1.1 z volume" is used, then the z box length will +shrink by the same 1.1 factor the x box length was increased by. + +If "x scale 1.1 y volume z volume" is used, then the y,z box lengths +will each shrink by sqrt(1.1) to keep the volume constant. In this +case, the y,z box lengths shrink so as to keep their relative aspect +ratio constant. + +If "x scale 1.1 z volume y scale 1.1 z volume" is used, then +the final box will be a factor of 10% larger in x and y, and a +factor of 21% smaller in z, so as to keep the volume constant. + +IMPORTANT NOTE: For solids or liquids, when one dimension of the box +is expanded, it may be physically undesirable to hold the other 2 box +lengths constant since that implies a density change. For solids, +adjusting the other dimensions via the {volume} style may make +physical sense (just as for a liquid), but may not be correct for +materials and potentials whose Poisson ratio is not 0.5. + +For the {scale} and {volume} styles, the box length is expanded or +compressed around its mid point. + +:line + +For the {xy}, {xz}, and {yz} parameters, this is the meaning of their +styles and values. Note that changing the tilt factors of a triclinic +box does not change its volume. + +For style {final}, the final tilt factor is specified. The value +can be in lattice or box distance units. See the discussion of the +units keyword below. + +For style {delta}, a plus or minus change in the tilt factor is +specified. The value can be in lattice or box distance units. See +the discussion of the units keyword below. + +All of these styles change the xy, xz, yz tilt factors. In LAMMPS, +tilt factors (xy,xz,yz) for triclinic boxes are required to be no 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. Any tilt factor specified by this command +must be within these limits. + +:line + +The {boundary} keyword takes arguments that have exactly the same +meaning as they do for the "boundary"_boundary.html command. In each +dimension, a single letter assigns the same style to both the lower +and upper face of the box. Two letters assigns the first style to the +lower face and the second style to the upper face. + +The style {p} means the box is periodic; the other styles mean +non-periodic. For style {f}, the position of the face is fixed. For +style {s}, the position of the face is set so as to encompass the +atoms in that dimension (shrink-wrapping), no matter how far they +move. For style {m}, shrink-wrapping occurs, but is bounded by the +current box edge in that dimension, so that the box will become no +smaller. See the "boundary"_boundary.html command for more +explanation of these style options. + +Note that the "boundary" command itself can only be used before the +simulation box is defined via a "read_data"_read_data.html or +"create_box"_create_box.html or "read_restart"_read_restart.html +command. This command allows the boundary conditions to be changed +later in your input script. Also note that the +"read_restart"_read_restart.html will change boundary conditions to +match what is stored in the restart file. So if you wish to change +them, you should use the change_box command after the read_restart +command. + +:line + +The {ortho} and {triclinic} keywords convert the simulation box to be +orthogonal or triclinic (non-orthongonal). See "this +section"_Section_howto#howto_13 for a discussion of how non-orthongal +boxes are represented in LAMMPS. + +The simulation box is defined as either orthogonal or triclinic when +it is created via the "create_box"_create_box.html, +"read_data"_read_data.html, or "read_restart"_read_restart.html +commands. + +These keywords allow you to toggle the existing simulation box from +orthogonal to triclinic and vice versa. For example, an initial equilibration simulation can be run in an orthogonal box, the box can -be toggled to non-orthogonal, and then a "non-equilibrium MD (NEMD) +be toggled to triclinic, and then a "non-equilibrium MD (NEMD) simulation"_Section_howto.html#howto_13 can be run with deformation via the "fix deform"_fix_deform.html command. -Note that if the simulation box is currently non-orthogonal and has -non-zero tilt in xy, yz, or xz, then it cannot be converted to an -orthogonal box. +If the simulation box is currently triclinic and has non-zero tilt in +xy, yz, or xz, then it cannot be converted to an orthogonal box. + +:line + +The {set} keyword saves the current box size/shape. This can be +useful if you wish to use the {remap} keyword more than once or if you +wish it to be applied to an intermediate box size/shape in a sequence +of keyword operations. Note that the box size/shape is saved before +any of the keywords are processed, i.e. the box size/shape at the time +the create_box command is encountered in the input script. + +The {remap} keyword remaps atom coordinates from the last saved box +size/shape to the current box state. For example, if you stretch the +box in the x dimension or tilt it in the xy plane via the {x} and {xy} +keywords, then the {remap} commmand will dilate or tilt the atoms to +conform to the new box size/shape, as if the atoms moved with the box +as it deformed. + +Note that this operation is performed without regard to periodic +boundaries. Any shrink-wrapping of non-periodic boundaries (see the +"boundary"_boundary.html command occurs after all keywords, including +this one, have been processed. + +Only atoms in the specified group are remapped. + +IMPORTANT NOTE: If you do not explicitly specify the {remap} keyword, +atom coordinates will not be changed even though the box size/shape +changes. This may be the behavior you desire, but can also cause +atoms to be lost. + +:line + +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"_units.html command, e.g. Angstroms for +units = real or metal. A {lattice} value means the distance units are +in lattice spacings. The "lattice"_lattice.html command must have +been previously used to define the lattice spacing. + +:line [Restrictions:] -At the point in the input script when this command is issued, no -"dumps"_dump.html can be active, nor can a "fix -ave/spatial"_fix_ave_spatial.html or "fix deform"_fix_deform.html be -active. This is because these commands test whether the simulation -box is orthogonal when they are first issued. Note that these -commands can appear in your script before a change_box command is -issued, so long as an "undump"_undump.html or "unfix"_unfix.html -command is also used to turn them off. +If you use the {ortho} or {triclinic} keywords, then at the point in +the input script when this command is issued, no "dumps"_dump.html can +be active, nor can a "fix ave/spatial"_fix_ave_spatial.html or "fix +deform"_fix_deform.html be active. This is because these commands +test whether the simulation box is orthogonal when they are first +issued. Note that these commands can be used in your script before a +change_box command is issued, so long as an "undump"_undump.html or +"unfix"_unfix.html command is also used to turn them off. -[Related commands:] none +[Related commands:] -[Default:] none +"fix deform"_fix_deform.html, "boundary"_boundary.html + +[Default:] + +The option default is units = lattice. diff --git a/doc/displace_atoms.html b/doc/displace_atoms.html index 3c433bc2c3..9f46e08d97 100644 --- a/doc/displace_atoms.html +++ b/doc/displace_atoms.html @@ -76,29 +76,29 @@ define the lattice spacing.


    -

    Care should be taken not to move atoms on top of other atoms. After -the move, atoms are remapped into the periodic simulation box if -needed. +

    IMPORTANT NOTE: Care should be taken not to move atoms on top of other +atoms. After the move, atoms are remapped into the periodic +simulation box if needed, and any shrink-wrap boundary conditions (see +the boundary command) are enforced which may change +the box size. Other than this effect, this command does not change +the size or shape of the simulation box. See the +change_box command if that effect is desired.

    -

    Atoms can be moved arbitrarily long distances by this command. If the -simulation box is non-periodic, this can change its size or shape. -This is not a problem, except that the mapping of processors to the -simulation box is not changed by this command from its initial 3d -configuration; see the processors command. Thus, if -the box size or shape changes dramatically, the simulation may not be -as well load-balanced (atoms per processor) as the initial mapping -tried to achieve. +

    IMPORTANT NOTE: Atoms can be moved arbitrarily long distances by this +command. If the simulation box is non-periodic and shrink-wrapped +(see the boundary command), this can change its size +or shape. This is not a problem, except that the mapping of +processors to the simulation box is not changed by this command from +its initial 3d configuration; see the processors +command. Thus, if the box size/shape changes dramatically, the +mapping of processors to the simulation box may not end up as optimal +as the initial mapping attempted to be.

    -

    Restrictions: -

    -

    This command requires inter-processor communication to migrate atoms -once they have been displaced. This means that your system must be -ready to perform a simulation before using this command (force fields -are setup, atom masses are set, etc). +

    Restrictions: none

    Related commands:

    -

    lattice +

    lattice, change_box

    Default:

    diff --git a/doc/displace_atoms.txt b/doc/displace_atoms.txt index d26f58e258..53585c059c 100644 --- a/doc/displace_atoms.txt +++ b/doc/displace_atoms.txt @@ -68,29 +68,29 @@ define the lattice spacing. :line -Care should be taken not to move atoms on top of other atoms. After -the move, atoms are remapped into the periodic simulation box if -needed. +IMPORTANT NOTE: Care should be taken not to move atoms on top of other +atoms. After the move, atoms are remapped into the periodic +simulation box if needed, and any shrink-wrap boundary conditions (see +the "boundary"_boundary.html command) are enforced which may change +the box size. Other than this effect, this command does not change +the size or shape of the simulation box. See the +"change_box"_change_box.html command if that effect is desired. -Atoms can be moved arbitrarily long distances by this command. If the -simulation box is non-periodic, this can change its size or shape. -This is not a problem, except that the mapping of processors to the -simulation box is not changed by this command from its initial 3d -configuration; see the "processors"_processors.html command. Thus, if -the box size or shape changes dramatically, the simulation may not be -as well load-balanced (atoms per processor) as the initial mapping -tried to achieve. +IMPORTANT NOTE: Atoms can be moved arbitrarily long distances by this +command. If the simulation box is non-periodic and shrink-wrapped +(see the "boundary"_boundary.html command), this can change its size +or shape. This is not a problem, except that the mapping of +processors to the simulation box is not changed by this command from +its initial 3d configuration; see the "processors"_processors.html +command. Thus, if the box size/shape changes dramatically, the +mapping of processors to the simulation box may not end up as optimal +as the initial mapping attempted to be. -[Restrictions:] - -This command requires inter-processor communication to migrate atoms -once they have been displaced. This means that your system must be -ready to perform a simulation before using this command (force fields -are setup, atom masses are set, etc). +[Restrictions:] none [Related commands:] -"lattice"_lattice.html +"lattice"_lattice.html, "change_box"_change_box.html [Default:] diff --git a/doc/displace_box.html b/doc/displace_box.html deleted file mode 100644 index d589e686c1..0000000000 --- a/doc/displace_box.html +++ /dev/null @@ -1,191 +0,0 @@ - -
    LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands -
    - - - - - - -
    - -

    displace_box command -

    -

    Syntax: -

    -
    displace_box group-ID parameter args ... keyword value ... 
    -
    -
    • group-ID = ID of group of atoms to displace - -
    • one or more parameter/arg pairs may be appended - -
      parameter = x or y or z or xy or xz or yz
      -  x, y, z args = style value(s)
      -    style = final or delta or scale or volume
      -      final values = lo hi
      -        lo hi = box boundaries at end of run (distance units)
      -      delta values = dlo dhi
      -        dlo dhi = change in box boundaries at end of run (distance units)
      -      scale values = factor
      -        factor = multiplicative factor for change in box length at end of run
      -      volume value = none = adjust this dim to preserve volume of system
      -  xy, xz, yz args = style value
      -    style = final or delta
      -      final value = tilt
      -        tilt = tilt factor at end of run (distance units)
      -      delta value = dtilt
      -        dtilt = change in tilt factor at end of run (distance units) 
      -
      -
    • zero or more keyword/value pairs may be appended - -
    • keyword = remap or units - -
        remap value = x or none
      -    x = remap coords of atoms in group into deforming box
      -    none = no remapping of coords
      -  units value = lattice or box
      -    lattice = distances are defined in lattice units
      -    box = distances are defined in simulation box units 
      -
      - -
    -

    Examples: -

    -
    displace_box all xy final -2.0 z final 0.0 5.0 units box
    -displace_box all x scale 1.1 y volume z volume 
    -
    -

    Description: -

    -

    Change the volume and/or shape of the simulation box. Orthogonal -simulation boxes have 3 adjustable parameters (x,y,z). Triclinic -(non-orthogonal) simulation boxes have 6 adjustable parameters -(x,y,z,xy,xz,yz). Any or all of them can be adjusted independently -and simultaneously by this command. This fix can be used to expand or -contract a box, or to apply a shear strain to a non-orthogonal box. -

    -

    Any parameter varied by this command must refer to a periodic -dimension - see the boundary command. For parameters -"xy", "xz", and "yz" this means both affected dimensions must be -periodic, e.g. x and y for "xy". Dimensions not varied by this -command can be periodic or non-periodic. -

    -

    The size and shape of the initial simulation box are specified by the -create_box or read_data or -read_restart command used to setup the simulation, -or they are the values from the end of the previous run. The -create_box, read data, and -read_restart commands also determine whether the -simulation box is orthogonal or triclinic and their doc pages explain -the meaning of the xy,xz,yz tilt factors. If the displace_box command -changes the xy,xz,yz tilt factors, then the simulation box must be -triclinic, even if its initial tilt factors are 0.0. -

    -
    - -

    For the x, y, and z parameters, this is the meaning of their -styles and values. -

    -

    For style final, the final lo and hi box boundaries of a dimension -are specified. The values can be in lattice or box distance units. -See the discussion of the units keyword below. -

    -

    For style delta, plus or minus changes in the lo/hi box boundaries -of a dimension are specified. The values can be in lattice or box -distance units. See the discussion of the units keyword below. -

    -

    For style scale, a multiplicative factor to apply to the box length -of a dimension is specified. For example, if the initial box length -is 10, and the factor is 1.1, then the final box length will be 11. A -factor less than 1.0 means compression. -

    -

    The volume style changes the specified dimension in such a way that -the box volume remains constant while other box dimensions are changed -explicitly via the styles discussed above. For example, "x scale 1.1 -y scale 1.1 z volume" will shrink the z box length as the x,y box -lengths increase, to keep the volume constant (product of x,y,z -lengths). If "x scale 1.1 z volume" is specified and parameter y is -unspecified, then the z box length will shrink as x increases to keep -the product of x,z lengths constant. If "x scale 1.1 y volume z -volume" is specified, then both the y,z box lengths will shrink as x -increases to keep the volume constant (product of x,y,z lengths). In -this case, the y,z box lengths shrink so as to keep their relative -aspect ratio constant. -

    -

    For solids or liquids, note that when one dimension of the box is -expanded by this command, it may be physically undesirable to hold the -other 2 box lengths constant (unspecified by this command) since that -implies a density change. Using the volume style for those 2 -dimensions to keep the box volume constant may make more physical -sense, but may also not be correct for materials and potentials whose -Poisson ratio is not 0.5. -

    -

    For the scale and volume styles, the box length is expanded or -compressed around its mid point. -

    -
    - -

    For the xy, xz, and yz parameters, this is the meaning of their -styles and values. Note that changing the tilt factors of a triclinic -box does not change its volume. -

    -

    For style final, the final tilt factor is specified. The value -can be in lattice or box distance units. See the discussion of the -units keyword below. -

    -

    For style delta, a plus or minus change in the tilt factor is -specified. The value can be in lattice or box distance units. See -the discussion of the units keyword below. -

    -

    All of these styles change the xy, xz, yz tilt factors. 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 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. Any tilt factor specified by this command must be within -these limits. -

    -
    - -

    The remap keyword determines whether atom positions are re-mapped to -the new box. If remap is set to x (the default), atoms in the fix -group are re-mapped; otherwise they are not. If remap is set to -none, then this remapping does not take place. -

    -

    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 -units = real or metal. A lattice value means the distance units are -in lattice spacings. The lattice command must have -been previously used to define the lattice spacing. -

    -
    - -

    The simulation box size or shape can be changed by arbitrarily large -amounts by this command. This is not a problem, except that the -mapping of processors to the simulation box is not changed by this -command from its initial 3d configuration; see the -processors command. Thus, if the box size or shape -changes dramatically, the simulation may not be as well load-balanced -(atoms per processor) as the initial mapping tried to achieve. -

    -

    Restrictions: -

    -

    Any box dimension varied by this fix must be periodic. -

    -

    This command requires inter-processor communication to migrate atoms -once they have moved. This means that your system must be ready to -perform a simulation before using this command (force fields are -setup, atom masses are set, etc). -

    -

    Related commands: -

    -

    fix deform -

    -

    Default: -

    -

    The option defaults are remap = x and units = lattice. -

    - diff --git a/doc/displace_box.txt b/doc/displace_box.txt deleted file mode 100644 index 263c53d0ae..0000000000 --- a/doc/displace_box.txt +++ /dev/null @@ -1,181 +0,0 @@ -"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 - -displace_box command :h3 - -[Syntax:] - -displace_box group-ID parameter args ... keyword value ... :pre - -group-ID = ID of group of atoms to displace :ulb,l -one or more parameter/arg pairs may be appended :l -parameter = {x} or {y} or {z} or {xy} or {xz} or {yz} - {x}, {y}, {z} args = style value(s) - style = {final} or {delta} or {scale} or {volume} - {final} values = lo hi - lo hi = box boundaries at end of run (distance units) - {delta} values = dlo dhi - dlo dhi = change in box boundaries at end of run (distance units) - {scale} values = factor - factor = multiplicative factor for change in box length at end of run - {volume} value = none = adjust this dim to preserve volume of system - {xy}, {xz}, {yz} args = style value - style = {final} or {delta} - {final} value = tilt - tilt = tilt factor at end of run (distance units) - {delta} value = dtilt - dtilt = change in tilt factor at end of run (distance units) :pre - -zero or more keyword/value pairs may be appended :l -keyword = {remap} or {units} :l - {remap} value = {x} or {none} - x = remap coords of atoms in group into deforming box - none = no remapping of coords - {units} value = {lattice} or {box} - lattice = distances are defined in lattice units - box = distances are defined in simulation box units :pre -:ule - -[Examples:] - -displace_box all xy final -2.0 z final 0.0 5.0 units box -displace_box all x scale 1.1 y volume z volume :pre - -[Description:] - -Change the volume and/or shape of the simulation box. Orthogonal -simulation boxes have 3 adjustable parameters (x,y,z). Triclinic -(non-orthogonal) simulation boxes have 6 adjustable parameters -(x,y,z,xy,xz,yz). Any or all of them can be adjusted independently -and simultaneously by this command. This fix can be used to expand or -contract a box, or to apply a shear strain to a non-orthogonal box. - -Any parameter varied by this command must refer to a periodic -dimension - see the "boundary"_boundary.html command. For parameters -"xy", "xz", and "yz" this means both affected dimensions must be -periodic, e.g. x and y for "xy". Dimensions not varied by this -command can be periodic or non-periodic. - -The size and shape of the initial simulation box are specified by the -"create_box"_create_box.html or "read_data"_read_data.html or -"read_restart"_read_restart.html command used to setup the simulation, -or they are the values from the end of the previous run. The -"create_box"_create_box.html, "read data"_read_data.html, and -"read_restart"_read_restart.html commands also determine whether the -simulation box is orthogonal or triclinic and their doc pages explain -the meaning of the xy,xz,yz tilt factors. If the displace_box command -changes the xy,xz,yz tilt factors, then the simulation box must be -triclinic, even if its initial tilt factors are 0.0. - -:line - -For the {x}, {y}, and {z} parameters, this is the meaning of their -styles and values. - -For style {final}, the final lo and hi box boundaries of a dimension -are specified. The values can be in lattice or box distance units. -See the discussion of the units keyword below. - -For style {delta}, plus or minus changes in the lo/hi box boundaries -of a dimension are specified. The values can be in lattice or box -distance units. See the discussion of the units keyword below. - -For style {scale}, a multiplicative factor to apply to the box length -of a dimension is specified. For example, if the initial box length -is 10, and the factor is 1.1, then the final box length will be 11. A -factor less than 1.0 means compression. - -The {volume} style changes the specified dimension in such a way that -the box volume remains constant while other box dimensions are changed -explicitly via the styles discussed above. For example, "x scale 1.1 -y scale 1.1 z volume" will shrink the z box length as the x,y box -lengths increase, to keep the volume constant (product of x,y,z -lengths). If "x scale 1.1 z volume" is specified and parameter {y} is -unspecified, then the z box length will shrink as x increases to keep -the product of x,z lengths constant. If "x scale 1.1 y volume z -volume" is specified, then both the y,z box lengths will shrink as x -increases to keep the volume constant (product of x,y,z lengths). In -this case, the y,z box lengths shrink so as to keep their relative -aspect ratio constant. - -For solids or liquids, note that when one dimension of the box is -expanded by this command, it may be physically undesirable to hold the -other 2 box lengths constant (unspecified by this command) since that -implies a density change. Using the {volume} style for those 2 -dimensions to keep the box volume constant may make more physical -sense, but may also not be correct for materials and potentials whose -Poisson ratio is not 0.5. - -For the {scale} and {volume} styles, the box length is expanded or -compressed around its mid point. - -:line - -For the {xy}, {xz}, and {yz} parameters, this is the meaning of their -styles and values. Note that changing the tilt factors of a triclinic -box does not change its volume. - -For style {final}, the final tilt factor is specified. The value -can be in lattice or box distance units. See the discussion of the -units keyword below. - -For style {delta}, a plus or minus change in the tilt factor is -specified. The value can be in lattice or box distance units. See -the discussion of the units keyword below. - -All of these styles change the xy, xz, yz tilt factors. 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 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. Any tilt factor specified by this command must be within -these limits. - -:line - -The {remap} keyword determines whether atom positions are re-mapped to -the new box. If {remap} is set to {x} (the default), atoms in the fix -group are re-mapped; otherwise they are not. If {remap} is set to -{none}, then this remapping does not take place. - -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"_units.html command, e.g. Angstroms for -units = real or metal. A {lattice} value means the distance units are -in lattice spacings. The "lattice"_lattice.html command must have -been previously used to define the lattice spacing. - -:line - -The simulation box size or shape can be changed by arbitrarily large -amounts by this command. This is not a problem, except that the -mapping of processors to the simulation box is not changed by this -command from its initial 3d configuration; see the -"processors"_processors.html command. Thus, if the box size or shape -changes dramatically, the simulation may not be as well load-balanced -(atoms per processor) as the initial mapping tried to achieve. - -[Restrictions:] - -Any box dimension varied by this fix must be periodic. - -This command requires inter-processor communication to migrate atoms -once they have moved. This means that your system must be ready to -perform a simulation before using this command (force fields are -setup, atom masses are set, etc). - -[Related commands:] - -"fix deform"_fix_deform.html - -[Default:] - -The option defaults are remap = x and units = lattice. diff --git a/doc/fix_deform.html b/doc/fix_deform.html index 76b723d59c..6be57e95ca 100644 --- a/doc/fix_deform.html +++ b/doc/fix_deform.html @@ -533,7 +533,7 @@ xy) that is shrink-wrapped via the boundary comamn

    Related commands:

    -

    displace_box +

    change_box

    Default:

    diff --git a/doc/fix_deform.txt b/doc/fix_deform.txt index 51baaea5a9..5a3a2ae584 100644 --- a/doc/fix_deform.txt +++ b/doc/fix_deform.txt @@ -523,7 +523,7 @@ xy) that is shrink-wrapped via the "boundary"_boundary.html comamnd. [Related commands:] -"displace_box"_displace_box.html +"change_box"_change_box.html [Default:]