Debian Codegraph @

include/deal.II/sundials/sunlinsol_wrapper.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15
16 #ifndef dealii_sundials_sunlinsol_wrapper_h
17 #define dealii_sundials_sunlinsol_wrapper_h
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_SUNDIALS
22
23 # include <sundials/sundials_linearsolver.h>
24
25 # include <exception>
26 # include <functional>
27 # include <memory>
28
29 DEAL_II_NAMESPACE_OPEN
30
31 namespace SUNDIALS
32 {
33 # ifndef DOXYGEN
34 // forward declarations
35 namespace internal
36 {
37 template <typename VectorType>
38 struct LinearSolverContent;
39 }
40 # endif
41
42 /**
43 * A linear operator that wraps SUNDIALS functionality.
44 */
45 template <typename VectorType>
46 struct SundialsOperator
47 {
48 /**
49 * Apply this LinearOperator to @p src and store the result in @p dst.
50 */
51 void
52 vmult(VectorType &dst, const VectorType &src) const;
53
54 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
55 /**
56 * Constructor.
57 *
58 * @param A_data Data required by @p a_times_fn
59 * @param a_times_fn A function pointer to the function that computes A*v
60 * @param linsol_ctx The context object used to set up the linear solver and all vectors
61 */
62 SundialsOperator(void *A_data,
63 SUNATimesFn a_times_fn,
64 SUNContext linsol_ctx);
65 # else
66 /**
67 * Constructor.
68 *
69 * @param A_data Data required by @p a_times_fn
70 * @param a_times_fn A function pointer to the function that computes A*v
71 */
72 SundialsOperator(void *A_data, ATimesFn a_times_fn);
73 # endif
74
75 private:
76 /**
77 * Data necessary to evaluate a_times_fn.
78 */
79 void *A_data;
80
81 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
82 /**
83 * %Function pointer declared by SUNDIALS to evaluate the matrix vector
84 * product.
85 */
86 SUNATimesFn a_times_fn;
87
88 /**
89 * Context object used for SUNDIALS logging.
90 */
91 SUNContext linsol_ctx;
92 # else
93 /**
94 * %Function pointer declared by SUNDIALS to evaluate the matrix vector
95 * product.
96 */
97 ATimesFn a_times_fn;
98 # endif
99 };
100
101
102
103 /**
104 * A linear operator that wraps preconditioner functionality as specified by
105 * SUNDIALS. The vmult() function solves the preconditioner equation $Px=b$,
106 * i.e., it computes $x=P^{-1}b$.
107 */
108 template <typename VectorType>
109 struct SundialsPreconditioner
110 {
111 /**
112 * Apply the wrapped preconditioner, i.e., solve $Px=b$ where $x$ is the
113 * @p dst vector and $b$ the @p src vector.
114 *
115 * @param dst Result vector of the preconditioner application
116 * @param src Target vector of the preconditioner application
117 */
118 void
119 vmult(VectorType &dst, const VectorType &src) const;
120
121 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
122 /**
123 * Constructor.
124 *
125 * @param P_data Data required by @p p_solve_fn
126 * @param p_solve_fn A function pointer to the function that computes A*v
127 * @param linsol_ctx The context object used to set up the linear solver and all vectors
128 * @param tol Tolerance, that an iterative solver should use to judge
129 * convergence
130 *
131 * @note This function is only available with SUNDIALS 6.0.0 and later.
132 * 6.0.0. If you are using an earlier version of SUNDIALS then you need to
133 * use the other constructor.
134 */
135 SundialsPreconditioner(void *P_data,
136 SUNPSolveFn p_solve_fn,
137 SUNContext linsol_ctx,
138 double tol);
139 # else
140 /**
141 * Constructor.
142 *
143 * @param P_data Data required by @p p_solve_fn
144 * @param p_solve_fn A function pointer to the function that computes A*v
145 * @param tol Tolerance, that an iterative solver should use to judge
146 * convergence
147 *
148 * @note This function is only available with versions of SUNDIALS prior to
149 * 6.0.0. If you are using SUNDIALS 6 or later then you need to use the
150 * other constructor.
151 */
152 SundialsPreconditioner(void *P_data, PSolveFn p_solve_fn, double tol);
153 # endif
154
155 private:
156 /**
157 * Data necessary to calls p_solve_fn
158 */
159 void *P_data;
160
161 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
162 /**
163 * %Function pointer to a function that computes the preconditioner
164 * application.
165 */
166 SUNPSolveFn p_solve_fn;
167
168 /**
169 * Context object used for SUNDIALS logging.
170 */
171 SUNContext linsol_ctx;
172 # else
173 /**
174 * %Function pointer to a function that computes the preconditioner
175 * application.
176 */
177 PSolveFn p_solve_fn;
178 # endif
179
180 /**
181 * Potential tolerance to use in the internal solve of the preconditioner
182 * equation.
183 */
184 double tol;
185 };
186
187 /**
188 * Type of function objects to interface with SUNDIALS' linear solvers
189 *
190 * This function type encapsulates the action of solving $P^{-1}Ax=P^{-1}b$.
191 * The LinearOperator @p op encapsulates the matrix vector product $Ax$ and
192 * the LinearOperator @p prec encapsulates the application of the
193 * preconditioner $P^{-1}z$.
194 * The user can specify function objects of this type to attach custom linear
195 * solver routines to SUNDIALS. The two LinearOperators @p op and @p prec are
196 * built internally by SUNDIALS based on user settings. The parameters are
197 * interpreted as follows:
198 *
199 * @param[in] op A LinearOperator that applies the matrix vector product
200 * @param[in] prec A LinearOperator that applies the preconditioner
201 * @param[out] x The output solution vector
202 * @param[in] b The right-hand side
203 * @param[in] tol Tolerance for the iterative solver
204 *
205 *
206 * @note This variable represents a
207 * @ref GlossUserProvidedCallBack "user provided callback".
208 * See there for a description of how to deal with errors and other
209 * requirements and conventions. In particular, ARKode can deal
210 * with "recoverable" errors in some circumstances, so callbacks
211 * can throw exceptions of type RecoverableUserCallbackError.
212 */
213 template <typename VectorType>
214 using LinearSolveFunction =
215 std::function<void(SundialsOperator<VectorType> &op,
216 SundialsPreconditioner<VectorType> &prec,
217 VectorType &x,
218 const VectorType &b,
219 double tol)>;
220
221 namespace internal
222 {
223 /**
224 * Attach wrapper functions to SUNDIALS' linear solver interface. We pretend
225 * that the user-supplied linear solver is matrix-free, even though it can
226 * be matrix-based. This way SUNDIALS does not need to understand our matrix
227 * types.
228 */
229 template <typename VectorType>
230 class LinearSolverWrapper
231 {
232 public:
233 explicit LinearSolverWrapper(
234 const LinearSolveFunction<VectorType> &lsolve,
235 std::exception_ptr &pending_exception
236 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
237 ,
238 SUNContext linsol_ctx
239 # endif
240 );
241
242 ~LinearSolverWrapper();
243
244 /**
245 * Implicit conversion to SUNLinearSolver.
246 */
247 operator SUNLinearSolver();
248
249 private:
250 SUNLinearSolver sun_linear_solver;
251 std::unique_ptr<LinearSolverContent<VectorType>> content;
252 };
253 } // namespace internal
254 } // namespace SUNDIALS
255
256 DEAL_II_NAMESPACE_CLOSE
257
258 #else
259
260 // Make sure the scripts that create the C++20 module input files have
261 // something to latch on if the preprocessor #ifdef above would
262 // otherwise lead to an empty content of the file.
263 DEAL_II_NAMESPACE_OPEN
264 DEAL_II_NAMESPACE_CLOSE
265
266 #endif
267 #endif