MercuryDPM
Beta

This page provides a short overview of the mathematics and models used in the code. We first introduce the basic components of a DPM simulation (global parameters and variables, properties of particles, walls, boundaries, force laws and interactions), and provide the notation used henceforth. Then we explain the basic steps taken in each simulation (setting initial conditions, looping through time, writing data). The document is structured similarly to the code, so the user can easily relate the relevant classes with their purpose. Throughout this text, we include references to the relevant classes and functions, so the user can view the implementation.
In its most basic implementation, a DPM simulation simulates the movement of a set of particles \(P_i,\ \ i=1,\dots,N\), each of which is subject to body forces \(\vec f_i^\mathrm{body}\) and interacts with other particles via interaction forces \(\vec f_{ij}\), and torques \(\vec t_{ij},\ \ i=1,\dots,N_\mathrm{interaction}\).
While the body forces are assumed to act in the particle's center of mass \(\vec r_i\), the interaction forces act at the contact point \(\vec c_{ij}\) between the particles. Thus, each particle is subjected to the total force and torque
\[\vec f_i = \vec f_i^\mathrm{body}+\sum_{j=1}^N \vec f_{ij},\quad \vec t_i = \sum_{j=1}^N \vec t_{ij} + (\vec{c}_{ij}\vec{r}_i)\times \vec f_{ij}.\]
To simulate the movement of each particle, the particles' initial properties are defined, then Newton's laws are applied, resulting in the equations of motion,
\[m_i \ddot{\vec{r_i}} = \vec f_i,\quad I_i \dot{\vec{\omega_i}} = \vec t_i,\]
where \(m_i\), \(I_i\), \(\omega_i\) are the mass, moment of inertia and angular velocity of each particle (we currently do not use the particles' orientation, as all particles are spherical).
The default body force applied to a particle is due to gravity, \(\vec f_i^\mathrm{body}=m_i \vec{g}\), with \(\vec g\) the gravitational acceleration. The interaction forces can be quite varied, but usually consist of a repulsive normal force due to the physical deformation when two particles are in contact, and possibly an adhesive normal force
\[\vec f_{ij} = (f_{ij}^{n,rep}f_{ij}^{n,rep})\vec n_{ij} + \vec f_{ij}^{t},\]
with \(\vec n_{ij}\) the normal direction at the contact point, which for spherical particles is given by \(\vec n_{ij}=\frac{\vec r_j\vec r_i}{\vec r_j\vec r_i}\).
Further, a set of walls \(W_j,\ \ j=1,\dots,N\) can be implemented, which can apply an additional force \(\vec f_{ij}\) and torque \(\vec t_{ij}\) to each particle \(P_i\). A typical, flat wall is defined by
\[\mathrm{W}_j = \{\vec{r}:\ \vec{n}_j \cdot (\vec{r}  \vec{r}_j) \leq 0 \},\]
with \( \vec{n}_j\) the unit vector pointing into the wall and \(\vec{r}_j\) a point on the wall. However, many other wall types are possible, such as intersections of planar walls (e.g. polyhedral walls), axisymmetric walls (e.g., cylinders or funnels), or even complex shapes (coils and helical walls).
More complex simulations include further boundary conditions \(B_j,\ \ j=1,\dots,N\), such as periodic walls and regions where particles get destroyed or added.
Time integration is done using Velocity Verlet, see http://en.wikipedia.org/wiki/Verlet_integration#Velocity_Verlet for details. The implementation can be found in DPMBase::solve.
In the following sections, we give a short overview over the parameters that can be specified in MercuryDPM, and introduce the variable names which are used throughout this documentation. We also include links to the implementation of each object/parameter. For the more complex type of objects (particles, species, interactions, walls, and boundaries), where multiple implementation exist, we give an overview ofthe common parameters and discuss the most common types.
Each simulation has the following global parameters:
These variables are all implemented in the class DPMBase. This class is a base class of Mercury3D, which is the typical class used in Driver code, such as the tutorials [add link]. The sets of particles, species, walls ... mentioned above are implemented as handlers, which contain a vector of pointers (=links) to objects. E.g., WallHandler contains a set of pointers to walls, which are possibly of different type (flat, cylindrical, polyhedral, ...). The same is true for the ParticleHandler, SpeciesHandler, InteractionHandler, and BoundaryHandler. Next, we introduce the basic types of objects these handlers can contain.
Currently, only one type of particle exists, the BaseParticle. Each BaseParticle \(P_i\) has the following properties:
There are several wall types: InfiniteWall, IntersectionOfWalls, AxisymmetricIntersectionOfWalls, Screw, and Coil. All these wall types aree derived from a common class, BaseWall, which has the following properties:
There are several boundaries, which can be categorized into three types:
There are several species, which are built up from four building blocks (see Species for more details):
The most commonly used normal force species, LinearViscoelasticNormalSpecies contains
AdhesiveForceSpecies: Describes the shortrange, adhesive normal contact force \(f^{n,ad}\), which is added to the normal contact force. Several adhesive forces are implemented:
If no adhesive force is required, the default EmptyAdhesiveSpecies is used. The most commonly used adhesive force species, ReversibleAdhesiveSpecies contains
FrictionForceSpecies: Describes the tangential frictional contact force. Several normal forces are implemented:
If no friction force is required, the EmptyFrictionSpecies is used. The most commonly used friction force species, SlidingFrictionSpecies contains:
Note that in the Coulomb friction model, the frictional yield force only depends on the contact force, e.g. \(f^{sl}\leq\mu^{sl}f^{n,c}\), which is why the two normal forces are split.
There are several Interaction types, one for each Species. While the Species contain the parameters of the contact model, the Interaction contains the variables stored for an individual interaction between a particle (or particlewall) pair. All interaction types have the following common properties:
For collisions between particle \( \mathrm{P}_i \) and wall \( \mathrm{w}_j \), some variables are defined differently: