Debian Codegraph @

include/deal.II/lac/petsc_compatibility.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2016 - 2025 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 * Rather than using ifdefs everywhere, try to wrap older versions of PETSc
17 * functions in one place.
18 *
19 * Functions that are not inlined are:
20 * - Functions returning PetscErrorCode that are supposed to be called within
21 * PETSc callbacks.
22 * - Functions that need access to internal PETSc headers that we don't want
23 * to expose to deal.II users
24 */
25 #ifndef dealii_petsc_compatibility_h
26 #define dealii_petsc_compatibility_h
27
28 #include <deal.II/base/config.h>
29
30 #include <deal.II/lac/exceptions.h>
31
32 #ifdef DEAL_II_WITH_PETSC
33
34 # include <petscksp.h>
35 # include <petscmat.h>
36 # include <petscpc.h>
37 # include <petscsnes.h>
38 # include <petscts.h>
39 # if DEAL_II_PETSC_VERSION_LT(3, 19, 0)
40 # define PETSC_SUCCESS 0
41 # endif
42
43 # include <string>
44
45 DEAL_II_NAMESPACE_OPEN
46
47 namespace PETScWrappers
48 {
49 /**
50 * Set an option in the global PETSc database. This function just wraps
51 * PetscOptionsSetValue and checks the error return value.
52 */
53 inline void
54 set_option_value(const std::string &name, const std::string &value)
55 {
56 const PetscErrorCode ierr =
57 PetscOptionsSetValue(nullptr, name.c_str(), value.c_str());
58 AssertThrow(ierr == 0, ExcPETScError(ierr));
59 }
60
61
62
63 /**
64 * Set a PETSc matrix option. This function wraps MatSetOption with a
65 * version check.
66 *
67 * @warning The argument option_value is ignored in versions of PETSc
68 * before 3.0.0 since the corresponding function did not take this argument.
69 */
70 inline void
71 set_matrix_option(Mat &matrix,
72 const MatOption option_name,
73 const PetscBool option_value = PETSC_FALSE)
74 {
75 const PetscErrorCode ierr = MatSetOption(matrix, option_name, option_value);
76 AssertThrow(ierr == 0, ExcPETScError(ierr));
77 }
78
79
80
81 /**
82 * Tell PETSc that we are not planning on adding new entries to the
83 * matrix. Generate errors in debug mode.
84 */
85 inline void
86 close_matrix(Mat &matrix)
87 {
88 if constexpr (running_in_debug_mode())
89 {
90 set_matrix_option(matrix, MAT_NEW_NONZERO_LOCATION_ERR, PETSC_TRUE);
91 }
92 else
93 {
94 set_matrix_option(matrix, MAT_NEW_NONZERO_LOCATIONS, PETSC_FALSE);
95 }
96 }
97
98
99
100 /**
101 * Tell PETSc to keep the SparsityPattern entries even if we delete a
102 * row with clear_rows() which calls MatZeroRows(). Otherwise one can
103 * not write into that row afterwards.
104 */
105 inline void
106 set_keep_zero_rows(Mat &matrix)
107 {
108 set_matrix_option(matrix, MAT_KEEP_NONZERO_PATTERN, PETSC_TRUE);
109 }
110
111
112
113 /**
114 * Tell PETSc that the status of the vector has changed.
115 */
116 void
117 petsc_increment_state_counter(Vec v);
118
119
120
121 /**
122 * Tell PETSc that the status of the matrix has changed.
123 */
124 void
125 petsc_increment_state_counter(Mat A);
126
127
128 /**
129 * Set the failed reason for the preconditioner.
130 */
131 PetscErrorCode
132 pc_set_failed_reason(PC pc, PCFailedReason reason);
133
134
135
136 /**
137 * Resets internal domain error flags in the SNES object.
138 */
139 void
140 snes_reset_domain_flags(SNES snes);
141
142
143
144 /**
145 * Resets internal domain error flags in the SNES object.
146 */
147 void
148 snes_set_jacobian_domain_error(SNES snes);
149
150
151
152 /**
153 * Tell PETSc nonlinear solver to use matrix free finite differencing (MFFD).
154 *
155 * @p mf_operator indicates to use MFFD for the linear system matrix
156 * but use a user defined matrix for preconditioning purposed.
157 *
158 * @p mf indicates to use MFFD for the both the linear system matrix
159 * and the preconditioning matrix.
160 */
161 void
162 set_use_matrix_free(SNES snes, const bool mf_operator, const bool mf);
163
164
165
166 /**
167 * Tell PETSc ODE solver to use matrix free finite differencing (MFFD).
168 *
169 * @p mf_operator indicates to use MFFD for the linear system matrix
170 * but use a user defined matrix for preconditioning purposed.
171 *
172 * @p mf indicates to use MFFD for the both the linear system matrix
173 * and the preconditioning matrix.
174 */
175 void
176 set_use_matrix_free(TS ts, const bool mf_operator, const bool mf);
177
178
179
180 /**
181 * Reset DM (no public API).
182 */
183 void
184 ts_reset_dm(TS ts);
185
186
187
188 /**
189 * Set final time for ODE integration.
190 */
191 void
192 ts_set_max_time(TS ts, const PetscReal maxtime);
193
194
195
196 /**
197 * Set maximum number of steps for ODE integration.
198 */
199 void
200 ts_set_max_steps(TS ts, const PetscInt maxsteps);
201
202
203
204 /**
205 * Return current step number.
206 */
207 unsigned int
208 ts_get_step_number(TS ts);
209
210
211
212 /**
213 * Return true if the TS has a SNES object.
214 */
215 bool
216 ts_has_snes(TS ts);
217
218 } // namespace PETScWrappers
219
220 DEAL_II_NAMESPACE_CLOSE
221
222 #else
223
224 // Make sure the scripts that create the C++20 module input files have
225 // something to latch on if the preprocessor #ifdef above would
226 // otherwise lead to an empty content of the file.
227 DEAL_II_NAMESPACE_OPEN
228 DEAL_II_NAMESPACE_CLOSE
229
230 #endif // DEAL_II_WITH_PETSC
231 #endif // dealii_petsc_compatibility_h