doc file changes/Qs added for body DEM particles

column is used as the {bstyle} argument for the "atom_style

body"_atom_style.html command.

{nparticle} | rigid body with N sub-particles |

{rounded/polygon} | 2d polygons with N vertices :tb(c=2,s=|)

{rounded/polyhedron} | 3d polyhedra with N vertices, E edges and F faces  :tb(c=2,s=|)

{nparticle} : rigid body with N sub-particles

{rounded/polygon} : 2d polygons with N vertices

{rounded/polyhedron} : 3d polyhedra with N vertices, E edges and F faces :tb(s=:)

The body style determines what attributes are stored for each body and

thus how they can be used to compute pairwise body/body or

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.

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

"pair_style body/rounded/polygon" doc page for a diagram of two

squares with rounded circles at the vertices.  Special cases for N = 1

(circle) and N = 2 (rod with rounded ends) can also be specified.

NOTE: include a diagram of 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.

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. The diameter value can be different

for each body particle. 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.

for each body particle. 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.

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

values consistent with the current orientation of the rigid body

{Atoms} section of the data file.

For example, the following information would specify a square particle

whose edge length is sqrt(2) and rounded diameter is 1.0 in length unit

and initial orientation is determined from the 6 moments of inertia

(ixx iyy izz ixy ixz iyz):

whose edge length is sqrt(2) and rounded diameter is 1.0.  The

orientation of the square is aligned with the xy coordinate axes which

is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz iyz =

1 1 4 0 0 0.

3 1 27

4

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.

"boundary"_boundary.html command.  See the "pair_style

body/rounded/polygon" doc page for a diagram of a two 2d squares with

rounded circles at the vertices.  A 3d cube with rounded spheres

at the 8 vertices and 12 rounded edges would be similar.

NOTE: include a diagram of a rounded polyhedron body particle

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

for a triangle, N = 3, E = 3 and F = 1.

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

TRUNG: What are the special cases allowed for 3d, if any?  Similar to

the N=1 (sphere) and N=2 (rod) special cases for 2d, descibed in

previous section.

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

"Wang"_#Wang.

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 diameter value = the rounded diameter of

the sphere that surrounds each vertex. The diameter value can be different

for each body particle. These floating-point values

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

the sphere that surrounds each vertex. The diameter value can be

different for each body particle. 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

{Atoms} section of the data file.

For example, the following information would specify a cubic particle

whose edge length is 2.0 and rounded diameter is 0.5 in length unit

and initial orientation is determined from the 6 moments of inertia

(ixx iyy izz ixy ixz iyz):

whose edge length is 2.0 and rounded diameter is 0.5.

The orientation of the cube is aligned with the xyz coordinate axes

which is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz

iyz = 0.667 0.667 0.667 0 0 0.

1 3 79

8 12 6

3 0 4 7

0.5 :pre

The "pair_style

body/rounded/polhedron"_pair_body_rounded_polyhedron.html command can

be used with this body style to compute body/body interactions.  The

"fix wall/body/polyhedron"_fix_wall_body_polygon.html command can be

used with this body style to compute the interaction of body particles

with a wall.

:line

For output purposes via the "compute

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/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 pairwise interaction between rounded polygons is described in

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 between two particles are defined with respect to the

separation of their respective rounded surfaces, not by the separation

of the vertices and edges themselves.

edges by half its circle diameter (as in the diagram below of a gray

and yellow square particle).  The interaction forces and energies

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

The forces between vertex-vertex, vertex-edge, vertex-face and edge-edge

particles (at any orientation) which would produce an overlap of the

two surfaces.  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.

The forces between vertex-vertex, vertex-edge, and edge-edge overlaps

are given by:

:c,image(Eqs/pair_body_rounded.jpg)

:c,image(JPG/pair_body_rounded.jpg)

In "Fraige"_#Fraige, the tangential friction force between two particles

that are in contact is modeled differently prior to gross sliding

(i.e. static friction) and during gross-sliding (kinetic friction).

The latter takes place when the tangential deformation exceeds

