Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
effective_medium_model.cc
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
8
9#include <algorithm>
10#include <cmath>
11
13 const Parameters::PhysicalProperties &physical_properties,
14 const unsigned int material_interaction_id,
15 const EffectiveMediumProperty &property,
18{
19 AssertThrow(material_interaction_id <
20 physical_properties.number_of_material_interactions,
21 ExcMessage("The material interaction of the effective medium "
22 "model does not exist."));
23
24 const Parameters::MaterialInteractions &interaction =
25 physical_properties.material_interactions[material_interaction_id];
26
27 // The material interaction gives the materials of the two phases of the
28 // mixture: the fluid and the dispersed phase for a fluid-dispersed
29 // phase interaction.
30 if (interaction.material_interaction_type ==
33 {
34 const auto &[fluid_id, dispersed_phase_id] =
35 interaction
37 AssertThrow(fluid_id < physical_properties.number_of_fluids &&
38 dispersed_phase_id <
39 physical_properties.number_of_unresolved_dispersed_phases,
40 ExcMessage("The fluid or the unresolved dispersed phase of "
41 "the fluid-dispersed phase interaction do not "
42 "exist."));
43
45 create_phase_models(physical_properties.fluids[fluid_id], property);
47 physical_properties.unresolved_dispersed_phases[dispersed_phase_id],
48 property);
49 }
50 else
51 AssertThrow(false,
52 ExcMessage("Effective medium models are only available for "
53 "fluid-dispersed phase interactions."));
54
55 // The property of phase 1 is used by every mixing law. The mixing laws that
56 // also use the property of phase 2 add the dependencies of its models in
57 // their constructor.
59}
60
61std::shared_ptr<EffectiveMediumModel>
63 const Parameters::PhysicalProperties &physical_properties,
64 const unsigned int material_interaction_id,
65 const EffectiveMediumProperty &property,
67{
68 const Parameters::MaterialInteractions &interaction =
69 physical_properties.material_interactions.at(material_interaction_id);
70
72 get_model_type(interaction, property);
73
74 if (model_type ==
76 return std::make_shared<NoEffectiveMediumModel>(physical_properties,
77 material_interaction_id,
78 property,
80 else if (model_type == Parameters::MaterialInteractions::
81 EffectiveMediumModelType::bruggeman)
82 return std::make_shared<BruggemanEffectiveMediumModel>(
83 physical_properties,
84 material_interaction_id,
85 property,
87 else
88 AssertThrow(false, InvalidEffectiveMediumModel());
89}
90
91double
92EffectiveMediumModel::value(const std::map<field, double> &field_values)
93{
94 const std::complex<double> phase_1_property =
95 phase_value(phase_1_models, field_values);
96 const std::complex<double> phase_2_property =
97 phase_value(phase_2_models, field_values);
98
100 this->apply_mixing_law(field_values, phase_1_property, phase_2_property));
101}
102
103void
105 const std::map<field, std::vector<double>> &field_vectors,
106 std::vector<double> &property_vector)
107{
108 const unsigned int n_points = property_vector.size();
109
110 // Local containers: the model is shared between threads, so it must not
111 // store intermediate results.
112 std::vector<std::complex<double>> phase_1_property(n_points);
113 std::vector<std::complex<double>> phase_2_property(n_points);
114 std::vector<std::complex<double>> mixture_property(n_points);
115
116 phase_vector_value(phase_1_models, field_vectors, phase_1_property);
117 phase_vector_value(phase_2_models, field_vectors, phase_2_property);
118
119 this->vector_apply_mixing_law(field_vectors,
120 phase_1_property,
121 phase_2_property,
122 mixture_property);
123
124 for (unsigned int i = 0; i < n_points; ++i)
125 property_vector[i] = get_complex_component(mixture_property[i]);
126}
127
128double
129EffectiveMediumModel::jacobian(const std::map<field, double> &field_values,
130 const field id)
131{
132 return this->numerical_jacobian(field_values, id);
133}
134
135void
137 const std::map<field, std::vector<double>> &field_vectors,
138 const field id,
139 std::vector<double> &jacobian_vector)
140{
141 this->vector_numerical_jacobian(field_vectors, id, jacobian_vector);
142}
143
144void
146{
147 // The mixture property depends on a field if at least one model of the phase
148 // depends on it. The use of or (||) ensures that a field on which the
149 // mixture property already depends is not erased.
150 for (auto &[field_id, mixture_depends_on_field] : this->model_depends_on)
151 {
152 for (const auto &model : phase_models.real_part_terms)
153 mixture_depends_on_field =
154 mixture_depends_on_field || model->depends_on(field_id);
155 for (const auto &model : phase_models.imaginary_part_terms)
156 mixture_depends_on_field =
157 mixture_depends_on_field || model->depends_on(field_id);
158 }
159}
160
163 const Parameters::Material &material_properties,
164 const EffectiveMediumProperty property)
165{
166 PhaseModels phase_models;
167
168 switch (property)
169 {
171 // Complex permittivity: eps' + i (eps'' + sigma)
172 phase_models.real_part_terms.push_back(
173 ElectricPermittivityModel::model_cast_real(material_properties));
174 phase_models.imaginary_part_terms.push_back(
175 ElectricPermittivityModel::model_cast_imag(material_properties));
176 phase_models.imaginary_part_terms.push_back(
177 ElectricConductivityModel::model_cast(material_properties));
178 break;
180 // Complex permeability: mu' + i mu''
181 phase_models.real_part_terms.push_back(
182 MagneticPermeabilityModel::model_cast_real(material_properties));
183 phase_models.imaginary_part_terms.push_back(
184 MagneticPermeabilityModel::model_cast_imag(material_properties));
185 break;
186 }
187
188 return phase_models;
189}
190
191std::complex<double>
193 const PhaseModels &phase_models,
194 const std::map<field, double> &field_values) const
195{
196 double real_part = 0.0;
197 for (const auto &model : phase_models.real_part_terms)
198 real_part += model->value(field_values);
199
200 double imaginary_part = 0.0;
201 for (const auto &model : phase_models.imaginary_part_terms)
202 imaginary_part += model->value(field_values);
203
204 return {real_part, imaginary_part};
205}
206
207void
209 const PhaseModels &phase_models,
210 const std::map<field, std::vector<double>> &field_vectors,
211 std::vector<std::complex<double>> &phase_property) const
212{
213 const unsigned int n_points = phase_property.size();
214 std::vector<double> real_part(n_points, 0.0);
215 std::vector<double> imaginary_part(n_points, 0.0);
216 std::vector<double> term_values(n_points);
217
218 for (const auto &model : phase_models.real_part_terms)
219 {
220 model->vector_value(field_vectors, term_values);
221 for (unsigned int i = 0; i < n_points; ++i)
222 real_part[i] += term_values[i];
223 }
224
225 for (const auto &model : phase_models.imaginary_part_terms)
226 {
227 model->vector_value(field_vectors, term_values);
228 for (unsigned int i = 0; i < n_points; ++i)
229 imaginary_part[i] += term_values[i];
230 }
231
232 for (unsigned int i = 0; i < n_points; ++i)
233 phase_property[i] = {real_part[i], imaginary_part[i]};
234}
235
236double
238 const std::complex<double> mixture_property) const
239{
241 std::real(mixture_property) :
242 std::imag(mixture_property);
243}
244
247 const Parameters::MaterialInteractions &interaction,
248 const EffectiveMediumProperty property)
249{
250 switch (property)
251 {
256 }
257
258 AssertThrow(false,
259 ExcMessage("Invalid effective medium property. The choices are "
260 "<electric_permittivity|magnetic_permeability>"));
262}
263
265 const Parameters::PhysicalProperties &physical_properties,
266 const unsigned int material_interaction_id,
267 const EffectiveMediumProperty property,
269 : EffectiveMediumModel(physical_properties,
270 material_interaction_id,
271 property,
273{
274 // The Bruggeman mixing law depends on the property of phase 2 and on the
275 // void fraction
278}
279
280std::complex<double>
282 const std::map<field, double> &field_values,
283 const std::complex<double> phase_1_property,
284 const std::complex<double> phase_2_property) const
285{
286 Assert(field_values.contains(field::void_fraction),
287 PhysicialPropertyModelFieldUndefined("BruggemanEffectiveMediumModel",
288 "void_fraction"));
289
290 return bruggeman(field_values.at(field::void_fraction),
291 phase_1_property,
292 phase_2_property);
293}
294
295void
297 const std::map<field, std::vector<double>> &field_vectors,
298 const std::vector<std::complex<double>> &phase_1_property,
299 const std::vector<std::complex<double>> &phase_2_property,
300 std::vector<std::complex<double>> &mixture_property) const
301{
302 Assert(field_vectors.contains(field::void_fraction),
303 PhysicialPropertyModelFieldUndefined("BruggemanEffectiveMediumModel",
304 "void_fraction"));
305
306 const std::vector<double> &void_fraction =
307 field_vectors.at(field::void_fraction);
308 AssertDimension(void_fraction.size(), mixture_property.size());
309 AssertDimension(phase_1_property.size(), mixture_property.size());
310 AssertDimension(phase_2_property.size(), mixture_property.size());
311
312 for (unsigned int i = 0; i < mixture_property.size(); ++i)
313 mixture_property[i] =
314 bruggeman(void_fraction[i], phase_1_property[i], phase_2_property[i]);
315}
316
317std::complex<double>
319 const double void_fraction,
320 const std::complex<double> phase_1_property,
321 const std::complex<double> phase_2_property)
322{
323 Assert(std::real(phase_1_property) > 0.0 &&
324 std::imag(phase_1_property) >= 0.0,
325 InvalidPhysicalPropertyComplex(phase_1_property));
326 Assert(std::real(phase_2_property) > 0.0 &&
327 std::imag(phase_2_property) >= 0.0,
328 InvalidPhysicalPropertyComplex(phase_2_property));
329
330 // We clamp the void fraction to be between 0 and 1, since the Bruggeman model
331 // is only valid for void fractions in this range and slightly out of range
332 // values can occur from the projected void fraction due to numerical errors.
333 const double phase_1_fraction = std::clamp(void_fraction, 0., 1.);
334 const double phase_2_fraction = 1.0 - phase_1_fraction;
335 const std::complex<double> factor =
336 (3.0 * phase_2_fraction - 1.0) * phase_2_property +
337 (3.0 * phase_1_fraction - 1.0) * phase_1_property;
338 const std::complex<double> discriminant_root =
339 std::sqrt(factor * factor + 8.0 * phase_2_property * phase_1_property);
340
341 // The std::sqrt function gives one of the branches of the complex plane. To
342 // ensure that the effective property is in the first quadrant of
343 // the complex plane, we compute both roots and select the proper one.
344 const std::complex<double> root_1 = 0.25 * (factor + discriminant_root);
345 const std::complex<double> root_2 = 0.25 * (factor - discriminant_root);
346
347 // The roots are computed with a round-off error of the order of the machine
348 // precision times the magnitude of the phase properties. When the exact
349 // effective property is real (e.g., a lossless fluid with a void fraction of
350 // one), the computed imaginary part of the admissible root can therefore be
351 // slightly negative. Such a root is accepted and its imaginary part is set to
352 // zero.
353 constexpr double root_selection_relative_tolerance = 1e-12;
354 const double imaginary_part_tolerance =
355 root_selection_relative_tolerance *
356 (std::abs(phase_1_property) + std::abs(phase_2_property));
357
358 if (std::real(root_1) > 0.0 && std::imag(root_1) >= -imaginary_part_tolerance)
359 return {std::real(root_1), std::max(std::imag(root_1), 0.0)};
360 if (std::real(root_2) > 0.0 && std::imag(root_2) >= -imaginary_part_tolerance)
361 return {std::real(root_2), std::max(std::imag(root_2), 0.0)};
362
363 Assert(
364 false,
365 ExcMessage(
366 "The computed effective property is not in the first quadrant of the complex plane."));
367 return {0.0, 0.0};
368}
static std::complex< double > bruggeman(const double void_fraction, const std::complex< double > phase_1_property, const std::complex< double > phase_2_property)
Bruggeman formula for a given void fraction.
void vector_apply_mixing_law(const std::map< field, std::vector< double > > &field_vectors, const std::vector< std::complex< double > > &phase_1_property, const std::vector< std::complex< double > > &phase_2_property, std::vector< std::complex< double > > &mixture_property) const override
Calculates the mixture property with the Bruggeman effective medium approximation at multiple points.
BruggemanEffectiveMediumModel(const Parameters::PhysicalProperties &physical_properties, const unsigned int material_interaction_id, const EffectiveMediumProperty property, const ComplexComponent complex_component)
Constructor. Adds the fields on which the models of phase 2 depend and the void fraction to the field...
std::complex< double > apply_mixing_law(const std::map< field, double > &field_values, const std::complex< double > phase_1_property, const std::complex< double > phase_2_property) const override
Calculates the mixture property with the Bruggeman effective medium approximation.
virtual std::complex< double > apply_mixing_law(const std::map< field, double > &field_values, const std::complex< double > phase_1_property, const std::complex< double > phase_2_property) const =0
Mixing law of the effective medium model.
const ComplexComponent complex_component
Part of the mixture property returned by the model.
double get_complex_component(const std::complex< double > mixture_property) const
Returns the selected part (real or imaginary) of a mixture property.
void add_phase_dependencies(const PhaseModels &phase_models)
Adds the fields on which the models of a phase depend to the fields on which the mixture property dep...
static Parameters::MaterialInteractions::EffectiveMediumModelType get_model_type(const Parameters::MaterialInteractions &interaction, const EffectiveMediumProperty property)
Returns the effective medium model chosen in a material interaction for a mixture property.
void vector_jacobian(const std::map< field, std::vector< double > > &field_vectors, const field id, std::vector< double > &jacobian_vector) override
Calculates the derivative of the selected part of the mixture property with respect to a field at mul...
double jacobian(const std::map< field, double > &field_values, const field id) override
Calculates the derivative of the selected part of the mixture property with respect to a field using ...
void vector_value(const std::map< field, std::vector< double > > &field_vectors, std::vector< double > &property_vector) override
Calculates the selected part of the mixture property at multiple points.
std::complex< double > phase_value(const PhaseModels &phase_models, const std::map< field, double > &field_values) const
Calculates the complex property of a phase from its models.
static std::shared_ptr< EffectiveMediumModel > model_cast(const Parameters::PhysicalProperties &physical_properties, const unsigned int material_interaction_id, const EffectiveMediumProperty &property, const ComplexComponent &complex_component)
Creates the model of a mixture property, with the mixing law given by the material interaction.
virtual void vector_apply_mixing_law(const std::map< field, std::vector< double > > &field_vectors, const std::vector< std::complex< double > > &phase_1_property, const std::vector< std::complex< double > > &phase_2_property, std::vector< std::complex< double > > &mixture_property) const =0
Mixing law of the effective medium model at multiple points.
void phase_vector_value(const PhaseModels &phase_models, const std::map< field, std::vector< double > > &field_vectors, std::vector< std::complex< double > > &phase_property) const
Calculates the complex property of a phase at multiple points from its models.
PhaseModels phase_2_models
Models of the property of phase 2.
PhaseModels phase_1_models
Models of the property of phase 1.
static PhaseModels create_phase_models(const Parameters::Material &material_properties, const EffectiveMediumProperty property)
Creates the models needed to calculate a property of the material of a phase.
double value(const std::map< field, double > &field_values) override
Calculates the selected part of the mixture property.
EffectiveMediumModel(const Parameters::PhysicalProperties &physical_properties, const unsigned int material_interaction_id, const EffectiveMediumProperty &property, const ComplexComponent &complex_component)
Constructor. Gets the materials of the two phases from the material interaction, creates the models o...
static std::shared_ptr< ElectricConductivityModel > model_cast(const Parameters::Material &material_properties)
Instantiates and returns a pointer to an ElectricConductivityModel object by casting it to the proper...
static std::shared_ptr< ElectricPermittivityModel > model_cast_imag(const Parameters::Material &material_properties)
Instantiates and returns a pointer to a ElectricPermittivityModel object by casting it to the proper ...
static std::shared_ptr< ElectricPermittivityModel > model_cast_real(const Parameters::Material &material_properties)
Instantiates and returns a pointer to a ElectricPermittivityModel object by casting it to the proper ...
static std::shared_ptr< MagneticPermeabilityModel > model_cast_imag(const Parameters::Material &material_properties)
Instantiates and returns a pointer to a MagneticPermeabilityModel object by casting it to the proper ...
static std::shared_ptr< MagneticPermeabilityModel > model_cast_real(const Parameters::Material &material_properties)
Instantiates and returns a pointer to a MagneticPermeabilityModel object by casting it to the proper ...
MaterialInteractions - Class that defines physical properties due to interactions between two differe...
Definition parameters.h:757
enum Parameters::MaterialInteractions::MaterialInteractionsType material_interaction_type
EffectiveMediumModelType magnetic_permeability_effective_medium_model
Definition parameters.h:798
EffectiveMediumModelType electric_permittivity_effective_medium_model
Definition parameters.h:796
std::pair< std::pair< unsigned int, unsigned int >, unsigned int > fluid_dispersed_phase_interaction_with_material_interaction_id
Definition parameters.h:806
Material - Class that defines the physical property of a material. Generally a material will be a flu...
Definition parameters.h:594
PhysicalProperties - Define the possible physical properties. All continuum equations share the same ...
Definition parameters.h:839
std::vector< Material > unresolved_dispersed_phases
Definition parameters.h:855
unsigned int number_of_unresolved_dispersed_phases
Definition parameters.h:856
std::vector< Material > fluids
Definition parameters.h:844
unsigned int number_of_material_interactions
Definition parameters.h:862
std::vector< MaterialInteractions > material_interactions
Definition parameters.h:861
void vector_numerical_jacobian(const std::map< field, std::vector< double > > &field_vectors, const field id, std::vector< double > &jacobian_vector)
vector_numerical_jacobian Calculates the vector of jacobian through forward finite difference (Euler)...
double numerical_jacobian(const std::map< field, double > &field_values, const field id)
numerical_jacobian Calculates the jacobian through a forward finite difference (Euler) approximation....
ComplexComponent
Part of a complex physical property returned by a model. A PhysicalPropertyModel can only return a si...
std::map< field, bool > model_depends_on
EffectiveMediumProperty
Physical property of a mixture that can be calculated with an effective medium model.
@ void_fraction
Models of the property of a phase. The effective property of the phase can be complex and builded fro...
std::vector< std::shared_ptr< PhysicalPropertyModel > > real_part_terms
Models whose values are summed to give the real part of the property.
std::vector< std::shared_ptr< PhysicalPropertyModel > > imaginary_part_terms