lammps/doc/region.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

region command :h3

[Syntax:]

region ID style args keyword value ... :pre

ID = user-assigned name for the region :ulb,l
style = {block} or {cylinder} or {prism} or {sphere} or {union} or {intersect} :l
  {block} args = xlo xhi ylo yhi zlo zhi
      xlo,xhi,ylo,yhi,zlo,zhi = bounds of block in all
        dimensions (distance units)
  {cylinder} args = dim c1 c2 radius lo hi
    dim = {x} or {y} or {z} = 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)
  {prism} 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)
  {sphere} args = x y z radius
      x,y,z = center of sphere (distance units)
      radius = radius of sphere (distance units)
  {union} 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
  {intersect} 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
zero or more keyword/value pairs may be appended :l
keyword = {side} or {units} :l
  {side} value = {in} or {out}
    {in} = the region is inside the specified geometry
    {out} = the region is outside the specified geometry
  {units} value = {lattice} or {box}
    {lattice} = the geometry is defined in lattice units
    {box} = the geometry is defined in simulation box units :pre
:ule

[Examples:]

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 INF units box
region 1 prism 0 10 0 10 0 10 2 0 0
region outside union 4 side1 side2 side3 side4 :pre

[Description:]

This command defines a geometric region of space.  Various other
commands use regions.  For example, the region can be filled with
atoms via the "create_atoms"_create_atoms.html command.  Or the atoms
in the region can be identified as a group via the "group"_group.html
command, or deleted via the "delete_atoms"_delete_atoms.html command.

The lo/hi values for {block} or {cylinder} or {prism} 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 simlation 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
"create_box"_create_box.html or "read_data"_read_data.html or
"read_restart"_read_restart.html commands), then an EDGE or INF
parameter cannot be used.

For style {cylinder}, 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 specifes 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.

For style {prism}, a parallelepiped is defined (it's too hard to spell
parallelepiped in an input script!).  Think of the parallelepided as
initially an axis-aligned orthogonal box with the same xyz lo/hi
parameters as region style {block} 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 {xy}
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 {xy}
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 {xz} and {yz}.  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).

A prism region used with the "create_box"_create_box.html 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.

The {union} style creates a region consisting of the volume of all the
listed regions combined.  The {intesect} style creates a region
consisting of the volume that is common to all the listed regions.

The {side} keyword determines whether the region is considered to be
inside or outside of the specified geometry.  Using this keyword in
conjunction with {union} and {intersect} regions, complex geometries
can be built up.  For example, if the interior of two spheres were
each defined as regions, and a {union} style with {side} = 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.

The {units} keyword determines the meaning of the distance units used
to define the region.  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.

[Restrictions:]

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.

[Related commands:]

"lattice"_lattice.html, "create_atoms"_create_atoms.html,
"delete_atoms"_delete_atoms.html, "group"_group.html

[Default:]

The option defaults are side = in and units = lattice.