Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
distributions.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2023-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_distributions_h
5#define lethe_distributions_h
6
8
9#include <random>
10
12{
13protected:
15
17 &distribution_weighting_type);
18
19 /**
20 * @brief Minimal cutoff diameters values.
21 */
23
24 /**
25 * @brief Maximum cutoff diameters values.
26 */
28
29public:
30 /**
31 * @brief Default destructor.
32 */
33 virtual ~Distribution() = default;
34
35 /**
36 * @brief Carries out the size sampling of particles. This is the base class of
37 * NormalDistribution, UniformDistribution and CustomDistribution classes.
38 *
39 * @param[in] number_of_particles Number of particles inserted at a given
40 * insertion time step.
41 */
42 virtual std::vector<double>
43 particle_size_sampling(const unsigned int &number_of_particles) = 0;
44
45 /**
46 * @brief Return the minimum diameter for a certain distribution.
47 *
48 * @return The minimum diameter of a certain distribution.
49 */
50 virtual double
52
53 /**
54 * @brief Return the maximum diameter for a certain distribution.
55 *
56 * @return The maximum diameter of a certain distribution.
57 */
58 virtual double
60
61 /**
62 * @brief Print the declaration string relative to the particle size
63 * distribution used.
64 *
65 * @param particle_type Particle type of the distribution
66 * @param pcout Parallel conditional output stream used to print the
67 * information
68 */
69 virtual void
70 print_psd_declaration_string(const unsigned int particle_type,
71 const ConditionalOStream &pcout) = 0;
72};
73
75{
76public:
77 /**
78 * @brief The constructor stores the parameters necessary to define the normal
79 * distribution.
80 *
81 * @param[in] d_average Average diameters for a certain normal distribution.
82 * @param[in] d_standard_deviation Standard deviation of the diameter for a
83 * certain normal distribution.
84 * @param[in] prn_seed Pseudo-random number seed for the diameter generation.
85 * @param[in] min_cutoff Minimum cutoff diameter.
86 * @param[in] max_cutoff Maximum cutoff diameter.
87 * @param[in] distribution_weighting_type Weighting type of the distribution.
88 */
89 NormalDistribution(const double &d_average,
90 const double &d_standard_deviation,
91 const unsigned int &prn_seed,
92 double min_cutoff,
93 double max_cutoff,
95 &distribution_weighting_type);
96
97 /**
98 * @brief Carries out the size sampling of each particle inserted at an
99 * insertion time step for the normal distribution.
100 *
101 * @param[in] number_of_particles Number of particles inserted at a given
102 * insertion time step.
103 */
104 virtual std::vector<double>
105 particle_size_sampling(const unsigned int &number_of_particles) override;
106
107 /**
108 * @brief Find the minimum diameter a normal distribution.
109 *
110 * @return The minimum diameter of a normal distribution.
111 */
112 double
113 find_min_diameter() override;
114
115 /**
116 * @brief Find the maximum diameter of the normal distribution.
117 *
118 * @return The maximum diameter of the normal distribution.
119 */
120 double
121 find_max_diameter() override;
122
123 /**
124 * @brief Print the declaration string relative to the particle size
125 * distribution used.
126 *
127 * @param particle_type Particle type of the distribution
128 * @param pcout Parallel conditional output stream used to print the
129 * information
130 */
131 void
132 print_psd_declaration_string(const unsigned int particle_type,
133 const ConditionalOStream &pcout) override;
134
135private:
136 /**
137 * @brief Average diameter of the normal distribution.
138 */
140
141 /**
142 * @brief Standard deviation of the normal distribution.
143 */
145
146 /**
147 * @brief Random number generator for the diameter selection.
148 */
149 std::mt19937 gen;
150};
151
152
154{
155public:
156 /**
157 * @brief The constructor stores the parameters necessary to define the normal
158 * distribution.
159 *
160 * @param[in] d_average Average diameters for a certain normal distribution.
161 * @param[in] d_standard_deviation Standard deviation of the diameter for a
162 * certain normal distribution.
163 * @param[in] prn_seed Pseudo-random number seed for the diameter generation.
164 * @param[in] min_cutoff Minimum cutoff diameter.
165 * @param[in] max_cutoff Maximum cutoff diameter.
166 * @param[in] distribution_weighting_type Weighting type of the distribution.
167 */
168 LogNormalDistribution(const double &d_average,
169 const double &d_standard_deviation,
170 const unsigned int &prn_seed,
171 double min_cutoff,
172 double max_cutoff,
174 &distribution_weighting_type);
175
176 /**
177 * @brief Carries out the size sampling of each particle inserted at an
178 * insertion time step for the normal distribution.
179 *
180 * @param[in] number_of_particles Number of particles inserted at a given
181 * insertion time step.
182 */
183 virtual std::vector<double>
184 particle_size_sampling(const unsigned int &number_of_particles) override;
185
186 /**
187 * @brief Find the minimum diameter a normal distribution.
188 *
189 * @return The minimum diameter of a normal distribution.
190 */
191 double
192 find_min_diameter() override;
193
194 /**
195 * @brief Find the maximum diameter of the normal distribution.
196 *
197 * @return The maximum diameter of the normal distribution.
198 */
199 double
200 find_max_diameter() override;
201
202 /**
203 * @brief Print the declaration string relative to the particle size
204 * distribution used.
205 *
206 * @param particle_type Particle type of the distribution
207 * @param pcout Parallel conditional output stream used to print the
208 * information
209 */
210 void
211 print_psd_declaration_string(const unsigned int particle_type,
212 const ConditionalOStream &pcout) override;
213
214private:
215 /**
216 * @brief Standard deviation of the normal distribution.
217 */
218 const double sigma_ln;
219
220 /**
221 * @brief Average diameter of the normal distribution.
222 */
223 double mu_ln;
224
225 /**
226 * @brief Random number generator for the diameter selection.
227 */
228 std::mt19937 gen;
229};
230
232{
233public:
234 /**
235 * @brief The constructor stores the parameters necessary to define the uniform
236 * distribution.
237 *
238 * @param d_values Diameter values for each particle type.
239 */
240 UniformDistribution(const double &d_values);
241
242 /**
243 * @brief Carries out the size sampling of every particle inserted at an
244 * insertion time step for the uniform distribution.
245 *
246 * @param[in] number_of_particles Number of particles inserted at a given
247 * insertion time step.
248 */
249 virtual std::vector<double>
250 particle_size_sampling(const unsigned int &number_of_particles) override;
251
252 /**
253 * @brief Find the minimum diameter of the uniform distribution.
254 *
255 * @return The diameter of the distribution.
256 */
257 double
258 find_min_diameter() override;
259
260 /**
261 * @brief Find the maximum diameter of the uniform distribution.
262 *
263 * @return The diameter of the distribution.
264 */
265 double
266 find_max_diameter() override;
267
268
269 /**
270 * @brief Print the declaration string relative to the particle size
271 * distribution used.
272 *
273 * @param particle_type Particle type of the distribution
274 * @param pcout Parallel conditional output stream used to print the
275 * information
276 */
277 void
278 print_psd_declaration_string(const unsigned int particle_type,
279 const ConditionalOStream &pcout) override;
280
281private:
282 /**
283 * @brief The diameter value of the distribution.
284 */
285 const double diameter_value;
286};
287
289{
290public:
291 /**
292 * @brief The constructor stores the parameters necessary to define the histogram
293 * distribution.
294 *
295 * @param[in] d_list Vector of diameter values.
296 * @param[in] d_probabilities Vector of probability values based on the volume
297 * fraction with respect to each diameter value.
298 * @param[in] prn_seed Pseudo-random number seed for the diameter generation.
299 * @param[in] min_cutoff Minimum cutoff diameter.
300 * @param[in] max_cutoff Maximum cutoff diameter.
301 * @param[in] distribution_weighting_type Weighting type of the distribution.
302 * @param[in] function_type_in Defines whether the input probability values
303 * correspond to the PDF or the CDF.
304 * @param[in] interpolate Indicates whether the diameter sampled values are
305 * linearly interpolated between input diameter and probability values.
306 */
308 const std::vector<double> &d_list,
309 const std::vector<double> &d_probabilities,
310 const unsigned int &prn_seed,
311 const double min_cutoff,
312 const double max_cutoff,
314 &distribution_weighting_type,
316 const bool interpolate);
317
318 /**
319 * @brief Carries out the size sampling of each particle inserted at an
320 * insertion time step for the histogram distribution.
321 *
322 * @param[in] number_of_particles Number of particles inserted at a given
323 * insertion time step.
324 */
325 virtual std::vector<double>
326 particle_size_sampling(const unsigned int &number_of_particles) override;
327
328 /**
329 * @brief Find the minimum diameter of the custom distribution.
330 *
331 * @return The minimum diameter of the distribution.
332 */
333 double
334 find_min_diameter() override;
335
336 /**
337 * @brief Find the maximum diameter of the custom distribution.
338 *
339 * @return The minimum diameter of the distribution.
340 */
341 double
342 find_max_diameter() override;
343
344 /**
345 * @brief Print the declaration string relative to the particle size
346 * distribution used.
347 *
348 * @param particle_type Particle type of the distribution
349 * @param pcout Parallel conditional output stream used to print the
350 * information
351 */
352 void
353 print_psd_declaration_string(const unsigned int particle_type,
354 const ConditionalOStream &pcout) override;
355
356private:
357 /**
358 * Vector containing all the diameter values.
359 */
360 const std::vector<double> diameter_values;
361
362 /**
363 * @brief Vector containing cumulative probabilities associated with the
364 * diameter_values vector. The stored values are based on the number-based
365 * CDF.
366 */
367 std::vector<double> number_based_cdf;
368
369 /**
370 * @brief Indicates whether the diameter values are interpolated between the
371 * input values during sampling.
372 */
374
375 /**
376 * @brief Random number generator for the diameter selection.
377 */
378 std::mt19937 gen;
379
380 /**
381 * @brief Defines if the custom distribution is a probability density function
382 * (PDF) or a cumulative density function (CDF).
383 */
385
386 // Normalized volume-based PDF values at each diameter node.
387 // Only populated when weighting_type == volume_based &&
388 // interpolate_diameter_values.
389 std::vector<double> fv;
390
391 // Normalization constant for the volume-based interpolated CDF
392 // (sum of all per-segment integrals of fv(d)/d³).
393 // Only populated when weighting_type == volume_based &&
394 // interpolate_diameter_values.
396};
397
398/**
399 * @brief Set up the distributions for each particle type at the start of a
400 * simulation.
401 */
402using namespace Parameters::Lagrangian;
403inline void
405 std::vector<std::shared_ptr<Distribution>>
406 &size_distribution_object_container,
407 double &maximum_particle_diameter,
408 const unsigned int mpi_process_id,
409 const ConditionalOStream &pcout)
410{
411 for (unsigned int particle_type = 0; particle_type < lpp.particle_type_number;
412 particle_type++)
413 {
414 switch (lpp.distribution_type.at(particle_type))
415 {
417 size_distribution_object_container[particle_type] =
418 std::make_shared<UniformDistribution>(
419 lpp.particle_average_diameter.at(particle_type));
420 break;
422 size_distribution_object_container[particle_type] =
423 std::make_shared<NormalDistribution>(
424 lpp.particle_average_diameter.at(particle_type),
425 lpp.particle_size_std.at(particle_type),
426 lpp.seed_for_distributions[particle_type] + mpi_process_id,
427 lpp.diameter_min_cutoff.at(particle_type),
428 lpp.diameter_max_cutoff.at(particle_type),
429 lpp.distribution_weighting_type.at(particle_type));
430 break;
432 size_distribution_object_container[particle_type] =
433 std::make_shared<LogNormalDistribution>(
434 lpp.particle_average_diameter.at(particle_type),
435 lpp.particle_size_std.at(particle_type),
436 lpp.seed_for_distributions[particle_type] + mpi_process_id,
437 lpp.diameter_min_cutoff.at(particle_type),
438 lpp.diameter_max_cutoff.at(particle_type),
439 lpp.distribution_weighting_type.at(particle_type));
440 break;
442 size_distribution_object_container[particle_type] =
443 std::make_shared<CustomDistribution>(
444 lpp.particle_custom_diameter.at(particle_type),
445 lpp.particle_custom_probability.at(particle_type),
446 lpp.seed_for_distributions[particle_type] + mpi_process_id,
447 lpp.diameter_min_cutoff.at(particle_type),
448 lpp.diameter_max_cutoff.at(particle_type),
449 lpp.distribution_weighting_type.at(particle_type),
450 lpp.custom_probability_function_type.at(particle_type),
451 lpp.custom_distribution_interpolation.at(particle_type));
452 break;
453 }
454 size_distribution_object_container[particle_type]
455 ->print_psd_declaration_string(particle_type, pcout);
456
457 maximum_particle_diameter = std::max(
458 maximum_particle_diameter,
459 size_distribution_object_container[particle_type]->find_max_diameter());
460 }
461}
462
463#endif
virtual std::vector< double > particle_size_sampling(const unsigned int &number_of_particles) override
Carries out the size sampling of each particle inserted at an insertion time step for the histogram d...
std::vector< double > number_based_cdf
Vector containing cumulative probabilities associated with the diameter_values vector....
std::mt19937 gen
Random number generator for the diameter selection.
std::vector< double > fv
double find_max_diameter() override
Find the maximum diameter of the custom distribution.
const std::vector< double > diameter_values
const bool interpolate_diameter_values
Indicates whether the diameter values are interpolated between the input values during sampling.
CustomDistribution(const std::vector< double > &d_list, const std::vector< double > &d_probabilities, const unsigned int &prn_seed, const double min_cutoff, const double max_cutoff, const Parameters::Lagrangian::DistributionWeightingType &distribution_weighting_type, const Parameters::Lagrangian::ProbabilityFunctionType &function_type_in, const bool interpolate)
The constructor stores the parameters necessary to define the histogram distribution.
void print_psd_declaration_string(const unsigned int particle_type, const ConditionalOStream &pcout) override
Print the declaration string relative to the particle size distribution used.
const Parameters::Lagrangian::ProbabilityFunctionType function_type
Defines if the custom distribution is a probability density function (PDF) or a cumulative density fu...
double find_min_diameter() override
Find the minimum diameter of the custom distribution.
Distribution(const Parameters::Lagrangian::DistributionWeightingType &distribution_weighting_type)
virtual double find_min_diameter()=0
Return the minimum diameter for a certain distribution.
virtual std::vector< double > particle_size_sampling(const unsigned int &number_of_particles)=0
Carries out the size sampling of particles. This is the base class of NormalDistribution,...
double dia_min_cutoff
Minimal cutoff diameters values.
double dia_max_cutoff
Maximum cutoff diameters values.
virtual ~Distribution()=default
Default destructor.
const Parameters::Lagrangian::DistributionWeightingType weighting_type
virtual void print_psd_declaration_string(const unsigned int particle_type, const ConditionalOStream &pcout)=0
Print the declaration string relative to the particle size distribution used.
virtual double find_max_diameter()=0
Return the maximum diameter for a certain distribution.
double mu_ln
Average diameter of the normal distribution.
double find_min_diameter() override
Find the minimum diameter a normal distribution.
double find_max_diameter() override
Find the maximum diameter of the normal distribution.
void print_psd_declaration_string(const unsigned int particle_type, const ConditionalOStream &pcout) override
Print the declaration string relative to the particle size distribution used.
virtual std::vector< double > particle_size_sampling(const unsigned int &number_of_particles) override
Carries out the size sampling of each particle inserted at an insertion time step for the normal dist...
const double sigma_ln
Standard deviation of the normal distribution.
LogNormalDistribution(const double &d_average, const double &d_standard_deviation, const unsigned int &prn_seed, double min_cutoff, double max_cutoff, const Parameters::Lagrangian::DistributionWeightingType &distribution_weighting_type)
The constructor stores the parameters necessary to define the normal distribution.
std::mt19937 gen
Random number generator for the diameter selection.
NormalDistribution(const double &d_average, const double &d_standard_deviation, const unsigned int &prn_seed, double min_cutoff, double max_cutoff, const Parameters::Lagrangian::DistributionWeightingType &distribution_weighting_type)
The constructor stores the parameters necessary to define the normal distribution.
double find_min_diameter() override
Find the minimum diameter a normal distribution.
double standard_deviation
Standard deviation of the normal distribution.
virtual std::vector< double > particle_size_sampling(const unsigned int &number_of_particles) override
Carries out the size sampling of each particle inserted at an insertion time step for the normal dist...
double find_max_diameter() override
Find the maximum diameter of the normal distribution.
std::mt19937 gen
Random number generator for the diameter selection.
double diameter_average
Average diameter of the normal distribution.
void print_psd_declaration_string(const unsigned int particle_type, const ConditionalOStream &pcout) override
Print the declaration string relative to the particle size distribution used.
UniformDistribution(const double &d_values)
The constructor stores the parameters necessary to define the uniform distribution.
const double diameter_value
The diameter value of the distribution.
double find_min_diameter() override
Find the minimum diameter of the uniform distribution.
virtual std::vector< double > particle_size_sampling(const unsigned int &number_of_particles) override
Carries out the size sampling of every particle inserted at an insertion time step for the uniform di...
double find_max_diameter() override
Find the maximum diameter of the uniform distribution.
void print_psd_declaration_string(const unsigned int particle_type, const ConditionalOStream &pcout) override
Print the declaration string relative to the particle size distribution used.
void setup_distributions(const LagrangianPhysicalProperties &lpp, std::vector< std::shared_ptr< Distribution > > &size_distribution_object_container, double &maximum_particle_diameter, const unsigned int mpi_process_id, const ConditionalOStream &pcout)
DistributionWeightingType
Weighting basis for particle size distributions.
Parameter structures for Lagrangian (DEM) particle simulations.
Physical properties of particles, walls, and interstitial gas for Lagrangian (DEM) simulations.
std::vector< ProbabilityFunctionType > custom_probability_function_type
Custom distribution function type (PDF or CDF).
std::vector< DistributionWeightingType > distribution_weighting_type
std::vector< std::vector< double > > particle_custom_probability
std::vector< double > particle_size_std
Size standard deviation of each particle type.
std::vector< double > diameter_min_cutoff
Minimum diameter cutoff for lognormal distribution.
std::vector< double > diameter_max_cutoff
Maximum diameter cutoff for lognormal distribution.
std::vector< std::vector< double > > particle_custom_diameter
List of diameters for the custom distribution for each particle type.
std::vector< double > particle_average_diameter
Average diameter of each particle type.
unsigned int particle_type_number
Number of particle types.
std::vector< unsigned int > seed_for_distributions
Random seed for the size distribution.