diff --git a/docs/source_docs/user_guide/inputs/solids_model.rst b/docs/source_docs/user_guide/inputs/solids_model.rst index f21e38b72774c346ce17b2ee477cf6c9d5b1e545..f5b3cba797e5dd7eb4da685cc27638097e560da8 100644 --- a/docs/source_docs/user_guide/inputs/solids_model.rst +++ b/docs/source_docs/user_guide/inputs/solids_model.rst @@ -230,4 +230,87 @@ when the particle density is much less than the fluid (such as bubbles). PIC model settings ------------------ -.. todo:: Add PIC inputs +The following inputs define the PIC solids model and its associated frictional stress parameters: + +.. math:: + + \tau_p = \frac{P_s \varepsilon_p^{\beta}}{\max \left[ (\varepsilon_{cp} - \varepsilon_p), \epsilon (1-\varepsilon_p)\right]} + + +The following inputs are defined with the prefix ``pic``: + ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++====================================+=========================================================================+==========+===========+ +| solve | Specified name(s) of the PIC types or None to disable the PIC solver. | Strings | "None" | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| close_pack | Solids volume fraction at close pack, :math:`\varepsilon_{cp}`. | Real | 0.55 | +| | Below this threshold, the solid stress tensor has minimal impact. | | | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| pressure_coefficient | Pressure linear scale factor in frictional stress model, :math:`P_s`. | Real | 100.0 | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| beta | Volume fraction exponential scale factor in frictional stress model, | Real | 3.0 | +| | :math:`\beta`. | | | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| small_number | Non-singularity term in frictional stress model, :math:`\epsilon`. | Real | 1.0e-7 | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| damping_factor | An empirical dampening factor for the frictional stress model. | Real | 0.4 | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| damping_factor_wall_normal | Normal coefficient of restitution for parcel-wall collisions. | Real | 0.3 | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| damping_factor_wall_tangent | Tangential coefficient of restitution for parcel-wall collisions. | Real | 0.99 | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| parcels_per_cell_at_pack | Specifies the number of particles that can occupy a regular | Real | 32.0 | +| | computational cell near close packing. | | | +| | | | | +| | Larger values reduce sensitivity to small changes in parcel positions, | | | +| | which helps stabilize the computed solids volume fraction and, by | | | +| | extension, the frictional stress model. However, increasing this value | | | +| | also results in simulations tracking a greater number of parcels. | | | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| verbose | Verbosity level for PIC-related output. | Int | 0 | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ + + +The solids volume fraction is required to evaluate the frictional stress model when advancing parcels from :math:`t^n` to +:math:`t^{n+1}`. Ideally, this evaluation would use either the volume fraction at the midpoint of the time step, +:math:`\varepsilon_p^{n+1/2}`, or at the end of the step, :math:`\varepsilon_p^{n+1}`. + +However, since neither of these values is available a priori, an iterative approach is used. An initial approximation of +the volume fraction is used to advance parcels to a tentative position at :math:`t^{n+1}`. These new positions are then +used to compute an updated volume fraction field, which is subsequently used in the next iteration to recompute the +tentative parcel positions. + +The following keywords control the iterative PIC algorithm and are defined with the prefix ``pic``: + ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++====================================+=========================================================================+==========+===========+ +| initial_step_type | Specifies the initial solids volume fraction used in PIC iterations to | String | "nth_eps" | +| | approximate the volume fraction at the end of the time step, | | | +| | :math:t^{n+1}. | | | +| | | | | +| | Options (case-insensitive): | | | +| | | | | +| | * ``nth_eps`` - use the volume fraction from the previous time step, | | | +| | :math:`t^{n}` | | | +| | * ``zero_eps`` - set the initial volume fraction to zero | | | +| | * ``taylor_approx`` - use a Taylor series expansion about parcel | | | +| | positions to approximate the volume fraction at :math:`t^{n+1}` | | | +| | | | | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| max_iter | Maximum number of iterations used to approximate the end state | Int | 3 | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| advance_vel_p | Specifies the weighting factor used to compute the averaged particle | Real | 0.5 | +| | velocity field during parcel advancement. The field-averaged velocity | | | +| | is used when applying forces to parcels. | | | +| | | | | +| | This parameter takes values between 0 and 1, blending the particle | | | +| | velocity at the beginning and end of the time step. A value of ``0.5`` | | | +| | (default) yields a time-centered average. | | | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+ +| velocity_reference_frame | The velocity reference frame scales the field-averaged velocity | Real | 0.5 | +| | used to compute the slip velocity between a parcel and the bulk when | | | +| | when the parcels is moving towards an area of higher solids | | | +| | concentration. This parameter takes values between 0 and 1. | | | ++------------------------------------+-------------------------------------------------------------------------+----------+-----------+