lammps/doc/fix_deform.txt

"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

fix deform command :h3

[Syntax:]

fix ID group-ID deform N parameter args ... keyword value ... :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l
deform = style name of this fix command :l
N = perform box deformation every this many timesteps :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 {vel} or {rate} 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
      {vel} value = V
        V = change box length at this velocity (distance/time units),
	    effectively an engineering strain rate
      {rate} value = R
        R = true strain rate (1/time units)
      {volume} value = none = adjust this dim to preserve volume of system
  {xy}, {xz}, {yz} args = style value
    style = {final} or {delta} or {vel} or {rate}
      {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)
      {vel} value = V
        V = change tilt factor at this velocity (distance/time units),
	    effectively an engineering shear strain rate
      {rate} value = R
        R = true shear strain rate (1/time units) :pre

zero or more keyword/value pairs may be appended to the args :l
keyword = {remap} or {units} :l
  {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
  {units} value = {lattice} or {box}
    lattice = distances are defined in lattice units
    box = distances are defined in simulation box units :pre
:ule

[Examples:]

fix 1 all deform x final 0.0 9.0 z final 0.0 5.0 units box
fix 1 all deform x rate 0.1 y volume z volume
fix 1 all deform xy rate 0.001 remap v
fix 1 all deform y delta 0.5 xz vel 1.0 :pre

[Description:]

Change the volume and/or shape of the simulation box during a dynamics
run.  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 perform non-equilibrium MD (NEMD) simulations of a
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" 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.  Unspecified dimensions can
also be controlled by a "fix npt"_fix_npt.html or "fix
nph"_fix_nph.html command.

The size and shape of the initial simulation box at the beginning of a
run 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 specify whether the simulation box is orthogonal or triclinic and
explain the meaning of the xy,xz,yz tilt factors.  If fix deform
changes the xy,xz,yz tilt factors, then the simulation box must be
triclinic, even if its initial tilt factors are 0.0.

As described below, the desired simulation box size and shape at the
end of the run are determined by the parameters of the fix deform
command.  Every Nth timestep during the run, the simulation box is
expanded, contracted, or tilted to ramped values between the initial
and final values.  The "run"_run.html command documents how to make
the ramping take place across multiple runs.

:line

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

The {final}, {delta}, {scale}, and {vel} styles all change the
specified dimension of the box via "constant displacement" which is
effectively a "constant engineering strain rate".  This means the box
dimension changes linearly with time from its initial to final value.

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

For style {vel}, a velocity at which the box length changes is
specified in units of distance/time.  This is effectively an
"engineering strain rate", where rate = V/L0 and L0 is the initial box
length.  The distance can be in lattice or box distance units.  See
the discussion of the units keyword below.  For example, if the
initial box length is 100 Angstroms, and V is 10 Angstroms/psec,
then after 10 psec, the box length will have doubled.  After 20 psec,
it will have tripled.

The {rate} style changes a dimension of the box at a "true constant
strain rate".  Note that this is not an "engineering strain rate", as
the other styles are.  Rather, for a "true" rate, the rate of change
is constant, which means the box dimension changes non-linearly with
time from its initial to final value.  The units of the specified
strain rate are 1/time.  See the "units"_units.html command for the
time units associated with different choices of simulation units,
e.g. picoseconds for "metal" units).  Thus if the {rate} R is 0.01 and
time units are picoseconds, this means the box length will increase by
1% every picosecond.  R = 1 or 2 means the box length will double or
triple every picosecond.  R = -0.1 means the box length will shrink by
10% every picosecond.  Note that for a "true" rate the change is
continuous, so running with R = 1 for 10 picoseconds does not expand
the box length by a factor of 10, but by a factor of 1024 since it
doubles every picosecond.

Note that to change the volume (or cross-sectional area) of the
simulation box at a constant rate, you can change multiple dimensions
via {rate}.  E.g. to double the box volume every picosecond, you could
set "x rate M", "y rate M", "z rate M", with M = pow(2,1/3) - 1 =
1.26, since if each box dimension grows by 26%, the box volume
doubles.

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 via fix deform (i.e. tensile strain), it may be physically
undesirable to hold the other 2 box lengths constant (unspecified by
fix deform) 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.  An alternative is to use
"fix npt aniso"_fix_npt.html with zero applied pressure on those 2
dimensions, so that they respond to the tensile strain dynamically.

For the {scale}, {vel}, {rate}, 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 discsussion of the units keyword below.

For style {vel}, a velocity at which the tilt factor changes is
specified in units of distance/time.  This is effectively an
"engineering shear strain rate", where rate = V/L0 and L0 is the
initial box length perpendicular to the direction of shear.  The
distance can be in lattice or box distance units.  See the discsussion
of the units keyword below.  For example, if the initial tilt factor
is 5 Angstroms, and the V is 10 Angstroms/psec, then after 1 psec, the
tilt factor will be 15 Angstroms.  After 2 psec, it will be 25
Angstroms.

The {rate} style changes a tilt factor at a "true constant shear
strain rate".  Note that this is not an "engineering shear strain
rate", as the other styles are.  Rather, for a "true" rate, the rate
of change is constant, which means the tilt factor changes
non-linearly with time from its initial to final value.  The units of
shear strain rate are 1/time.  See the "units"_units.html command for
the time units associated with different choices of simulation units,
e.g. picoseconds for "metal" units).  Thus if the {rate} R is 0.01 and
time units are picoseconds, this means the tilt factor will increase
by 1% every picosecond.  R = 1 or 2 means the tilt factor will double
or triple every picosecond.  R = -0.1 means the tilt factor will
shrink by 10% every picosecond.  Note that the change is continuous,
so running with R = 1 for 10 picoseconds does not change the tilt
factor by a factor of 10, but by a factor of 1024 since it doubles
every picosecond.  Also note, that the initial tilt factor must be
non-zero to use the {rate} option.

Note that shear strain is defined as the tilt factor divided by the
perpendicular box length.  The {rate} style controls the tilt factor,
but assumes the perpendicular box length remains constant.  If this is
not the case (e.g. it changes due to another fix deform parameter),
then this effect on the shear strain is ignored.

All of these 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
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.

To obey this constraint and allow for large shear deformations to be
applied via the {xy}, {xz}, or {yz} parameters, the folloiwng
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.

:line

Each time the box size or shape is changed, 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 {v}, then any
atom in the fix group that crosses a periodic boundary will have a
delta added to its velocity equal to the difference in velocities
between the lo and hi boundaries.  Note that this velocity difference
can include tilt components, e.g. a delta in the x velocity when an
atom crosses the y periodic boundary.  If {remap} is set to {none},
then neither of these remappings take place.

IMPORTANT NOTE: When non-equilibrium MD (NEMD) simulations are
performed using this fix, the option "remap v" should normally be
used.  This is because "fix nvt/sllod"_fix_nvt_sllod.html adjusts the
atom positions and velocities to provide a velocity profile that
matches the changing box size/shape.  Thus atom coordinates should NOT
be remapped by fix deform, but velocities SHOULD be when atoms cross
periodic boundaries, since when atoms cross periodic boundaries since
that is consistent with maintaining the velocity profile created by
fix nvt/sllod.  LAMMPS will warn you if this settings is not
consistent.

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.  Note that the
units choice also affects the {vel} style parameters since it is
defined in terms of distance/time.

:line

[Restrictions:]

Any box dimension varied by this fix must be periodic.

[Related commands:] none

[Default:]

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