Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
cls_subequations_interface.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2024-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_subequations_interface_h
5#define lethe_subequations_interface_h
6
10
11#include <algorithm>
12#include <utility>
13
14using namespace dealii;
15
17 ValidityMapNotReset,
18 "The subequation validity map is not reset. Call "
19 "'set_cls_solution_and_dof_handler' before 'set_cls_solution'.");
20
22 InvalidSubequationSolution,
23 std::string,
24 "The current solution of the "
25 << arg1
26 << " is invalid. \n"
27 "A new CLS solution has been set but the subequation was not solved "
28 "afterwards.");
29
30DeclException2(PhaseGradientProjectionIsInvalid,
31 std::string,
32 std::string,
33 "The " << arg1 << " has to be solved before " << arg2 << ".");
34
35DeclException2(CurvatureProjectionIsInvalid,
36 std::string,
37 std::string,
38 "The " << arg1 << " has to be solved before " << arg2 << ".");
39
40/**
41 * @brief Interface for secondary equations (subequations) solved within
42 * the CLS auxiliary physics.
43 *
44 * @tparam dim Number of dimensions of the problem.
45 */
46template <int dim>
48{
49public:
50 /**
51 * @brief Constructor of an interface for subequations that require the use of
52 * a solver within the span of the CLS auxiliary physics' resolution.
53 *
54 * @param[in] p_simulation_parameters Simulation parameters.
55 *
56 * @param[in] p_pcout Parallel cout used to print the information.
57 *
58 * @param[in] p_triangulation Distributed mesh information.
59 *
60 * @param[in] p_simulation_control SimulationControl object.
61 */
63 const SimulationParameters<dim> &p_simulation_parameters,
64 const ConditionalOStream &p_pcout,
65 const std::shared_ptr<parallel::DistributedTriangulationBase<dim>>
66 &p_triangulation,
67 const std::shared_ptr<SimulationControl> &p_simulation_control)
68 : pcout(p_pcout)
69 {
70 initialize_subequations(p_simulation_parameters,
71 p_triangulation,
72 p_simulation_control);
73 }
74
75 /**
76 * @brief Default destructor.
77 */
79
80 /**
81 * @brief Initialize subequations necessary for the simulation and reset
82 * subeqaution validation map.
83 *
84 * @param[in] p_simulation_parameters Simulation parameters.
85 *
86 * @param[in] p_triangulation Distributed mesh information.
87 *
88 * @param[in] p_simulation_control SimulationControl object.
89 */
90 void
92 const SimulationParameters<dim> &p_simulation_parameters,
93 const std::shared_ptr<parallel::DistributedTriangulationBase<dim>>
94 &p_triangulation,
95 const std::shared_ptr<SimulationControl> &p_simulation_control);
96
97 /**
98 * @brief Setup the DofHandler and the degree of freedom associated with the
99 * subequations.
100 */
101 void
103 {
104 for (const auto &subequation : this->subequations)
105 {
106 subequation.second->setup_dofs();
107 }
108 };
109
110 /**
111 * @brief Setup the DofHandler and the degree of freedom associated with the
112 * physics.
113 *
114 * @param[in] subequation_id Identifier associated with the subequation wished
115 * to solve.
116 */
117 void
119 {
120 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
121 this->active_subequations.end()),
122 ExcInternalError());
123
124 this->subequations.find(subequation_id)->second->setup_dofs();
125 };
126
127 /**
128 * @brief Call solving method of active subequations.
129 */
130 void
132 {
133 for (const auto &subequation : this->subequations)
134 {
135 subequation.second->solve();
136 }
137 }
138
139 /**
140 * @brief Call solving method for a specific subequation.
141 *
142 * @param[in] subequation_id Identifier associated with the subequation wished
143 * to solve.
144 */
145 void
147 {
148 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
149 this->active_subequations.end()),
150 ExcInternalError());
151
152 this->subequations.find(subequation_id)->second->solve();
153 }
154
155 /**
156 * @brief Get vector of active subequations.
157 *
158 * @return Vector of active subequations identifiers.
159 */
160 std::vector<CLSSubequationsID>
162 {
163 return this->active_subequations;
164 }
165
166 /**
167 * @brief Get a reference to the DoFHandler of a specific subequation.
168 *
169 * @param[in] subequation_id Identifier associated with a specific
170 * subequation.
171 *
172 * @return Reference to the DoFHandler of the specified subequation.
173 */
174 const DoFHandler<dim> &
175 get_dof_handler(const CLSSubequationsID &subequation_id)
176 {
177 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
178 this->active_subequations.end()),
179 ExcInternalError());
180
181 return *this->subequations_dof_handler[subequation_id];
182 }
183
184 /**
185 * @brief Get a reference to the DoFHandler of the CLS auxiliary physics.
186 *
187 * @return Reference to the DoFHandler of the CLS auxiliary physics associated
188 * to the set CLS solution field.
189 */
190 const DoFHandler<dim> &
192 {
193 return this->dof_handler_cls->get();
194 }
195
196 /**
197 * @brief Get a reference to the solution vector of a specific subequation.
198 *
199 * @param[in] subequation_id Identifier associated with a specific
200 * subequation.
201 *
202 * @return Reference to the solution vector of the specified subequation.
203 */
204 const GlobalVectorType &
205 get_solution(const CLSSubequationsID &subequation_id)
206 {
207 AssertThrow(this->get_solution_validity(subequation_id),
208 InvalidSubequationSolution(
209 this->get_subequation_string(subequation_id)));
210
211 return *this->subequations_solutions[subequation_id];
212 }
213
214 /**
215 * @brief Get a reference to the phase indicator solution vector.
216 *
217 * @return Reference to the phase indicator solution vector.
218 */
219 const GlobalVectorType &
221 {
222 return *this->cls_solution_vector;
223 }
224
225 /**
226 * @brief Check and return a boolean indicating if the solution of the
227 * subequation has been solved for the corresponding @p dof_handler_cls
228 * and/or @p cls_solution_vector previously set with
229 * CLSSubequationsInterface<dim>::set_cls_solution_and_dof_handler
230 *
231 * @param[in] subequation_id Identifier associated with a specific
232 * subequation.
233 *
234 * @return
235 * - @p true if the solution of the subequation corresponds to the set
236 * @p dof_handler_cls and/or @p cls_solution_vector.
237 * - Otherwise, @p false.
238 */
239 bool
241 {
242 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
243 this->active_subequations.end()),
244 ExcInternalError());
245 return this->subequations_solutions_validity[subequation_id];
246 }
247
248 /**
249 * @brief Get the string associated with a specific subequation.
250 *
251 * @param[in] subequation_id Identifier associated with a specific
252 * subequation.
253 *
254 * @return String associated with the specified subequation.
255 *
256 * @note This is used for printing purposes.
257 */
258 std::string
260 {
261 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
262 this->active_subequations.end()),
263 ExcInternalError());
264
265 std::string subequation_string;
266
268 subequation_string = "CLS phase indicator gradient L2 projection";
269 else if (subequation_id == CLSSubequationsID::curvature_projection)
270 subequation_string = "CLS curvature L2 projection";
271 else if (subequation_id ==
273 subequation_string = "CLS PDE-based interface reinitialization";
274 else
275 throw(std::invalid_argument("Invalid CLSSubequationID. Options are: \n"
276 " <phase_gradient_projection>\n"
277 " <curvature_projection>\n"
278 " <pde_based_interface_reinitialization>"));
279
280 return subequation_string;
281 }
282
283 /**
284 * @brief Set the DoFHandler associated with a specific subequation in the
285 * interface.
286 *
287 * @param[in] subequation_id Identifier associated with a specific
288 * subequation.
289 *
290 * @param[in] dof_handler Shared pointer to the DoFHandler of a specific
291 * subequation.
292 */
293 void
294 set_dof_handler(const CLSSubequationsID &subequation_id,
295 std::shared_ptr<DoFHandler<dim>> dof_handler)
296 {
297 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
298 this->active_subequations.end()),
299 ExcInternalError());
300 this->subequations_dof_handler[subequation_id] = std::move(dof_handler);
301 }
302
303 /**
304 * @brief Set the solution associated with a specific subequation in the
305 * interface.
306 *
307 * @param[in] subequation_id Identifier associated with a specific
308 * subequation.
309 *
310 * @param[in] solution_vector Shared pointer to the solution vector of a
311 * specific subequation.
312 */
313 void
314 set_solution(const CLSSubequationsID &subequation_id,
315 std::shared_ptr<GlobalVectorType> solution_vector)
316 {
317 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
318 this->active_subequations.end()),
319 ExcInternalError());
320 this->subequations_solutions[subequation_id] = std::move(solution_vector);
321 }
322
323 /**
324 * @brief Set a new CLS solution vector and DoFHandler for the subequations
325 * to be solved and reset their validity.
326 *
327 * @param[in] cls_solution_vector CLS solution vector associated with the
328 * subequations to be solved.
329 *
330 * @param[in] dof_handler_cls Reference to the DoFHandler associated with the
331 * specified CLS solution.
332 */
333 void
335 const DoFHandler<dim> &dof_handler_cls)
336 {
337 // Reset validity map
339
340 // Set solution values and DoFHandler
341 this->cls_solution_vector = std::cref(cls_solution_vector);
342 this->dof_handler_cls = std::cref(dof_handler_cls);
343 }
344
345 /**
346 * @brief Set the solution as valid after solving it.
347 *
348 * @param[in] subequation_id Identifier associated with a specific
349 * subequation.
350 */
351 void
353 {
354 AssertThrow((std::ranges::find(this->active_subequations, subequation_id) !=
355 this->active_subequations.end()),
356 ExcInternalError());
357 this->subequations_solutions_validity[subequation_id] = true;
358 }
359
360 /**
361 * @brief Check if all booleans in subequations_solutions_validity have been
362 * reset to @p false.
363 *
364 * @return
365 * - @p true if all booleans in the map are set to @p false or;
366 * - @p false if at least one of the booleans is set to @p true
367 */
368 bool
370 {
371 for (const auto &pair : subequations_solutions_validity)
372 {
373 if (pair.second == true)
374 return false;
375 }
376 return true;
377 }
378
379private:
380 /**
381 * @brief Reset all boolean in the validity associated with active
382 * subequations to @p false.
383 */
384 void
386 {
387 for (const CLSSubequationsID &subequation_id : this->active_subequations)
388 {
389 subequations_solutions_validity[subequation_id] = false;
390 }
391 }
392
393 /// Parallel consol output object
394 const ConditionalOStream pcout;
395
396 /// CLS DoFHandler associated with solved equations
397 std::optional<std::reference_wrapper<const DoFHandler<dim>>> dof_handler_cls;
398
399 /** CLS solution field associated with solved equations
400 * @note Serves as initial condition in PDE-based reinitialization */
401 std::optional<std::reference_wrapper<const GlobalVectorType>>
403
404 /// Data structure that stores all enabled subequations
405 std::vector<CLSSubequationsID> active_subequations;
406
407 /** Subequations are stored within a map of shared pointer to ensure proper
408 * memory management */
409 std::map<CLSSubequationsID, std::shared_ptr<PhysicsSubequationsSolverBase>>
411
412 /// Map of DoFHandler of subequations
413 std::map<CLSSubequationsID, std::shared_ptr<DoFHandler<dim>>>
415
416 /// Present solutions map
417 std::map<CLSSubequationsID, std::shared_ptr<GlobalVectorType>>
419
420 /**
421 * Booleans indicating if the subequation has been solved with the set CLS
422 * solution vector. The CLS solution vector is set with
423 * CLSSubequationsInterface<dim>::set_cls_solution_and_dof_handler.
424 *
425 * During initialization
426 * (CLSSubequationsInterface<dim>::initialize_subequations),
427 * all boolean are set to @p false.
428 *
429 * We start by setting a CLS solution and DOFHandler
430 * (CLSSubequationsInterface<dim>::set_cls_solution_and_dof_handler),
431 * and then start solving equations making sure that dependencies are met
432 * (CLSPhaseGradientProjection<dim>::check_dependencies_validity,
433 * CLSCurvatureProjection<dim>::check_dependencies_validity, and
434 * CLSPDEBasedInterfaceReinitialization<dim>::check_dependencies_validity).
435 * For instance, to solve the curvature projection subequation, the phase
436 * gradient projection subequation has to be solved before as the projected
437 * phase gradient is used in the curvature projection subequation.
438 *
439 * A subequation in the validity map is to @p true only when it is solved, and
440 * it remains valid until a new CLS solution and/or DOFHandler are
441 * set through
442 * CLSSubequationsInterface<dim>::set_cls_solution_and_dof_handler.
443 *
444 * This validation mechanism allows, to check if:
445 * - A new CLS solution has been set;
446 * - All dependencies of the subequation have been solved;
447 * - The current solution of the subequation is valid, and avoid unnecessarily
448 * solving it once more.
449 *
450 * @note
451 * CLSSubequationsInterface<dim>::set_cls_solution_and_dof_handler
452 * also resets the validity map values to @p false.
453 */
454 std::map<CLSSubequationsID, bool> subequations_solutions_validity;
455};
456
457#endif
const ConditionalOStream pcout
Parallel consol output object.
std::optional< std::reference_wrapper< const GlobalVectorType > > cls_solution_vector
std::map< CLSSubequationsID, std::shared_ptr< DoFHandler< dim > > > subequations_dof_handler
Map of DoFHandler of subequations.
void solve_specific_subequation(const CLSSubequationsID &subequation_id)
Call solving method for a specific subequation.
const DoFHandler< dim > & get_cls_dof_handler()
Get a reference to the DoFHandler of the CLS auxiliary physics.
void set_cls_solution_and_dof_handler(const GlobalVectorType &cls_solution_vector, const DoFHandler< dim > &dof_handler_cls)
Set a new CLS solution vector and DoFHandler for the subequations to be solved and reset their validi...
std::map< CLSSubequationsID, bool > subequations_solutions_validity
void solve()
Call solving method of active subequations.
void setup_dofs()
Setup the DofHandler and the degree of freedom associated with the subequations.
const GlobalVectorType & get_solution(const CLSSubequationsID &subequation_id)
Get a reference to the solution vector of a specific subequation.
std::vector< CLSSubequationsID > get_active_subequations()
Get vector of active subequations.
~CLSSubequationsInterface()=default
Default destructor.
void setup_specific_subequation_dofs(const CLSSubequationsID &subequation_id)
Setup the DofHandler and the degree of freedom associated with the physics.
void set_solution_valid(const CLSSubequationsID &subequation_id)
Set the solution as valid after solving it.
void reset_subequations_solutions_validity()
Reset all boolean in the validity associated with active subequations to false.
std::vector< CLSSubequationsID > active_subequations
Data structure that stores all enabled subequations.
void set_dof_handler(const CLSSubequationsID &subequation_id, std::shared_ptr< DoFHandler< dim > > dof_handler)
Set the DoFHandler associated with a specific subequation in the interface.
CLSSubequationsInterface(const SimulationParameters< dim > &p_simulation_parameters, const ConditionalOStream &p_pcout, const std::shared_ptr< parallel::DistributedTriangulationBase< dim > > &p_triangulation, const std::shared_ptr< SimulationControl > &p_simulation_control)
Constructor of an interface for subequations that require the use of a solver within the span of the ...
void set_solution(const CLSSubequationsID &subequation_id, std::shared_ptr< GlobalVectorType > solution_vector)
Set the solution associated with a specific subequation in the interface.
std::map< CLSSubequationsID, std::shared_ptr< PhysicsSubequationsSolverBase > > subequations
bool validity_map_has_been_reset()
Check if all booleans in subequations_solutions_validity have been reset to false.
bool get_solution_validity(const CLSSubequationsID &subequation_id)
Check and return a boolean indicating if the solution of the subequation has been solved for the corr...
std::string get_subequation_string(const CLSSubequationsID &subequation_id)
Get the string associated with a specific subequation.
void initialize_subequations(const SimulationParameters< dim > &p_simulation_parameters, const std::shared_ptr< parallel::DistributedTriangulationBase< dim > > &p_triangulation, const std::shared_ptr< SimulationControl > &p_simulation_control)
Initialize subequations necessary for the simulation and reset subeqaution validation map.
std::map< CLSSubequationsID, std::shared_ptr< GlobalVectorType > > subequations_solutions
Present solutions map.
std::optional< std::reference_wrapper< const DoFHandler< dim > > > dof_handler_cls
CLS DoFHandler associated with solved equations.
const GlobalVectorType & get_cls_solution()
Get a reference to the phase indicator solution vector.
const DoFHandler< dim > & get_dof_handler(const CLSSubequationsID &subequation_id)
Get a reference to the DoFHandler of a specific subequation.
CLSSubequationsID
IDs associated to the different subequations solved in Lethe.
@ curvature_projection
CLS curvature L2 projection.
@ pde_based_interface_reinitialization
CLS PDE-based interface reinitialization.
@ phase_gradient_projection
CLS phase indicator gradient L2 projection.
DeclException1(InvalidSubequationSolution, std::string, "The current solution of the "<< arg1<< " is invalid. \n" "A new CLS solution has been set but the subequation was not solved " "afterwards.")
DeclExceptionMsg(ValidityMapNotReset, "The subequation validity map is not reset. Call " "'set_cls_solution_and_dof_handler' before 'set_cls_solution'.")
DeclException2(PhaseGradientProjectionIsInvalid, std::string, std::string, "The "<< arg1<< " has to be solved before "<< arg2<< ".")
dealii::TrilinosWrappers::MPI::Vector GlobalVectorType
Definition vector.h:17