Updated doc page for pair body rounded/polygon

doc/src/body.txt

@@ -28,16 +28,14 @@ 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=|)
+{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=|)
 
 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
 10.12"_Section_modify.html#mod_12 for details on how to add a new body
 style to the code.
@@ -175,13 +173,11 @@ The {bflag2} argument is ignored.
 
 [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 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
+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:
 
@@ -203,15 +199,14 @@ x1 y1 z1
 ...
 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)
 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.
+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.
 
@@ -235,7 +230,10 @@ particles whose edge length is sqrt(2):
 -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
 
 The "pair_style body/rounded/polygon"_pair_body_rounded_polygon.html
@@ -257,8 +255,8 @@ the body particle itself.  These values are calculated using the
 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
+{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
@@ -267,6 +265,52 @@ tangent to the spheres).  The drawn diameter of each line segment is
 determined by the {bflag1} parameter for the {body} keyword.  The
 {bflag2} argument is ignored.
 
+The {rounded/polyhedon} body style represents body particles as
+a polyhedron with N vertices, E edges and F faces.
+Special cases for N = 1 (spheres) and N = 2 (rods) are also valid.
+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
+
+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.
+
 :line
 
 :link(Fraige)

doc/src/pair_body_rounded_polygon.txt

@@ -8,12 +8,58 @@
 
 pair_style body/rounded/polygon command :h3
 
+[Syntax:]
+
+pair_style body/rounded/polygon c_n c_t mu delta_ua cutoff :pre
+c_n = normal damping coefficient
+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
+
+[Examples:]
+
+pair_style body/rounded/polygon ${c_n} ${c_t} ${mu} ${delta_ua} ${cutoff}
+pair_coeff * * 100.0 1.0
+pair_coeff 1 1 100.0 1.0 :pre
+
 [Description:]
 
-Note: This feature is not yet implemented.
+Style {body/rounded/polygon} is for use with body particles and 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.
+
+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 i + rounded diameter of 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:
+
+k_n (energy/distance^2)
+k_na (energy/distance^2) :ul
 
 [Related commands:]
 
 "pair_style body"_pair_body.html
 
 [Default:] none
+
+:link(Fraige)
+[(Fraige)] F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds,
+Particuology, 6, 455 (2008).

src/BODY/pair_body_rounded_polygon.h

@@ -76,24 +76,31 @@ class PairBodyRoundedPolygon : public Pair {
   void allocate();
   void body2space(int);
 
+  // sphere-sphere interaction
+  void sphere_against_sphere(int i, int j, double delx, double dely, double delz,
+                             double rsq, double k_n, double k_na,
+                             double** x, double** v, double** f, int evflag);
+  // vertex-edge interaction
   int vertex_against_edge(int i, int j, double k_n, double k_na,
                           double** x, double** f, double** torque,
                           tagint* tag, Contact* contact_list,
                           int &num_contacts, double &evdwl, double* facc);
-  void sphere_against_sphere(int i, int j, double delx, double dely, double delz,
-                             double rsq, double k_n, double k_na,
-                             double** x, double** v, double** f, int evflag);
+  // compute distance between a point and an edge from another body
   int compute_distance_to_vertex(int ibody, int edge_index, double* xmi,
                                  double rounded_radius, double* x0,
                                  double x0_rounded_radius, double cut_inner,
                                  double &d, double hi[3], double &t,
                                  int &contact);
-  double contact_separation(const Contact& c1, const Contact& c2);
+  // compute contact forces if contact points are detected
   void contact_forces(Contact& contact, double j_a, double** x, 
-                      double** v, double** f, double** angmom, 
+                      double** v, double** f, double** angmom,
+  // compute the separation between two contacts
+  double contact_separation(const Contact& c1, const Contact& c2);
                       double** torque, double &evdwl, double* facc);
+  // accumulate torque to a body given a force at a given point
   void sum_torque(double* xm, double *x, double fx,
                   double fy, double fz, double* torque);
+  // helper functions
   int opposite_sides(double* x1, double* x2, double* a, double* b);
   void total_velocity(double* p, double *xcm, double* vcm, double *angmom,
                       double *inertia, double *quat, double* vi);