Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
distributions.cc
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#include <core/utilities.h>
5
6#include <dem/distributions.h>
7
8#include <deal.II/lac/lapack_full_matrix.h>
9
10#include <numbers>
11#include <numeric>
13 const DistributionWeightingType &distribution_weighting_type)
14 : weighting_type(distribution_weighting_type)
17{}
18
20 const double &d_average,
21 const double &d_standard_deviation,
22 const unsigned int &prn_seed,
23 const double min_cutoff,
24 const double max_cutoff,
25 const DistributionWeightingType &distribution_weighting_type)
26 : Distribution(distribution_weighting_type)
27 , gen(prn_seed)
28{
29 // We need the average and the standard deviation to be based on number to do
30 // our sampling.
32 {
33 diameter_average = d_average;
34 standard_deviation = d_standard_deviation;
35 }
36 // If the user specified the distribution as volume-based, we need to convert
37 // the average and standard deviation to be number-based. To do so, we need to
38 // solve a nonlinear system.
39 // https://mfix.netl.doe.gov/doc/mfix-exa/guide/latest/references/size_distributions.html#normal-distribution
40 else // this->weighting_type == DistributionWeightingType::volume_based
41 {
42 // Either there is an error with the Newton-Raphson solver or the problem
43 // is too stiff due to the order of the polynomial we are trying to solve
44 // for. Because of this, volume-based distribution is not supported for
45 // now. MFIX-exa uses a homotopy method to solve the system.
46
47 // Volume-based parameters
48 const double mv = d_average; // volume-based mean
49 const double mv2 = mv * mv; // volume-based mean squared
50
51 const double sv = d_standard_deviation; // volume-based standard deviation
52 const double sv2 = sv * sv; // volume-based standard deviation squared
53
54 // Matrix and RHS
55 LAPACKFullMatrix<double> system_matrix;
56 Vector<double> system_rhs;
57
58 double residual_l2_norm = 1.;
59 unsigned int iteration_counter = 0;
60
61 // Initial estimates
62 // mean based on number
63 double mu_n = d_average;
64 // standard deviation based on number
65 double sigma_n = d_standard_deviation;
66
67 while (residual_l2_norm > 1.e-12 && iteration_counter < 100)
68 {
69 system_matrix.reinit(2);
70 system_rhs.reinit(2);
71
72 const double mn = mu_n; // mean
73 const double mn2 = mn * mn; // mean squared
74 const double mn3 = mn2 * mn; // mean cubed
75 const double mn4 = mn2 * mn2; // mean ^4
76 const double mn5 = mn4 * mn; // mean ^5
77
78 const double sn = sigma_n; // standard deviation
79 const double sn2 = sn * sn; // standard deviation squared
80 const double sn3 = sn2 * sn; // standard deviation cubed
81 const double sn4 = sn2 * sn2; // standard deviation ^4
82
83 // Jacobian
84 const double dR1_sigma_n =
85 6. * (2. * (sn3 + sn * mn2) - mv * sn * mn);
86
87 const double dR1_mu_n =
88 12. * sn2 * mn + 4 * mn3 - 3. * mv * (sn2 + mn2);
89
90 const double dR2_sigma_n =
91 12. * sn3 * (5. * mn - 2. * mv) +
92 2. * sn * (10. * mn3 - 12. * mn2 * mv + 3. * mn * mv2) -
93 6. * sv2 * sn * mn;
94
95 const double dR2_mu_n = 15. * sn4 +
96 sn2 * (30. * mn2 - 24. * mn * mv + 3. * mv2) +
97 5. * mn4 + 3. * mn2 * mv2 - 8. * mn3 * mv -
98 sv2 * (3. * sn2 + 3. * mn2);
99
100 system_matrix.set(0, 0, dR1_sigma_n);
101 system_matrix.set(0, 1, dR1_mu_n);
102 system_matrix.set(1, 0, dR2_sigma_n);
103 system_matrix.set(1, 1, dR2_mu_n);
104
105 // Residual RHS
106 const double R1 =
107 3. * sn4 + 6. * sn2 * mn2 + mn4 - mv * (3. * sn2 * mn + mn3);
108
109 const double R2 = 3. * sn4 * (5. * mn - 2. * mv) +
110 sn2 * (10. * mn3 - 12. * mn2 * mv + 3. * mn * mv2) +
111 mn5 + mn3 * mv2 - 2. * mn4 * mv -
112 sv2 * (3. * sn2 * mn + mn3);
113
114 // Add the minus sign for Newton-Raphson
115 system_rhs[0] = -R1;
116 system_rhs[1] = -R2;
117
118 // Solve for the update
119 system_matrix.compute_lu_factorization();
120 system_matrix.solve(system_rhs);
121
122 // Apply the delta
123 sigma_n += system_rhs[0];
124 mu_n += system_rhs[1];
125
126 // While loop conditions
127 residual_l2_norm = system_rhs.l2_norm();
128 iteration_counter++;
129 }
130 AssertThrow(
131 iteration_counter < 100.,
132 ExcMessage("The numbered weighted mean and standard deviation of "
133 "the normal distribution has not been found from the volume "
134 "weighted values provided in the parameter file. To solve "
135 "this issue, define the distribution as number-based."));
136
137 diameter_average = mu_n;
138 standard_deviation = sigma_n;
139 }
140
141 if (min_cutoff < 0.)
142 {
143 // 2.5 -> approx 99% of all diameters are bigger
145 AssertThrow(this->dia_min_cutoff > 0.,
146 ExcMessage(
147 "The \"standard deviation\" parameter is too "
148 "high relative to the \"average diameter\" "
149 "parameter. This would results with frequent negative "
150 "diameter values. To fix this problem, please change "
151 "the value of those two parameters or define a "
152 "\"minimum diameter cutoff\" bigger than \"0.\""));
153 }
154 else
155 this->dia_min_cutoff = min_cutoff;
156
157 if (max_cutoff < 0.)
158 // 2.5 -> approx 99% of all diameters are smaller
160 else
161 this->dia_max_cutoff = max_cutoff;
162
164 ExcMessage("The \"minimum diameter cutoff\" parameter needs to"
165 " be smaller than the \"maximum diameter cutoff\"."));
166}
167
168std::vector<double>
170 const unsigned int &number_of_particles)
171{
172 std::vector<double> particle_sizes;
173 particle_sizes.reserve(number_of_particles);
174
175 std::normal_distribution<> distribution{diameter_average, standard_deviation};
176
177 unsigned int n_created_diameter = 0;
178 while (n_created_diameter < number_of_particles)
179 {
180 const double temp_diameter = distribution(gen);
181 if (temp_diameter > this->dia_min_cutoff &&
182 temp_diameter < this->dia_max_cutoff)
183 {
184 n_created_diameter++;
185 particle_sizes.push_back(temp_diameter);
186 }
187 }
188 return particle_sizes;
189}
190
191double
196
197double
202
203void
205 const unsigned int particle_type,
206 const ConditionalOStream &pcout)
207{
208 const double z_min =
210 const double z_max =
212
213 // Quantile
214 const double q_min = 0.5 * (1.0 + std::erf(z_min / std::numbers::sqrt2));
215 const double q_max = 0.5 * (1.0 + std::erf(z_max / std::numbers::sqrt2));
216
217 pcout << "The particle size distribution of particle type " << particle_type
218 << " is normal." << std::endl;
219
220 if (q_min > 0.25 || q_max < 0.75)
221 pcout
222 << "Warning: The minimal and maximal cutoffs of the distribution are at "
223 << q_min * 100. << " and " << q_max * 100. << " respectively."
224 << std::endl;
225 else
226 pcout << "The minimal and maximal cutoffs of the distribution are at "
227 << q_min * 100. << " and " << q_max * 100. << " respectively."
228 << std::endl;
229}
230
232 const double &d_average,
233 const double &d_standard_deviation,
234 const unsigned int &prn_seed,
235 double min_cutoff,
236 double max_cutoff,
238 &distribution_weighting_type)
239 : Distribution(distribution_weighting_type)
240 , sigma_ln(std::sqrt(std::log(
241 1. + Utilities::fixed_power<2>(d_standard_deviation / d_average))))
242 , gen(prn_seed)
243{
244 // We need the number-based average and standard deviation to do
245 // our sample. The standard deviation is always the same.
247 {
248 mu_ln = std::log(d_average) - 0.5 * Utilities::fixed_power<2>(sigma_ln);
249 }
250 // If the user specified the distribution as volume-based, we need to convert
251 // the average and standard deviation to be number-based.
252 // https://mfix.netl.doe.gov/doc/mfix-exa/guide/latest/references/size_distributions.html#log-normal-distribution
253 else // this->weighting_type == DistributionWeightingType::volume_based
254 {
255 mu_ln = std::log(d_average) - 3.5 * Utilities::fixed_power<2>(sigma_ln);
256 }
257
258 if (min_cutoff < 0.)
259 {
260 // approx 99% of all diameters are bigger
261 this->dia_min_cutoff = std::exp(mu_ln - 2.5 * sigma_ln);
262 AssertThrow(this->dia_min_cutoff > 0.,
263 ExcMessage(
264 "The \"standard deviation\" parameter is to "
265 "high relative to the \"average diameter\" "
266 "parameter. This would results with frequent negative "
267 "diameter values. To fix this problem, please change "
268 "the value of those two parameters or define a "
269 "\"minimum diameter cutoff\" bigger than \"0.\""));
270 }
271 else
272 this->dia_min_cutoff = min_cutoff;
273
274 if (max_cutoff < 0.)
275 // approx 99% of all diameters are bigger
276 this->dia_max_cutoff = std::exp(mu_ln + 2.5 * sigma_ln);
277 else
278 this->dia_max_cutoff = max_cutoff;
279
281 ExcMessage(
282 "The \"minimum diameter cutoff\" parameter need to be smaller "
283 "than the \"maximum diameter cutoff\"."));
284}
285
286
287std::vector<double>
289 const unsigned int &number_of_particles)
290{
291 std::vector<double> particle_sizes;
292 particle_sizes.reserve(number_of_particles);
293
294 std::lognormal_distribution<> distribution{mu_ln, sigma_ln};
295
296 unsigned int n_created_diameter = 0;
297 while (n_created_diameter < number_of_particles)
298 {
299 const double temp_diameter = distribution(gen);
300 if (temp_diameter > this->dia_min_cutoff &&
301 temp_diameter < this->dia_max_cutoff)
302 {
303 n_created_diameter++;
304 particle_sizes.push_back(temp_diameter);
305 }
306 }
307 return particle_sizes;
308}
309
310double
315
316double
321
322void
324 const unsigned int particle_type,
325 const ConditionalOStream &pcout)
326{
327 const double z_min = (std::log(this->dia_min_cutoff) - mu_ln) / sigma_ln;
328 const double z_max = (std::log(this->dia_max_cutoff) - mu_ln) / sigma_ln;
329
330 // Quantile
331 const double q_min = 0.5 * (1.0 + std::erf(z_min / std::numbers::sqrt2));
332 const double q_max = 0.5 * (1.0 + std::erf(z_max / std::numbers::sqrt2));
333
334 pcout << "The particle size distribution of particle type " << particle_type
335 << " is lognormal." << std::endl;
336
337 if (q_min > 0.25 || q_max < 0.75)
338 pcout
339 << "Warning: The minimal and maximal cutoffs of the distribution are at "
340 << q_min * 100. << " and " << q_max * 100. << " percentiles respectively."
341 << std::endl;
342 else
343 pcout << "The minimal and maximal cutoffs of the distribution are at "
344 << q_min * 100. << " and " << q_max * 100.
345 << " percentiles respectively." << std::endl;
346}
347
353
354std::vector<double>
356 const unsigned int &number_of_particles)
357{
358 std::vector<double> particle_sizes;
359 particle_sizes.reserve(number_of_particles);
360
361 for (unsigned int n = 0; n < number_of_particles; ++n)
362 particle_sizes.push_back(this->diameter_value);
363
364 return particle_sizes;
365}
366
367double
372
373double
378
379void
381 const unsigned int particle_type,
382 const ConditionalOStream &pcout)
383{
384 pcout << "The particle size distribution of particle type " << particle_type
385 << " is uniform." << std::endl;
386}
387
389 const std::vector<double> &d_list,
390 const std::vector<double> &d_probabilities,
391 const unsigned int &prn_seed,
392 const double min_cutoff,
393 const double max_cutoff,
395 &distribution_weighting_type,
397 const bool interpolate)
398 : Distribution(distribution_weighting_type)
399 , diameter_values(d_list)
400 , interpolate_diameter_values(interpolate)
401 , gen(prn_seed)
402 , function_type(function_type_in)
403{
404 // Diameter values are in ascending order.
405 // Min cutoff: The default value is -1. If the user did not change the default
406 // value, the minimum cutoff is set to the smallest diameter value, minus a
407 // small epsilon.
408 if (min_cutoff < 0.)
409 this->dia_min_cutoff = diameter_values[0] - 1e-8;
410 else
411 this->dia_min_cutoff = min_cutoff;
412
413 // Same thing for the max cutoff.
414 if (max_cutoff < 0.)
415 this->dia_max_cutoff = diameter_values.back() + 1e-8;
416 else
417 this->dia_max_cutoff = max_cutoff;
418
419 // We do all the checks here to simplify the readability
420 const unsigned int number_d_values = diameter_values.size();
421 number_based_cdf.resize(number_d_values, 0.);
422
423 AssertThrow(number_d_values == d_probabilities.size(),
424 ExcMessage("The number of diameter values and "
425 "probability values need to be the same."));
426
427 AssertThrow(std::ranges::is_sorted(diameter_values),
428 ExcMessage("The \"custom distribution diameters values\" "
429 "parameter is not defined properly. Make sure to "
430 "define the diameter values in ascending order."));
431
433 {
434 AssertThrow(
435 std::ranges::is_sorted(d_probabilities) &&
436 d_probabilities.back() <= 1.0 + 1e-5,
437 ExcMessage("When using a custom distribution defined as a "
438 "CDF, the probability values need to be defined in"
439 " ascending order and the last probability value needs to be"
440 " equal to 1."));
442 {
443 AssertThrow(d_probabilities[0] == 0.,
444 ExcMessage("When using a custom distribution defined"
445 " as a CDF with interpolation, the first "
446 "probability value needs to be equal to 0."));
447 }
448 }
450 {
452 {
453 AssertThrow(d_probabilities[0] == 0.,
454 ExcMessage("When using the custom distribution "
455 "defined as a PDF with interpolation, the "
456 "first probability value needs to be equal"
457 " to 0."));
458
459 AssertThrow(d_probabilities.back() == 0.,
460 ExcMessage("When using the custom distribution defined"
461 " as a PDF with interpolation, the last "
462 "probability value needs to be equal to 0."));
463 }
464 else
465 {
466 AssertThrow(std::abs(std::accumulate(d_probabilities.begin(),
467 d_probabilities.end(),
468 0.) -
469 1.) <= 1e-5,
470 ExcMessage("When using the custom distribution "
471 "defined as a PDF without interpolation, "
472 "probability values are used as fraction, "
473 "thus the sum of every probability value "
474 "should be equal to 1."));
475 }
476 }
477
478 // We need to convert the input probability values (d_probabilities)
479 // to a number-based CDF to sample diameter values correctly.
481 {
483 {
484 // If the input probability function is already given as a
485 // number-based CDF, nothing needs to be done.
486 number_based_cdf = d_probabilities;
487 }
489 {
491 {
492 number_based_cdf[0] = 0.;
493 // Compute the cumulative distribution function (CDF) from the
494 // sampled PDF using the trapezoidal rule:
495 //
496 // CDF(d_i) = ∫_{d_0}^{d_i} PDF(d) dd
497 // ≈ Σ_{k=1}^{i}
498 // (PDF(d_{k-1}) + PDF(d_k))/2 · (d_k - d_{k-1})
499 //
500 // The resulting cumulative values are then normalized so that
501 // CDF(d_last) = 1.
502 for (unsigned int i = 1; i < number_d_values; ++i)
504 number_based_cdf[i - 1] +
505 0.5 * (d_probabilities[i - 1] + d_probabilities[i]) *
506 (diameter_values[i] - diameter_values[i - 1]);
507
508 // We normalize the new CDF.
509 for (unsigned int i = 0; i < number_d_values; ++i)
511 }
512 else // No interpolation
513 {
514 // d_probabilities represents the fractions of every
515 // diameter value over the total number. (n_d/N_tot)
516 number_based_cdf[0] = d_probabilities[0];
517 for (unsigned int i = 1; i < number_d_values; ++i)
519 number_based_cdf[i - 1] + d_probabilities[i];
520
521 for (unsigned int i = 0; i < number_d_values; ++i)
523 }
524 }
525 }
527 {
529 {
531 {
532 // Normalize the input volume PDF so that ∫ fv dd = 1
533 // We use the trapezoidal method to do the integral.
534 double fv_integral = 0.0;
535 for (unsigned int i = 0; i < number_d_values - 1; ++i)
536 fv_integral += 0.5 *
537 (d_probabilities[i] + d_probabilities[i + 1]) *
538 (diameter_values[i + 1] - diameter_values[i]);
539
540 // Stores the differential probability
541 fv.resize(number_d_values);
542 for (unsigned int i = 0; i < number_d_values; ++i)
543 fv[i] = d_probabilities[i] / fv_integral;
544
545 // Use the exact integral of fv(d)/d³ over each segment/bin.
546 // Between two diameter samples, the normalized volume PDF is
547 // assumed to vary linearly:
548 //
549 // fv(d) = a_i + b_i d, d ∈ [d_low, d_high]
550 //
551 // The corresponding number-based PDF is proportional to fv(d)/d³.
552 // Since fv(d) is linear within each interval, the integral over
553 // the bin can be evaluated analytically instead of using
554 // numerical quadrature.
555 std::vector<double> segment_integral(number_d_values - 1, 0.0);
556 total_integral = 0.0;
557
558 for (unsigned int i = 0; i < number_d_values - 1; ++i)
559 {
560 // Compute the coefficients of the linear interpolation
561 // fv(d) = a_i + b_i d over the current diameter interval.
562 // Could you add some comments to describe this part?
563 const double d_low = diameter_values[i];
564 const double d_high = diameter_values[i + 1];
565
566 const double b_i = (fv[i + 1] - fv[i]) / (d_high - d_low);
567 const double a_i = fv[i] - b_i * d_low;
568
569 // Antiderivative of (a_i + b_i d)/d³:
570 //
571 // ∫ (a_i + b_i d)/d³ dd
572 // = -a_i/(2d²) - b_i/d.
573 //
574 // Evaluating this primitive at the interval endpoints gives
575 // the exact contribution of the current bin to the
576 // unnormalized number-based CDF.
577 const double F_high =
578 -a_i / (2.0 * d_high * d_high) - b_i / d_high;
579 const double F_low =
580 -a_i / (2.0 * d_low * d_low) - b_i / d_low;
581
582 segment_integral[i] = F_high - F_low;
583 total_integral += segment_integral[i];
584 }
585
586 // Build the normalized number-based CDF by accumulating the exact
587 // integral of fv(d)/d³ over each interval.
588 number_based_cdf[0] = 0.0;
589 for (unsigned int i = 1; i < number_d_values; ++i)
591 segment_integral[i - 1] / total_integral;
592
593 number_based_cdf.back() = 1.0; // safety clamp
594 }
595 else // (function_type == ProbabilityFunctionType::CDF)
596 {
597 // Relative number fraction (dfn)
598 std::vector<double> dfn(number_d_values - 1, 0.0);
599 double number_fraction_sum = 0.0;
600
601 // Calculate the number-fractions for each bin
602 // We iterate through (N-1) bins.
603 for (unsigned int i = 0; i < number_d_values - 1; ++i)
604 {
605 // Boundaries of the current size bin
606 const double d_low = diameter_values[i];
607 const double d_high = diameter_values[i + 1];
608
609 // The volume fraction (dfv) is the area under the PDF or the
610 // difference in CDF between consecutive diameter values.
611 // The difference between two consecutive nodes gives
612 // the volume fraction contained in this bin.
613 double this_bin_volume_fraction =
614 d_probabilities[i + 1] - d_probabilities[i];
615
616 // Number (N) scales with Volume (V) by N = V / (pi/6
617 // * D^3). Since D varies across the bin, we must use the
618 // average of (1/D^3) of this bin.
619 //
620 // Assumption: The volume is distributed LINEARLY across this
621 // diameter bin. Under this assumption, the 'Weight' is the
622 // Mean Value of the function 1/D^3:
623 // Weight = [1 / (d_high - d_low)] * Integral from d_low to
624 // d_high of (1/x^3) dx
625 //
626 // Solving the integral:
627 // 1. Integral of x^-3 dx = -1/(2x^2).
628 // 2. Evaluate the integral: [1/(2*d_low^2) - 1/(2*d_high^2)]
629 // 3. Simplify the evaluated integral:
630 // (d_high^2 - d_low^2) / [2 * d_low^2 * d_high^2 ]
631 // 4. Using (a^2 - b^2) = (a-b)(a+b), (d_high^2 - d_low^2)
632 // becomes (d_high - d_low)(d_high + d_low).
633 // 5. Weight = [1 / (d_high - d_low)] * Integral, thus the
634 // (d_high - d_low) term is cancelled.
635 //
636 // Final Weight Formula: (d_low + d_high) / (2 * d_low^2 *
637 // d_high^2)
638 const double weight =
639 (d_low + d_high) / (2.0 * std::pow(d_low * d_high, 2));
640
641 // Convert the volume fraction to a relative number fraction
642 // (dfn). Note: This value is not yet normalized; it's a
643 // relative particle count.
644 dfn[i] = this_bin_volume_fraction * weight;
645
646 // Sum the relative counts. This sum will be used as the
647 // denominator to normalize the final number-based CDF so it
648 // ends at 1.0.
649 number_fraction_sum += dfn[i];
650 }
651
652 // Reconstruct the CDF from the Number fractions while making sure
653 // to normalize every value.
654 number_based_cdf[0] = 0.0;
655 for (unsigned int i = 1; i < number_d_values - 1; ++i)
657 number_based_cdf[i - 1] + (dfn[i - 1] / number_fraction_sum);
658
659 number_based_cdf.back() = 1.;
660 }
661 }
662 else // No interpolation
663 {
664 // Volume fraction of every diameter value.
665 std::vector<double> volume_fraction(number_d_values, 0.);
666
667 // If the user specifies a volume-based CDF, we convert it to a
668 // volume-based PDF first.
670 {
671 volume_fraction[0] = d_probabilities[0];
672 for (unsigned int i = 1; i < number_d_values; ++i)
673 volume_fraction[i] =
674 d_probabilities[i] - d_probabilities[i - 1];
675 }
676
677 // If the input function is already a PDF, we simply copy it
679 volume_fraction = d_probabilities;
680
681 std::vector<double> number_based_pdf(number_d_values);
682 double n_tot = 0.;
683 for (unsigned int i = 0; i < number_d_values; ++i)
684 {
685 number_based_pdf[i] =
686 volume_fraction[i] /
687 Utilities::fixed_power<3>(diameter_values[i]);
688
689 n_tot += number_based_pdf[i];
690 }
691
692 // Normalized
693 number_based_cdf[0] = number_based_pdf[0] / n_tot;
694 for (unsigned int i = 1; i < number_d_values; ++i)
696 number_based_cdf[i - 1] + number_based_pdf[i] / n_tot;
697 }
698 }
699}
700
701std::vector<double>
703 const unsigned int &number_of_particles)
704{
705 std::vector<double> particle_sizes;
706 particle_sizes.reserve(number_of_particles);
707 unsigned int n_created_diameter = 0;
708
709 // We sample a random number U between [0, 1]
710 std::uniform_real_distribution<> dis(0.0, 1 - 1e-12);
711
713 {
714 while (n_created_diameter < number_of_particles)
715 {
716 // Number between 0. and 1.
717 const double u_global = dis(gen);
718
719 // Find the first element in the CDF strictly greater than our
720 // random number u_global. 'it' will point to the upper bound of
721 // the bin (node i+1).
722 auto it = std::ranges::upper_bound(number_based_cdf, u_global);
723
724 const unsigned int index_high =
725 static_cast<unsigned int>(it - number_based_cdf.begin());
726 const unsigned int index_low = index_high - 1;
727
728 const double d_low = diameter_values[index_low];
729 const double d_high = diameter_values[index_high];
730
731 const double cdf_low = number_based_cdf[index_low];
732 const double cdf_high = number_based_cdf[index_high];
733 const double delta_cdf = cdf_high - cdf_low;
734
735 // Between 0 and 1 relative to the current bin
736 const double u_local = (u_global - cdf_low) / delta_cdf;
737
738 double sampled_diameter;
739
742 {
743 // The volume-based PDF is assumed to be piecewise linear:
744 //
745 // fv(d) = a_i + b_i d
746 //
747 // The number-based CDF used for sampling was obtained by
748 // integrating fv(d)/d³ exactly. To sample within the selected
749 // bin, invert the antiderivative
750 //
751 // F(d) = -a_i/(2d²) - b_i/d,
752 //
753 // which results in a quadratic equation for d.
754 const double b_i =
755 (fv[index_high] - fv[index_low]) / (d_high - d_low);
756 const double a_i = fv[index_low] - b_i * d_low;
757
758 auto antideriv = [a_i, b_i](const double d) {
759 return -a_i / (2.0 * d * d) - b_i / d;
760 };
761
762 const double F_low = antideriv(d_low);
763 // Solve for d such that
764 // (u_global - cdf_low) * total_integral + F_low = F(d),
765 // or equivalently
766 // C = -a_i/(2d²) - b_i/d.
767 // Rearranging gives
768 // 2*C*d² + 2*b_i*d + a_i = 0.
769 const double C = (u_global - cdf_low) * total_integral + F_low;
770 const double A = 2.0 * C;
771 const double B = 2.0 * b_i;
772
773 constexpr double tol = 1e-12;
774
775 if (std::abs(A) < tol)
776 {
777 // Degenerate case: the quadratic reduces to the linear
778 // equation
779 //
780 // 2*b_i*d + a_i = 0.
781 AssertThrow(
782 std::abs(B) > tol,
783 ExcMessage(
784 "Degenerate analytical CDF inversion encountered."));
785
786 sampled_diameter = -a_i / B;
787 sampled_diameter =
788 std::clamp(sampled_diameter, d_low, d_high);
789 }
790 else
791 {
792 const double discriminant =
793 std::max(B * B - 4.0 * A * a_i, 0.0);
794 const double sqrt_disc = std::sqrt(discriminant);
795
796 const double root1 = (-B + sqrt_disc) / (2.0 * A);
797 const double root2 = (-B - sqrt_disc) / (2.0 * A);
798
799 if (root1 >= d_low - tol && root1 <= d_high + tol)
800 sampled_diameter = std::clamp(root1, d_low, d_high);
801 else if (root2 >= d_low - tol && root2 <= d_high + tol)
802 sampled_diameter = std::clamp(root2, d_low, d_high);
803 else
804 {
805 AssertThrow(false,
806 ExcMessage(
807 "Failed to invert the analytical CDF "
808 "within the selected diameter interval."));
809 }
810 }
811 }
812 else
813 {
814 const double inv_d_low2 = 1.0 / (d_low * d_low);
815 const double inv_d_high2 = 1.0 / (d_high * d_high);
816
817 sampled_diameter =
818 1.0 /
819 std::sqrt(inv_d_low2 - u_local * (inv_d_low2 - inv_d_high2));
820 }
821
822
823 // If the sampled diameter falls outside the min-max values,
824 // we resample the distribution.
825 if (sampled_diameter > this->dia_min_cutoff &&
826 sampled_diameter < this->dia_max_cutoff)
827 {
828 n_created_diameter++;
829 particle_sizes.push_back(sampled_diameter);
830 }
831 }
832 }
833 else // No interpolation
834 {
835 while (n_created_diameter < number_of_particles)
836 {
837 // Number between 0. and 1.
838 const double u = dis(gen);
839
840 // Find the first element in the CDF strictly greater than our
841 // random number u_global. 'it' will point to the upper bound of
842 // the bin (node i+1).
843 auto it = std::ranges::upper_bound(number_based_cdf, u);
844
845 const unsigned int index_high =
846 static_cast<unsigned int>(it - number_based_cdf.begin());
847
848 // Discrete Sampling
849 // We simply pick the diameter corresponding to the upper bound
850 // node and check if it is within the cutoffs.
851 const double sampled_diameter = diameter_values[index_high];
852 if (sampled_diameter > this->dia_min_cutoff &&
853 sampled_diameter < this->dia_max_cutoff)
854 {
855 n_created_diameter++;
856 particle_sizes.push_back(sampled_diameter);
857 }
858 }
859 }
860 return particle_sizes;
861}
862
863double
868
869double
874
875void
877 const unsigned int particle_type,
878 const ConditionalOStream &pcout)
879{
880 pcout << "The particle size distribution of particle type " << particle_type
881 << " is custom." << std::endl;
882}
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)
double dia_min_cutoff
Minimal cutoff diameters values.
double dia_max_cutoff
Maximum cutoff diameters values.
const Parameters::Lagrangian::DistributionWeightingType weighting_type
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.
DistributionWeightingType
Weighting basis for particle size distributions.
@ volume_based
Volume-based distribution weighting.
@ number_based
Number-based distribution weighting.