diff --git a/docs/source_docs/references/images/custom_bimodal_dem_FNw.png b/docs/source_docs/references/images/custom_bimodal_dem_FNw.png new file mode 100644 index 0000000000000000000000000000000000000000..9564bce871e22e84c9a1d58c9f59d36a72c1cb2d Binary files /dev/null and b/docs/source_docs/references/images/custom_bimodal_dem_FNw.png differ diff --git a/docs/source_docs/references/images/custom_bimodal_pic_FNw.png b/docs/source_docs/references/images/custom_bimodal_pic_FNw.png new file mode 100644 index 0000000000000000000000000000000000000000..2c84f5ccee782a2355062f8d8a9d495565f774e0 Binary files /dev/null and b/docs/source_docs/references/images/custom_bimodal_pic_FNw.png differ diff --git a/docs/source_docs/references/images/custom_qicpic_dem.png b/docs/source_docs/references/images/custom_qicpic_dem.png new file mode 100644 index 0000000000000000000000000000000000000000..6b2ed0fb9b7f5a7b120159eb752f287039889597 Binary files /dev/null and b/docs/source_docs/references/images/custom_qicpic_dem.png differ diff --git a/docs/source_docs/references/images/custom_qicpic_pic.png b/docs/source_docs/references/images/custom_qicpic_pic.png new file mode 100644 index 0000000000000000000000000000000000000000..ae99fb5a8cb922116193596066a9eb958de3a7bd Binary files /dev/null and b/docs/source_docs/references/images/custom_qicpic_pic.png differ diff --git a/docs/source_docs/references/size_distributions.rst b/docs/source_docs/references/size_distributions.rst index b16dede9e108882eaabf4b67b3ca7026c0176700..4400978b41ce3cbf08ab33afc82f2f8f69109327 100644 --- a/docs/source_docs/references/size_distributions.rst +++ b/docs/source_docs/references/size_distributions.rst @@ -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.