Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
interface_property_model.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_interface_property_model_h
5#define lethe_interface_property_model_h
6
7#include <core/parameters.h>
9
10using namespace dealii;
11
12/**
13 * @brief Abstract class that defines the interface for a interface property model.
14 * Interface property model provides an abstract interface to calculate the
15 * value of an interface property or a vector of interface property value for
16 * given field value. By default, the interface does not require that all (or
17 * any) fields be specified. This is why a map is used to pass the dependent
18 * variable. To allow for the calculation of the appropriate jacobian matrix
19 * (when that is necessary) the interface also provides a jacobian function,
20 * which must provide the derivative with respect to the field specified as an
21 * argument.
22 */
24{
25public:
26 /**
27 * @brief class Default constructor. Set the model_depends_on to false for all variables.
28 */
37
38 /**
39 * @brief Default destructor.
40 */
41 virtual ~InterfacePropertyModel() = default;
42
43 /**
44 * @brief Returns true if the InterfacePropertyModel depends on a field, false if not.
45 */
46
47 inline bool
48 depends_on(const field &id)
49 {
50 return model_depends_on[id];
51 }
52
53
54 /**
55 * @brief value Calculates the value of an interface property.
56 * @param fields_value Value of the various field on which the property may depend.
57 * @return value of the interface property calculated with the fields_value
58 */
59 virtual double
60 value(const std::map<field, double> &fields_value) = 0;
61
62 /**
63 * @brief vector_value Calculates the values of an interface property for multiple points
64 * @param field_vectors
65 */
66 virtual void
67 vector_value(const std::map<field, std::vector<double>> &field_vectors,
68 std::vector<double> &property_vector) = 0;
69
70 /**
71 * @brief jacobian Calculates the jacobian (the partial derivative) of the interface
72 * property with respect to a field
73 * @param field_values Value of the various fields on which the property may depend.
74 * @param id Indicator of the field with respect to which the jacobian
75 * should be calculated
76 * @return value of the partial derivative of the property with respect to the field.
77 */
78
79 virtual double
80 jacobian(const std::map<field, double> &field_values, const field id) = 0;
81
82 /**
83 * @brief vector_jacobian Calculate the derivative of the property with respect to a field
84 * @param field_vectors Vector for the values of the fields used to evaluate the property
85 * @param id Identifier of the field with respect to which a derivative should be calculated
86 * @param jacobian Vector of the value of the derivative of the property with respect to the field id
87 */
88
89 virtual void
90 vector_jacobian(const std::map<field, std::vector<double>> &field_vectors,
91 const field id,
92 std::vector<double> &jacobian_vector) = 0;
93
94
95 /**
96 * @brief numerical_jacobian Calculates the jacobian through a forward finite difference (Euler) approximation.
97 * This approach, although not preferable, is meant as a fall-back when
98 * calculating the jacobian manually is too difficult.
99 * @param fields_values The values of the various fields
100 * @param id Field id of the field with respect to which the jacobian should be calculated
101 * @return
102 */
103 inline double
104 numerical_jacobian(const std::map<field, double> &field_values,
105 const field id)
106 {
107 double f_x = this->value(field_values);
108 auto x_dx = field_values;
109 double dx = std::max(1e-6 * x_dx[id], 1e-8);
110 x_dx[id] = x_dx[id] + dx;
111 double f_xdx = this->value(x_dx);
112 return (f_xdx - f_x) / dx;
113 }
114
115 /**
116 * @brief vector_numerical_jacobian Calculates the vector of jacobian through forward finite difference (Euler) approximation.
117 * This approach, although not preferable, is meant as a fall-back when
118 * calculating the jacobian manually is too difficult.
119 * @param field_vectors
120 * @param field_id
121 * @param jacobian_vector
122 * @return
123 */
124 inline void
126 const std::map<field, std::vector<double>> &field_vectors,
127 const field id,
128 std::vector<double> &jacobian_vector)
129 {
130 const unsigned int n_pts = jacobian_vector.size();
131
132 // Evaluate the properties using the values of the field vector
133 std::vector<double> f_x(n_pts);
134 vector_value(field_vectors, f_x);
135
136 // Make a copy of the field vector for the field we will perturbate
137 std::map<field, std::vector<double>> perturbed_field_vectors =
138 field_vectors;
139 std::vector<double> &x = perturbed_field_vectors.at(id);
140 std::vector<double> dx(n_pts);
141
142 // Perturb the field by dx
143 for (unsigned int i = 0; i < n_pts; ++i)
144 {
145 dx[i] = std::max(1e-6 * x[i], 1e-8);
146 x[i] += dx[i];
147 }
148
149 // Evaluate the properties using the perturbed value of the field vector
150 std::vector<double> f_xdx(n_pts);
151 vector_value(perturbed_field_vectors, f_xdx);
152
153 // Fill jacobian
154 for (unsigned int i = 0; i < n_pts; ++i)
155 jacobian_vector[i] = (f_xdx[i] - f_x[i]) / dx[i];
156 }
157
158protected:
159 // Map to indicate on which variables the model depends on
160 std::map<field, bool> model_depends_on;
161};
162
163#endif
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....
bool depends_on(const field &id)
Returns true if the InterfacePropertyModel depends on a field, false if not.
virtual double jacobian(const std::map< field, double > &field_values, const field id)=0
jacobian Calculates the jacobian (the partial derivative) of the interface property with respect to a...
virtual ~InterfacePropertyModel()=default
Default destructor.
virtual double value(const std::map< field, double > &fields_value)=0
value Calculates the value of an interface property.
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 an interface property for multiple points
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 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)...
InterfacePropertyModel()
class Default constructor. Set the model_depends_on to false for all variables.
std::map< field, bool > model_depends_on