Debian Codegraph @

include/deal.II/lac/petsc_matrix_free.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2012 - 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 #ifndef dealii_petsc_matrix_free_h
16 #define dealii_petsc_matrix_free_h
17
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_PETSC
22 # include <deal.II/lac/exceptions.h>
23 # include <deal.II/lac/petsc_matrix_base.h>
24 # include <deal.II/lac/petsc_vector.h>
25 DEAL_II_NAMESPACE_OPEN
26
27
28
29 namespace PETScWrappers
30 {
31 /**
32 * Implementation of a parallel matrix class based on PETSc
33 * <tt>MatShell</tt> matrix-type. This base class implements only the
34 * interface to the PETSc matrix object, while all the functionality is
35 * contained in the matrix-vector multiplication which must be reimplemented
36 * in derived classes.
37 *
38 * This interface is an addition to the dealii::MatrixFree class to realize
39 * user-defined matrix-classes together with PETSc solvers and
40 * functionalities. See also the documentation of dealii::MatrixFree class
41 * and step-37 and step-48.
42 *
43 * Similar to other matrix classes in namespaces PETScWrappers and
44 * PETScWrappers::MPI, the MatrixFree class provides the usual matrix-vector
45 * multiplication <tt>vmult(VectorBase &dst, const VectorBase &src)</tt>
46 * which is pure virtual and must be reimplemented in derived classes.
47 * Besides the usual interface, this class has a matrix-vector
48 * multiplication <tt>vmult(Vec &dst, const Vec &src)</tt> taking PETSc Vec
49 * objects, which will be called by <tt>matrix_free_mult(Mat A, Vec src, Vec
50 * dst)</tt> registered as matrix-vector multiplication of this PETSc matrix
51 * object. The default implementation of the vmult function in the base
52 * class wraps the given PETSc vectors with the PETScWrappers::VectorBase
53 * class and then calls the usual vmult function with the usual interface.
54 *
55 * @ingroup PETScWrappers
56 * @ingroup Matrix1
57 */
58 class MatrixFree : public MatrixBase
59 {
60 public:
61 /**
62 * Default constructor. Create an empty matrix object.
63 */
64 MatrixFree();
65
66 /**
67 * Create a matrix object of dimensions @p m times @p n with communication
68 * happening over the provided @p communicator.
69 *
70 * For the meaning of the @p local_rows and @p local_columns parameters,
71 * see the PETScWrappers::MPI::SparseMatrix class documentation.
72 *
73 * As other PETSc matrices, also the matrix-free object needs to have
74 * a size and to perform matrix vector multiplications efficiently in
75 * parallel also @p local_rows and @p local_columns. But in contrast to
76 * PETSc::SparseMatrix classes a PETSc matrix-free object does not need
77 * any estimation of non_zero entries and has no option
78 * <tt>is_symmetric</tt>.
79 */
80 MatrixFree(const MPI_Comm communicator,
81 const unsigned int m,
82 const unsigned int n,
83 const unsigned int local_rows,
84 const unsigned int local_columns);
85
86 /**
87 * Create a matrix object of dimensions @p m times @p n with communication
88 * happening over the provided @p communicator.
89 *
90 * As other PETSc matrices, also the matrix-free object needs to have
91 * a size and to perform matrix vector multiplications efficiently in
92 * parallel also @p local_rows and @p local_columns. But in contrast to
93 * PETSc::SparseMatrix classes a PETSc matrix-free object does not need
94 * any estimation of non_zero entries and has no option
95 * <tt>is_symmetric</tt>.
96 */
97 MatrixFree(const MPI_Comm communicator,
98 const unsigned int m,
99 const unsigned int n,
100 const std::vector<unsigned int> &local_rows_per_process,
101 const std::vector<unsigned int> &local_columns_per_process,
102 const unsigned int this_process);
103
104 /**
105 * Constructor for the serial case: Same function as
106 * <tt>MatrixFree()</tt>, see above, with <tt>communicator =
107 * MPI_COMM_WORLD</tt>.
108 */
109 MatrixFree(const unsigned int m,
110 const unsigned int n,
111 const unsigned int local_rows,
112 const unsigned int local_columns);
113
114 /**
115 * Constructor for the serial case: Same function as
116 * <tt>MatrixFree()</tt>, see above, with <tt>communicator =
117 * MPI_COMM_WORLD</tt>.
118 */
119 MatrixFree(const unsigned int m,
120 const unsigned int n,
121 const std::vector<unsigned int> &local_rows_per_process,
122 const std::vector<unsigned int> &local_columns_per_process,
123 const unsigned int this_process);
124
125 /**
126 * Throw away the present matrix and generate one that has the same
127 * properties as if it were created by the constructor of this class with
128 * the same argument list as the present function.
129 */
130 void
131 reinit(const MPI_Comm communicator,
132 const unsigned int m,
133 const unsigned int n,
134 const unsigned int local_rows,
135 const unsigned int local_columns);
136
137 /**
138 * Throw away the present matrix and generate one that has the same
139 * properties as if it were created by the constructor of this class with
140 * the same argument list as the present function.
141 */
142 void
143 reinit(const MPI_Comm communicator,
144 const unsigned int m,
145 const unsigned int n,
146 const std::vector<unsigned int> &local_rows_per_process,
147 const std::vector<unsigned int> &local_columns_per_process,
148 const unsigned int this_process);
149
150 /**
151 * Call the @p reinit() function above with <tt>communicator =
152 * MPI_COMM_WORLD</tt>.
153 */
154 void
155 reinit(const unsigned int m,
156 const unsigned int n,
157 const unsigned int local_rows,
158 const unsigned int local_columns);
159
160 /**
161 * Call the @p reinit() function above with <tt>communicator =
162 * MPI_COMM_WORLD</tt>.
163 */
164 void
165 reinit(const unsigned int m,
166 const unsigned int n,
167 const std::vector<unsigned int> &local_rows_per_process,
168 const std::vector<unsigned int> &local_columns_per_process,
169 const unsigned int this_process);
170
171 /**
172 * Release all memory and return to a state just like after having called
173 * the default constructor.
174 */
175 void
176 clear();
177
178 /**
179 * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i>
180 * being this matrix.
181 *
182 * Source and destination must not be the same vector.
183 *
184 * Note that if the current object represents a parallel distributed
185 * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
186 * have to be distributed vectors as well. Conversely, if the matrix is
187 * not distributed, then neither of the vectors may be.
188 */
189 virtual void
190 vmult(VectorBase &dst, const VectorBase &src) const = 0;
191
192 /**
193 * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
194 * <i>M</i> being this matrix. This function does the same as @p vmult()
195 * but takes the transposed matrix.
196 *
197 * Source and destination must not be the same vector.
198 *
199 * Note that if the current object represents a parallel distributed
200 * matrix then both vectors have to be distributed vectors as well.
201 * Conversely, if the matrix is not distributed, then neither of the
202 * vectors may be.
203 */
204 virtual void
205 Tvmult(VectorBase &dst, const VectorBase &src) const = 0;
206
207 /**
208 * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i>
209 * with <i>M</i> being this matrix.
210 *
211 * Source and destination must not be the same vector.
212 *
213 * Note that if the current object represents a parallel distributed
214 * matrix then both vectors have to be distributed vectors as well.
215 * Conversely, if the matrix is not distributed, then neither of the
216 * vectors may be.
217 */
218 virtual void
219 vmult_add(VectorBase &dst, const VectorBase &src) const = 0;
220
221 /**
222 * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
223 * <i>dst</i> with <i>M</i> being this matrix. This function does the same
224 * as @p vmult_add() but takes the transposed matrix.
225 *
226 * Source and destination must not be the same vector.
227 *
228 * Note that if the current object represents a parallel distributed
229 * matrix then both vectors have to be distributed vectors as well.
230 * Conversely, if the matrix is not distributed, then neither of the
231 * vectors may be.
232 */
233 virtual void
234 Tvmult_add(VectorBase &dst, const VectorBase &src) const = 0;
235
236 /**
237 * The matrix-vector multiplication called by @p matrix_free_mult(). This
238 * function can be reimplemented in derived classes for efficiency. The
239 * default implementation copies the given vectors into
240 * PETScWrappers::*::Vector and calls <tt>vmult(VectorBase &dst, const
241 * VectorBase &src)</tt> which is purely virtual and must be reimplemented
242 * in derived classes.
243 */
244 virtual void
245 vmult(Vec &dst, const Vec &src) const;
246
247 private:
248 /**
249 * Callback-function registered as the matrix-vector multiplication of
250 * this matrix-free object called by PETSc routines. This function must be
251 * static and takes a PETSc matrix @p A, and vectors @p src and @p dst,
252 * where <i>dst = A*src</i>
253 *
254 * Source and destination must not be the same vector.
255 *
256 * This function calls <tt>vmult(Vec &dst, const Vec &src)</tt> which
257 * should be reimplemented in derived classes.
258 */
259 static int
260 matrix_free_mult(Mat A, Vec src, Vec dst);
261
262 /**
263 * Do the actual work for the respective @p reinit() function and the
264 * matching constructor, i.e. create a matrix object. Getting rid of the
265 * previous matrix is left to the caller.
266 */
267 void
268 do_reinit(const MPI_Comm comm,
269 const unsigned int m,
270 const unsigned int n,
271 const unsigned int local_rows,
272 const unsigned int local_columns);
273 };
274
275
276
277 } // namespace PETScWrappers
278
279 DEAL_II_NAMESPACE_CLOSE
280
281 #else
282
283 // Make sure the scripts that create the C++20 module input files have
284 // something to latch on if the preprocessor #ifdef above would
285 // otherwise lead to an empty content of the file.
286 DEAL_II_NAMESPACE_OPEN
287 DEAL_II_NAMESPACE_CLOSE
288
289 #endif // DEAL_II_WITH_PETSC
290
291 #endif