the Coulomb frictional limit.  In the current implementation, however,

we do not take into account frictional history, i.e. we do not keep track

of how many time steps the two particles have been in contact

nor calculate the tangential deformation. We assume that gross sliding

takes place right when two particles are in contact.

In "Fraige"_#Fraige, the tangential friction force between two

particles that are in contact is modeled differently prior to gross

sliding (i.e. static friction) and during gross-sliding (kinetic

friction).  The latter takes place when the tangential deformation

exceeds the Coulomb frictional limit.  In the current implementation,

however, we do not take into account frictional history, i.e. we do

not keep track of how many time steps the two particles have been in

contact nor calculate the tangential deformation.  Instead, we assume

that gross sliding takes place as soon as two particles are in

contact.

TRUNG: The diagram label "cohesive regions" confuses me.  Are you

saying there is some distance d for which the force is attractive,

i.e. the particles are cohesive?  I think when d > Ri + Rj, since Ri +

Rj is the surface/surface overlap discussed above?  If so, then the

discussion above about the specified cutoff is wrong?  I.e. you can

specify a large cutoff than the surface/surface overlap to get

cohesive interactions?  If so, this should be explained up above.

But an additional confusion is that the specied cutoff (Rc in diagram?)

is a single number, but depedning on the orientiation of the 2

particles they might have a suface/surface overlap at a much

smaller value of Ri + Rj.  So what is Rc then?

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,

k_n (energy/distance^2 units)

k_na (energy/distance^2 units) :ul

Effectively, k_n and k_na are the slopes of the red lines in the plot

above for force versus distance, for r < 0 and 0 < r < rc

respectively.  TRUNG: is this sentence correct?

TRUNG: reminder to copy any change in this file

to the pair polyhedron file as well (and vice versa)

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

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

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

body particles.

TRUNG: I think we need a paragraph here about how body/sphere

interactions are handled.  Does this pair style only do body/body but

allow for a body = sphere or rod or some other degenerate case?  Or

does this pair style allow you to model a simulation of mixed body and

point particles, where point particles are spheroids.  If so, does

this pair style do body/body and body/point, and you use one of the

other granular pair styles to do point/point?  I.e. a pair hybrid

model?  Or does everything have to be defined as bodies.  Actually

this paragraph would make more sense in the body.txt file about how to

create a model that includes non-body particles (spheres).  And in

this pair style file just a couple lines about which part of the

interactions this pair style computes.  Ditto in the pair body polygon

file.

This pairwise interaction between rounded polyhedra is described in

"Wang"_#Wang, where a polyhedron does not have sharp corners and

edges, but is rounded at its vertices and edges by spheres centered on

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

particles that far apart could be touching.

The forces between vertex-vertex, vertex-edge, vertex-face, edge-edge

and edge-face are given by:

The forces between vertex-vertex, vertex-edge, vertex-face, edge-edge,

and edge-face overlaps are given by:

:c,image(Eqs/pair_body_rounded.jpg)

In "Wang"_#Wang, the tangential friction force between two particles

that are in contact is modeled differently prior to gross sliding

(i.e. static friction) and during gross-sliding (kinetic friction).

The latter takes place when the tangential deformation exceeds

the Coulomb frictional limit.  In the current implementation, however,

we do not take into account frictional history, i.e. we do not keep track

of how many time steps the two particles have been in contact

nor calculate the tangential deformation. We assume that gross sliding

takes place right when two particles are in contact.

The latter takes place when the tangential deformation exceeds the

Coulomb frictional limit.  In the current implementation, however, we

do not take into account frictional history, i.e. we do not keep track

of how many time steps the two particles have been in contact nor

calculate the tangential deformation.  Instead, we assume that gross

sliding takes place as soon as two particles are in contact.

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,

k_n (energy/distance^2 units)

k_na (energy/distance^2 units) :ul

Effectively, k_n and k_na are the slopes of the red lines in the plot

above for force versus distance, for r < 0 and 0 < r < rc

respectively.  TRUNG: is this sentence correct?

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

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