\(\renewcommand{\AA}{\text{Å}}\)
pair_style body/rounded/polygon command
Accelerator Variants: body/rounded/polygon/omp
Syntax
pair_style body/rounded/polygon c_n c_t mu delta_ua cutoff keyword
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 separation cutoff for interactions (distance units), see below for definition zero or more keywords may be appended keyword = history history = keep track of the tangential deformation at the contacts (no value)
Examples
pair_style body/rounded/polygon 20.0 5.0 0.0 1.0 0.5
pair_coeff * * 100.0 1.0
pair_coeff 1 1 100.0 1.0
pair_style body/rounded/polygon 20.0 5.0 0.5 1.0 0.5 history
pair_coeff * * 100.0 1.0 30.0
Description
Style body/rounded/polygon is for use with 2d models of body particles of style rounded/polygon. It calculates pairwise body/body interactions which can include body particles modeled as 1-vertex circular disks with a specified diameter. See the Howto body page for more details on using body rounded/polygon particles.
This pairwise interaction between rounded polygons is described in 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 between pairs of adjacent vertices. The circle diameter for each polygon is specified in the data file read by the read data 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 (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 is the cutoff distance, \(r_c\), for the surface separation, \(\delta_n\) (see figure below). This is the distance at which two particles no longer interact. If \(r_c\) is specified as 0.0, then it is a contact-only interaction. I.e. the two particles must overlap in order to exert a repulsive force on each other. If \(r_c > 0.0\), then the force between two particles will be attractive for surface separations from 0 to \(r_c\), and repulsive once the particles overlap.
Note that unlike for other pair styles, the specified cutoff is not the distance between the centers of two particles at which they stop interacting. This center-to-center distance depends on the shape and size of the two particles and their relative orientation. LAMMPS takes that into account when computing the surface separation distance and applying the \(r_c\) cutoff.
The forces between vertex-vertex, vertex-edge, and edge-edge overlaps are given by:
Note that \(F_n\) and \(F_t\) are functions of the surface separation \(\delta_n = d - (R_i + R_j)\). In this model, when \((R_i + R_j) < d < (R_i + R_j) + r_c\), that is, \(0 < \delta_n < r_c\), the cohesive region of the two surfaces overlap and the two surfaces are attractive to each other.
Here, positive values of \(F_n\) are repulsive. The cohesive force \(k_{na} (r_c - \delta_n)\) grows with the overlap of the cohesive regions of the two surfaces, also when the surfaces deform. When two particles touch at multiple contact points, the cohesive force at the contacts is scaled by the factor \(j_a \ge 1\), which grows with the length of the contact region (see delta_ua), following Fraige. The elastic force \(k_n \delta_n\) is not scaled. The damping forces act at each contact, while there is a single friction force per pair of particles, at the contact with the largest overlap (see below for the history keyword). The damping and friction forces act at the contact point between the rounded surfaces and depend on the relative velocity of the two particles at that point, including their rotation, so that they also exert torques, e.g. to make disks roll. Each vertex of one particle interacts with the point of the other particle nearest to it, which lies inside an edge or at a vertex. Two vertices interact with each other only if each of them is the vertex of its particle nearest to the other one, and a vertex that has penetrated the other particle is pushed out through the nearest edge. Following Fraige, the contact forces are applied at up to two contacts, the two contacts farthest apart, whose distance is the length of the contact region.
In 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. Unless the history keyword is used (see below), 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.
Changed in version 30Sep2026.
The friction term in \(F_t\) acts in the tangential direction, opposite to the tangential relative velocity \(v_t\) at the contact point, with a magnitude of \(\mu\) times the elastic normal force \(k_n |\delta_n|\), but at most \(c_t |v_t|\). This limit lets the friction force vanish smoothly as the sliding stops, instead of reversing the sliding direction within a time step, and implies that the friction term requires \(c_t > 0\). Previously, the friction term was applied along the normal direction at every contact and thus only increased the normal repulsion. Also, the scaling factor \(j_a\) now applies only to the cohesive force as in the reference model, instead of to the whole normal force, and the cohesive force keeps growing when the surfaces deform, instead of staying constant. The damping and friction forces now act at the contact point between the rounded surfaces, instead of at the vertices, and the friction force now also applies to disks. Each vertex now interacts with the nearest point of the other particle, as described above, instead of with all edges within the cutoff, and the contact forces are applied at the two contacts farthest apart, instead of at the first two contacts found. The reported energy now includes only the contacts to which forces are applied.
Added in version 30Sep2026.
With the history keyword, the friction force is instead that of a tangential spring, which also acts prior to gross sliding. The tangential deformation \(\xi\) of each pair of particles in contact is accumulated from their tangential relative velocity, \(\xi \leftarrow \xi + v_t \Delta t\), and the friction force is
with a magnitude of the spring force \(k_t |\xi|\) of at most \(\mu \sum k_n |\delta_n|\), the sum of the elastic normal forces of all contacts of the pair. Once the spring force exceeds this limit, the particles slide and \(\xi\) is reduced accordingly. There is still a single friction force per pair of particles, but it acts at the average of the contact points of the pair, and \(v_t\) and the contact normal are averages over the contacts as well, all weighted by the elastic normal forces of the contacts. This deviates from Fraige, where the friction force acts at the contact with the largest overlap. With that choice, the friction force jumps between contacts whenever the contact with the largest overlap changes, so that e.g. a particle resting with an edge on another particle under a sideways load keeps rocking instead of coming to rest. Since the contact normal changes as the particles move and rotate, \(\xi\) is rotated into the current tangent direction at each time step, keeping its magnitude, following Eq. 17 of Luding. The tangential deformation is reset to zero when the particles are no longer in contact. As in pair_style gran/hooke/history, the tangential deformations are stored by an internal fix NEIGH_HISTORY. The damping forces are unchanged. This extends the model of Fraige and makes static packings of particles with friction possible.
The following coefficients must be defined for each pair of atom types via the pair_coeff command as in the examples above, or in the data file read by the read_data command:
\(k_n\) (energy/distance^2 units)
\(k_{na}\) (energy/distance^2 units)
\(k_t\) (energy/distance^2 units) (optional)
Effectively, \(k_n - k_{na}\) and \(k_{na}\) are the magnitudes of the slopes of the lines in the plot above for force versus surface separation, for \(\delta_n < 0\) and \(0 < \delta_n < r_c\) respectively. The tangential stiffness \(k_t\) is used only with the history keyword. If it is not specified, it is set to \(\frac{2}{7} k_n\) as in pair_style gran/hooke/history.
Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix. They have been optimized to run faster, depending on your available hardware, as discussed on the Accelerator packages page. The accelerated styles take the same arguments and should produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP, and OPT packages, respectively. They are only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Accelerator packages page for more instructions on how to use the accelerated styles effectively.
Mixing, shift, table, tail correction, restart, rRESPA info
This pair style does not support the pair_modify mix, shift, table, and tail options.
Note
The forces of this pair style do not conserve the total energy, even without damping and friction (c_n = c_t = mu = 0). This is a property of the model of Fraige as implemented here:
The contact forces are scaled up with the length of the contact region (controlled by delta_ua), but no corresponding energy is defined.
When two particles touch at more than two points, whether between a vertex and an edge or between two vertices, the contact forces are applied only at the first two contacts that are at different places, and a contact between two vertices is counted only once. As the particles move, contacts appear and disappear abruptly, which changes the forces discontinuously. With cohesion (\(k_{na} > 0\)), the energy of a contact does not vanish when the surfaces just touch, so that these changes also change the energy.
The reported pair energy includes all vertex-edge interactions, also those at contacts that do not receive a force by the rule above. While such contacts exist, the reported energy does not match the applied forces.
The damping and friction forces dissipate energy as intended. The quantities described next can be used to check the energy balance of a simulation.
Added in version 30Sep2026.
This pair style computes two extra quantities that can be accessed by the compute pair command, as elements 1 and 2 of its global vector. They are the accumulated work (energy units) done since the pair style was defined by two kinds of forces that do not derive from the reported pair energy:
the part of the contact forces added by their scaling with the contact size (controlled by delta_ua),
the damping and friction forces (controlled by c_n, c_t, and mu), including the tangential spring with the history keyword.
The first one exists because the model scales the contact forces but not the energy. The kinetic plus potential energy minus these two quantities stays constant during a time integration with fix nve/body, up to the time integration error and to the changes of the set of contacts between two particles, which the model treats as discontinuous. The work is not accumulated during an energy minimization. Note that the kinetic energy must include the rotational energy of the particles, e.g. via compute temp/body with 3 degrees of freedom per particle as in the example below, while the thermo keyword ke includes only the translational part.
compute wp all pair body/rounded/polygon
compute tb all temp/body
compute_modify tb extra/dof 0
compute pe all pe
variable etot equal c_tb*3*count(all)/2+c_pe
variable ebal equal v_etot-c_wp[1]-c_wp[2]
This pair style does not write its information to binary restart files. Thus, you need to re-specify the pair_style and pair_coeff commands in an input script that reads a restart file. With the history keyword, the tangential deformations at the contacts are written to the restart file and are used again when the pair style is re-specified with the history keyword.
This pair style can only be used via the pair keyword of the run_style respa 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 Build package page for more info.
This pair style requires the newton setting to be “on” for pair interactions.
Default
The history keyword is not used, and \(k_t = \frac{2}{7} k_n\).
(Fraige) F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds, Particuology, 6, 455 (2008).
(Luding) S. Luding, Cohesive, frictional powders: contact models for tension, Granular Matter, 10, 235 (2008).