small changes to Trung body files

bond/non-body (point particle) interactions.  More details of each

style are described below.

We hope to add more styles in the future.  See "Section

More styles ma be added in the future.  See "Section

10.12"_Section_modify.html#mod_12 for details on how to add a new body

style to the code.

By contrast, when body particles are used, LAMMPS treats an entire

body as a single particle for purposes of computing pairwise

interactions, building neighbor lists, migrating particles between

processors, outputting particles to a dump file, etc.  This means that

processors, output of particles to a dump file, etc.  This means that

interactions between pairs of bodies or between a body and non-body

(point) particle need to be encoded in an appropriate pair style.  If

such a pair style were to mimic the "fix rigid"_fix_rigid.html model,

Thus it only makes sense to use body particles and develop such a pair

style, when particle/particle interactions are more complex than what

the "fix rigid"_fix_rigid.html command can already calculate.  For

example, if particles have one or more of the following attributes:

example, consider particles with one or more of the following

attributes:

represented by a surface mesh

represented by a collection of geometric entities (e.g. planes + spheres)

deformable

internal stress that induces fragmentation :ul

then the interaction between pairs of particles is likely to be more

complex than the summation of simple sub-particle interactions.  An

example is contact or frictional forces between particles with planar

surfaces that inter-penetrate.

For these models, the interaction between pairs of particles is likely

to be more complex than the summation of simple pairwise interactions.

An example is contact or frictional forces between particles with

planar surfaces that inter-penetrate.  Likewise, the body particle may

store internal state, such as a stress tensor used to compute a

fracture criterion.

These are additional LAMMPS commands that can be used with body

particles of different styles

...

xN yN zN :pre

N is the number of sub-particles in the body particle.  M = 6 + 3*N.

where M = 6 + 3*N, and N is the number of sub-particles in the body

particle.  

The integer line has a single value N.  The floating point line(s)

list 6 moments of inertia followed by the coordinates of the N

sub-particles (x1 to zN) as 3N values.  These values can be listed on

[Specifics of body style rounded/polygon:]

The {rounded/polygon} body style represents body particles as

a polygon with a variable number N of vertices, which can only be

used for 2d models. Special cases for N = 1 (spheres) and N = 2

(rods) are also included. One example use of this body style is for 2d

discrete element models, as described in "Fraige"_#Fraige. Similar to

body style {nparticle}, the atom_style body command for this body

style takes two additional arguments:

The {rounded/polygon} body style represents body particles as a 2d

polygon with a variable number of N vertices.  This style can only be

used for 2d models; see the "boundary"_boundary.html command.

NOTE: include a diagram of a a rounded polygon body particle

Special cases for N = 1 (spheres) and N = 2 (rods) are also included.

One use of this body style is for 2d discrete element models, as

described in "Fraige"_#Fraige.

Similar to body style {nparticle}, the atom_style body command for

this body style takes two additional arguments:

atom_style body rounded/polygon Nmin Nmax

Nmin = minimum # of vertices in any body in the system

i j j k k ...

diameter :pre

N is the number of vertices in the body particle.  M = 6 + 3*N + 2*N +

1.  The integer line has a single value N.  The floating point line(s)

where M = 6 + 3*N + 2*N + 1, and N is the number of vertices in the

body particle.

The integer line has a single value N.  The floating point line(s)

list 6 moments of inertia followed by the coordinates of the N

vertices (x1 to zN) as 3N values, followed by 2N vertex indices

corresponding to the end points of the N edges, followed by a single

diameter value = the rounded diameter of the vertices.

These floating-point values can be listed on as many lines as you

wish; see the "read_data"_read_data.html command for more details.

vertices (x1 to zN) as 3N values (with z = 0.0 for each), followed by

2N vertex indices corresponding to the end points of the N edges,

followed by a single diameter value = the rounded diameter of the

circle that surrounds each vertex.  These floating-point values can be

listed on as many lines as you wish; see the

"read_data"_read_data.html command for more details.

NOTE: can the diameter value be different for each body particle?

The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the

values consistent with the current orientation of the rigid body

position of the particle is specified by the x,y,z values in the

{Atoms} section of the data file.

For example, the following information would specify a square

