Debian Codegraph @

include/deal.II/lac/diagonal_matrix.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 #ifndef dealii_diagonal_matrix_h
16 #define dealii_diagonal_matrix_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/lac/vector.h>
22 #include <deal.II/lac/vector_operation.h>
23
24 DEAL_II_NAMESPACE_OPEN
25
26 // forward declarations
27 #ifndef DOXYGEN
28 template <typename number>
29 class Vector;
30 namespace LinearAlgebra
31 {
32 namespace distributed
33 {
34 template <typename, typename>
35 class Vector;
36 } // namespace distributed
37 } // namespace LinearAlgebra
38 #endif
39
40 /**
41 * This class represents a <i>n x n</i> diagonal matrix based on a vector of
42 * size <i>n</i>. The matrix-vector products are realized by @p
43 * VectorType::scale, so the template vector class needs to provide a
44 * @p scale() method.
45 *
46 * When using this class with AffineConstraints::distribute_local_to_global(),
47 * the underlying vector needs to provide write access to all entries referenced
48 * by cells in an assembly process. This means that this class also needs access
49 * to ghost entries that are owned by other processors than the calling one.
50 * In practice this requires initialization of the vector as follows
51 * @code
52 * DiagonalMatrix<LinearAlgebra::distributed::Vector<double> > diagonal_matrix;
53 * LinearAlgebra::distributed::Vector<double> &diagonal_vector =
54 * diagonal_matrix.get_vector();
55 * diagonal_vector.reinit(locally_owned_dofs,
56 * locally_relevant_dofs,
57 * mpi_communicator);
58 * @endcode
59 */
60 template <typename VectorType = Vector<double>>
61 class DiagonalMatrix : public EnableObserverPointer
62 {
63 public:
64 using value_type = typename VectorType::value_type;
65 using size_type = typename VectorType::size_type;
66
67 /**
68 * Default constructor. The object needs still to be reinitialized to be
69 * usable.
70 */
71 DiagonalMatrix() = default;
72
73 /**
74 * Constructor initializing this object as a diagonal matrix of size `n x n`
75 * where `n` is the size of the vector, and with diagonal entries equal to the
76 * elements of @p vec.
77 */
78 explicit DiagonalMatrix(const VectorType &vec);
79
80 /**
81 * Initialize with a given vector by copying the content of the vector
82 * @p vec.
83 */
84 void
85 reinit(const VectorType &vec);
86
87 /**
88 * Compresses the data structures and allows the resulting matrix to be used
89 * in all other operations like matrix-vector products. This is a collective
90 * operation, i.e., it needs to be run on all processors when used in
91 * parallel.
92 */
93 void
94 compress(VectorOperation::values operation);
95
96 /**
97 * Return a reference to the underlying vector for manipulation of the
98 * entries on the matrix diagonal.
99 */
100 VectorType &
101 get_vector();
102
103 /**
104 * Clear content of this object and reset to the state of default constructor.
105 */
106 void
107 clear();
108
109 /**
110 * Return a read-only reference to the underlying vector.
111 */
112 const VectorType &
113 get_vector() const;
114
115 /**
116 * Number of rows of this matrix. This number corresponds to the size of the
117 * underlying vector.
118 */
119 size_type
120 m() const;
121
122 /**
123 * Number of columns of this matrix. This number corresponds to the size of
124 * the underlying vector.
125 */
126 size_type
127 n() const;
128
129 /**
130 * Read-only access to a value. This is restricted to the case where
131 * <i>i==j</i> due to the matrix storage.
132 *
133 * If the vector representing the diagonal is distributed with MPI, not all
134 * of the indices <i>i</i> might actually be accessible. Refer to the method
135 * <code>get_vector().locally_owned_elements()</code> for the entries that
136 * actually are accessible.
137 */
138 value_type
139 operator()(const size_type i, const size_type j) const;
140
141 /**
142 * Read-write access to a value. This is restricted to the case where
143 * <i>i==j</i> due to the matrix storage.
144 *
145 * If the vector representing the diagonal is distributed with MPI, not all
146 * of the indices <i>i</i> might actually be accessible. Refer to the method
147 * <code>get_vector().locally_owned_elements()</code> for the entries that
148 * actually are accessible.
149 */
150 value_type &
151 operator()(const size_type i, const size_type j);
152
153 /**
154 * Add an array of values given by <tt>values</tt> in the given global
155 * matrix row at columns specified by col_indices. Due to the storage of
156 * this matrix, entries are only added to the diagonal of the matrix. All
157 * other entries are ignored and no exception is thrown.
158 *
159 * This function is for a consistent interface with the other matrix
160 * classes in deal.II and can be used in
161 * AffineConstraints::distribute_local_to_global to get exactly the same
162 * diagonal as when assembling into a sparse matrix.
163 */
164 template <typename number2>
165 void
166 add(const size_type row,
167 const size_type n_cols,
168 const size_type *col_indices,
169 const number2 *values,
170 const bool elide_zero_values = true,
171 const bool col_indices_are_sorted = false);
172
173 /**
174 * Add value to the element (i,j).
175 *
176 * Due to the storage of this matrix, entries are only added to the diagonal
177 * of the matrix. All other entries are ignored and no exception is thrown.
178 */
179 void
180 add(const size_type i, const size_type j, const value_type value);
181
182 /**
183 * Performs a matrix-vector multiplication with the given matrix.
184 */
185 void
186 vmult(VectorType &dst, const VectorType &src) const;
187
188 /**
189 * Performs a transpose matrix-vector multiplication with the given
190 * matrix. Since this represents a diagonal matrix, exactly the same as
191 * vmult().
192 */
193 void
194 Tvmult(VectorType &dst, const VectorType &src) const;
195
196 /**
197 * Adds the result of a matrix-vector multiplication into the destination
198 * vector dst. Needs to create a temporary vector, which makes performance
199 * slower than for @p vmult().
200 */
201 void
202 vmult_add(VectorType &dst, const VectorType &src) const;
203
204 /**
205 * Adds the result of a transpose matrix-vector multiplication into the
206 * destination vector dst. Needs to create a temporary vector, which makes
207 * performance slower than for @p Tvmult().
208 */
209 void
210 Tvmult_add(VectorType &dst, const VectorType &src) const;
211
212 /**
213 * Apply the preconditioner to a single vector entry. Note that index of the
214 * unknown needs to be expressed by an MPI-local index as it would be
215 * accessed in the action on a vector.
216 */
217 value_type
218 apply(const unsigned int index, const value_type src) const;
219
220 /**
221 * Apply the preconditioner only to a subrange of elements in an array
222 * `src`, and store the result in another array `dst`, for compatibility
223 * with classes support vector operations on a slice of entries, such as
224 * SolverCG or PreconditionChebyshev. Note that the range indicates
225 * MPI-local indices as they would be accessed in the action on a
226 * vector. The pointers are supposed to point to the beginning of the given
227 * range.
228 */
229 void
230 apply_to_subrange(const unsigned int begin_range,
231 const unsigned int end_range,
232 const value_type *src_pointer_to_current_range,
233 value_type *dst_pointer_to_current_range) const;
234
235 /**
236 * Initialize vector @p dst to have the same size and partition as
237 * @p diagonal member of this class.
238 *
239 * This is a part of the interface required
240 * by linear_operator().
241 */
242 void
243 initialize_dof_vector(VectorType &dst) const;
244
245 /**
246 * Return the memory consumption of this object.
247 */
248 std::size_t
249 memory_consumption() const;
250
251 private:
252 /**
253 * The stored vector.
254 */
255 VectorType diagonal;
256 };
257
258 /* ---------------------------------- Inline functions ------------------- */
259
260 #ifndef DOXYGEN
261
262 template <typename VectorType>
263 DiagonalMatrix<VectorType>::DiagonalMatrix(const VectorType &vec)
264 : diagonal(vec)
265 {}
266
267
268
269 template <typename VectorType>
270 void
271 DiagonalMatrix<VectorType>::clear()
272 {
273 diagonal.reinit(0);
274 }
275
276
277
278 template <typename VectorType>
279 std::size_t
280 DiagonalMatrix<VectorType>::memory_consumption() const
281 {
282 return diagonal.memory_consumption();
283 }
284
285
286
287 template <typename VectorType>
288 void
289 DiagonalMatrix<VectorType>::reinit(const VectorType &vec)
290 {
291 diagonal = vec;
292 }
293
294
295
296 template <typename VectorType>
297 void
298 DiagonalMatrix<VectorType>::initialize_dof_vector(VectorType &dst) const
299 {
300 dst.reinit(diagonal);
301 }
302
303
304
305 template <typename VectorType>
306 void
307 DiagonalMatrix<VectorType>::compress(VectorOperation::values operation)
308 {
309 diagonal.compress(operation);
310 }
311
312
313
314 template <typename VectorType>
315 VectorType &
316 DiagonalMatrix<VectorType>::get_vector()
317 {
318 return diagonal;
319 }
320
321
322
323 template <typename VectorType>
324 const VectorType &
325 DiagonalMatrix<VectorType>::get_vector() const
326 {
327 return diagonal;
328 }
329
330
331
332 template <typename VectorType>
333 typename VectorType::size_type
334 DiagonalMatrix<VectorType>::m() const
335 {
336 return diagonal.size();
337 }
338
339
340
341 template <typename VectorType>
342 typename VectorType::size_type
343 DiagonalMatrix<VectorType>::n() const
344 {
345 return diagonal.size();
346 }
347
348
349
350 template <typename VectorType>
351 typename VectorType::value_type
352 DiagonalMatrix<VectorType>::operator()(const size_type i,
353 const size_type j) const
354 {
355 Assert(i == j, ExcIndexRange(j, i, i + 1));
356 return diagonal(i);
357 }
358
359
360
361 template <typename VectorType>
362 typename VectorType::value_type &
363 DiagonalMatrix<VectorType>::operator()(const size_type i, const size_type j)
364 {
365 Assert(i == j, ExcIndexRange(j, i, i + 1));
366 return diagonal(i);
367 }
368
369
370
371 template <typename VectorType>
372 template <typename number2>
373 void
374 DiagonalMatrix<VectorType>::add(const size_type row,
375 const size_type n_cols,
376 const size_type *col_indices,
377 const number2 *values,
378 const bool,
379 const bool)
380 {
381 for (size_type i = 0; i < n_cols; ++i)
382 if (col_indices[i] == row)
383 diagonal(row) += values[i];
384 }
385
386
387
388 template <typename VectorType>
389 void
390 DiagonalMatrix<VectorType>::add(const size_type i,
391 const size_type j,
392 const value_type value)
393 {
394 if (i == j)
395 diagonal(i) += value;
396 }
397
398
399
400 namespace internal
401 {
402 namespace DiagonalMatrix
403 {
404 template <typename VectorType>
405 void
406 assign_and_scale(VectorType &dst,
407 const VectorType &src,
408 const VectorType &diagonal)
409 {
410 dst = src;
411 dst.scale(diagonal);
412 }
413
414 template <typename Number>
415 void
416 assign_and_scale(
417 LinearAlgebra::distributed::Vector<Number, MemorySpace::Host> &dst,
418 const LinearAlgebra::distributed::Vector<Number, MemorySpace::Host> &src,
419 const LinearAlgebra::distributed::Vector<Number, MemorySpace::Host>
420 &diagonal)
421 {
422 auto *const dst_ptr = dst.begin();
423 const auto *const src_ptr = src.begin();
424 const auto *const diagonal_ptr = diagonal.begin();
425
426 DEAL_II_OPENMP_SIMD_PRAGMA
427 for (unsigned int i = 0; i < src.locally_owned_size(); ++i)
428 dst_ptr[i] = src_ptr[i] * diagonal_ptr[i];
429 }
430 } // namespace DiagonalMatrix
431 } // namespace internal
432
433
434
435 template <typename VectorType>
436 void
437 DiagonalMatrix<VectorType>::vmult(VectorType &dst, const VectorType &src) const
438 {
439 internal::DiagonalMatrix::assign_and_scale(dst, src, diagonal);
440 }
441
442
443
444 template <typename VectorType>
445 void
446 DiagonalMatrix<VectorType>::Tvmult(VectorType &dst, const VectorType &src) const
447 {
448 vmult(dst, src);
449 }
450
451
452
453 template <typename VectorType>
454 void
455 DiagonalMatrix<VectorType>::vmult_add(VectorType &dst,
456 const VectorType &src) const
457 {
458 VectorType tmp(src);
459 tmp.scale(diagonal);
460 dst += tmp;
461 }
462
463
464
465 template <typename VectorType>
466 void
467 DiagonalMatrix<VectorType>::Tvmult_add(VectorType &dst,
468 const VectorType &src) const
469 {
470 vmult_add(dst, src);
471 }
472
473
474
475 template <typename VectorType>
476 typename VectorType::value_type
477 DiagonalMatrix<VectorType>::apply(const unsigned int index,
478 const value_type src) const
479 {
480 AssertIndexRange(index, diagonal.locally_owned_elements().n_elements());
481 return diagonal.local_element(index) * src;
482 }
483
484
485
486 template <typename VectorType>
487 void
488 DiagonalMatrix<VectorType>::apply_to_subrange(
489 const unsigned int begin_range,
490 const unsigned int end_range,
491 const value_type *src_pointer_to_current_range,
492 value_type *dst_pointer_to_current_range) const
493 {
494 AssertIndexRange(begin_range,
495 diagonal.locally_owned_elements().n_elements() + 1);
496 AssertIndexRange(end_range,
497 diagonal.locally_owned_elements().n_elements() + 1);
498
499 const value_type *diagonal_entry = diagonal.begin() + begin_range;
500 const unsigned int length = end_range - begin_range;
501
502 DEAL_II_OPENMP_SIMD_PRAGMA
503 for (unsigned int i = 0; i < length; ++i)
504 dst_pointer_to_current_range[i] =
505 diagonal_entry[i] * src_pointer_to_current_range[i];
506 }
507
508
509 #endif
510
511 DEAL_II_NAMESPACE_CLOSE
512
513 #endif