Merge pull request #962 from ndtrung81/body-dem

\documentstyle[12pt]{article}

\begin{document}

\begin{eqnarray*}

 F_n &=& k_n \delta_n - c_n v_n, \qquad \delta_n \le 0 \\

     &=& -k_{na} \delta_n - c_n v_n, \qquad 0 < \delta_n \le r_c \\

     &=& 0 \qquad \qquad \qquad \qquad \delta_n > r_c \\

 F_t &=& \mu k_n \delta_n - c_t v_t, \qquad \delta_n \le 0 \\

     &=& 0 \qquad \qquad \qquad \qquad \delta_n > 0

\end{eqnarray*}

\end{document}

"vector"_fix_vector.html,

"viscosity"_fix_viscosity.html,

"viscous"_fix_viscous.html,

"wall/body/polygon"_fix_wall_body_polygon.html,

"wall/body/polyhedron"_fix_wall_body_polyhedron.html,

"wall/colloid"_fix_wall.html,

"wall/gran"_fix_wall_gran.html,

"wall/gran/region"_fix_wall_gran_region.html,

"airebo (oi)"_pair_airebo.html,

"airebo/morse (oi)"_pair_airebo.html,

"beck (go)"_pair_beck.html,

"body"_pair_body.html,

"body/nparticle"_pair_body_nparticle.html,

"body/rounded/polygon"_pair_body_rounded/polygon.html,

"body/rounded/polyhedron"_pair_body_rounded/polyhedron.html,

"bop"_pair_bop.html,

"born (go)"_pair_born.html,

"born/coul/dsf"_pair_born.html,

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 convex polygon with N vertices :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

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

style are described below.

NOTE: The rounded/polygon style listed in the table above and

described below has not yet been relesed in LAMMPS.  It will be soon.

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

More styles may 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:]

NOTE: Aug 2016 - This body style has not yet been added to LAMMPS.

The info below is a placeholder.

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

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

described in "Fraige"_#body-Fraige.

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

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

used for 2d models.  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:

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

...

xN yN zN

i j j k k ...

radius :pre

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

radius value = the smallest circle encompassing the polygon.  That

last value is used to facilitate the body/body contact detection.

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

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) 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. Note that only Izz matters in 2D simulations.

3 1 27

4

-0.7071 0.7071 0

0.7071 0.7071 0

0.7071 -0.7071 0

0 1 1 2 2 3 3 0

0 1

1 2

2 3

3 0

1.0 :pre

A rod in 2D, whose length is 4.0, mass 1.0, rounded at two ends

by circles of diameter 0.5, is specified as follows:

1 1 13

2

1 1 1.33333 0 0 0

-2 0 0

2 0 0

0.5 :pre

A disk, whose diameter is 3.0, mass 1.0, is specified as follows:

1 1 10

1

1 1 4.5 0 0 0

0 0 0

3.0 :pre

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 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.  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.  Special cases

for N = 1 (sphere) and N = 2 (rod with rounded ends) can also be

specified.

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

"Wang"_#body-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

Nmax = maximum # of vertices in any body in the system :pre

The Nmin and Nmax arguments are used to bound the size of data

structures used internally by each particle.

When the "read_data"_read_data.html command reads a data file for this

body style, the following information must be provided for each entry

in the {Bodies} section of the data file:

atom-ID 3 M

N E F

ixx iyy izz ixy ixz iyz

x1 y1 z1

...

xN yN zN

0 1

1 2 

2 3

...

0 1 2 -1

0 2 3 -1

...

1 2 3 4

diameter :pre

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

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

The ordering of the 4 vertices within a face should follow

the right-hand rule so that the normal vector of the face points

outwards from the center of mass.

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

0.667 0.667 0.667 0 0 0

1 1 1

1 -1 1

-1 -1 1

-1 1 1

1 1 -1

1 -1 -1

-1 -1 -1

-1 1 -1

0 1

1 2

2 3

3 0

4 5

5 6

6 7

7 4

0 4

1 5

2 6

3 7

0 1 2 3

4 5 6 7

0 1 5 4

1 2 6 5

2 3 7 6

3 0 4 7

0.5 :pre

A rod in 3D, whose length is 4.0, mass 1.0 and rounded at two ends

by circles of diameter 0.5, is specified as follows:

1 1 13

2

0 1.33333 1.33333 0 0 0

-2 0 0

2 0 0

0.5 :pre

A sphere whose diameter is 3.0 and mass 1.0, is specified as follows:

1 1 10

1

0.9 0.9 0.9 0 0 0

0 0 0

3.0 :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

body/local"_compute_body_local.html and "dump local"_dump.html

current COM and orientation of the body particle.

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 convex

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

{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

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

:line

:link(Fraige)

:link(body-Fraige)

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

Particuology, 6, 455 (2008).

:link(body-Wang)

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

Matter, 13, 1 (2011).