particles whose edge length is sqrt(2):

For example, the following information would specify a square particle

whose edge length is sqrt(2):

NOTE: oriented how?

3 1 27

4

The "pair_style body/rounded/polygon"_pair_body_rounded_polygon.html

command can be used with this body style to compute body/body

interactions.

interactions.  The "fix wall/body/polygon"_fix_wall_body_polygon.html

command can be used with this body style to compute the interaction of

body particles with a wall.

:line

[Specifics of body style rounded/polyhedron:]

The {rounded/polyhedron} body style represents body particles as

a polyhedron with N vertices, E edges and F faces.

The {rounded/polyhedron} body style represents body particles as a 3d

polyhedron with a variable number of N vertices, E edges and F faces.

This style can only be used for 3d models; see the

"boundary"_boundary.html command.

NOTE: include a diagram of a a rounded polyhedron body particle

Special cases for N = 1 (spheres) and N = 2 (rods) are also valid.

This body style is for 3d discrete element models, as described in "Wang"_#Wang. 

Similar to body style {rounded/polygon}, the atom_style body command for this body

style takes two additional arguments:

NOTE: can 2d objects also be specified as a special case, e.g. a

triangle?

This body style is for 3d discrete element models, as described in

"Wang"_#Wang.

Similar to body style {rounded/polygon}, the atom_style body command

for this body style takes two additional arguments:

atom_style body rounded/polyhedron Nmin Nmax

Nmin = minimum # of vertices in any body in the system

1 2 3 4

diameter :pre

N is the number of vertices in the body particle. M = 6 + 3*N + 2*E

+ 4*F + 1.  The integer line has three values: number of vertices (N),

number of edges (E) and number of faces (F). The floating point line(s)

list 6 moments of inertia followed by the coordinates of the N

vertices (x1 to zN) as 3N values, followed by 2N vertex indices

corresponding to the end points of the E edges, 4*F vertex indices defining F faces.

The last value is the radius value = the rounded diameter of the vertices.

These floating-point values can be listed on as many lines as you

wish; see the "read_data"_read_data.html command for more details.

Because the maxmimum vertices per face is hard-coded to be 4 (i.e. quadrilaterals),

faces with more than 4 vertices need to be split into triangles or quadrilaterals.

For triangular faces, the last index should be set to -1.

where M = 6 + 3*N + 2*E + 4*F + 1, and N is the number of vertices in

the body particle, E = number of edges, F = number of faces.

The integer line has three values: number of vertices (N), number of

edges (E) and number of faces (F). The floating point line(s) list 6

moments of inertia followed by the coordinates of the N vertices (x1

to zN) as 3N values, followed by 2N vertex indices corresponding to

the end points of the E edges, then 4*F vertex indices defining F

faces.  The last value is the radius value = the rounded diameter of

the sphere that surrounds each vertex.  These floating-point values

can be listed on as many lines as you wish; see the

"read_data"_read_data.html command for more details.  Because the

maxmimum vertices per face is hard-coded to be 4

(i.e. quadrilaterals), faces with more than 4 vertices need to be

split into triangles or quadrilaterals.  For triangular faces, the

last vertex index should be set to -1.

NOTE: is there some right-hand rule for the ordering of the 4 vertices

within each face?

NOTE: can the diameter value be different for each body particle?

The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the

values consistent with the current orientation of the rigid body

around its center of mass.  The values are with respect to the

simulation box XYZ axes, not with respect to the principal axes of the

rigid body itself.  LAMMPS performs the latter calculation internally.

The coordinates of each vertex are specified as its x,y,z displacement

from the center-of-mass of the body particle.  The center-of-mass

position of the particle is specified by the x,y,z values in the

{Atoms} section of the data file.

For example, the following information would specify a cubic particle

whose edge length is 1.0:

NOTE: oriented how?

NOTE: fill in these values correctly

3 1 27

4

1 1 4 0 0 0

-0.7071 -0.7071 0

-0.7071 0.7071 0

0.7071 0.7071 0

0.7071 -0.7071 0

0 1

1 2

2 3

3 0

1.0 :pre

:line

For images created by the "dump image"_dump_image.html command, if the

