Merge branch 'released-key-renames' into 'main' (945a324a) · Commits · exa / docs

docs/source_docs/tutorials/fluid/index.rst

+1 −1

Changes for docs/source_docs/tutorials/fluid/index.rst: 1 added line, 1 removed line.
Original line number	Diff line number	Diff line
		@@ -4,7 +4,7 @@ Fluid
		=======

		Tutorials in this category use MFIX-Exa's fluid solver with no particle
		phase present (``solids.dem = none``, ``solids.pic = none``). This includes
		phase present (``solids = none``). This includes
		ordinary single-fluid flow as well as any case that tracks two immiscible
		fluids by density within the same solver, such as a Rayleigh-Taylor case.

docs/source_docs/user_guide/inputs/dem_model.rst

0 → 100644

+171 −0

Changes for docs/source_docs/user_guide/inputs/dem_model.rst: 171 added lines, 0 removed lines.
Original line number	Diff line number	Diff line
		DEM model
		=========

		.. _InputsDEM:

		Inputs for the discrete element method (DEM), used when ``solids.model = dem``
		(see :ref:`particle options<InputsParticleOptions>`). Every type listed in
		``solids`` is a DEM type.

		Contact model
		-------------

		The following input is defined with the prefix ``dem``:

		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| \| Description \| Type \| Default \|
		+===============================+=========================================================================+==========+===========+
		\| contact_model \| Contact model for particle-particle and particle-wall collisions. \| String \| lsd \|
		\| \| \| \| \|
		\| \| Options: \| \| \|
		\| \| \| \| \|
		\| \| * ``lsd`` : Linear spring-dashpot. \| \| \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

		The linear spring-dashpot model takes the following inputs, defined with the
		prefix ``dem.lsd``:

		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| \| Description \| Type \| Default \|
		+===============================+=========================================================================+==========+===========+
		\| spring_const.pp \| Normal spring constant :: particle to particle collisions [required] \| Real \| 0 \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| spring_const.pw \| Normal spring constant :: particle to wall collisions [required] \| Real \| 0 \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| spring_tang_fac.pp \| Tangential-to-normal spring constant factor :: particle to particle \| Real \| 0.2857 \|
		\| \| collisions \| \| \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| spring_tang_fac.pw \| Tangential-to-normal spring constant factor :: particle to wall \| Real \| 0.2857 \|
		\| \| collisions \| \| \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| 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 \| \| \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+

		Restitution coefficients
		------------------------

		The following inputs use the solids type names from ``solids`` to define restitution
		coefficients and are defined with the prefix ``dem.restitution_coeff``. They must be
		defined for every solid-solid and solid-wall combination.

		+--------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| \| Description \| Type \| Default \|
		+==========================+=========================================================================+==========+===========+
		\| [dem_solid].[dem_solid2] \| Specifies the restitution coefficient between DEM solids. \| Real \| 0 \|
		\| \| Order is not important and this could be defined as \| \| \|
		\| \| ``[dem_solid2].[dem_solid]``. If both are defined they must be equal. \| \| \|
		+--------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| [dem_solid].wall \| Specifies the restitution coefficient between solid and the wall. \| Real \| 0 \|
		\| \| Order is not important and this could be defined as \| \| \|
		\| \| ``wall.[dem_solid]``. If both are defined they must be equal. \| \| \|
		+--------------------------+-------------------------------------------------------------------------+----------+-----------+

		Friction and tangential history
		-------------------------------

		.. \|RollingFricModelA\| replace:: :math:`\boldsymbol{\tau}_{ij}^{(r)} = -\mu_{r}\hat{r}_{ij} \left\| f_{ij}^{(n)} \right\| \frac{\omega_{ij}}{\left\|\omega_{ij}\right\|}`
		.. \|RollingFricModelB\| replace:: :math:`\boldsymbol{\tau}_{ij}^{(r)} = -\mu_{r}\hat{r}_{ij} \left\| f_{ij}^{(n)} \right\| \boldsymbol{u}_{ij}^{\omega}`

		The following inputs apply to every contact model and are defined with the prefix ``dem``:

		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| \| Description \| Type \| Default \|
		+===============================+=========================================================================+==========+===========+
		\| friction_coeff.pp \| Friction coefficient :: particle to particle collisions [required] \| Real \| 0 \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| friction_coeff.pw \| Friction coefficient :: particle to wall collisions [required] \| Real \| 0 \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| tan_history \| Include tangential history force in the collision model. \| Bool \| false \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| tan_history.max_contacts \| Maximum number of contacts per particle tracked at any point when \| Int \| 10 \|
		\| \| tangential history is enabled. \| \| \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| rolling_friction \| Rolling friction model :cite:p:`zhou1999,ai2011,wensrich2012,blais2019` \| String \| None \|
		\| \| \| \| \|
		\| \| Options: \| \| \|
		\| \| \| \| \|
		\| \| * ``None`` \| \| \|
		\| \| \| \| \|
		\| \| * ``ModelA`` \| \| \|
		\| \| \| \| \|
		\| \| \|RollingFricModelA\| \| \| \|
		\| \| \| \| \|
		\| \| * ``ModelB`` \| \| \|
		\| \| \| \| \|
		\| \| \|RollingFricModelB\| \| \| \|
		\| \| \| \| \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+
		\| rolling_friction.coefficient \| Rolling friction coefficient when using a rolling friction model \| Real \| 0 \|
		+-------------------------------+-------------------------------------------------------------------------+----------+-----------+


		Example
		-------

		Below is an example for specifying the inputs for two DEM solids.

		.. code-block:: none

		solids = sand char
		solids.model = dem

		dem.contact_model = lsd

		dem.lsd.spring_const.pp = 100.0
		dem.lsd.spring_const.pw = 100.0

		dem.lsd.spring_tang_fac.pp = 0.2857
		dem.lsd.spring_tang_fac.pw = 0.2857

		dem.lsd.damping_tang_fac.pp = 0.5
		dem.lsd.damping_tang_fac.pw = 0.5

		dem.friction_coeff.pp = 0.25
		dem.friction_coeff.pw = 0.15

		dem.restitution_coeff.sand.sand = 0.85
		dem.restitution_coeff.sand.char = 0.88
		dem.restitution_coeff.char.char = 0.90

		dem.restitution_coeff.sand.wall = 0.85
		dem.restitution_coeff.char.wall = 0.89

		.. _InputsDEMImplicitDrag:

		Implicit drag
		-------------

		By default (``solids.momentum.update = explicit``), the fluid-particle drag force is applied
		explicitly to particles,

		.. math::

		u_p^{n^{\prime}+1} = u_p^{n^\prime} + dt_{\mathrm{DEM}}\left(\beta^n (u_f^{n+1} - u_p^{n}) + \mathcal{F}_p^{n^\prime}\right)/m_p

		where
		:math:`u_p` is the `p`-th particle velocity at the indicated time level,
		:math:`\beta^n` is the drag coefficient,
		:math:`u_f^{n+1}` is the fluid velocity,
		:math:`\mathcal{F}_p` are all non-drag forces (e.g., gravitational, buoyancy, collision etc.), and
		:math:`m_p` is particle mass.
		Terms exist at different time levels due in part to how the fluid and particle models are coupled
		and partly because particles typically sub-step in time. Specifically, a time step advances the fluid from
		:math:`t^n` to :math:`t^{n+1}`, then particles take multiple smaller time steps to traverse the same
		total time. In the above equation, prime markers differentiate quantities updated at each DEM sub-step.

		The updated particle velocity, :math:`u_p^{n^{\prime}+1}`, is substituted into the drag expression when
		``solids.momentum.update = implicit``.

		.. math::

		u_p^{n^{\prime}+1} = \frac{u_p^{n^\prime} + dt_{\mathrm{DEM}}\left( \beta^n u_f^{n+1} + \mathcal{F}_p^{n^\prime} \right)/m_p}{1 + dt_{\mathrm{DEM}} \beta^n / m_p}

		By using the updated velocity, the drag force computed for the fluid and particles is inconsistent,
		and interphase momentum is not conserved. However, implicit drag may be needed for numerical stability
		when the particle density is much less than the fluid (such as bubbles). The implicit update is
		required when virtual mass is included, and the virtual mass coefficient is added to the particle
		mass in the denominator.

