Homec4science
Diffusion lammps (runner) Browse

lammps/doc/region.html
d80c13054b7brunner

Last Change
Raw File

region.html
View Options

<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>region command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>region ID style args keyword value ...
</PRE>
<UL><LI>ID = user-assigned name for the region
<LI>style = <I>delete</I> or <I>block</I> or <I>cone</I> or <I>cylinder</I> or <I>plane</I> or <I>prism</I> or <I>sphere</I> or <I>union</I> or <I>intersect</I>
<PRE> <I>delete</I> = no args
<I>block</I> args = xlo xhi ylo yhi zlo zhi
xlo,xhi,ylo,yhi,zlo,zhi = bounds of block in all dimensions (distance units)
<I>cone</I> args = dim c1 c2 radlo radhi lo hi
dim = <I>x</I> or <I>y</I> or <I>z</I> = axis of cone
c1,c2 = coords of cone axis in other 2 dimensions (distance units)
radlo,radhi = cone radii at lo and hi end (distance units)
lo,hi = bounds of cone in dim (distance units)
<I>cylinder</I> args = dim c1 c2 radius lo hi
dim = <I>x</I> or <I>y</I> or <I>z</I> = axis of cylinder
c1,c2 = coords of cylinder axis in other 2 dimensions (distance units)
radius = cylinder radius (distance units)
lo,hi = bounds of cylinder in dim (distance units)
<I>plane</I> args = px py pz nx ny nz
px,py,pz = point on the plane (distance units)
nx,ny,nz = direction normal to plane (distance units)
<I>prism</I> args = xlo xhi ylo yhi zlo zhi xy xz yz
xlo,xhi,ylo,yhi,zlo,zhi = bounds of untilted prism (distance units)
xy = distance to tilt y in x direction (distance units)
xz = distance to tilt z in x direction (distance units)
yz = distance to tilt z in y direction (distance units)
<I>sphere</I> args = x y z radius
x,y,z = center of sphere (distance units)
radius = radius of sphere (distance units)
<I>union</I> args = N reg-ID1 reg-ID2 ...
N = # of regions to follow, must be 2 or greater
reg-ID1,reg-ID2, ... = IDs of regions to join together
<I>intersect</I> args = N reg-ID1 reg-ID2 ...
N = # of regions to follow, must be 2 or greater
reg-ID1,reg-ID2, ... = IDs of regions to intersect
</PRE>
<LI>zero or more keyword/value pairs may be appended
<LI>keyword = <I>side</I> or <I>units</I> or <I>vel</I> or <I>wiggle</I> or <I>rotate</I>
<PRE> <I>side</I> value = <I>in</I> or <I>out</I>
<I>in</I> = the region is inside the specified geometry
<I>out</I> = the region is outside the specified geometry
<I>units</I> value = <I>lattice</I> or <I>box</I>
<I>lattice</I> = the geometry is defined in lattice units
<I>box</I> = the geometry is defined in simulation box units
<I>vel</I> args = Vx Vy Vz
Vx,Vy,Vz = components of velocity vector (velocity units)
<I>wiggle</I> args = Ax Ay Az period
Ax,Ay,Az = components of amplitude vector (distance units)
period = period of oscillation (time units)
<I>rotate</I> args = Px Py Pz Rx Ry Rz period
Px,Py,Pz = origin point of axis of rotation (distance units)
Rx,Ry,Rz = axis of rotation vector
period = period of rotation (time units)
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>region 1 block -3.0 5.0 INF 10.0 INF INF
region 2 sphere 0.0 0.0 0.0 5 side out
region void cylinder y 2 3 5 -5.0 EDGE units box
region 1 prism 0 10 0 10 0 10 2 0 0
region outside union 4 side1 side2 side3 side4
region 2 sphere 0.0 0.0 0.0 5 side out wiggle 1 1 0 10
</PRE>
<P><B>Description:</B>
</P>
<P>This command defines a geometric region of space. Various other
commands use regions. For example, the region can be filled with
atoms via the <A HREF = "create_atoms.html">create_atoms</A> command. Or the atoms
in the region can be identified as a group via the <A HREF = "group.html">group</A>
command, or deleted via the <A HREF = "delete_atoms.html">delete_atoms</A> command.
Or the surface of the region can be used as a boundary wall via the
<A HREF = "fix_wall_region.html">fix wall/region</A> command.
</P>
<P>Normally, regions in LAMMPS are "static", meaning their geometric
extent does not change with time. If the <I>vel</I> or <I>wiggle</I> or
<I>rotate</I> keyword is used, as described below, the region becomes
"dynamic", meaning it's location or orientation changes with time.
This may be useful, for example, when thermostatting a region, via the
compute temp/region command, or when the fix wall/region command uses
a region surface as a bounding wall on particle motion, i.e. a
rotating container.
</P>
<P>The <I>delete</I> style removes the named region. Since there is little
overhead to defining extra regions, there is normally no need to do
this, unless you are defining and discarding large numbers of regions
in your input script.
</P>
<P>The lo/hi values for <I>block</I> or <I>cone</I> or <I>cylinder</I> or <I>prism</I> styles
can be specified as EDGE or INF. EDGE means they extend all the way
to the global simulation box boundary. Note that this is the current
box boundary; if the box changes size during a simulation, the region
does not. INF means a large negative or positive number (1.0e20), so
it should encompass the simulation box even if it changes size. If a
region is defined before the simulation box has been created (via
<A HREF = "create_box.html">create_box</A> or <A HREF = "read_data.html">read_data</A> or
<A HREF = "read_restart.html">read_restart</A> commands), then an EDGE or INF
parameter cannot be used. For a <I>prism</I> region, a non-zero tilt
factor in any pair of dimensions cannot be used if both the lo/hi
values in either of those dimensions are INF. E.g. if the xy tilt is
non-zero, then xlo and xhi cannot both be INF, nor can ylo and yhi.
</P>
<P>IMPORTANT NOTE: Regions in LAMMPS do not get wrapped across periodic
boundaries, as specified by the <A HREF = "boundary.html">boundary</A> command. For
example, a spherical region that is defined so that it overlaps a
periodic boundary is not treated as 2 half-spheres, one on either side
of the simulation box.
</P>
<P>IMPORTANT NOTE: Regions in LAMMPS are always 3d geometric objects,
regardless of whether the <A HREF = "dimension.html">dimension</A> of a simulation
is 2d or 3d. Thus when using regions in a 2d simulation, you should
be careful to define the region so that its intersection with the 2d
x-y plane of the simulation is the 2d geometric object you want.
</P>
<P>For style <I>cone</I>, an axis-aligned cone is defined which is like a
<I>cylinder</I> except that two different radii (one at each end) can be
defined. Either of the radii (but not both) can be 0.0.
</P>
<P>For style <I>cone</I> and <I>cylinder</I>, the c1,c2 params are coordinates in
the 2 other dimensions besides the cylinder axis dimension. For dim =
x, c1/c2 = y/z; for dim = y, c1/c2 = x/z; for dim = z, c1/c2 = x/y.
Thus the third example above specifies a cylinder with its axis in the
y-direction located at x = 2.0 and z = 3.0, with a radius of 5.0, and
extending in the y-direction from -5.0 to the upper box boundary.
</P>
<P>For style <I>plane</I>, a plane is defined which contain the point
(px,py,pz) and has a normal vector (nx,ny,nz). The normal vector does
not have to be of unit length. The "inside" of the plane is the
half-space in the direction of the normal vector; see the discussion
of the <I>side</I> option below.
</P>
<P>For style <I>prism</I>, a parallelepiped is defined (it's too hard to spell
parallelepiped in an input script!). Think of the parallelepiped as
initially an axis-aligned orthogonal box with the same xyz lo/hi
parameters as region style <I>block</I> would define. Then, while holding
the (xlo,ylo,zlo) corner point fixed, the box is "skewed" or "tilted"
in 3 directions. First, for the lower xy face of the box, the <I>xy</I>
factor is how far the upper y edge is shifted in the x direction. The
lower xy face is now a parallelogram. A plus or minus value for <I>xy</I>
can be specified; 0.0 means no tilt. Then, the upper xy face of the
box is translated in the x and y directions by <I>xz</I> and <I>yz</I>. This
results in a parallelepiped whose "origin" is at (xlo,ylo,zlo) with 3
edge vectors starting from its origin given by a = (xhi-xlo,0,0); b =
(xy,yhi-ylo,0); c = (xz,yz,zhi-zlo).
</P>
<P>A prism region used with the <A HREF = "create_box.html">create_box</A> command must
have tilt factors (xy,xz,yz) that do not skew the box more than half
the distance of the parallel box length. For example, if xlo = 2 and
xhi = 12, then the x box length is 10 and the xy tilt factor must be
between -5 and 5. Similarly, both xz and yz must be between
-(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation,
since if the maximum tilt factor is 5 (as in this example), then
configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all
equivalent.
</P>
<P>The <I>union</I> style creates a region consisting of the volume of all the
listed regions combined. The <I>intersect</I> style creates a region
consisting of the volume that is common to all the listed regions.
</P>
<HR>
<P>The <I>side</I> keyword determines whether the region is considered to be
inside or outside of the specified geometry. Using this keyword in
conjunction with <I>union</I> and <I>intersect</I> regions, complex geometries
can be built up. For example, if the interior of two spheres were
each defined as regions, and a <I>union</I> style with <I>side</I> = out was
constructed listing the region-IDs of the 2 spheres, the resulting
region would be all the volume in the simulation box that was outside
both of the spheres.
</P>
<P>The <I>units</I> keyword determines the meaning of the distance units used
to define the region for any argument above listed as having distance
units. It also affects the scaling of the velocity vector specfied
with the <I>vel</I> keyword, the amplitude vector specified with the
<I>wiggle</I> keyword, and the rotation point specified with the <I>rotate</I>
keyword, since they each involve a distance metric.
</P>
<P>A <I>box</I> value selects standard distance units as defined by the
<A HREF = "units.html">units</A> command, e.g. Angstroms for units = real or metal.
A <I>lattice</I> value means the distance units are in lattice spacings.
The <A HREF = "lattice.html">lattice</A> command must have been previously used to
define the lattice spacings which are used as follows:
</P>
<UL><LI>For style <I>block</I>, the lattice spacing in dimension x is applied to
xlo and xhi, similarly the spacings in dimensions y,z are applied to
ylo/yhi and zlo/zhi.
<LI>For style <I>cone</I>, the lattice spacing in argument <I>dim</I> is applied to
lo and hi. The spacings in the two radial dimensions are applied to
c1 and c2. The two cone radii are scaled by the lattice
spacing in the dimension corresponding to c1.
<LI>For style <I>cylinder</I>, the lattice spacing in argument <I>dim</I> is applied
to lo and hi. The spacings in the two radial dimensions are applied
to c1 and c2. The cylinder radius is scaled by the lattice
spacing in the dimension corresponding to c1.
<LI>For style <I>plane</I>, the lattice spacing in dimension x is applied to
px and nx, similarly the spacings in dimensions y,z are applied to
py/ny and pz/nz.
<LI>For style <I>prism</I>, the lattice spacing in dimension x is applied to
xlo and xhi, similarly for ylo/yhi and zlo/zhi. The lattice spacing
in dimension x is applied to xy and xz, and the spacing in dimension y
to yz.
<LI>For style <I>sphere</I>, the lattice spacing in dimensions x,y,z are
applied to the sphere center x,y,z. The spacing in dimension x is
applied to the sphere radius.
</UL>
<HR>
<P>If the <I>vel</I> or <I>wiggle</I> or <I>rotate</I> keywords are used, the region
is "dynamic", meaning its location or orientation changes with time.
No more than one of these keywords can be used at a time. These
keywords cannot be used with a <I>union</I> or <I>intersect</I> style region.
Instead, the keywords should be used to define the individual
sub-regions of the <I>union</I> or <I>intersect</I> region. Normally, each
sub-region should be "dynamic" in the same manner (e.g. rotate around
the same point), though this is not a requirement.
</P>
<P>The <I>vel</I> style moves the region at a constant velocity, so that its
position <I>X</I> = (x,y,z) as a function of time is given in vector
notation as
</P>
<PRE>X(t) = X0 + V * delta
</PRE>
<P>where <I>X0</I> = (x0,y0,z0) is its position at the time the region is
specified, <I>V</I> is the specified velocity vector with components
(Vx,Vy,Vz), and <I>delta</I> is the time elapsed since the region was
specified.
</P>
<P>The <I>wiggle</I> style moves the region in an oscillatory fashion, so that
its position <I>X</I> = (x,y,z) as a function of time is given in vector
notation as
</P>
<PRE>X(t) = X0 + A sin(omega*delta)
</PRE>
<P>where <I>X0</I> = (x0,y0,z0) is its position at the time the region is
specified, <I>A</I> is the specified amplitude vector with components
(Ax,Ay,Az), <I>omega</I> is 2 PI / <I>period</I>, and <I>delta</I> is the time
elapsed since the region was specified.
</P>
<P>The <I>rotate</I> style rotates the region around a rotation axis <I>R</I> =
(Rx,Ry,Rz) that goes thru a point <I>P</I> = (Px,Py,Pz). The <I>period</I> of
the rotation is also specified. The direction of rotation for the
region around the rotation axis is consistent with the right-hand
rule: if your right-hand thumb points along <I>R</I>, then your fingers
wrap around the axis in the direction of rotation.
</P>
<P><B>Restrictions:</B>
</P>
<P>A prism cannot be of 0.0 thickness in any dimension; use a small z
thickness for 2d simulations. For 2d simulations, the xz and yz
parameters must be 0.0.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "lattice.html">lattice</A>, <A HREF = "create_atoms.html">create_atoms</A>,
<A HREF = "delete_atoms.html">delete_atoms</A>, <A HREF = "group.html">group</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are side = in, units = lattice, and no
velocity, wiggling, or rotation.
</P>
</HTML>
c4science · Help