Document the Hertz-Mindlin contact model and its time step

Jordan Musserrequested to merge
jmusser/exa-docs:feature/dem-hertz into main
  • DEM model: the dem.hertz.* inputs (Young's modulus and Poisson ratio per type and for the walls, tangential damping factors), with an example.
  • Time stepping: what tcoll and tcoll_ratio mean under each model (collision time for lsd, Rayleigh time for hertz), and the tcoll_ratio default per model: 10 with hertz, 50 otherwise. The new label InputsDEMTimeStep points at that section.
  • Adds the Tsuji et al. (1992) reference.

Merge request reports

docs/source_docs/user_guide/inputs/dem_model.rst

+49 −0
Changes for docs/source_docs/user_guide/inputs/dem_model.rst: 49 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -20,6 +20,7 @@ The following input is defined with the prefix ``dem``: 
|                               | Options:                                                                |          |           |

|                               |                                                                         |          |           |

|                               | * ``lsd`` : Linear spring-dashpot.                                      |          |           |

|                               | * ``hertz`` : Hertz-Mindlin.                                            |          |           |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+



The linear spring-dashpot model takes the following inputs, defined with the
@@ -45,6 +46,38 @@ prefix ``dem.lsd``: 
|                               | damping coefficient :: particle to wall collisions                      |          |           |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+



The Hertz-Mindlin model :cite:p:`tsuji1992` stiffens as particles overlap. For a contact with

effective radius :math:`R^*`, effective mass :math:`m^*` and overlap :math:`\delta`, the normal

force is :math:`\frac{4}{3} E^* \sqrt{R^*} \delta^{3/2}` and the tangential stiffness is

:math:`8 G^* \sqrt{R^* \delta}`, where :math:`E^*` and :math:`G^*` are the effective Young's and

shear moduli of the two materials. The normal damping is set from the restitution coefficient

so that it holds at every impact velocity. The tangential stiffness and damping act only with

``dem.tan_history``. Each contact uses its own particles' radii and masses, so particles of

different sizes within a type are handled exactly. The model takes the following inputs, defined

with the prefix ``dem.hertz``:



+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

|                               | Description                                                             |   Type   | Default   |

+===============================+=========================================================================+==========+===========+

| youngs_modulus.[dem_solid]    | Young's modulus of the type's particles (Pa) [required]                 | Real     | None      |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

| youngs_modulus.wall           | Young's modulus of the walls (Pa) [required]                            | Real     | None      |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

| poisson_ratio.[dem_solid]     | Poisson ratio of the type's particles, greater than -1 and at most 0.5  | Real     | None      |

|                               | [required]                                                              |          |           |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

| poisson_ratio.wall            | Poisson ratio of the walls, greater than -1 and at most 0.5 [required]  | Real     | None      |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

| damping_tang_fac.pp           | Factor relating the tangential damping coefficient to the normal        | Real     |  0.5      |

|                               | damping coefficient :: particle to particle collisions                  |          |           |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

| damping_tang_fac.pw           | Factor relating the tangential damping coefficient to the normal        | Real     |  0.5      |

|                               | damping coefficient :: particle to wall collisions                      |          |           |

+-------------------------------+-------------------------------------------------------------------------+----------+-----------+



The solids time step is set differently by the two models: from the collision time with ``lsd``,

and from the Rayleigh time with ``hertz`` (see :ref:`DEM time step<InputsDEMTimeStep>`).



Restitution coefficients

------------------------
@@ -134,6 +167,22 @@ Below is an example for specifying the inputs for two DEM solids. 
   dem.restitution_coeff.sand.wall =  0.85

   dem.restitution_coeff.char.wall =  0.89



The same solids with the Hertz-Mindlin model:



.. code-block:: none



   dem.contact_model = hertz



   dem.hertz.youngs_modulus.sand =  7.0e10

   dem.hertz.youngs_modulus.char =  5.0e9

   dem.hertz.youngs_modulus.wall =  2.0e11



   dem.hertz.poisson_ratio.sand  =  0.25

   dem.hertz.poisson_ratio.char  =  0.3

   dem.hertz.poisson_ratio.wall  =  0.3



The friction and restitution coefficients are given as for ``lsd``.



.. _InputsDEMImplicitDrag:



Implicit drag

docs/source_docs/user_guide/inputs/time_stepping.rst

+25 −3
Changes for docs/source_docs/user_guide/inputs/time_stepping.rst: 25 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -41,11 +41,13 @@ step is computed based on the advective CFL condition. 


          amrex::Abort::0::"Current dt is smaller than dt_min !!!



.. _InputsDEMTimeStep:



.. rubric:: Particle-only DEM simulations



In particle-only DEM simulations, the time step used to advance particles, ``dtsolid``,

is determined by computing the collision time ``tcoll`` from particle properties, then dividing

the result by the number of steps per collision, ``tcoll_ratio``:

is determined by computing a time scale ``tcoll`` from particle properties, then dividing

the result by ``tcoll_ratio``:



.. highlight:: c++
@@ -53,6 +55,22 @@ the result by the number of steps per collision, ``tcoll_ratio``: 


    dtsolid = tcoll / tcoll_ratio;



The time scale depends on the contact model (``dem.contact_model``, see

:ref:`DEM model<InputsDEM>`), and so does what ``tcoll_ratio`` means:



* ``lsd``: ``tcoll`` is the shortest collision time of a linear spring-dashpot contact, over every

  pair of types and every type with the walls, computed for each type's average particle. A

  linear contact lasts this long at any impact velocity, so ``tcoll_ratio`` is the number of

  steps per collision.



* ``hertz``: ``tcoll`` is the shortest Rayleigh time, the time a Rayleigh wave takes to cross

  a particle, :math:`\pi R \sqrt{\rho/G}/(0.1631\nu + 0.8766)`, over each type's smallest

  particle. A Hertz contact lasts longer the slower the impact, so no velocity-independent

  collision time exists. The Rayleigh time is usually a fraction of a Hertz contact (about a

  sixth for 1 mm glass beads meeting at 1 m/s), so a given ``tcoll_ratio`` resolves a Hertz

  contact with several times more steps than a linear one. The default ``tcoll_ratio`` is

  therefore 10 with ``hertz``, against 50 with ``lsd``: about 60 steps for that contact.



.. note::



  ``mfix.fixed_dt`` must be defined for particle-only DEM simulations, however it is only
@@ -111,7 +129,11 @@ The following inputs are defined using the prefix ``mfix``: 
+----------------------+-----------------------------------------------------------------------+-------------+--------------+

| dt_max               | Maximum value of ``dt`` if ``fixed_dt`` is not set.                   |    Real     |  1.e14       |

+----------------------+-----------------------------------------------------------------------+-------------+--------------+

| tcoll_ratio          | DEM time step equals the min collision time divided by this value.    |    Real     |   50.0       |

| tcoll_ratio          | DEM time step equals the min collision time (``lsd``) or Rayleigh     |    Real     | See note     |

|                      | time (``hertz``) divided by this value.                               |             |              |

|                      |                                                                       |             |              |

|                      | * Default ``10`` when ``dem.contact_model == hertz``.                 |             |              |

|                      | * Default ``50`` otherwise.                                           |             |              |

+----------------------+-----------------------------------------------------------------------+-------------+--------------+

| walltime_limit       | Runtime limit specified with format HH:MM:SS. When the runtime has    |    String   |              |

|                      | almost reached the limit (approaching is computed by considering the  |             |              |

docs/source_docs/refs.bib

+11 −0
Changes for docs/source_docs/refs.bib: 11 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -808,3 +808,14 @@ year = {2011} 
  year={1999},

  publisher={Elsevier}

}



@article{tsuji1992,

  title={Lagrangian numerical simulation of plug flow of cohesionless particles in a horizontal pipe},

  author={Tsuji, Yutaka and Tanaka, Toshitsugu and Ishida, T},

  journal={Powder Technology},

  volume={71},

  number={3},

  pages={239--250},

  year={1992},

  publisher={Elsevier}

}