Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
effective_medium_model.h
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
4#ifndef lethe_effective_medium_model_h
5#define lethe_effective_medium_model_h
6
7#include <core/parameters.h>
9
10#include <deal.II/base/exceptions.h>
11
12#include <complex>
13#include <cstdint>
14#include <map>
15#include <memory>
16#include <vector>
17
19 InvalidPhysicalPropertyComplex,
20 std::complex<double>,
21 << "Invalid physical property value: " << arg1
22 << ". The physical property values must be in the first quadrant of the complex plane (positive real part and non-negative imaginary part).");
23
25 InvalidEffectiveMediumModel,
26 "The effective medium model is not valid. The available models are 'none' and 'bruggeman'.");
27
28/**
29 * @brief Physical property of a mixture that can be calculated with an
30 * effective medium model.
31 */
37
38/**
39 * @brief Effective medium model for the calculation of a physical property of a mixture
40 * of two phases. The mixture and its two phases are defined by a material
41 * interaction. The property of each phase is calculated with the physical
42 * property models of its material. The mixing is done with complex values to
43 * allow for the calculation of complex properties, such as the complex
44 * permittivity or permeability. The mixture property depends on the fields on
45 * which the models of the phases used by the mixing law depend, and on the
46 * fields required by the mixing law itself (e.g., the void fraction).
47 */
49{
50public:
51 /**
52 * @brief Constructor. Gets the materials of the two phases from the material
53 * interaction, creates the models of their property and sets the fields on
54 * which these models depend.
55 *
56 * @param[in] physical_properties Physical properties parameters.
57 * @param[in] material_interaction_id Index of the material interaction that
58 * defines the mixture.
59 * @param[in] property Mixture property calculated by the model.
60 * @param[in] complex_component Part of the mixture property returned by the
61 * model.
62 */
64 const Parameters::PhysicalProperties &physical_properties,
65 const unsigned int material_interaction_id,
66 const EffectiveMediumProperty &property,
68
69 /**
70 * @brief Creates the model of a mixture property, with the mixing law given
71 * by the material interaction.
72 *
73 * @param[in] physical_properties Physical properties parameters.
74 * @param[in] material_interaction_id Index of the material interaction that
75 * defines the mixture.
76 * @param[in] property Mixture property calculated by the model.
77 * @param[in] complex_component Part of the mixture property returned by the
78 * model.
79 *
80 * @return A shared pointer to the created effective medium model.
81 */
82 static std::shared_ptr<EffectiveMediumModel>
83 model_cast(const Parameters::PhysicalProperties &physical_properties,
84 const unsigned int material_interaction_id,
85 const EffectiveMediumProperty &property,
87
88 /**
89 * @brief Calculates the selected part of the mixture property.
90 *
91 * @param[in] field_values Values of the fields on which the property
92 * depends.
93 *
94 * @return Real or imaginary part of the mixture property.
95 */
96 double
97 value(const std::map<field, double> &field_values) override;
98
99 /**
100 * @brief Calculates the selected part of the mixture property at multiple
101 * points.
102 *
103 * @param[in] field_vectors Values of the fields on which the property
104 * depends at each point.
105 * @param[in,out] property_vector Real or imaginary part of the mixture
106 * property at each point. Its size sets the number of points.
107 */
108 void
109 vector_value(const std::map<field, std::vector<double>> &field_vectors,
110 std::vector<double> &property_vector) override;
111
112 /**
113 * @brief Calculates the derivative of the selected part of the mixture
114 * property with respect to a field using a finite difference.
115 *
116 * @param[in] field_values Values of the fields on which the property
117 * depends.
118 * @param[in] id Field with respect to which the derivative is calculated.
119 *
120 * @return Derivative of the property with respect to the field.
121 */
122 double
123 jacobian(const std::map<field, double> &field_values,
124 const field id) override;
125
126 /**
127 * @brief Calculates the derivative of the selected part of the mixture
128 * property with respect to a field at multiple points using a finite
129 * difference.
130 *
131 * @param[in] field_vectors Values of the fields on which the property
132 * depends at each point.
133 * @param[in] id Field with respect to which the derivative is calculated.
134 * @param[in,out] jacobian_vector Derivative of the property at each point.
135 */
136 void
137 vector_jacobian(const std::map<field, std::vector<double>> &field_vectors,
138 const field id,
139 std::vector<double> &jacobian_vector) override;
140
141 /**
142 * @brief Mixing law of the effective medium model.
143 *
144 * @param[in] field_values Values of the fields on which the mixing law
145 * depends.
146 * @param[in] phase_1_property Property of phase 1.
147 * @param[in] phase_2_property Property of phase 2.
148 *
149 * @return Property of the mixture.
150 */
151 virtual std::complex<double>
152 apply_mixing_law(const std::map<field, double> &field_values,
153 const std::complex<double> phase_1_property,
154 const std::complex<double> phase_2_property) const = 0;
155
156 /**
157 * @brief Mixing law of the effective medium model at multiple points.
158 *
159 * @param[in] field_vectors Values of the fields on which the mixing law
160 * depends at each point.
161 * @param[in] phase_1_property Property of phase 1 at each point.
162 * @param[in] phase_2_property Property of phase 2 at each point.
163 * @param[in,out] mixture_property Property of the mixture at each point.
164 */
165 virtual void
167 const std::map<field, std::vector<double>> &field_vectors,
168 const std::vector<std::complex<double>> &phase_1_property,
169 const std::vector<std::complex<double>> &phase_2_property,
170 std::vector<std::complex<double>> &mixture_property) const = 0;
171
172protected:
173 /**
174 * @brief Models of the property of a phase. The effective property of the phase can be complex and builded from the sum of the real part models plus i times the sum of the imaginary part models (e.g., eps_eff = eps' + i (eps'' + sigma) for the permittivity).
175 */
177 {
178 /// Models whose values are summed to give the real part of the property
179 std::vector<std::shared_ptr<PhysicalPropertyModel>> real_part_terms;
180
181 /// Models whose values are summed to give the imaginary part of the
182 /// property
183 std::vector<std::shared_ptr<PhysicalPropertyModel>> imaginary_part_terms;
184 };
185
186 /**
187 * @brief Adds the fields on which the models of a phase depend to the fields
188 * on which the mixture property depends.
189 *
190 * @param[in] phase_models Models of the property of the phase.
191 */
192 void
193 add_phase_dependencies(const PhaseModels &phase_models);
194
195 /// Models of the property of phase 1
197
198 /// Models of the property of phase 2
200
201private:
202 /**
203 * @brief Creates the models needed to calculate a property of the material
204 * of a phase.
205 *
206 * @param[in] material_properties Parameters of the material.
207 * @param[in] property Property described by the models.
208 *
209 * @return Models of the property.
210 */
211 static PhaseModels
212 create_phase_models(const Parameters::Material &material_properties,
213 const EffectiveMediumProperty property);
214
215 /**
216 * @brief Calculates the complex property of a phase from its models.
217 *
218 * @param[in] phase_models Models of the property of the phase.
219 * @param[in] field_values Values of the fields.
220 *
221 * @return Property of the phase.
222 */
223 std::complex<double>
224 phase_value(const PhaseModels &phase_models,
225 const std::map<field, double> &field_values) const;
226
227 /**
228 * @brief Calculates the complex property of a phase at multiple points from
229 * its models.
230 *
231 * @param[in] phase_models Models of the property of the phase.
232 * @param[in] field_vectors Values of the fields at each point.
233 * @param[in,out] phase_property Property of the phase at each point. Its
234 * size sets the number of points.
235 */
236 void
237 phase_vector_value(const PhaseModels &phase_models,
238 const std::map<field, std::vector<double>> &field_vectors,
239 std::vector<std::complex<double>> &phase_property) const;
240
241 /**
242 * @brief Returns the selected part (real or imaginary) of a mixture property.
243 *
244 * @param[in] mixture_property Property of the mixture.
245 *
246 * @return Real or imaginary part of the mixture property.
247 */
248 double
249 get_complex_component(const std::complex<double> mixture_property) const;
250
251 /**
252 * @brief Returns the effective medium model chosen in a material interaction
253 * for a mixture property.
254 *
255 * @param[in] interaction Parameters of the material interaction.
256 * @param[in] property Mixture property calculated by the model.
257 *
258 * @return Type of the effective medium model of the property.
259 */
262 const EffectiveMediumProperty property);
263
264 /// Part of the mixture property returned by the model
266};
267
268/**
269 * @brief Mixture without effective medium model: the mixture property is the
270 * property of phase 1. It is used when one of the phases has no impact on the
271 * mixture property.
272 */
274{
275public:
277
278 /**
279 * @brief Returns the property of phase 1.
280 *
281 * @param[in] field_values Values of the fields (unused).
282 * @param[in] phase_1_property Property of phase 1.
283 * @param[in] phase_2_property Property of phase 2 (unused).
284 *
285 * @return Property of phase 1.
286 */
287 std::complex<double>
289 [[maybe_unused]] const std::map<field, double> &field_values,
290 const std::complex<double> phase_1_property,
291 [[maybe_unused]] const std::complex<double> phase_2_property) const override
292 {
293 return phase_1_property;
294 }
295
296 /**
297 * @brief Returns the property of phase 1 at multiple points.
298 *
299 * @param[in] field_vectors Values of the fields at each point (unused).
300 * @param[in] phase_1_property Property of phase 1 at each point.
301 * @param[in] phase_2_property Property of phase 2 at each point (unused).
302 * @param[in,out] mixture_property Property of phase 1 at each point.
303 */
304 void
306 [[maybe_unused]] const std::map<field, std::vector<double>> &field_vectors,
307 const std::vector<std::complex<double>> &phase_1_property,
308 [[maybe_unused]] const std::vector<std::complex<double>> &phase_2_property,
309 std::vector<std::complex<double>> &mixture_property) const override
310 {
311 mixture_property = phase_1_property;
312 }
313};
314
315/**
316 * @brief Two-phase Bruggeman effective medium approximation for spherical
317 * inclusions. With the void fraction \f$\epsilon\f$ (volume fraction of phase
318 * 1), the mixture property \f$\alpha_\mathrm{eff}\f$ is the root of
319 * \f$\epsilon\frac{\alpha_1 - \alpha_\mathrm{eff}}{\alpha_1 +
320 * 2\alpha_\mathrm{eff}} + (1-\epsilon)\frac{\alpha_2 -
321 * \alpha_\mathrm{eff}}{\alpha_2 + 2\alpha_\mathrm{eff}} = 0\f$, a quadratic
322 * equation. The root with a positive real part and a non-negative imaginary
323 * part is kept.
324 */
326{
327public:
328 /**
329 * @brief Constructor. Adds the fields on which the models of phase 2 depend
330 * and the void fraction to the fields on which the mixture property depends.
331 *
332 * @param[in] physical_properties Physical properties parameters.
333 * @param[in] material_interaction_id Index of the material interaction that
334 * defines the mixture.
335 * @param[in] property Mixture property calculated by the model.
336 * @param[in] complex_component Part of the mixture property returned by the
337 * model.
338 */
340 const Parameters::PhysicalProperties &physical_properties,
341 const unsigned int material_interaction_id,
342 const EffectiveMediumProperty property,
344
345 /**
346 * @brief Calculates the mixture property with the Bruggeman effective medium
347 * approximation.
348 *
349 * @param[in] field_values Values of the fields. It must contain the void
350 * fraction.
351 * @param[in] phase_1_property Property of phase 1.
352 * @param[in] phase_2_property Property of phase 2.
353 *
354 * @return Property of the mixture.
355 */
356 std::complex<double>
357 apply_mixing_law(const std::map<field, double> &field_values,
358 const std::complex<double> phase_1_property,
359 const std::complex<double> phase_2_property) const override;
360
361 /**
362 * @brief Calculates the mixture property with the Bruggeman effective medium
363 * approximation at multiple points.
364 *
365 * @param[in] field_vectors Values of the fields at each point. It must
366 * contain the void fraction.
367 * @param[in] phase_1_property Property of phase 1 at each point.
368 * @param[in] phase_2_property Property of phase 2 at each point.
369 * @param[in,out] mixture_property Property of the mixture at each point.
370 */
371 void
373 const std::map<field, std::vector<double>> &field_vectors,
374 const std::vector<std::complex<double>> &phase_1_property,
375 const std::vector<std::complex<double>> &phase_2_property,
376 std::vector<std::complex<double>> &mixture_property) const override;
377
378private:
379 /**
380 * @brief Bruggeman formula for a given void fraction.
381 *
382 * @param[in] void_fraction Void fraction of the mixture (volume fraction of
383 * phase 1).
384 * @param[in] phase_1_property Property of phase 1.
385 * @param[in] phase_2_property Property of phase 2.
386 *
387 * @return Property of the mixture.
388 */
389 static std::complex<double>
390 bruggeman(const double void_fraction,
391 const std::complex<double> phase_1_property,
392 const std::complex<double> phase_2_property);
393};
394
395#endif
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...
Mixture without effective medium model: the mixture property is the property of phase 1....
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
Returns the property of phase 1 at multiple points.
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
Returns the property of phase 1.
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...
MaterialInteractions - Class that defines physical properties due to interactions between two differe...
Definition parameters.h:757
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
PhysicalPropertyModel()
Default constructor. Set the model_depends_on to false for all variables.
ComplexComponent
Part of a complex physical property returned by a model. A PhysicalPropertyModel can only return a si...
EffectiveMediumProperty
Physical property of a mixture that can be calculated with an effective medium model.
DeclExceptionMsg(InvalidEffectiveMediumModel, "The effective medium model is not valid. The available models are 'none' and 'bruggeman'.")
DeclException1(InvalidPhysicalPropertyComplex, std::complex< double >,<< "Invalid physical property value: "<< arg1<< ". The physical property values must be in the first quadrant of the complex plane (positive real part and non-negative imaginary part).")
@ 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