Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
physical_property_model.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2022-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_physical_property_model_h
5#define lethe_physical_property_model_h
6
7#include <core/parameters.h>
9
10#include <cstdint>
11
12using namespace dealii;
13
15 SimulationControlUsageByProperty,
16 "The usage of the simulation control object is currently only supported by the SpecificHeat models");
17
18DeclException2(SizeOfFields,
19 unsigned int,
20 unsigned int,
21 << "The number of values for a field : " << arg1
22 << " is not equal to the number of values for another field "
23 << arg2);
24
25DeclException2(PhysicialPropertyModelFieldUndefined,
26 std::string,
27 std::string,
28 << "Error in '" << arg1 << "' model. \n "
29 << "The '" << arg2
30 << "' field required by the model is not defined.");
31
32/*
33 * Fields on which physical property can depend. All fields are assumed
34 * to be at time t+dt other than those for which a _p suffix is explicitly
35 * given. The suffix _p1 implies that the field is at time t (previous one step)
36 * and the suffix _p2 implies that the field is at time t_dt (previous two
37 * steps).
38 */
52
53inline void
55 const std::vector<double> &data,
56 std::map<field, std::vector<double>> &fields)
57{
58 std::vector<double> &target = fields.at(id);
59 size_t sz = target.size();
60 for (size_t i = 0; i < sz; ++i)
61 {
62 target[i] = data[i];
63 }
64}
65
66/**
67 * @brief Abstract class that defines the interface for a physical property model
68 * Physical property model provides an abstract interface to calculate the
69 * value of a physical property or a vector of physical property value for
70 * given field value. By default, the interface does not require that all (or
71 * any) fields be specified. This is why a map is used to pass the dependent
72 * variable. To allow for the calculation of the appropriate jacobian matrix
73 * (when that is necessary) the interface also provides a jacobian function,
74 * which must provide the derivative with respect to the field specified as an
75 * argument.
76 */
78{
79public:
80 /**
81 * @brief Part of a complex physical property returned by a model. A
82 * PhysicalPropertyModel can only return a single double value, so this flag
83 * is used to select which part of the complex property is returned.
84 */
85 enum class ComplexComponent : std::int8_t
86 {
89 };
90
91 /**
92 * @brief Default constructor. Set the model_depends_on to false for all variables.
93 */
106
107 /**
108 * @brief Default virtual destructor. Does not do anything.
109 */
110 virtual ~PhysicalPropertyModel() = default;
111
112 /**
113 * @brief Returns true if the PhysicalPropertyModel depends on a field, false if not.
114 */
115
116 inline bool
117 depends_on(const field &id)
118 {
119 return model_depends_on[id];
120 }
121
122
123 /**
124 * @brief value Calculates the value of a physical property.
125 * @param fields_value Value of the various field on which the property may depend.
126 * @return value of the physical property calculated with the fields_value
127 */
128 virtual double
129 value(const std::map<field, double> &fields_value) = 0;
130
131 /**
132 * @brief vector_value Calculates the values of a physical property for multiple points
133 * @param field_vectors
134 */
135 virtual void
136 vector_value(const std::map<field, std::vector<double>> &field_vectors,
137 std::vector<double> &property_vector) = 0;
138
139 /**
140 * @brief jacobian Calcualtes the jacobian (the partial derivative) of the physical
141 * property with respect to a field
142 * @param field_values Value of the various fields on which the property may depend.
143 * @param id Indicator of the field with respect to which the jacobian
144 * should be calculated
145 * @return value of the partial derivative of the property with respect to the field.
146 */
147
148 virtual double
149 jacobian(const std::map<field, double> &field_values, const field id) = 0;
150
151 /**
152 * @brief vector_jacobian Calculate the derivative of the property with respect to a field
153 * @param field_vectors Vector for the values of the fields used to evaluate the property
154 * @param id Identifier of the field with respect to which a derivative should be calculated
155 * @param jacobian Vector of the value of the derivative of the property with respect to the field id
156 */
157
158 virtual void
159 vector_jacobian(const std::map<field, std::vector<double>> &field_vectors,
160 const field id,
161 std::vector<double> &jacobian_vector) = 0;
162
163 /**
164 * @brief Provides the physical property with the simulation control object ensuring
165 * that the PhysicalPropertyModel can calculate physical properties that
166 * depend on time or time-history
167 *
168 * @param p_simulation_control shared pointed to a SimulationControl object. A copy of this shared pointer is stored in the physical property.
169 */
170
171 void
173 std::shared_ptr<SimulationControl> &p_simulation_control)
174 {
175 simulation_control = p_simulation_control;
176 }
177
178 /**
179 * @brief numerical_jacobian Calculates the jacobian through a forward finite difference (Euler) approximation.
180 * This approach, although not preferable, is meant as a fall-back when
181 * calculating the jacobian manually is too difficult.
182 * @param fields_values The values of the various fields
183 * @param id Field id of the field with respect to which the jacobian should be calculated
184 * @return
185 */
186 inline double
187 numerical_jacobian(const std::map<field, double> &field_values,
188 const field id)
189 {
190 double f_x = this->value(field_values);
191 auto x_dx = field_values;
192 double dx = std::max(1e-6 * x_dx[id], 1e-8);
193 x_dx[id] = x_dx[id] + dx;
194 double f_xdx = this->value(x_dx);
195 return (f_xdx - f_x) / dx;
196 }
197
198 /**
199 * @brief vector_numerical_jacobian Calculates the vector of jacobian through forward finite difference (Euler) approximation.
200 * This approach, although not preferable, is meant as a fall-back when
201 * calculating the jacobian manually is too difficult.
202 * @param field_vectors
203 * @param field_id
204 * @param jacobian_vector
205 * @return
206 */
207 inline void
209 const std::map<field, std::vector<double>> &field_vectors,
210 const field id,
211 std::vector<double> &jacobian_vector)
212 {
213 const unsigned int n_pts = jacobian_vector.size();
214
215 // Evaluate the properties using the values of the field vector
216 std::vector<double> f_x(n_pts);
217 vector_value(field_vectors, f_x);
218
219 // Make a copy of the field vector for the field we wil perturbate
220 std::map<field, std::vector<double>> perturbed_field_vectors =
221 field_vectors;
222 std::vector<double> &x = perturbed_field_vectors.at(id);
223 std::vector<double> dx(n_pts);
224
225 // Perturb the field by dx
226 for (unsigned int i = 0; i < n_pts; ++i)
227 {
228 dx[i] = std::max(1e-6 * x[i], 1e-8);
229 x[i] += dx[i];
230 }
231
232 // Evaluate the properties using the perturbed value of the field vector
233 std::vector<double> f_xdx(n_pts);
234 vector_value(perturbed_field_vectors, f_xdx);
235
236 // Fill jacobian
237 for (unsigned int i = 0; i < n_pts; ++i)
238 jacobian_vector[i] = (f_xdx[i] - f_x[i]) / dx[i];
239 }
240
241protected:
242 std::shared_ptr<SimulationControl> &
244 {
245 AssertThrow(simulation_control, SimulationControlUsageByProperty());
246 return simulation_control;
247 }
248
249 // Map to indicate on which variables the model depends on
250 std::map<field, bool> model_depends_on;
251
252private:
253 // SimulationControl object. This can be used to set time-dependent
254 // physical properties or properties which depend on time derivatives.
255 // The SimulationControl must be provided to the physical property
256 // through the solver itself.
257 std::shared_ptr<SimulationControl> simulation_control;
258};
259
260
261
262#endif
virtual ~PhysicalPropertyModel()=default
Default virtual destructor. Does not do anything.
std::shared_ptr< SimulationControl > simulation_control
virtual double value(const std::map< field, double > &fields_value)=0
value Calculates the value of a physical property.
std::shared_ptr< SimulationControl > & get_simulation_control()
virtual double jacobian(const std::map< field, double > &field_values, const field id)=0
jacobian Calcualtes the jacobian (the partial derivative) of the physical property with respect to a ...
virtual void vector_jacobian(const std::map< field, std::vector< double > > &field_vectors, const field id, std::vector< double > &jacobian_vector)=0
vector_jacobian Calculate the derivative of the property with respect to a field
void provide_simulation_control(std::shared_ptr< SimulationControl > &p_simulation_control)
Provides the physical property with the simulation control object ensuring that the PhysicalPropertyM...
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....
PhysicalPropertyModel()
Default constructor. Set the model_depends_on to false for all variables.
virtual void vector_value(const std::map< field, std::vector< double > > &field_vectors, std::vector< double > &property_vector)=0
vector_value Calculates the values of a physical property for multiple points
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
bool depends_on(const field &id)
Returns true if the PhysicalPropertyModel depends on a field, false if not.
@ void_fraction
@ phase_order_cahn_hilliard_filtered
DeclException2(SizeOfFields, unsigned int, unsigned int,<< "The number of values for a field : "<< arg1<< " is not equal to the number of values for another field "<< arg2)
void set_field_vector(const field &id, const std::vector< double > &data, std::map< field, std::vector< double > > &fields)
DeclExceptionMsg(SimulationControlUsageByProperty, "The usage of the simulation control object is currently only supported by the SpecificHeat models")
Simulation control classes for managing time-stepping and iteration control in Lethe.