zhyang-dev/openfoam
1
0
Fork 0
mirror of https://develop.openfoam.com/Development/openfoam.git synced 2025-11-28 03:28:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

DOC: distributionModels: improve header file documentation

Browse Source
This commit is contained in:
Kutalmis Bercin
2021-08-24 08:55:05 +01:00
parent 2bd37c7643
commit 4be5511f8c
10 changed files with 777 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
src/lagrangian/distributionModels/RosinRammler/RosinRammler.H
View File

@ -28,13 +28,107 @@ Class
Foam::distributionModels::RosinRammler
Description
Rosin-Rammler distributionModel
Particle-size distribution model wherein random samples are drawn
from the doubly-truncated two-parameter Rosin-Rammler (Weibull)
probability density function:
\f[
CDF(x) =
(1 - exp(-(x/d)^n + (d_0/d)^n)
/(1 - exp(-(d_1/d)^n + (d_0/d)^n)
\f]
\f[
f(x; \lambda, n, A, B) =
\frac{
\frac{n}{\lambda}
\left( \frac{x}{\lambda} \right)^{n-1}
\exp\{ -(\frac{x}{\lambda})^n \}
}{
\exp\{- (\frac{A}{\lambda})^n \}
- \exp\{- (\frac{B}{\lambda})^n \}
}
\f]
where
\vartable
f(x; \lambda, n, A, B) | Rosin-Rammler probability density function
\lambda | Scale parameter
n | Shape parameter
x | Sample
A | Minimum of the distribution
B | Maximum of the distribution
\endvartable
Constraints:
- \f$ \infty > B > A > 0\f$
- \f$ x \in [B,A] \f$
- \f$ \lambda > 0 \f$
- \f$ n > 0 \f$
Random samples are generated by the inverse transform sampling technique
by using the quantile function of the doubly-truncated two-parameter
Rosin-Rammler (Weibull) probability density function:
\f[
x = \lambda \left( q_{min} - \ln (1 - u r) \right)^{1/n}
\f]
with
\f[
r = 1 - \exp(-q_{max} + q_{min})
\f]
\f[
q_{min} = \left(\frac{A}{\lambda}\right)^n
\f]
\f[
q_{max} = \left(\frac{B}{\lambda}\right)^n
\f]
where \f$ u \f$ is sample drawn from the uniform probability
density function on the unit interval \f$ (0, 1) \f$.
Reference:
\verbatim
Doubly-truncated two-parameter Weibull distribution and its moments (tag:C):
Crénin, F. (2015).
Truncated Weibull Distribution Functions and Moments.
SSRN 2690255.
DOI:10.2139/ssrn.2690255
\endverbatim
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type RosinRammler;
RosinRammlerDistribution
{
lambda <scaleParameterValue>;
n <shapeParameterValue>;
minValue <minValue>;
maxValue <maxValue>;
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: RosinRammler | word | yes | -
RosinRammlerDistribution | Distribution settings | dict | yes | -
lambda | Scale parameter | scalar | yes | -
n | Shape parameter | scalar | yes | -
minValue | Minimum of the distribution | scalar | yes | -
maxValue | Maximum of the distribution | scalar | yes | -
\endtable
SourceFiles
RosinRammler.C

53
src/lagrangian/distributionModels/binned/binned.H
View File

@ -27,8 +27,57 @@ Class
Foam::distributionModels::binned
Description
A binned distribution model where the random sample is taken from a
discrete set of bins
Particle-size distribution model wherein random samples are
drawn from a given discrete set of (\c bin, \c probability) pairs,
where in terms of its meaning, \c bins correspond to particle sizes
and \c probabilities correspond to (relative) probability of occurrences.
The second column (i.e. \c probability) are normalised by the sum of all
its values, resulting in a normalised column in the domain of [0,1].
To generate a sample, first a sample drawn from the uniform probability
density function on the unit interval (i.e. \c u), and then, the \c bin
corresponding to the first \c probability larger than \c u is fetched
as the particle size to be further processed.
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type binned;
binnedDistribution
{
distribution
(
(<bin1> <probability1>)
(<bin2> <probability2>)
...
(<binN> <probabilityN>)
);
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: binned | word | yes | -
binnedDistribution | Distribution settings | dict | yes | -
distribution | \<bin\>-\<probability\> pairs | dict | yes | -
\<bin\> | Particle size | scalar | yes | -
\<probability\> | Probability of occurrence | scalar | yes | -
\endtable
SourceFiles
binned.C

19
src/lagrangian/distributionModels/distributionModel/distributionModel.H
View File

@ -24,15 +24,21 @@ License
You should have received a copy of the GNU General Public License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
Namespace
Foam::distributionModels
Description
A namespace for various probability distribution model implementations.
Class
Foam::distributionModel
Description
A library of runtime-selectable distribution models.
A library of runtime-selectable doubly-truncated probability distribution
models. Returns random samples based on given distribution parameters.
Returns a sampled value given the expectation (nu) and variance (sigma^2)
Current distribution models include:
Available distribution models include:
- binned
- exponential
- fixedValue
- general
@ -42,11 +48,6 @@ Description
- Mass-based Rosin-Rammler
- uniform
The distributionModel is tabulated in equidistant nPoints, in an interval.
These values are integrated to obtain the cumulated distribution model,
which is then used to change the distribution from unifrom to
the actual distributionModel.
SourceFiles
distributionModel.C
distributionModelNew.C

82
src/lagrangian/distributionModels/exponential/exponential.H
View File

@ -28,7 +28,87 @@ Class
Foam::distributionModels::exponential
Description
exponential distribution model
Particle-size distribution model wherein random samples are drawn
from the doubly-truncated exponential probability density function:
\f[
f(x; \lambda, A, B) =
\lambda \frac{\exp(-\lambda (x - A))}{1 - \exp(-\lambda(B-A))}
\f]
where
\vartable
f(x; \lambda, A, B) | Exponential probability density function
\lambda | Rate parameter
x | Sample
A | Minimum of the distribution
B | Maximum of the distribution
\endvartable
Constraints:
- \f$ \infty > B > A > 0 \f$
- \f$ x \in [B,A] \f$
- \f$ \lambda > 0 \f$
Random samples are generated by the inverse transform sampling technique
by using the quantile function of the doubly-truncated exponential
probability density function:
\f[
x = - \frac{1}{\lambda} \ln (r)
\f]
with
\f[
r = q_{min} + u (q_{max} - q_{min})
\f]
\f[
q_{min} = \exp(-\lambda A)
\f]
\f[
q_{max} = \exp(-\lambda B)
\f]
where \f$ u \f$ is a sample drawn from the uniform probability
density function on the unit interval \f$ (0, 1) \f$.
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type exponential;
exponentialDistribution
{
lambda <lambdaValue>;
minValue <minValue>;
maxValue <maxValue>;
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: exponential | word | yes | -
exponentialDistribution | Distribution settings | dict | yes | -
lambda | Rate parameter | scalar | yes | -
minValue | Minimum of the distribution | scalar | yes | -
maxValue | Maximum of the distribution | scalar | yes | -
\endtable
SourceFiles
exponential.C

35
src/lagrangian/distributionModels/fixedValue/fixedValue.H
View File

@ -6,6 +6,7 @@
\\/ M anipulation |
-------------------------------------------------------------------------------
Copyright (C) 2011-2016 OpenFOAM Foundation
Copyright (C) 2021 OpenCFD Ltd.
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
@ -27,7 +28,39 @@ Class
Foam::distributionModels::fixedValue
Description
Returns a fixed value
Particle-size distribution model wherein samples are given fixed values.
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type fixedValue;
fixedValueDistribution
{
value <value>;
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: fixedValue | word | yes | -
fixedValueDistribution | Distribution settings | dict | yes | -
value | Fixed value for size | scalar | yes | -
\endtable
SourceFiles
fixedValue.C

61
src/lagrangian/distributionModels/general/general.H
View File

@ -28,7 +28,66 @@ Class
Foam::distributionModels::general
Description
general distribution model
Particle-size distribution model wherein random samples are
drawn from a given arbitrary probability density function
or cumulative distribution function. Input distributions are
specified as pairs of (size, probability) (i.e. (point, value) ).
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type general;
generalDistribution
{
cumulative false;
distribution
(
(<size1> <probability1>)
(<size2> <probability2>)
...
(<sizeN> <probabilityN>)
);
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: general | word | yes | -
generalDistribution | Distribution settings | dict | yes | -
distribution | \<size\>-\<probability\> pairs | dict | yes | -
\<size\> | Particle size | scalar | yes | -
\<probability\> | Volume fraction/probability | scalar | yes | -
cumulative | Flag to determine if input distribution is specified <!--
--> as cumulative or as density | bool | no | false
\endtable
Note
- An example for a pair within \c distribution subdictionary
can be given as follows: "(1e-07 1.3)" means 1.3\% of particles
are modelled with a particle diameter of "1e-7" [m], and so on.
- Variation between input pairs is assumed to be linear.
- Elements in the second column (i.e. probability) are normalised.
- Elements in the second column for cumulative distribution
functions must start from zero and must be non-decreasing (i.e. monotonic).
- Elements in the first column (i.e. size) must be specified
in an ascending order.
- Input pairs cannot contain any negative element.
SourceFiles
general.C

136
src/lagrangian/distributionModels/massRosinRammler/massRosinRammler.H
View File

@ -25,27 +25,141 @@ License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
Class
Foam::massRosinRammler
Foam::distributionModels::massRosinRammler
Description
Mass-based Rosin-Rammler distributionModel.
Particle-size distribution model wherein random samples are drawn
from the two-parameter Rosin-Rammler (Weibull) probability density
function corrected to take into account varying number of particles
per parcels for fixed-mass parcels.
Corrected form of the Rosin-Rammler distribution taking into account the
varying number of particels per parces for for fixed-mass parcels. This
distribution should be used when
"There is a factor of \f$x^3\f$ difference between the size distribution
probability density function of individual particles and modeled parcels
of particles, \f$ f_{parcels}(D) = x^3 f_{particles}(D) \f$, because the
submodel parameter, \f$ PPP \f$ (number of particles per parcel) is based
on a fixed mass per parcel which weights the droplet distribution by
a factor proportional to \f$ 1/x^3 \f$ (i.e. \f$ PPP = \dot{m}_{total}
\Delta_{t_{inj(per-parcel)}} / {m}_{particle} \f$)." (YHD:p. 1374-1375).
\c massRosinRammler should be preferred over \c RosinRammler
when \c parcelBasisType is based on \c mass:
\verbatim
parcelBasisType mass;
\endverbatim
See equation 10 in reference:
The doubly-truncated mass-corrected
Rosin-Rammler probability density function:
\f[
f(x; \lambda, n, A, B) =
x^3
\frac{n}{\lambda}
\left( \frac{x}{\lambda} \right)^{n-1}
\frac{
\exp\{ -(\frac{x}{\lambda})^n \}
}
{
\exp\{ -(\frac{A}{\lambda})^n \}
- \exp\{ -(\frac{B}{\lambda})^n \}
}
\f]
where
\vartable
f(x; \lambda, n, A, B) | Rosin-Rammler probability density function
\lambda | Scale parameter
n | Shape parameter
x | Sample
A | Minimum of the distribution
B | Maximum of the distribution
\endvartable
Constraints:
- \f$ \lambda > 0 \f$
- \f$ n > 0 \f$
Random samples are generated by the inverse transform sampling technique
by using the quantile function of the doubly-truncated two-parameter
mass-corrected Rosin-Rammler (Weibull) probability density function:
\f[
d = \lambda \, Q(a, u)^{1/n}
\f]
with
\f[
a = \frac{3}{n} + 1
\f]
where \f$ Q(z_1, z_2) \f$ is the inverse of regularised lower incomplete
gamma function, and \f$ u \f$ is a sample drawn from the uniform
probability density function on the interval \f$ (x, y) \f$:
\f[
x = \gamma \left( a, \frac{A}{\lambda}^n \right)
\f]
\f[
y = \gamma \left( a, \frac{B}{\lambda}^n \right)
\f]
where \f$ \gamma(z_1, z_2) \f$ is the lower incomplete gamma function.
Reference:
\verbatim
Yoon, S. S., Hewson, J. C., DesJardin, P. E., Glaze, D. J.,
Black, A. R., & Skaggs, R. R. (2004).
Numerical modeling and experimental measurements of a high speed
solid-cone water spray for use in fire suppression applications.
International Journal of Multiphase Flow, 30(11), 1369-1388.
Standard model (tag:YHD):
Yoon, S. S., Hewson, J. C., DesJardin, P. E.,
Glaze, D. J., Black, A. R., & Skaggs, R. R. (2004).
Numerical modeling and experimental measurements of a high speed
solid-cone water spray for use in fire suppression applications.
International Journal of Multiphase Flow, 30(11), 1369-1388.
DOI:10.1016/j.ijmultiphaseflow.2004.07.006
\endverbatim
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
parcelBasisType mass;
...
sizeDistribution
{
type massRosinRammler;
massRosinRammlerDistribution
{
lambda <scaleParameterValue>;
n <shapeParameterValue>;
minValue <minValue>;
maxValue <maxValue>;
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: massRosinRammler | word | yes | -
massRosinRammlerDistribution | Distribution settings | dict | yes | -
lambda | Scale parameter | scalar | yes | -
n | Shape parameter | scalar | yes | -
minValue | Minimum of the distribution | scalar | yes | -
maxValue | Maximum of the distribution | scalar | yes | -
\endtable
Note
- In the current context, \c lambda (or \c d) is called "characteristic
droplet size", and \c n "empirical dimensionless constant to specify
the distribution width, sometimes referred to as the dispersion
coefficient." (YHD:p. 1374).
SourceFiles
massRosinRammler.C

141
src/lagrangian/distributionModels/multiNormal/multiNormal.H
View File

@ -28,12 +28,149 @@ Class
Foam::distributionModels::multiNormal
Description
A multiNormal distribution model
Particle-size distribution model wherein random samples are drawn
from a mixture of a finite set of doubly-truncated univariate normal
probability density functions:
\f[
g (\mathbf{x}; \mathbf{\mu}, \mathbf{\sigma}, A, B) =
\sum_i w_i f(x_i; \mu_i, \sigma_i, A, B)
\f]
with for any distribution:
\f[
f(x; \mu, \sigma, A, B) =
\frac{1}{\sigma}
\frac{
\phi \left( \frac{x - \mu}{\sigma} \right)
}{
\Phi \left( \frac{B - \mu}{\sigma} \right)
- \Phi \left( \frac{A - \mu}{\sigma} \right)
}
\f]
where
\vartable
f(x; \mu, \sigma, A, B) | Doubly-truncated univariate normal distribution
\mu | Mean of the parent general normal distribution
\sigma | Standard deviation of the parent general normal distribution
\phi(\cdot) | General normal probability density function
\Phi(\cdot) | General normal cumulative distribution function
x | Sample
A | Minimum of the distribution (the same for each distribution)
B | Maximum of the distribution (the same for each distribution)
w_i | Weighting factor
\endvartable
Constraints:
- \f$ \infty > B > A > 0 \f$
- \f$ x \in [B,A] \f$
- \f$ \sigma^2 > 0 \f$
- \f$ w_i >= 0 \f$
Random samples are generated by a combination of the inverse transform
sampling technique and categorical sampling in three steps:
- Draw a sample from the uniform probability density function
on the unit interval \f$u = (0, 1)\f$
- Find the interval among normalised cumulative weight intervals
wherein \f$ u \f$ resides
- Draw a sample from the distribution corresponding to the interval by
using the quantile function of the doubly-truncated univariate normal
probability density function by the following expressions (similar to
\c distributionModels::normal):
\f[
x = \mu + \sigma \sqrt{2} \, {erf}^{-1} \left( 2 p - 1 \right)
\f]
with
\f[
p = u \,
\left(
\Phi\left(
\frac{B - \mu}{\sigma}
\right)
- \Phi\left(
\frac{A - \mu}{\sigma}
\right)
\right)
+ \Phi\left( \frac{A - \mu}{\sigma} \right)
\f]
\f[
\Phi(\xi) =
\frac{1}{2}
\left(
1 + {erf}\left(\frac{\xi - \mu}{\sigma \sqrt{2} }\right)
\right)
\f]
where \f$ u \f$ is another sample drawn from the uniform probability
density function on the unit interval \f$ (0, 1) \f$.
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
model = sum_i strength_i * exp(-0.5*((x - expectation_i)/variance_i)^2 )
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type multiNormal;
multiNormalDistribution
{
minValue <min>;
maxValue <max>;
mu
(
<mean1>
<mean2>
...
);
sigma
(
<standard deviation1>
<standard deviation2>
...
);
weight
(
<weight1>
<weight2>
...
);
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: multiNormal | word | yes | -
multiNormalDistribution | Distribution settings | dict | yes | -
minValue | Minimum of the distribution | scalar | yes | -
maxValue | Maximum of the distribution | scalar | yes | -
mu | List of means of parent general normal <!--
--> distributions | scalarList | yes | -
sigma | List of standard deviations of parent <!--
--> general normal distributions | scalarList | yes | -
weight | List of weights of a given distribution in <!--
--> the distribution mixture | scalarList | yes | -
\endtable
Notes
- The sum of normal distributions (i.e. a mixture distribution) should not
be confused with the sum of normally-distributed random variables.
- \c minValue and \c maxValue are the same for all distributions
in the distribution mixture.
- \c weight should always be input in a non-decreasing (i.e. monotonic) order.
SourceFiles
multiNormal.C

117
src/lagrangian/distributionModels/normal/normal.H
View File

@ -28,13 +28,124 @@ Class
Foam::distributionModels::normal
Description
A normal distribution model
Particle-size distribution model wherein random samples are drawn
from the doubly-truncated univariate normal probability density function:
\f[
f(x; \mu, \sigma, A, B) =
\frac{1}{\sigma}
\frac{
\phi \left( \frac{x - \mu}{\sigma} \right)
}{
\Phi \left( \frac{B - \mu}{\sigma} \right)
- \Phi \left( \frac{A - \mu}{\sigma} \right)
}
\f]
where
\vartable
f(x; \mu, \sigma, A, B) | Doubly-truncated univariate normal distribution
\mu | Mean of the parent general normal distribution
\sigma | Standard deviation of the parent general normal distribution
\phi(\cdot) | General normal probability density function
\Phi(\cdot) | General normal cumulative distribution function
x | Sample
A | Minimum of the distribution
B | Maximum of the distribution
\endvartable
Constraints:
- \f$ \infty > B > A > 0 \f$
- \f$ x \in [B,A] \f$
- \f$ \sigma^2 > 0 \f$
Random samples are generated by the inverse transform sampling technique
by using the quantile function of the doubly-truncated univariate normal
probability density function:
\f[
x = \mu + \sigma \sqrt{2} \, {erf}^{-1} \left( 2 p - 1 \right)
\f]
with
\f[
p = u \,
\left(
\Phi\left(
\frac{B - \mu}{\sigma}
\right)
- \Phi\left(
\frac{A - \mu}{\sigma}
\right)
\right)
+ \Phi\left( \frac{A - \mu}{\sigma} \right)
\f]
\f[
\Phi(\xi) =
\frac{1}{2}
\left(
1 + {erf}\left(\frac{\xi - \mu}{\sigma \sqrt{2} }\right)
\right)
\f]
where \f$ u \f$ is sample drawn from the uniform probability
density function on the unit interval \f$ (0, 1) \f$.
Reference:
\verbatim
model = strength * exp(-0.5*((x - expectation)/variance)^2 )
Governing expressions (tag:B):
Burkardt, J. (2014).
The truncated normal distribution.
Department of Scientific Computing Website,
Florida State University, 1-35.
URL:people.sc.fsu.edu/~jburkardt/presentations/truncated_normal.pdf
(Retrieved on: 19 Feb 2021)
\endverbatim
strength only has meaning if there's more than one distribution model
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type normal;
normalDistribution
{
mu <mean>;
sigma <stardard deviation>;
minValue <min>;
maxValue <max>;
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: normal | word | yes | -
normalDistribution | Distribution settings | dict | yes | -
mu | Mean of the parent general normal distribution <!--
--> | scalar | yes | -
sigma | Standard deviation of the parent general normal <!--
--> distribution | scalar | yes | -
minValue | Minimum of the distribution | scalar | yes | -
maxValue | Maximum of the distribution | scalar | yes | -
\endtable
Note
- The mean and standard deviation of the parent general normal probability
distribution function (i.e. input) are not the same with those of the
truncated probability distribution function.
SourceFiles
normal.C

64
src/lagrangian/distributionModels/uniform/uniform.H
View File

@ -28,7 +28,69 @@ Class
Foam::distributionModels::uniform
Description
Uniform/equally-weighted distribution model
Particle-size distribution model wherein random samples are drawn
from the doubly-truncated uniform probability density function:
\f[
f(x; A, B) = \frac{1}{B - A}
\f]
where
\vartable
f(x; A, B) | Doubly-truncated uniform distribution
x | Sample
A | Minimum of the distribution
B | Maximum of the distribution
\endvartable
Constraints:
- \f$ \infty > B > A > 0 \f$
- \f$ x \in [B,A] \f$
- \f$ \sigma^2 > 0 \f$
Random samples are generated by the inverse transform sampling technique
by using the quantile function of the uniform probability density function:
\f[
x = u \, (B - A) + A
\f]
where \f$ u \f$ is sample drawn from the uniform probability
density function on the unit interval \f$ (0, 1) \f$.
Usage
Minimal example by using \c constant/\<CloudProperties\>:
\verbatim
subModels
{
injectionModels
{
<name>
{
...
sizeDistribution
{
type uniform;
uniformDistribution
{
minValue <min>;
maxValue <max>;
}
}
}
}
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Reqd | Deflt
type | Type name: uniform | word | yes | -
uniformDistribution | Distribution settings | dict | yes | -
minValue | Minimum of the distribution | scalar | yes | -
maxValue | Maximum of the distribution | scalar | yes | -
\endtable
SourceFiles
uniform.C