Additional updates for particle distributions

Jordan Musserrequested to merge
jmusser/exa-docs:particle-distributions into main

Add supporting documentation for particle size distributions

Somehow missed in previous MR.

Merge request reports

docs/source_docs/references/images/custom_bimodal_dem_FNw.png

0 → 100644
+29.4 KiB
Loading image diff...

docs/source_docs/references/images/custom_bimodal_pic_FNw.png

0 → 100644
+29.7 KiB
Loading image diff...

docs/source_docs/references/images/custom_qicpic_dem.png

0 → 100644
+12.2 KiB
Loading image diff...

docs/source_docs/references/images/custom_qicpic_pic.png

0 → 100644
+23.7 KiB
Loading image diff...

docs/source_docs/references/size_distributions.rst

+210 −8
Changes for docs/source_docs/references/size_distributions.rst: 210 added lines, 8 removed lines.
Original line number Diff line number Diff line
@@ -489,7 +489,7 @@ The log-normal variable is returned by applying the exponential function, :math: 




``uniform`` distribution

^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^



The ``uniform`` distribution is given by
@@ -715,22 +715,191 @@ A user-defined ``custom`` distribution can be specified by providing discrete pr 
| max                 | Maximum particle diameter. Drawn samples above ``max`` are discarded  | Real        | N/A       |

|                     | and a new sample is drawn.                                            |             |           |

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

| interpolate         | Enable linear interpolation between discrete bins                     | bool        | true      |

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

| resample            | Resample the distribution to obtain uniform bin widths                | bool        | true      |

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

| bins                | Number of bins used when resampleing the distribution.                | int         | 64        |

| interpolate         | Enable linear interpolation between discrete bins. This option is     | bool        | false     |

|                     | only available when the initial distribution probability is zero.     |             |           |

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





The distribution input file contains four components:



+ line 1: number of distribution entries (integer)

+ line 2: specifies the distribution as ``CDF`` or ``PDF`` (string)

+ line 3: comment or blank line (unused by solver)

+ remaining lines define the bin and probability (Real  Real)



The following sections provide a few examples of custom distribution configurations.





.. rubric:: Bidisperse mixutre without interpoaltion



In the following example, a cuboid with volume 0.001 m\ :sup:`3` is filled with a number-weighted distribution. The

distribution is a 50/50 mixture of two particle sizes.



.. code-block:: bash

   :caption: Snippet of inputs defining a ``constant`` distribution. **This is not a complete input file.**

   :caption: Snippet of inputs defining a number-weighted ``custom`` distribution. **This is not a complete input file.**



   # Regions for defining ICs and BCs

   # -----------------------------------------------------------------------

   mfix.regions = full-domain



   regions.full-domain.lo  = 0.0  0.0  0.0

   regions.full-domain.hi  = 0.1  0.1  0.1



   # Initial Conditions

   # -----------------------------------------------------------------------

   ic.regions = full-domain



   mfix.particle_init_type = Auto



   # Full domain

   #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~>

   ic.full-domain.fluid.volfrac  = 0.95



   ic.full-domain.fluid.density  = 1.0

   ic.full-domain.fluid.pressure = 0.0

   ic.full-domain.fluid.velocity = 0.0  0.0  0.0



   ic.full-domain.solids  = solid0



   ic.full-domain.packing = random



   ic.full-domain.solid0.volfrac   = 0.05

   ic.full-domain.solid0.velocity  = 0.00  0.00  0.00



   ic.full-domain.solid0.diameter = custom

   ic.full-domain.solid0.diameter.custom = bidisperse-pdf.dist

   ic.full-domain.solid0.diameter.type = number-weighted



   ic.full-domain.solid0.density =  constant

   ic.full-domain.solid0.density.constant  =  2500.0    # (kg/m^3)



   ic.full-domain.solid0.density =  constant

   ic.full-domain.solid0.density.constant  = 2500.0 # (kg/m^3)





.. code-block:: bash

   :caption: Custom distribution defining a 50/50 mixture of two particle sizes.

   :linenos:



   2

   PDF

   # bidisperse mixture

    500.e-6  0.5

   1000.e-6  0.5





An MFIX-Exa DEM simulation with these settings generates approximately 180,000 particles with half

of the particles having diameter 0.5 mm and half have diameter 1.0 mm.

An MFIX-Exa PIC simulation with the same settings generates approximately 82,000 parcels when ``pic.close_pack = 0.64``,

``pic.parcels_per_cell_at_pack = 32``, and the Eulerian mesh spacing :math:`\Delta x` is 3.125 mm. Approximately

10% of the parcels have diameter 0.5 mm and 90% have diameter 1.0 mm.





.. rubric:: Bimodal mixutre



The following example uses the same layout as the previous example, however the custom distribution

is of a CDF describing a bimodal distribution created by combining two normal distributions.



.. code-block:: bash



   ic.full-domain.solid0.volfrac   = 0.05

   ic.full-domain.solid0.velocity  = 0.00  0.00  0.00



   ic.full-domain.solid0.diameter = custom

   ic.full-domain.solid0.diameter.custom = bimodal-cdf.dist

   ic.full-domain.solid0.diameter.type = number-weighted



