GCC Code Coverage Report

Directory: ./
File: PETScInterface/SNESInterface.hpp
Date: 2024-04-14 07:32:34
Exec Total Coverage
Lines: 2 2 100.0%
Branches: 0 0 -%
Line Branch Exec Source
1 // ______ ______ _ _ _____ ______
2 // | ____| ____| | (_)/ ____| | ____|
3 // | |__ | |__ | | _| (___ ___| |__
4 // | __| | __| | | | |\___ \ / __| __|
5 // | | | |____| |____| |____) | (__| |____
6 // |_| |______|______|_|_____/ \___|______|
7 // Finite Elements for Life Sciences and Engineering
8 //
9 // License: LGL2.1 License
10 // FELiScE default license: LICENSE in root folder
11 //
12 // Main authors: Vicente Mataix Ferrandiz
13 //
14
15 #ifndef SNES_INTERFACE_HPP
16 #define SNES_INTERFACE_HPP
17
18 // System includes
19
20 // External includes
21 #include "Core/NoThirdPartyWarning/Petsc/snes.hpp"
22
23 // Project includes
24 #include "Core/felisce.hpp"
25 #include "Core/shared_pointers.hpp"
26 #include "PETScInterface/petscVector.hpp"
27 #include "PETScInterface/petscMatrix.hpp"
28
29 namespace felisce
30 {
31 ///@name felisce Globals
32 ///@{
33
34 ///@}
35 ///@name Type Definitions
36 ///@{
37
38 // Forward declarations.
39 class LinearProblem;
40
41 ///@}
42 ///@name Enum's
43 ///@{
44
45 ///@}
46 ///@name Functions
47 ///@{
48
49 ///@}
50 ///@name felisce Classes
51 ///@{
52
53 /**
54 * @brief Interface for the SNES solver
55 */
56 class SNESInterface
57 {
58 public:
59 ///@name Type Definitions
60 ///@{
61
62 /// Pointer definition of SNESInterface
63 FELISCE_CLASS_POINTER_DEFINITION(SNESInterface);
64
65 ///@}
66 ///@name Life Cycle
67 ///@{
68
69 /**
70 * @brief Default constructor
71 */
72 SNESInterface();
73
74 /**
75 * @brief Destructor
76 */
77 ~SNESInterface();
78
79 ///@}
80 ///@name Operators
81 ///@{
82
83 ///@}
84 ///@name Operations
85 ///@{
86
87 /**
88 * @brief Initializes the SNES solver
89 */
90 void init();
91
92 /**
93 * @brief Initializes the SNES solver with custom MPI_Comm
94 */
95 void init(MPI_Comm comm);
96
97 /**
98 * @brief Sets the function evaluation routine and function vector for use by the SNES routines in solving systems of nonlinear equations.
99 * @details The Newton-like methods typically solve linear systems of the form
100 * f'(x) x = -f(x),
101 * where f'(x) denotes the Jacobian matrix and f(x) is the function.
102 * @param[in] r Vector to store function values
103 * @param[in] f Function evaluation routine; see SNESFunction for calling sequence details
104 * @param[in] ctx [optional] User-defined context for private data for the function evaluation routine (may be NULL)
105 */
106 void setFunction(
107 PetscVector& r,
108 PetscErrorCode (*f)(SNES,Vec,Vec,void*),
109 void* ctx = nullptr
110 );
111
112 /**
113 * @brief Sets the function to compute Jacobian as well as the location to store the matrix.
114 * @param[in] Amat The matrix that defines the (approximate) Jacobian
115 * @param[in] Pmat The matrix to be used in constructing the preconditioner, usually the same as Amat.
116 * @param[in] J Jacobian evaluation routine (if NULL then SNES retains any previously set value), see SNESJacobianFunction for details
117 * @param[in] ctx [optional] User-defined context for private data for the Jacobian evaluation routine (may be NULL) (if NULL then SNES retains any previously set value)
118 */
119 void setJacobian(
120 PetscMatrix& Amat,
121 PetscMatrix& Pmat,
122 PetscErrorCode (*J)(SNES,Vec,Mat,Mat,void*),
123 void* ctx = nullptr
124 );
125
126 /**
127 * @brief Returns the vector where the solution update is stored.
128 * @param[in,out] rDeltaX Vector to store the solution increment
129 */
130 void getSolutionUpdate(PetscVector& rDeltaX);
131
132 /**
133 * @brief Sets various SNES and KSP parameters from user options
134 */
135 void setFromOptions()
136 {
137 SNESSetFromOptions(m_SNES);
138 }
139
140 /**
141 * @brief Returns the KSP context for a SNES solver.
142 * @note Krylov method: https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/index.html
143 * @param[in,out] pKSP The KSP context
144 */
145 void getKSP(KSP* pKSP);
146
147 /**
148 * @brief Sets an ADDITIONAL function that is to be used at every iteration of the nonlinear solver to display the iteration's progress.
149 * @param[in] pLinearProblem The linear problem to be solved
150 */
151 void setMonitorSetLinearProblem(LinearProblem* pLinearProblem);
152
153 /**
154 * @brief This method sets the tolerances for the SNES solver with the given values
155 * @note https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/SNES/SNESSetTolerances.html
156 * @param[in] absoluteTolerance Absolute convergence tolerance
157 * @param[in] relativeTolerance Relative convergence tolerance
158 * @param[in] solutionTolerance Convergence tolerance in terms of the norm of the change in the solution between steps, || delta x || < stol*|| x ||
159 * @param[in] maxIterationSNES Maximum number of iterations
160 * @param[in] maxFunctionEvaluatedSNES Maximum number of function evaluations (-1 indicates no limit)
161 * @param[in] divergenceTolerance Divergence tolerance
162 */
163 void setTolerances(
164 const double absoluteTolerance,
165 const double relativeTolerance,
166 const double solutionTolerance,
167 const int maxIterationSNES,
168 const int maxFunctionEvaluatedSNES,
169 const double divergenceTolerance
170 );
171
172 /**
173 * @brief This function solves using the SNES object
174 * @param[in,out] rX The vector to be solved
175 * @return The number of SNES iterations
176 */
177 PetscInt solve(PetscVector& rX);
178
179 ///@}
180 ///@name Access
181 ///@{
182
183 /**
184 * @brief This function returns if the SNES object must be used or not
185 * @return true if the SNES object must be used, false otherwise
186 */
187 37926 bool& doUseSNES()
188 {
189 37926 return m_doUseSNES;
190 }
191
192 /**
193 * @brief This function returns if the SNES object must be used or not
194 * @return true if the SNES object must be used, false otherwise
195 */
196 bool doUseSNES() const
197 {
198 return m_doUseSNES;
199 }
200
201 /**
202 * @brief This function returns the SNES object
203 * @return The SNES object
204 */
205 SNES& getSNES()
206 {
207 return m_SNES;
208 }
209
210 /**
211 * @brief This function returns the SNES object (const version)
212 * @return The SNES object
213 */
214 const SNES& getSNES() const
215 {
216 return m_SNES;
217 }
218
219 ///@}
220 ///@name Inquiry
221 ///@{
222
223 ///@}
224 ///@name Input and output
225 ///@{
226
227 ///@}
228 ///@name Friends
229 ///@{
230
231 friend class KSPInterface;
232
233 ///@}
234 protected:
235 ///@name Protected static Member Variables
236 ///@{
237
238 ///@}
239 ///@name Protected member Variables
240 ///@{
241
242 ///@}
243 ///@name Protected Operators
244 ///@{
245
246 ///@}
247 ///@name Protected Operations
248 ///@{
249
250 ///@}
251 ///@name Protected Access
252 ///@{
253
254 ///@}
255 ///@name Protected Inquiry
256 ///@{
257
258 ///@}
259 ///@name Protected LifeCycle
260 ///@{
261
262 ///@}
263 private:
264 ///@name Private static Member Variables
265 ///@{
266
267 ///@}
268 ///@name Private member Variables
269 ///@{
270
271 bool m_doUseSNES = false; /// Flag to use the SNES solver (auxiliary)
272
273 SNES m_SNES; /// Nonlinear solver
274
275 MPI_Comm m_comm = MPI_COMM_NULL; /// The MPI communicator
276
277 ///@}
278 ///@name Private Operators
279 ///@{
280
281 ///@}
282 ///@name Private Operations
283 ///@{
284
285 ///@}
286 ///@name Private Access
287 ///@{
288
289 ///@}
290 ///@name Private Inquiry
291 ///@{
292
293 ///@}
294 ///@name Private LifeCycle
295 ///@{
296
297 ///@}
298 };
299
300 ///@}
301 ///@name Type Definitions
302 ///@{
303
304 ///@}
305
306 }
307
308 #endif // SNES_INTERFACE_HPP
309