{body} keyword is set, then each body particle is drawn as a polygon

consisting of N line segments.  Note that the line segments

are drawn between the N vertices, which does not correspond exactly to

the physical extent of the body (because the "pair_style

consisting of N line segments.  Note that the line segments are drawn

between the N vertices, which does not correspond exactly to the

physical extent of the body (because the "pair_style

rounded/polygon"_pair_body_rounded_polygon.html defines finite-size

spheres at those point and the line segments between the spheres are

tangent to the spheres).  The drawn diameter of each line segment is

Particuology, 6, 455 (2008).

:link(Wang)

[(Wang)] J. Wang, H. S. Yu, P. A. Langston, F. Y. Fraige, Granular Matter, 13, 1 (2011).

[(Wang)] J. Wang, H. S. Yu, P. A. Langston, F. Y. Fraige, Granular

Matter, 13, 1 (2011).

ID, group-ID are documented in "fix"_fix.html command :ulb,l

wall/body/polygon = style name of this fix command :l

k_n = normal repulsion strength (force/distance units or pressure units - see discussion below) :l

c_n = normal damping coefficient (force/distance units or pressure units - see discussion below) :l

c_t = tangential damping coefficient (force/distance units or pressure units - see discussion below) :l

k_n = normal repulsion strength (force/distance or pressure units) :l

c_n = normal damping coefficient (force/distance or pressure units) :l

c_t = tangential damping coefficient (force/distance or pressure units) :l

wallstyle = {xplane} or {yplane} or {zplane} or {zcylinder} :l

args = list of arguments for a particular style :l

  {xplane} or {yplane} args = lo hi

[Description:]

Bound the simulation domain of systems of body particles of style

body/rounded/polygon with wall(s). All particles in the group interact

with the wall when they are close enough to touch it.

The nature of the interaction between the wall and the polygons is

the same as that between the polygons themselves, which is similar to the Hookean potential.

This fix is for use with 2d models of body particles of style

{rounded/polygon}.  It bounds the simulation domain with wall(s).  All

particles in the group interact with the wall when they are close

enough to touch it.  The nature of the interaction between the wall

and the polygon particles is the same as that between the polygon

particles themselves, which is similar to a Hookean potential.  See

"Section 6.14"_Section_howto.html#howto_14 of the manual and the

"body"_body.html doc page for more details on using body particles.

This fix is designed for use with the "body/rounded/polygon" body style,

which is specified as an argument to the "atom-style body" command.

The parameters {k_n}, {c_n}, {c_t} have the same meaning and units as those specified with the

"pair_style body/rounded/polygon"_pair_body_rounded_polygon.html commands.

The parameters {k_n}, {c_n}, {c_t} have the same meaning and units as

those specified with the "pair_style

body/rounded/polygon"_pair_body_rounded_polygon.html command.

The {wallstyle} can be planar or cylindrical.  The 3 planar options

The {wallstyle} can be planar or cylindrical.  The 2 planar options

specify a pair of walls in a dimension.  Wall positions are given by

{lo} and {hi}.  Either of the values can be specified as NULL if a

single wall is desired.  For a {zcylinder} wallstyle, the cylinder's

axis is at x = y = 0.0, and the radius of the cylinder is specified.

Optionally, the wall can be moving, if the {wiggle} keyword is appended.

Optionally, the wall can be moving, if the {wiggle} keyword is

appended.

For the {wiggle} keyword, the wall oscillates sinusoidally, similar to

the oscillations of particles which can be specified by the

"fix move"_fix_move.html command.  This is useful in packing

simulations of particles.  The arguments to the {wiggle}

keyword specify a dimension for the motion, as well as it's

{amplitude} and {period}.  Note that if the dimension is in the plane

of the wall, this is effectively a shearing motion.  If the dimension

is perpendicular to the wall, it is more of a shaking motion.  A

{zcylinder} wall can only be wiggled in the z dimension.

the oscillations of particles which can be specified by the "fix

move"_fix_move.html command.  This is useful in packing simulations of

particles.  The arguments to the {wiggle} keyword specify a dimension

for the motion, as well as it's {amplitude} and {period}.  Note that

if the dimension is in the plane of the wall, this is effectively a

shearing motion.  If the dimension is perpendicular to the wall, it is

more of a shaking motion.  A {zcylinder} wall can only be wiggled in

the z dimension.

Each timestep, the position of a wiggled wall in the appropriate {dim}

is set according to this equation:

[Restrictions:]

This fix is part of the BODY package.  It is only enabled if

LAMMPS was built with that package.  See the "Making

This fix is part of the BODY package.  It is only enabled if LAMMPS

was built with that package.  See the "Making

LAMMPS"_Section_start.html#start_3 section for more info.

Any dimension (xyz) that has a wall must be non-periodic.

Any dimension (xy) that has a wall must be non-periodic.

[Related commands:]

"pair_style body/rounded/polygon"_pair_body_rounded_polygon.html

"atom_style body"_atom_style.html, "pair_style

body/rounded/polygon"_pair_body_rounded_polygon.html

[Default:] none

[Description:]

Bound the simulation domain of systems of body particles of style

body/rounded/polyhedron with wall(s). All particles in the group interact

with the wall when they are close enough to touch it.

The nature of the interaction between the wall and the polygons is

the same as that between the polygons themselves, which is similar to the Hookean potential.

This fix is designed for use with the "body/rounded/polyhedron" body style,

which is specified as an argument to the "atom-style body" command.

The parameters {k_n}, {c_n}, {c_t} have the same meaning and units as those specified with the

"pair_style body/rounded/polyhedron"_pair_body_rounded_polygon.html commands.

This fix is for use with 3d models of body particles of style

{rounded/polyhedron}.  It bounds the simulation domain with wall(s).

All particles in the group interact with the wall when they are close

enough to touch it.  The nature of the interaction between the wall

and the polygon particles is the same as that between the polygon

particles themselves, which is similar to a Hookean potential.  See

"Section 6.14"_Section_howto.html#howto_14 of the manual and the

"body"_body.html doc page for more details on using body particles.

The parameters {k_n}, {c_n}, {c_t} have the same meaning and units as

those specified with the "pair_style

body/rounded/polyhedron"_pair_body_rounded_polyhedron.html command.

The {wallstyle} can be planar or cylindrical.  The 3 planar options

specify a pair of walls in a dimension.  Wall positions are given by

Optionally, the wall can be moving, if the {wiggle} keyword is appended.

For the {wiggle} keyword, the wall oscillates sinusoidally, similar to

the oscillations of particles which can be specified by the

"fix move"_fix_move.html command.  This is useful in packing

simulations of particles.  The arguments to the {wiggle}

keyword specify a dimension for the motion, as well as it's

{amplitude} and {period}.  Note that if the dimension is in the plane

of the wall, this is effectively a shearing motion.  If the dimension

is perpendicular to the wall, it is more of a shaking motion.  A

{zcylinder} wall can only be wiggled in the z dimension.

the oscillations of particles which can be specified by the "fix

move"_fix_move.html command.  This is useful in packing simulations of

particles.  The arguments to the {wiggle} keyword specify a dimension

for the motion, as well as it's {amplitude} and {period}.  Note that

if the dimension is in the plane of the wall, this is effectively a

shearing motion.  If the dimension is perpendicular to the wall, it is

more of a shaking motion.  A {zcylinder} wall can only be wiggled in

the z dimension.

Each timestep, the position of a wiggled wall in the appropriate {dim}

is set according to this equation:

[Related commands:]

"pair_style body/rounded/polyhedron"_pair_body_rounded_polygon.html

"atom_style body"_atom_style.html, "pair_style

body/rounded/polyhedron"_pair_body_rounded_polyhedron.html

[Default:] none

c_t = tangential damping coefficient

mu = normal friction coefficient during gross sliding

delta_ua = multiple contact scaling factor

cutoff = global sepration cutoff for interactions (distance units), see below for definition :pre

cutoff = global separation cutoff for interactions (distance units), see below for definition :pre

NOTE: what does gross sliding mean?

[Examples:]

[Description:]

Style {body/rounded/polygon} is for use with body particles and calculates pairwise

Style {body/rounded/polygon} is for use with 2d models of body

particles of style {rounded/polygon}.  It calculates pairwise

body/body interactions as well as interactions between body and

point-particles.  See "Section 6.14"_Section_howto.html#howto_14

of the manual and the "body"_body.html doc page for more details on

using body particles.

This pair style is designed for use with the "body/rounded/polygon" body style,

which is specified as an argument to the "atom-style body" command.

See the "body/rounded/polygon"_body.html doc page for more details about the body

styles LAMMPS supports. The pairwise interaction between the rounded polygons is described

in "Fraige"_#Fraige, where the polygons are rounded at the vertices and edges

by circles of diameter a. This is a version of discrete element models (DEM)

with multiple contact points.

Because the polygons can have different rounded diameters, the cutoff specified in

the pair style command is for the surface separation between two interacting entities

(e.g. vertex-vertex, vertex-edge or edge-edge) excluding their rounded diameters,

i.e. separation = center-center distance - (rounded diameter of entity i + rounded diameter of entity j)/2.

The interaction forces and energies are also defined with respect to the rounded surface separation,

instead of center-center distance.

For style {body/rounded/polygon}, the following coefficients must be defined for each

pair of atoms types via the "pair_coeff"_pair_coeff.html command as in

the examples above, or in the data file or restart files read by the

"read_data"_read_data.html or "read_restart"_read_restart.html

commands:

point-particles.  See "Section 6.14"_Section_howto.html#howto_14 of

the manual and the "body"_body.html doc page for more details on using

body particles.

This pairwise interaction between rounded polygons is described in

"Fraige"_#Fraige, where a polygon does not have sharp corners, but is

rounded at its vertices by circles centered on each vertex with a

specified diameter.  The edges of the polygon are defined bewteen

pairs of adjacent vertices.  The circle diameter for each polygon is

specified in the data file read by the "read data"_read_data.html

command.  This is a 2d discrete element model (DEM) which allows for

multiple contact points.

Note that when two particles interact, the effective surface of each

polygon particle is displaced outward from each of its vertices and

edges by half its circle diameter.  The interaction forces and

energies bewteen two particles are defined with respect to the

separation of their respective rounded surfaces, not by the separation

of the vertices and edges themselves.

This means that the specified cutoff in the pair_style command should

be large enough to encompass the center-to-center distance between two

particles (at any orientation) which would produce a surface-surface

overlap.  For example, consider two square particles with edge length

= 1.0 and circle diameter 0.2.  The maximum distance of one polygon's

surface from its center is not sqrt(2)/2, but (sqrt(2)+0.1)/2.  Thus

the cutoff distance should be sqrt(2) + 0.1, since the surfaces of two

particles that far apart could be touching.

NOTE: Do we need a diagram of 2 overlapping polygon particles that

explains how contact is defined?  Do we need an equation(s) that

explain what the params in pair style and coeff mean, for damping and

spring constants?  Or do we just want to reference the paper for that?

NOTE: say something about no frictional history ?

The following coefficients must be defined for each pair of atom types

via the "pair_coeff"_pair_coeff.html command as in the examples above,

or in the data file read by the "read_data"_read_data.html command:

k_n (energy/distance^2 units)

k_na (energy/distance^2 units) :ul

[Mixing, shift, table, tail correction, restart, rRESPA info]:

This pair style does not support the "pair_modify"_pair_modify.html

mix, shift, table, and tail options.

This pair style does not write its information to "binary restart

files"_restart.html.  Thus, you need to re-specify the pair_style and

pair_coeff commands in an input script that reads a restart file.

This pair style can only be used via the {pair} keyword of the

"run_style respa"_run_style.html command.  It does not support the

{inner}, {middle}, {outer} keywords.

[Restrictions:]

These pair styles are part of the BODY package.  They are only enabled

if LAMMPS was built with that package.  See the "Making

LAMMPS"_Section_start.html#start_3 section for more info.

NOTE: is there a newton on or off requirement for using this pair style?

If so, say something like this:

This pair style requires the "newton"_newton.html setting to be "on"

for pair interactions.

[Related commands:]

"pair_coeff"_pair_coeff.html

:link(Fraige)

[(Fraige)] F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds,

Particuology, 6, 455 (2008).