docs/source_docs/user_guide/inputs/model_options.rst

+4 −1

Changes for docs/source_docs/user_guide/inputs/model_options.rst: 4 added lines, 1 removed line.
Original line number	Diff line number	Diff line
		@@ -137,6 +137,8 @@ The following inputs are defined using the prefix ``mfix``:
		The thermodynamic pressure is a scalar value, not a scalar field. This is a consequence of
		the low Mach number assumption.

		.. _InputsParticleOptions:

		Particle options
		----------------

		@@ -145,7 +147,8 @@ The following inputs are defined using the prefix ``solids``:
		+---------------------+---------------------------------------------------------------------------+-------------+-------------+
		\| \| Description \| Type \| Default \|
		+=====================+===========================================================================+=============+=============+
		\| model \| Solids model used by the solids solver. \| String \| None \|
		\| model \| Solids model used for every type in ``solids``. Required when \| String \| None \|
		\| \| solids types are defined. \| \| \|
		\| \| \| \| \|
		\| \| Options: \| \| \|
		\| \| \| \| \|

docs/source_docs/user_guide/inputs/pic_model.rst

0 → 100644

+91 −0

Changes for docs/source_docs/user_guide/inputs/pic_model.rst: 91 added lines, 0 removed lines.
Original line number	Diff line number	Diff line
		PIC model
		=========

		.. _InputsPIC:

		Inputs for the particle-in-cell (PIC) method, used when ``solids.model = pic``
		(see :ref:`particle options<InputsParticleOptions>`). Every type listed in
		``solids`` is a PIC type.

		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 \|
		+====================================+=========================================================================+==========+===========+
		\| 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. \| \| \|
		+------------------------------------+-------------------------------------------------------------------------+----------+-----------+

docs/source_docs/user_guide/inputs/solids_model.rst

+4 −246

File changed.

Preview size limit exceeded, changes collapsed.

Original line number	Diff line number	Diff line
		PIC model
		=========

		.. _InputsPIC:

		Inputs for the particle-in-cell (PIC) method, used when ``solids.model = pic``
		(see :ref:`particle options<InputsParticleOptions>`). Every type listed in
		``solids`` is a PIC type.

		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 \|
		+====================================+=========================================================================+==========+===========+
		\| 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. \| \| \|
		+------------------------------------+-------------------------------------------------------------------------+----------+-----------+