The OpenFOAM Foundation
distribution.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration | Website: https://openfoam.org
5  \\ / A nd | Copyright (C) 2011-2023 OpenFOAM Foundation
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
9  This file is part of OpenFOAM.
10
11  OpenFOAM is free software: you can redistribute it and/or modify it
13  the Free Software Foundation, either version 3 of the License, or
14  (at your option) any later version.
15
16  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19  for more details.
20
21  You should have received a copy of the GNU General Public License
22  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23
24 Class
25  Foam::distribution
26
27 Description
28  Base class for statistical distributions
29
30  All distributions (except fixedValue) require a "size exponent", Q, to be
31  specified along with their other coefficients. If a distribution's CDF(x)
32  (cumulative distribution function) represents what proportion of the
33  distribution takes a value below x, then Q determines what is meant by
34  "proportion":
35
36  - If Q=0, then "proportion" means the number of sampled values expected to
37  be below x divided by the total number of sampled values.
38
39  - If Q=3, then "proportion" means the expected sum of sampled values cubed
40  for values below x divided by the total sum of values cubed. If x is a
41  length, then this can be interpreted as a proportion of the total volume
42  of sampled objects.
43
44  - If Q=2, and x is a length, then the distribution might represent the
45  proportion of surface area, and so on...
46
47  In addition to the user-specification of Q defining what size the given
48  distribution relates to, an implementation that uses a distribution can
49  also programmatically define a samplingQ to determine what sort of sample
50  is being constructed; whether the samples should have an equal number
51  (sampleQ=0), volume (sampleQ=3), area (sampleQ=2), etc...
52
53 SourceFiles
54  distribution.C
55  distributionNew.C
56
57 \*---------------------------------------------------------------------------*/
58
59 #ifndef distribution_H
60 #define distribution_H
61
62 #include "dictionary.H"
63 #include "Random.H"
64 #include "scalarField.H"
65
66 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
67
68 namespace Foam
69 {
70
71 /*---------------------------------------------------------------------------*\
72  Class distribution Declaration
73 \*---------------------------------------------------------------------------*/
74
75 class distribution
76 {
77 protected:
78
79  // Protected data
80
81  //- Reference to a random number generator
82  Random& rndGen_;
83
84  //- Distribution size exponent
85  const label Q_;
86
87  //- Sample size exponent
88  const label sampleQ_;
89
90
91  // Protected Member Functions
92
93  //- Validate that the bounds are monotonic
94  virtual void validateBounds(const dictionary& dict) const;
95
96  //- Validate that the lower bound is positive
97  virtual void validatePositive(const dictionary& dict) const;
98
99  //- Clip the PDF values to zero outside the bounds
101  (
102  const scalarField& x,
103  const tmp<scalarField>& pdf
104  ) const;
105
106  //- Return the effective distribution size exponent
107  inline label q() const
108  {
109  return sampleQ_ - Q_;
110  }
111
112
113 public:
114
115  //-Runtime type information
116  TypeName("distribution");
117
118
119  //- Declare runtime constructor selection table
121  (
122  autoPtr,
123  distribution,
124  dictionary,
125  (
126  const dictionary& dict,
127  Random& rndGen,
128  const label sampleQ
129  ),
130  (dict, rndGen, sampleQ)
131  );
132
133
134  // Constructors
135
136  //- Construct from dictionary
138  (
139  const word& name,
140  const dictionary& dict,
141  Random& rndGen,
142  const label sampleQ
143  );
144
145  //- Construct from components
146  distribution(Random& rndGen, const label Q, const label sampleQ);
147
148  //- Construct copy
149  distribution(const distribution& d, const label sampleQ);
150
151  //- Construct and return a clone
152  virtual autoPtr<distribution> clone(const label sampleQ) const = 0;
153
154  //- Construct and return a clone
155  inline autoPtr<distribution> clone() const
156  {
157  return clone(sampleQ_);
158  }
159
160
161  //- Selector
163  (
164  const dictionary& dict,
165  Random& rndGen,
166  const label sampleQ
167  );
168
169
170  //- Destructor
171  virtual ~distribution();
172
173
174  // Member Functions
175
176  //- Sample the distribution
177  virtual scalar sample() const = 0;
178
179  //- Sample the distribution
180  virtual tmp<scalarField> sample(const label n) const = 0;
181
182  //- Return the minimum value
183  virtual scalar min() const = 0;
184
185  //- Return the maximum value
186  virtual scalar max() const = 0;
187
188  //- Return the mean value
189  virtual scalar mean() const = 0;
190
191  //- Report
192  void report() const;
193
194  //- Return coordinates to plot across the range of the distribution
195  virtual tmp<scalarField> x(const label n) const;
196
197  //- Return the distribution probability density function
198  virtual tmp<scalarField> PDF(const scalarField& x) const = 0;
199 };
200
201
202 /*---------------------------------------------------------------------------*\
203  Class FieldDistribution Declaration
204 \*---------------------------------------------------------------------------*/
205
206 template<class Base, class Derived>
207 class FieldDistribution
208 :
209  public Base
210 {
211 public:
212
213  // Constructors
214
215  //- Inherit constructors
216  using Base::Base;
217
218
219  // Member Functions
220
221  //- Sample the distribution
222  using Base::sample;
223
224  //- Sample the distribution
225  virtual tmp<scalarField> sample(const label n) const
226  {
227  tmp<scalarField> tResult(new scalarField(n));
228  scalarField& result = tResult.ref();
229
230  forAll(result, i)
231  {
232  result[i] =
233  static_cast<const Derived&>(*this).sample();
234  }
235
236  return tResult;
237  }
238 };
239
240
241 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
242
243 } // End namespace Foam
244
245 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
246
247 #endif
248
249 // ************************************************************************* //
label n
#define forAll(list, i)
Loop across all elements in list.
Definition: UList.H:434
virtual tmp< scalarField > sample(const label n) const
Sample the distribution.
Definition: distribution.H:224
Random number generator.
Definition: Random.H:58
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: autoPtr.H:51
A list of keyword definitions, which are a keyword followed by any number of values (e....
Definition: dictionary.H:160
Accumulating histogram of values. Specified bin resolution automatic generation of bins.
Definition: distribution.H:61
virtual tmp< scalarField > PDF(const scalarField &x) const =0
Return the distribution probability density function.
void report() const
Report.
Definition: distribution.C:133
virtual scalar max() const =0
Return the maximum value.
autoPtr< distribution > clone() const
Construct and return a clone.
Definition: distribution.H:154
Random & rndGen_
Reference to a random number generator.
Definition: distribution.H:81
declareRunTimeSelectionTable(autoPtr, distribution, dictionary,(const dictionary &dict, Random &rndGen, const label sampleQ),(dict, rndGen, sampleQ))
Declare runtime constructor selection table.
virtual void validatePositive(const dictionary &dict) const
Validate that the lower bound is positive.
Definition: distribution.C:51
tmp< scalarField > clipPDF(const scalarField &x, const tmp< scalarField > &pdf) const
Clip the PDF values to zero outside the bounds.
Definition: distribution.C:65
virtual scalar sample() const =0
Sample the distribution.
const label Q_
Distribution size exponent.
Definition: distribution.H:84
label q() const
Return the effective distribution size exponent.
Definition: distribution.H:106
virtual ~distribution()
Destructor.
Definition: distribution.C:78
static autoPtr< distribution > New(const dictionary &dict, Random &rndGen, const label sampleQ)
Selector.
virtual tmp< scalarField > x(const label n) const
Return coordinates to plot across the range of the distribution.
Definition: distribution.C:140
const label sampleQ_
Sample size exponent.
Definition: distribution.H:87
virtual void validateBounds(const dictionary &dict) const
Validate that the bounds are monotonic.
Definition: distribution.C:39
TypeName("distribution")
Runtime type information.
distribution()
Construct null.
Definition: distribution.C:55
virtual scalar min() const =0
Return the minimum value.
scalar mean() const
Definition: distribution.C:125
A class for managing temporary objects.
Definition: tmp.H:55
T & ref() const
Return non-const reference or generate a fatal error.
Definition: tmpI.H:181
A class for handling words, derived from string.
Definition: word.H:62
Namespace for OpenFOAM.
intWM_LABEL_SIZE_t label
A label is an int32_t or int64_t as specified by the pre-processor macro WM_LABEL_SIZE.
Definition: label.H:59
word name(const bool)
Return a word representation of a bool.
Definition: boolIO.C:39
Field< scalar > scalarField
Specialisation of Field<T> for scalar.
dictionary dict
Random rndGen(label(0))