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-2024 OpenFOAM Foundation
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9  This file is part of OpenFOAM.
10 
11  OpenFOAM is free software: you can redistribute it and/or modify it
12  under the terms of the GNU General Public License as published by
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 "randomGenerator.H"
64 #include "fieldTypes.H"
65 #include "scalarField.H"
66 
67 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
68 
69 namespace Foam
70 {
71 
72 /*---------------------------------------------------------------------------*\
73  Class distribution Declaration
74 \*---------------------------------------------------------------------------*/
75 
76 class distribution
77 {
78 protected:
79 
80  // Protected data
81 
82  //- Distribution size exponent
83  const label Q_;
84 
85  //- Sample size exponent
86  const label sampleQ_;
87 
88  //- Random number generator
89  mutable randomGenerator rndGen_;
90 
91 
92  // Protected Member Functions
93 
94  //- Validate that the bounds are monotonic
95  virtual void validateBounds(const dictionary& dict) const;
96 
97  //- Validate that the lower bound is positive
98  virtual void validatePositive(const dictionary& dict) const;
99 
100  //- Clip the PDF values to zero outside the bounds
102  (
103  const scalarField& x,
104  const tmp<scalarField>& pdf
105  ) const;
106 
107  //- Return the effective distribution size exponent
108  inline label q() const
109  {
110  return sampleQ_ - Q_;
111  }
112 
113  //- Sample the distribution into components of a primitive type
114  #define VIRTUAL_SAMPLE_TYPE(Type, nullArg) \
115  virtual Type CAT(sample, CAPITALIZE(Type))() const = 0;
117  #undef VIRTUAL_SAMPLE_TYPE
118 
119 
120 public:
121 
122  //- Runtime type information
123  TypeName("distribution");
124 
125 
126  //- Declare runtime constructor selection table
128  (
129  autoPtr,
130  distribution,
131  dictionary,
132  (
133  const unitConversion& units,
134  const dictionary& dict,
135  const label sampleQ,
137  ),
138  (units, dict, sampleQ, std::move(rndGen))
139  );
140 
141 
142  // Constructors
143 
144  //- Construct from dictionary
146  (
147  const word& name,
148  const unitConversion& units,
149  const dictionary& dict,
150  const label sampleQ,
152  );
153 
154  //- Construct from components
156  (
157  const label Q,
158  const label sampleQ,
160  );
161 
162  //- Construct copy
163  distribution(const distribution& d, const label sampleQ);
164 
165  //- Construct and return a clone
166  virtual autoPtr<distribution> clone(const label sampleQ) const = 0;
167 
168  //- Construct and return a clone
169  inline autoPtr<distribution> clone() const
170  {
171  return clone(sampleQ_);
172  }
173 
174 
175  // Selectors
176 
177  //- Select from dictionary and a random generator
179  (
180  const unitConversion& units,
181  const dictionary& dict,
182  const label sampleQ,
184  const bool report = true
185  );
186 
187  //- Select from a dictionary and a random generator seed and global flag
189  (
190  const unitConversion& units,
191  const dictionary& dict,
192  const label sampleQ,
193  const randomGenerator::seed& s,
194  const bool global = false,
195  const bool report = true
196  );
197 
198  //- Re-select with a different sample size exponent
200  (
201  autoPtr<distribution>& dPtr,
202  const label sampleQ
203  );
204 
205 
206  //- Destructor
207  virtual ~distribution();
208 
209 
210  // Member Functions
211 
212  //- Sample the distribution
213  virtual scalar sample() const = 0;
214 
215  //- Sample the distribution into components of a primitive type
216  template<class Type>
217  Type sample() const;
218 
219  //- Sample the distribution into a field
220  virtual tmp<scalarField> sample(const label n) const = 0;
221 
222  //- Return the minimum value
223  virtual scalar min() const = 0;
224 
225  //- Return the maximum value
226  virtual scalar max() const = 0;
227 
228  //- Return the mean value
229  virtual scalar mean() const = 0;
230 
231  //- Write to a stream
232  virtual void write(Ostream& os, const unitConversion& units) const;
233 
234  //- Write the state to a stream
235  virtual void writeState(Ostream& os) const;
236 
237  //- Return coordinates to plot across the range of the distribution
238  virtual tmp<scalarField> x(const label n) const;
239 
240  //- Return the distribution probability density function
241  virtual tmp<scalarField> PDF(const scalarField& x) const = 0;
242 };
243 
244 
245 #define DISTRIBUTION_TEMPLATED_SAMPLE_TYPE(Type, nullArg) \
246  template<> \
247  inline Type Foam::distribution::sample<Type>() const \
248  { \
249  return CAT(sample, CAPITALIZE(Type))(); \
250  }
252 #undef DISTRIBUTION_TEMPLATED_SAMPLE_TYPE
253 
254 
255 void writeEntry
256 (
257  Ostream& os,
258  const unitConversion&,
259  const distribution& d,
260  const bool write = true,
261  const bool writeState = true
262 );
263 
264 
265 /*---------------------------------------------------------------------------*\
266  Class FieldDistribution Declaration
267 \*---------------------------------------------------------------------------*/
268 
269 template<class Base, class Derived>
270 class FieldDistribution
271 :
272  public Base
273 {
274 protected:
275 
276  // Protected Member Functions
277 
278  //- Sample the distribution into components of a primitive type
279  #define VIRTUAL_SAMPLE_TYPE(Type, nullArg) \
280  virtual Type CAT(sample, CAPITALIZE(Type))() const \
281  { \
282  return sample<Type>(); \
283  }
285  #undef VIRTUAL_SAMPLE_TYPE
286 
287 
288 public:
289 
290  // Constructors
291 
292  //- Inherit constructors
293  using Base::Base;
294 
295 
296  // Member Functions
297 
298  //- Sample the distribution
299  using Base::sample;
300 
301  //- Sample the distribution into components of a primitive type
302  template<class Type>
303  Type sample() const;
304 
305  //- Sample the distribution into a field
306  virtual tmp<scalarField> sample(const label n) const;
307 };
308 
309 
310 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
311 
312 } // End namespace Foam
313 
314 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
315 
316 #ifdef NoRepository
317  #include "distributionTemplates.C"
318 #endif
319 
320 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
321 
322 #endif
323 
324 // ************************************************************************* //
label n
Type sample() const
Sample the distribution into components of a primitive type.
FOR_ALL_FIELD_TYPES(VIRTUAL_SAMPLE_TYPE)
An Ostream is an abstract base class for all output systems (streams, files, token lists,...
Definition: Ostream.H:57
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:162
Base class for statistical distributions.
Definition: distribution.H:76
virtual tmp< scalarField > PDF(const scalarField &x) const =0
Return the distribution probability density function.
declareRunTimeSelectionTable(autoPtr, distribution, dictionary,(const unitConversion &units, const dictionary &dict, const label sampleQ, randomGenerator &&rndGen),(units, dict, sampleQ, std::move(rndGen)))
Declare runtime constructor selection table.
virtual scalar max() const =0
Return the maximum value.
autoPtr< distribution > clone() const
Construct and return a clone.
Definition: distribution.H:168
virtual void writeState(Ostream &os) const
Write the state to a stream.
Definition: distribution.C:141
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:82
label q() const
Return the effective distribution size exponent.
Definition: distribution.H:107
virtual ~distribution()
Destructor.
Definition: distribution.C:128
virtual tmp< scalarField > x(const label n) const
Return coordinates to plot across the range of the distribution.
Definition: distribution.C:147
const label sampleQ_
Sample size exponent.
Definition: distribution.H:85
distribution(const word &name, const unitConversion &units, const dictionary &dict, const label sampleQ, randomGenerator &&rndGen)
Construct from dictionary.
Definition: distribution.C:77
virtual void validateBounds(const dictionary &dict) const
Validate that the bounds are monotonic.
Definition: distribution.C:39
FOR_ALL_FIELD_TYPES(VIRTUAL_SAMPLE_TYPE)
TypeName("distribution")
Runtime type information.
virtual void write(Ostream &os, const unitConversion &units) const
Write to a stream.
Definition: distribution.C:134
virtual scalar mean() const =0
Return the mean value.
virtual scalar min() const =0
Return the minimum value.
randomGenerator rndGen_
Random number generator.
Definition: distribution.H:88
static autoPtr< distribution > New(const unitConversion &units, const dictionary &dict, const label sampleQ, randomGenerator &&rndGen, const bool report=true)
Select from dictionary and a random generator.
Random number generator.
A class for managing temporary objects.
Definition: tmp.H:55
Unit conversion structure. Contains the associated dimensions and the multiplier with which to conver...
A class for handling words, derived from string.
Definition: word.H:62
#define VIRTUAL_SAMPLE_TYPE(Type, nullArg)
Sample the distribution into components of a primitive type.
Definition: distribution.H:278
#define DISTRIBUTION_TEMPLATED_SAMPLE_TYPE(Type, nullArg)
Definition: distribution.H:244
Include the header files for all the primitive types that Fields are instantiated for.
gmvFile<< "tracers "<< particles.size()<< nl;forAllConstIter(Cloud< passiveParticle >, particles, iter){ gmvFile<< iter().position().x()<< " ";}gmvFile<< nl;forAllConstIter(Cloud< passiveParticle >, particles, iter){ gmvFile<< iter().position().y()<< " ";}gmvFile<< nl;forAllConstIter(Cloud< passiveParticle >, particles, iter){ gmvFile<< iter().position().z()<< " ";}gmvFile<< nl;forAll(lagrangianScalarNames, i){ word name=lagrangianScalarNames[i];IOField< scalar > s(IOobject(name, runTime.name(), cloud::prefix, mesh, IOobject::MUST_READ, IOobject::NO_WRITE))
void write(std::ostream &os, const bool binary, List< floatScalar > &fField)
Write floats ascii or binary.
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
const HashTable< unitConversion > & units()
Get the table of unit conversions.
void writeEntry(Ostream &os, const HashTable< T, Key, Hash > &ht)
Definition: HashTableIO.C:96
FOR_ALL_FIELD_TYPES(makeFieldSourceTypedef)
dictionary dict
randomGenerator rndGen(653213)