.. code-block:: bash

   :caption: Custom bimodal distribution created by combining two normal distributions

   :linenos:



   25

   CDF

   # bimodal distribution created from two normal distributions

   0.000144  0.0000

   0.000240  0.0063

   0.000336  0.0360

   0.000384  0.0818

   0.000416  0.1356

   0.000432  0.1919

   0.000456  0.2495

   0.000480  0.3053

   0.000496  0.3587

   0.000528  0.4055

   0.000568  0.4447

   0.000584  0.4822

   0.000600  0.5191

   0.000616  0.5566

   0.000632  0.5958

   0.000664  0.6408

   0.000704  0.6942

   0.000720  0.7501

   0.000752  0.8075

   0.000768  0.8638

   0.000784  0.9177

   0.000816  0.9635

   0.000864  0.9932

   0.000960  0.9995

   0.001056  1.0000





An MFIX-Exa DEM simulation with these settings generates approximately 2,285,000 particles. The particle size

distribution (open circles), and number-weighted (orange), and volume-weighted (blue) density functions are

shown in :numref:`fig_custom_bimodal_dem_MFIX`.



.. _fig_custom_bimodal_dem_MFIX:



.. figure:: ./images/custom_bimodal_dem_FNw.png

   :width: 95%

   :align: center

   :alt: DEM custom bimodal distribution



   MFIX-Exa DEM custom bimodal particle size distribution (open circles) and number-weighted (orange)

   and volume-weighted (blue) density functions.





An MFIX-Exa PIC simulation with the same settings generates approximately 82,000 parcels when ``pic.close_pack = 0.64``,

``pic.parcels_per_cell_at_pack = 32``, and the Eulerian mesh spacing :math:`\Delta x` is 3.125 mm. The parcel size distribution

shown in :numref:`fig_custom_bimodal_pic_MFIX` (open triangles) follows the volume-weighted density function.

Small closed circles illustrate the effective particle size distribution, computed by multiplying each observation

by the parcel statistical weight.



.. _fig_custom_bimodal_pic_MFIX:



.. figure:: ./images/custom_bimodal_pic_FNw.png

   :width: 95%

   :align: center

   :alt: PIC custom bimodal distribution



   MFIX-Exa PIC custom bimodal parcel size distribution (open triangles), number-weighted (orange) and

   volume-weighted (blue) density functions. Small closed circles indicated the particle size

   distribution modeled by the parcels.







.. rubric:: Measured size distribution





The final example uses the same layout as the previous examples, however the custom distribution

is a CDF describing an experimentally measured size distribution and the distribution type is ``volume-weighted``.



.. code-block:: bash



   ic.full-domain.solid0.volfrac   = 0.05

   ic.full-domain.solid0.velocity  = 0.00  0.00  0.00



   ic.full-domain.solid0.diameter = custom

   ic.full-domain.solid0.diameter.custom = qicpic-cdf.dist

   ic.full-domain.solid0.diameter.type = volume-weighted





.. code-block:: bash

   :caption: Measured custom distribution

   :linenos:



   32

   CDF

   # comment about the distribution



   0.00025   0.0013499

   0.000298387   0.00250452

   0.000346774   0.00448884
@@ -763,3 +932,36 @@ A user-defined ``custom`` distribution can be specified by providing discrete pr 
   0.00165323   0.995511

   0.00170161   0.997495

   0.00175   0.99865





An MFIX-Exa DEM simulation with these settings generates approximately 963,000 particles. The particle size

distribution (open circles), and number-weighted (orange plus), and volume-weighted (blue cross) probabilities

are shown in :numref:`fig_custom_qicpic_dem_MFIX`.



.. _fig_custom_qicpic_dem_MFIX:



.. figure:: ./images/custom_qicpic_dem.png

   :width: 95%

   :align: center

   :alt: DEM custom qicpic distribution



   MFIX-Exa DEM custom bimodal particle size distribution (open circles) and number-weighted (orange plus)

   and volume-weighted (blue cross ) probabilities.





An MFIX-Exa PIC simulation with the same settings generates approximately 164,000 parcels when ``pic.close_pack = 0.64``,

``pic.parcels_per_cell_at_pack = 64``, and the Eulerian mesh spacing :math:`\Delta x` is 3.125 mm. The parcel size distribution

shown in :numref:`fig_custom_qicpic_pic_MFIX` (open triangles) follows the volume-weighted probabilities.

Small closed circles illustrate the effective particle size distribution, computed by multiplying each observation

by the parcel statistical weight.



.. _fig_custom_qicpic_pic_MFIX:



.. figure:: ./images/custom_qicpic_pic.png

   :width: 95%

   :align: center

   :alt: PIC custom bimodal distribution



   MFIX-Exa PIC custom bimodal parcel size distribution (open triangles), number-weighted (orange plus) and

   volume-weighted (blue cross) probabilities. Small closed circles indicated the particle size

   distribution modeled by the parcels.