Debian Codegraph @

include/deal.II/lac/full_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_full_matrix_h
16 #define dealii_full_matrix_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/numbers.h>
22 #include <deal.II/base/table.h>
23 #include <deal.II/base/tensor.h>
24
25 #include <deal.II/lac/exceptions.h>
26 #include <deal.II/lac/identity_matrix.h>
27 #include <deal.II/lac/vector_operation.h>
28
29 #include <cstring>
30 #include <iomanip>
31 #include <vector>
32
33 DEAL_II_NAMESPACE_OPEN
34
35
36 // forward declarations
37 #ifndef DOXYGEN
38 template <typename number>
39 class Vector;
40 template <typename number>
41 class LAPACKFullMatrix;
42 #endif
43
44 /**
45 * @addtogroup Matrix1
46 * @{
47 */
48
49
50 /**
51 * This class implements a rectangular, dense ("full") matrix, that is,
52 * a matrix where we store every element whether it is zero or
53 * nonzero. This is in contrast to the SparseMatrix and related
54 * classes, which store a "sparse" representation in which memory is
55 * only allocated for those elements for which it is known that they
56 * are (or, more precisely, could be) nonzero.
57 *
58 * The data type of the entries of the matrix is provided by the
59 * template argument <tt>number</tt>.
60 *
61 * This class provides a number of operations that involve both the
62 * current matrix and either another matrix or one or more
63 * vectors. Each of these other objects may store their elements in a
64 * different data type than the current object does (again, as
65 * indicated by the corresponding template arguments of the other
66 * objects). In these cases, internal calculations are usually done
67 * with the accuracy of the vector argument, or with the more accurate
68 * of the data types.
69 *
70 * @note Instantiations for this template are provided for <tt>@<float@>,
71 * @<double@>, @<std::complex@<float@>@>,
72 * @<std::complex@<double@>@></tt>. Others can be generated in application
73 * programs, see
74 * @ref Instantiations
75 * for details.
76 */
77 template <typename number>
78 class FullMatrix : public Table<2, number>
79 {
80 public:
81 /**
82 * This class only supports basic numeric types (i.e., we support double and
83 * float but not automatically differentiated numbers).
84 *
85 * @note we test real_type here to get the underlying scalar type when using
86 * std::complex.
87 */
88 static_assert(
89 std::is_arithmetic_v<typename numbers::NumberTraits<number>::real_type>,
90 "The FullMatrix class only supports basic numeric types. In particular, it "
91 "does not support automatically differentiated numbers.");
92
93
94 /**
95 * A type of used to index into this container.
96 */
97 using size_type = std::size_t;
98
99 /**
100 * Type of matrix entries. This alias is analogous to <tt>value_type</tt>
101 * in the standard library containers.
102 */
103 using value_type = number;
104
105 /**
106 * Use the base class mutable iterator type.
107 */
108 using iterator = typename Table<2, number>::iterator;
109
110 /**
111 * Use the base class constant iterator type.
112 */
113 using const_iterator = typename Table<2, number>::const_iterator;
114
115 /**
116 * Use the base class iterator functions.
117 */
118 using Table<2, number>::begin;
119
120 /**
121 * Use the base class iterator functions
122 */
123 using Table<2, number>::end;
124
125 /**
126 * Declare a type that has holds real-valued numbers with the same precision
127 * as the template argument to this class. If the template argument of this
128 * class is a real data type, then real_type equals the template argument.
129 * If the template argument is a std::complex type then real_type equals the
130 * type underlying the complex numbers.
131 *
132 * This alias is used to represent the return type of norms.
133 */
134 using real_type = typename numbers::NumberTraits<number>::real_type;
135
136 /**
137 * @name Constructors and initialization. See also the base class Table.
138 */
139 /** @{ */
140
141 /**
142 * Constructor. Initialize the matrix as a square matrix with dimension
143 * <tt>n</tt>.
144 *
145 * In order to avoid the implicit conversion of integers and other types to
146 * a matrix, this constructor is declared <tt>explicit</tt>.
147 *
148 * By default, no memory is allocated.
149 */
150 explicit FullMatrix(const size_type n = 0);
151
152 /**
153 * Constructor. Initialize the matrix as a rectangular matrix.
154 */
155 FullMatrix(const size_type rows, const size_type cols);
156
157 /**
158 * Constructor initializing from an array of numbers. The array is arranged
159 * line by line. No range checking is performed.
160 */
161 FullMatrix(const size_type rows, const size_type cols, const number *entries);
162
163 /**
164 * Construct a full matrix that equals the identity matrix of the size of
165 * the argument. Using this constructor, one can easily create an identity
166 * matrix of size <code>n</code> by saying
167 * @code
168 * FullMatrix<double> M(IdentityMatrix(n));
169 * @endcode
170 */
171 FullMatrix(const IdentityMatrix &id);
172 /**
173 * @}
174 */
175
176 /**
177 * @name Copying into and out of other matrices
178 * @{
179 */
180
181 /**
182 * Variable assignment operator.
183 */
184 template <typename number2>
185 FullMatrix<number> &
186 operator=(const FullMatrix<number2> &);
187
188 /**
189 * This operator assigns a scalar to a matrix. To avoid confusion with the
190 * semantics of this function, zero is the only value allowed for
191 * <tt>d</tt>, allowing you to clear a matrix in an intuitive way.
192 *
193 * @dealiiOperationIsMultithreaded
194 */
195 FullMatrix<number> &
196 operator=(const number d);
197
198 /**
199 * Copy operator to create a full matrix that equals the identity matrix of
200 * the size of the argument. This way, one can easily create an identity
201 * matrix of size <code>n</code> by saying
202 * @code
203 * M = IdentityMatrix(n);
204 * @endcode
205 */
206 FullMatrix<number> &
207 operator=(const IdentityMatrix &id);
208
209 /**
210 * Assignment operator for a LapackFullMatrix. The calling matrix must be of
211 * the same size as the LAPACK matrix.
212 */
213 template <typename number2>
214 FullMatrix<number> &
215 operator=(const LAPACKFullMatrix<number2> &);
216
217
218 /**
219 * Assignment from different matrix classes. This assignment operator uses
220 * iterators of the typename MatrixType. Therefore, sparse matrices are
221 * possible sources.
222 */
223 template <typename MatrixType>
224 void
225 copy_from(const MatrixType &);
226
227 /**
228 * Transposing assignment from different matrix classes. This assignment
229 * operator uses iterators of the typename MatrixType. Therefore, sparse
230 * matrices are possible sources.
231 */
232 template <typename MatrixType>
233 void
234 copy_transposed(const MatrixType &);
235
236 /**
237 * Fill matrix with elements extracted from a tensor, taking rows included
238 * between <tt>r_i</tt> and <tt>r_j</tt> and columns between <tt>c_i</tt>
239 * and <tt>c_j</tt>. The resulting matrix is then inserted in the
240 * destination matrix at position <tt>(dst_r, dst_c)</tt> Checks on the
241 * indices are made.
242 */
243 template <int dim>
244 void
245 copy_from(const Tensor<2, dim> &T,
246 const unsigned int src_r_i = 0,
247 const unsigned int src_r_j = dim - 1,
248 const unsigned int src_c_i = 0,
249 const unsigned int src_c_j = dim - 1,
250 const size_type dst_r = 0,
251 const size_type dst_c = 0);
252
253 /**
254 * Insert a submatrix (also rectangular) into a tensor, putting its upper
255 * left element at the specified position <tt>(dst_r, dst_c)</tt> and the
256 * other elements consequently. Default values are chosen so that no
257 * parameter needs to be specified if the size of the tensor and that of the
258 * matrix coincide.
259 */
260 template <int dim>
261 void
262 copy_to(Tensor<2, dim> &T,
263 const size_type src_r_i = 0,
264 const size_type src_r_j = dim - 1,
265 const size_type src_c_i = 0,
266 const size_type src_c_j = dim - 1,
267 const unsigned int dst_r = 0,
268 const unsigned int dst_c = 0) const;
269
270 /**
271 * Copy a subset of the rows and columns of another matrix into the current
272 * object.
273 *
274 * @param matrix The matrix from which a subset is to be taken from.
275 * @param row_index_set The set of rows of @p matrix from which to extract.
276 * @param column_index_set The set of columns of @p matrix from which to
277 * extract. @pre The number of elements in @p row_index_set and @p
278 * column_index_set shall be equal to the number of rows and columns in the
279 * current object. In other words, the current object is not resized for
280 * this operation.
281 */
282 template <typename MatrixType, typename index_type>
283 void
284 extract_submatrix_from(const MatrixType &matrix,
285 const std::vector<index_type> &row_index_set,
286 const std::vector<index_type> &column_index_set);
287
288 /**
289 * Copy the elements of the current matrix object into a specified set of
290 * rows and columns of another matrix. Thus, this is a scatter operation.
291 *
292 * @param row_index_set The rows of @p matrix into which to write.
293 * @param column_index_set The columns of @p matrix into which to write.
294 * @param matrix The matrix within which certain elements are to be
295 * replaced. @pre The number of elements in @p row_index_set and @p
296 * column_index_set shall be equal to the number of rows and columns in the
297 * current object. In other words, the current object is not resized for
298 * this operation.
299 */
300 template <typename MatrixType, typename index_type>
301 void
302 scatter_matrix_to(const std::vector<index_type> &row_index_set,
303 const std::vector<index_type> &column_index_set,
304 MatrixType &matrix) const;
305
306 /**
307 * Fill rectangular block.
308 *
309 * A rectangular block of the matrix <tt>src</tt> is copied into
310 * <tt>this</tt>. The upper left corner of the block being copied is
311 * <tt>(src_offset_i,src_offset_j)</tt>. The upper left corner of the
312 * copied block is <tt>(dst_offset_i,dst_offset_j)</tt>. The size of the
313 * rectangular block being copied is the maximum size possible, determined
314 * either by the size of <tt>this</tt> or <tt>src</tt>.
315 */
316 template <typename number2>
317 void
318 fill(const FullMatrix<number2> &src,
319 const size_type dst_offset_i = 0,
320 const size_type dst_offset_j = 0,
321 const size_type src_offset_i = 0,
322 const size_type src_offset_j = 0);
323
324
325 /**
326 * Make function of base class available.
327 */
328 template <typename number2>
329 void
330 fill(const number2 *);
331
332 /**
333 * Fill with permutation of another matrix.
334 *
335 * The matrix <tt>src</tt> is copied into the target. The two permutation
336 * <tt>p_r</tt> and <tt>p_c</tt> operate in a way, such that <tt>result(i,j)
337 * = src(p_r[i], p_c[j])</tt>.
338 *
339 * The vectors may also be a selection from a larger set of integers, if the
340 * matrix <tt>src</tt> is bigger. It is also possible to duplicate rows or
341 * columns by this method.
342 */
343 template <typename number2>
344 void
345 fill_permutation(const FullMatrix<number2> &src,
346 const std::vector<size_type> &p_rows,
347 const std::vector<size_type> &p_cols);
348
349 /**
350 * Set a particular entry of the matrix to a value. Thus, calling
351 * <code>A.set(1,2,3.141);</code> is entirely equivalent to the operation
352 * <code>A(1,2) = 3.141;</code>. This function exists for compatibility with
353 * the various sparse matrix objects.
354 *
355 * @param i The row index of the element to be set.
356 * @param j The columns index of the element to be set.
357 * @param value The value to be written into the element.
358 */
359 void
360 set(const size_type i, const size_type j, const number value);
361 /**
362 * @}
363 */
364 /**
365 * @name Non-modifying operators
366 * @{
367 */
368
369 /**
370 * Comparison operator. Be careful with this thing, it may eat up huge
371 * amounts of computing time! It is most commonly used for internal
372 * consistency checks of programs.
373 */
374 bool
375 operator==(const FullMatrix<number> &) const;
376
377 /**
378 * Number of rows of this matrix. Note that the matrix is of dimension <i>m
379 * x n</i>.
380 */
381 size_type
382 m() const;
383
384 /**
385 * Number of columns of this matrix. Note that the matrix is of dimension
386 * <i>m x n</i>.
387 */
388 size_type
389 n() const;
390
391 /**
392 * Return whether the matrix contains only elements with value zero. This
393 * function is mainly for internal consistency checks and should seldom be
394 * used when not in debug mode since it uses quite some time.
395 */
396 bool
397 all_zero() const;
398
399 /**
400 * Return the square of the norm of the vector <tt>v</tt> induced by this
401 * matrix, i.e. <i>(v,Mv)</i>. This is useful, e.g. in the finite element
402 * context, where the <i>L<sup>2</sup></i> norm of a function equals the
403 * matrix norm with respect to the @ref GlossMassMatrix "mass matrix" of the vector representing
404 * the nodal values of the finite element function.
405 *
406 * Obviously, the matrix needs to be quadratic for this operation, and for
407 * the result to actually be a norm it also needs to be either real
408 * symmetric or complex hermitian.
409 *
410 * The underlying template types of both this matrix and the given vector
411 * should either both be real or complex-valued, but not mixed, for this
412 * function to make sense.
413 */
414 template <typename number2>
415 number2
416 matrix_norm_square(const Vector<number2> &v) const;
417
418 /**
419 * Build the matrix scalar product <tt>u<sup>T</sup> M v</tt>. This function
420 * is mostly useful when building the cellwise scalar product of two
421 * functions in the finite element context.
422 *
423 * The underlying template types of both this matrix and the given vector
424 * should either both be real or complex-valued, but not mixed, for this
425 * function to make sense.
426 */
427 template <typename number2>
428 number2
429 matrix_scalar_product(const Vector<number2> &u,
430 const Vector<number2> &v) const;
431
432 /**
433 * Return the <i>l<sub>1</sub></i>-norm of the matrix, where $||M||_1 =
434 * \max_j \sum_i |M_{ij}|$ (maximum of the sums over columns).
435 */
436 real_type
437 l1_norm() const;
438
439 /**
440 * Return the $l_\infty$-norm of the matrix, where $||M||_\infty = \max_i
441 * \sum_j |M_{ij}|$ (maximum of the sums over rows).
442 */
443 real_type
444 linfty_norm() const;
445
446 /**
447 * Compute the Frobenius norm of the matrix. Return value is the root of
448 * the square sum of all matrix entries.
449 *
450 * @note For the timid among us: this norm is not the norm compatible with
451 * the <i>l<sub>2</sub></i>-norm of the vector space.
452 */
453 real_type
454 frobenius_norm() const;
455
456 /**
457 * Compute the relative norm of the skew-symmetric part. The return value is
458 * the Frobenius norm of the skew-symmetric part of the matrix divided by
459 * that of the matrix.
460 *
461 * Main purpose of this function is to check, if a matrix is symmetric
462 * within a certain accuracy, or not.
463 */
464 real_type
465 relative_symmetry_norm2() const;
466
467 /**
468 * Compute the determinant of a matrix. This is only implemented for one,
469 * two, and three dimensions, since for higher dimensions the numerical work
470 * explodes. Obviously, the matrix needs to be quadratic for this function.
471 */
472 number
473 determinant() const;
474
475 /**
476 * Return the trace of the matrix, i.e. the sum of the diagonal values
477 * (which happens to also equal the sum of the eigenvalues of a matrix).
478 * Obviously, the matrix needs to be quadratic for this function.
479 */
480 number
481 trace() const;
482
483 /**
484 * Output of the matrix in user-defined format given by the specified
485 * precision and width. This function saves width and precision of the
486 * stream before setting these given values for output, and restores the
487 * previous values after output.
488 */
489 template <typename StreamType>
490 void
491 print(StreamType &s,
492 const unsigned int width = 5,
493 const unsigned int precision = 2) const;
494
495 /**
496 * Print the matrix and allow formatting of entries.
497 *
498 * The parameters allow for a flexible setting of the output format:
499 *
500 * @param out This specifies the stream to write to.
501 *
502 * @param precision denotes the number of trailing digits.
503 *
504 * @param scientific is used to determine the number format, where
505 * <code>scientific = false</code> means fixed point notation.
506 *
507 * @param width denotes the with of each column. A zero entry for
508 * @p width makes the function compute a width, but it may be changed
509 * to a positive value, if output is crude.
510 *
511 * @param zero_string specifies a string printed for zero entries.
512 *
513 * @param denominator Multiply the whole matrix by this common
514 * denominator to get nicer numbers.
515 *
516 * @param threshold all entries with absolute value smaller than
517 * this are considered zero.
518 *
519 * @param separator specifies a string printed to separate row entries.
520 */
521 void
522 print_formatted(std::ostream &out,
523 const unsigned int precision = 3,
524 const bool scientific = true,
525 const unsigned int width = 0,
526 const char *zero_string = " ",
527 const double denominator = 1.,
528 const double threshold = 0.,
529 const char *separator = " ") const;
530
531 /**
532 * Determine an estimate for the memory consumption (in bytes) of this
533 * object.
534 */
535 std::size_t
536 memory_consumption() const;
537
538 /** @} */
539 /**
540 * @name Iterator functions
541 * @{
542 */
543
544 /**
545 * Mutable iterator starting at the first entry of row <tt>r</tt>.
546 */
547 iterator
548 begin(const size_type r);
549
550 /**
551 * One past the end mutable iterator of row <tt>r</tt>.
552 */
553 iterator
554 end(const size_type r);
555
556 /**
557 * Constant iterator starting at the first entry of row <tt>r</tt>.
558 */
559 const_iterator
560 begin(const size_type r) const;
561
562 /**
563 * One past the end constant iterator of row <tt>r</tt>.
564 */
565 const_iterator
566 end(const size_type r) const;
567
568 /** @} */
569 /**
570 * @name Modifying operators
571 * @{
572 */
573
574 /**
575 * Scale the entire matrix by a fixed factor.
576 */
577 FullMatrix &
578 operator*=(const number factor);
579
580 /**
581 * Scale the entire matrix by the inverse of the given factor.
582 */
583 FullMatrix &
584 operator/=(const number factor);
585
586 /**
587 * Simple addition of a scaled matrix, i.e. <tt>*this += a*A</tt>.
588 *
589 * The matrix <tt>A</tt> may be a full matrix over an arbitrary underlying
590 * scalar type, as long as its data type is convertible to the data type of
591 * this matrix.
592 */
593 template <typename number2>
594 void
595 add(const number a, const FullMatrix<number2> &A);
596
597 /**
598 * Multiple addition of scaled matrices, i.e. <tt>*this += a*A + b*B</tt>.
599 *
600 * The matrices <tt>A</tt> and <tt>B</tt> may be a full matrix over an
601 * arbitrary underlying scalar type, as long as its data type is convertible
602 * to the data type of this matrix.
603 */
604 template <typename number2>
605 void
606 add(const number a,
607 const FullMatrix<number2> &A,
608 const number b,
609 const FullMatrix<number2> &B);
610
611 /**
612 * Multiple addition of scaled matrices, i.e. <tt>*this += a*A + b*B +
613 * c*C</tt>.
614 *
615 * The matrices <tt>A</tt>, <tt>B</tt> and <tt>C</tt> may be a full matrix
616 * over an arbitrary underlying scalar type, as long as its data type is
617 * convertible to the data type of this matrix.
618 */
619 template <typename number2>
620 void
621 add(const number a,
622 const FullMatrix<number2> &A,
623 const number b,
624 const FullMatrix<number2> &B,
625 const number c,
626 const FullMatrix<number2> &C);
627
628 /**
629 * Add rectangular block.
630 *
631 * A rectangular block of the matrix <tt>src</tt> is added to <tt>this</tt>.
632 * The upper left corner of the block being copied is
633 * <tt>(src_offset_i,src_offset_j)</tt>. The upper left corner of the
634 * copied block is <tt>(dst_offset_i,dst_offset_j)</tt>. The size of the
635 * rectangular block being copied is the maximum size possible, determined
636 * either by the size of <tt>this</tt> or <tt>src</tt> and the given
637 * offsets.
638 */
639 template <typename number2>
640 void
641 add(const FullMatrix<number2> &src,
642 const number factor,
643 const size_type dst_offset_i = 0,
644 const size_type dst_offset_j = 0,
645 const size_type src_offset_i = 0,
646 const size_type src_offset_j = 0);
647
648 /**
649 * Weighted addition of the transpose of <tt>B</tt> to <tt>this</tt>.
650 *
651 * <i>A += s B<sup>T</sup></i>
652 */
653 template <typename number2>
654 void
655 Tadd(const number s, const FullMatrix<number2> &B);
656
657 /**
658 * Add transpose of a rectangular block.
659 *
660 * A rectangular block of the matrix <tt>src</tt> is transposed and
661 * addedadded to <tt>this</tt>. The upper left corner of the block being
662 * copied is <tt>(src_offset_i,src_offset_j)</tt> in the coordinates of the
663 * <b>non</b>-transposed matrix. The upper left corner of the copied block
664 * is <tt>(dst_offset_i,dst_offset_j)</tt>. The size of the rectangular
665 * block being copied is the maximum size possible, determined either by the
666 * size of <tt>this</tt> or <tt>src</tt>.
667 */
668 template <typename number2>
669 void
670 Tadd(const FullMatrix<number2> &src,
671 const number factor,
672 const size_type dst_offset_i = 0,
673 const size_type dst_offset_j = 0,
674 const size_type src_offset_i = 0,
675 const size_type src_offset_j = 0);
676
677 /**
678 * Add a single element at the given position.
679 */
680 void
681 add(const size_type row, const size_type column, const number value);
682
683 /**
684 * Add an array of values given by <tt>values</tt> in the given global
685 * matrix row at columns specified by col_indices in the full matrix. This
686 * function is present for compatibility with the various sparse matrices in
687 * deal.II. In particular, the two boolean fields @p elide_zero_values and
688 * @p col_indices_are_sorted do not impact the performance of this routine,
689 * as opposed to the sparse matrix case and are indeed ignored in the
690 * implementation.
691 */
692 template <typename number2, typename index_type>
693 void
694 add(const size_type row,
695 const size_type n_cols,
696 const index_type *col_indices,
697 const number2 *values,
698 const bool elide_zero_values = true,
699 const bool col_indices_are_sorted = false);
700
701 /**
702 * <i>A(i,1...n) += s*A(j,1...n)</i>. Simple addition of rows of this
703 */
704 void
705 add_row(const size_type i, const number s, const size_type j);
706
707 /**
708 * <i>A(i,1...n) += s*A(j,1...n) + t*A(k,1...n)</i>. Multiple addition of
709 * rows of this.
710 */
711 void
712 add_row(const size_type i,
713 const number s,
714 const size_type j,
715 const number t,
716 const size_type k);
717
718 /**
719 * <i>A(1...n,i) += s*A(1...n,j)</i>. Simple addition of columns of this.
720 */
721 void
722 add_col(const size_type i, const number s, const size_type j);
723
724 /**
725 * <i>A(1...n,i) += s*A(1...n,j) + t*A(1...n,k)</i>. Multiple addition of
726 * columns of this.
727 */
728 void
729 add_col(const size_type i,
730 const number s,
731 const size_type j,
732 const number t,
733 const size_type k);
734
735 /**
736 * Swap <i>A(i,1...n) <-> A(j,1...n)</i>. Swap rows i and j of this
737 */
738 void
739 swap_row(const size_type i, const size_type j);
740
741 /**
742 * Swap <i>A(1...n,i) <-> A(1...n,j)</i>. Swap columns i and j of this
743 */
744 void
745 swap_col(const size_type i, const size_type j);
746
747 /**
748 * Add constant to diagonal elements of this, i.e. add a multiple of the
749 * identity matrix.
750 */
751 void
752 diagadd(const number s);
753
754 /**
755 * Assignment <tt>*this = a*A</tt>.
756 */
757 template <typename number2>
758 void
759 equ(const number a, const FullMatrix<number2> &A);
760
761 /**
762 * Assignment <tt>*this = a*A + b*B</tt>.
763 */
764 template <typename number2>
765 void
766 equ(const number a,
767 const FullMatrix<number2> &A,
768 const number b,
769 const FullMatrix<number2> &B);
770
771 /**
772 * Assignment <tt>*this = a*A + b*B + c*C</tt>.
773 */
774 template <typename number2>
775 void
776 equ(const number a,
777 const FullMatrix<number2> &A,
778 const number b,
779 const FullMatrix<number2> &B,
780 const number c,
781 const FullMatrix<number2> &C);
782
783 /**
784 * Symmetrize the matrix by forming the mean value between the existing
785 * matrix and its transpose, <i>A = 1/2(A+A<sup>T</sup>)</i>.
786 *
787 * Obviously the matrix must be quadratic for this operation.
788 */
789 void
790 symmetrize();
791
792 /**
793 * A=Inverse(A). A must be a square matrix. Inversion of this matrix by
794 * Gauss-Jordan algorithm with partial pivoting. This process is
795 * well-behaved for positive definite matrices, but be aware of round-off
796 * errors in the indefinite case.
797 *
798 * In case deal.II was configured with LAPACK, the functions Xgetrf and
799 * Xgetri build an LU factorization and invert the matrix upon that
800 * factorization, providing best performance up to matrices with a few
801 * hundreds rows and columns.
802 *
803 * The numerical effort to invert an $n \times n$ matrix is of the order
804 * $n^3$.
805 */
806 void
807 gauss_jordan();
808
809 /**
810 * Assign the inverse of the given matrix to <tt>*this</tt>. This function
811 * is hardcoded for quadratic matrices of dimension one to four. However,
812 * since the amount of code needed grows quickly, the method gauss_jordan()
813 * is invoked implicitly if the dimension is larger.
814 */
815 template <typename number2>
816 void
817 invert(const FullMatrix<number2> &M);
818
819 /**
820 * Assign the Cholesky decomposition $A=:L L^T$ of the given matrix $A$ to
821 * <tt>*this</tt>, where $L$ is lower triangular matrix. The given matrix must
822 * be symmetric positive definite.
823 *
824 * ExcMatrixNotPositiveDefinite will be thrown in the case that the matrix
825 * is not positive definite.
826 */
827 template <typename number2>
828 void
829 cholesky(const FullMatrix<number2> &A);
830
831 /**
832 * <tt>*this(i,j)</tt> = $V(i) W(j)$ where $V,W$ are vectors of the same
833 * length.
834 */
835 template <typename number2>
836 void
837 outer_product(const Vector<number2> &V, const Vector<number2> &W);
838
839 /**
840 * Assign the left_inverse of the given matrix to <tt>*this</tt>. The
841 * calculation being performed is <i>(A<sup>T</sup>*A)<sup>-1</sup>
842 * *A<sup>T</sup></i>.
843 */
844 template <typename number2>
845 void
846 left_invert(const FullMatrix<number2> &M);
847
848 /**
849 * Assign the right_inverse of the given matrix to <tt>*this</tt>. The
850 * calculation being performed is <i>A<sup>T</sup>*(A*A<sup>T</sup>)
851 * <sup>-1</sup></i>.
852 */
853 template <typename number2>
854 void
855 right_invert(const FullMatrix<number2> &M);
856
857 /** @} */
858 /**
859 * @name Multiplications
860 * @{
861 */
862
863 /**
864 * Matrix-matrix-multiplication.
865 *
866 * The optional parameter <tt>adding</tt> determines, whether the result is
867 * stored in <tt>C</tt> or added to <tt>C</tt>.
868 *
869 * if (adding) <i>C += A*B</i>
870 *
871 * if (!adding) <i>C = A*B</i>
872 *
873 * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
874 * <tt>C</tt> already has the right size.
875 *
876 * This function uses the BLAS function Xgemm if the product of the three
877 * matrix dimensions is larger than 300 and BLAS was detected during
878 * configuration. Using BLAS usually results in considerable performance
879 * gains.
880 */
881 template <typename number2>
882 void
883 mmult(FullMatrix<number2> &C,
884 const FullMatrix<number2> &B,
885 const bool adding = false) const;
886
887 /**
888 * Matrix-matrix-multiplication using transpose of <tt>this</tt>.
889 *
890 * The optional parameter <tt>adding</tt> determines, whether the result is
891 * stored in <tt>C</tt> or added to <tt>C</tt>.
892 *
893 * if (adding) <i>C += A<sup>T</sup>*B</i>
894 *
895 * if (!adding) <i>C = A<sup>T</sup>*B</i>
896 *
897 * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
898 * <tt>C</tt> already has the right size.
899 *
900 * This function uses the BLAS function Xgemm if the product of the three
901 * matrix dimensions is larger than 300 and BLAS was detected during
902 * configuration. Using BLAS usually results in considerable performance
903 * gains.
904 */
905 template <typename number2>
906 void
907 Tmmult(FullMatrix<number2> &C,
908 const FullMatrix<number2> &B,
909 const bool adding = false) const;
910
911 /**
912 * Matrix-matrix-multiplication using transpose of <tt>B</tt>.
913 *
914 * The optional parameter <tt>adding</tt> determines, whether the result is
915 * stored in <tt>C</tt> or added to <tt>C</tt>.
916 *
917 * if (adding) <i>C += A*B<sup>T</sup></i>
918 *
919 * if (!adding) <i>C = A*B<sup>T</sup></i>
920 *
921 * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
922 * <tt>C</tt> already has the right size.
923 *
924 * This function uses the BLAS function Xgemm if the product of the three
925 * matrix dimensions is larger than 300 and BLAS was detected during
926 * configuration. Using BLAS usually results in considerable performance
927 * gains.
928 */
929 template <typename number2>
930 void
931 mTmult(FullMatrix<number2> &C,
932 const FullMatrix<number2> &B,
933 const bool adding = false) const;
934
935 /**
936 * Matrix-matrix-multiplication using transpose of <tt>this</tt> and
937 * <tt>B</tt>.
938 *
939 * The optional parameter <tt>adding</tt> determines, whether the result is
940 * stored in <tt>C</tt> or added to <tt>C</tt>.
941 *
942 * if (adding) <i>C += A<sup>T</sup>*B<sup>T</sup></i>
943 *
944 * if (!adding) <i>C = A<sup>T</sup>*B<sup>T</sup></i>
945 *
946 * Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
947 * <tt>C</tt> already has the right size.
948 *
949 * This function uses the BLAS function Xgemm if the product of the three
950 * matrix dimensions is larger than 300 and BLAS was detected during
951 * configuration. Using BLAS usually results in considerable performance
952 * gains.
953 */
954 template <typename number2>
955 void
956 TmTmult(FullMatrix<number2> &C,
957 const FullMatrix<number2> &B,
958 const bool adding = false) const;
959
960 /**
961 * Add to the current matrix the triple product <b>B A D</b>. Optionally,
962 * use the transposes of the matrices <b>B</b> and <b>D</b>. The scaling
963 * factor scales the whole product, which is helpful when adding a multiple
964 * of the triple product to the matrix.
965 *
966 * This product was written with the Schur complement <b>B<sup>T</sup>
967 * A<sup>-1</sup> D</b> in mind. Note that in this case the argument for
968 * <tt>A</tt> must be the inverse of the matrix <b>A</b>.
969 */
970 void
971 triple_product(const FullMatrix<number> &A,
972 const FullMatrix<number> &B,
973 const FullMatrix<number> &D,
974 const bool transpose_B = false,
975 const bool transpose_D = false,
976 const number scaling = number(1.));
977
978
979 /**
980 * @brief Compute the Kronecker product of two matrices.
981 *
982 * This function computes the Kronecker product of two matrices A and B, and
983 * stores the result in the current matrix. The Kronecker product of an
984 * m x n matrix A and a p x q matrix B is an (m*p) x (n*q) matrix defined as:
985 *
986 * ```
987 * A ⊗ B = | a11*B a12*B ... a1n*B |
988 * | a21*B a22*B ... a2n*B |
989 * | ... ... ... ... |
990 * | am1*B am2*B ... amn*B |
991 * ```
992 *
993 * where aij are the elements of the matrix A.
994 *
995 * @param A The first matrix (m x n).
996 * @param B The second matrix (p x q).
997 * @param adding If `true`, the result is added to the current matrix. If
998 * `false` (default), the current matrix is overwritten.
999 */
1000 void
1001 kronecker_product(const FullMatrix<number> &A,
1002 const FullMatrix<number> &B,
1003 const bool adding = false);
1004
1005 /**
1006 * Matrix-vector-multiplication.
1007 *
1008 * The optional parameter <tt>adding</tt> determines, whether the result is
1009 * stored in <tt>w</tt> or added to <tt>w</tt>.
1010 *
1011 * if (adding) <i>w += A*v</i>
1012 *
1013 * if (!adding) <i>w = A*v</i>
1014 *
1015 * Source and destination must not be the same vector.
1016 */
1017 template <typename number2>
1018 void
1019 vmult(Vector<number2> &w,
1020 const Vector<number2> &v,
1021 const bool adding = false) const;
1022
1023 /**
1024 * Adding Matrix-vector-multiplication. <i>w += A*v</i>
1025 *
1026 * Source and destination must not be the same vector.
1027 */
1028 template <typename number2>
1029 void
1030 vmult_add(Vector<number2> &w, const Vector<number2> &v) const;
1031
1032 /**
1033 * Transpose matrix-vector-multiplication.
1034 *
1035 * The optional parameter <tt>adding</tt> determines, whether the result is
1036 * stored in <tt>w</tt> or added to <tt>w</tt>.
1037 *
1038 * if (adding) <i>w += A<sup>T</sup>*v</i>
1039 *
1040 * if (!adding) <i>w = A<sup>T</sup>*v</i>
1041 *
1042 *
1043 * Source and destination must not be the same vector.
1044 */
1045 template <typename number2>
1046 void
1047 Tvmult(Vector<number2> &w,
1048 const Vector<number2> &v,
1049 const bool adding = false) const;
1050
1051 /**
1052 * Adding transpose matrix-vector-multiplication. <i>w +=
1053 * A<sup>T</sup>*v</i>
1054 *
1055 * Source and destination must not be the same vector.
1056 */
1057 template <typename number2>
1058 void
1059 Tvmult_add(Vector<number2> &w, const Vector<number2> &v) const;
1060
1061 /**
1062 * Apply the Jacobi preconditioner, which multiplies every element of the
1063 * <tt>src</tt> vector by the inverse of the respective diagonal element and
1064 * multiplies the result with the damping factor <tt>omega</tt>.
1065 */
1066 template <typename somenumber>
1067 void
1068 precondition_Jacobi(Vector<somenumber> &dst,
1069 const Vector<somenumber> &src,
1070 const number omega = 1.) const;
1071
1072 /**
1073 * <i>dst=b-A*x</i>. Residual calculation, returns the
1074 * <i>l<sub>2</sub></i>-norm |<i>dst</i>|.
1075 *
1076 * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
1077 */
1078 template <typename number2, typename number3>
1079 number
1080 residual(Vector<number2> &dst,
1081 const Vector<number2> &x,
1082 const Vector<number3> &b) const;
1083
1084 /**
1085 * Forward elimination of lower triangle. Inverts the lower triangle of a
1086 * rectangular matrix for a given right hand side.
1087 *
1088 * If the matrix has more columns than rows, this function only operates on
1089 * the left quadratic submatrix. If there are more rows, the upper quadratic
1090 * part of the matrix is considered.
1091 *
1092 * @note It is safe to use the same object for @p dst and @p src.
1093 */
1094 template <typename number2>
1095 void
1096 forward(Vector<number2> &dst, const Vector<number2> &src) const;
1097
1098 /**
1099 * Backward elimination of upper triangle.
1100 *
1101 * See forward()
1102 *
1103 * @note It is safe to use the same object for @p dst and @p src.
1104 */
1105 template <typename number2>
1106 void
1107 backward(Vector<number2> &dst, const Vector<number2> &src) const;
1108
1109 /**
1110 * Dummy function for compatibility with distributed, parallel matrices.
1111 */
1112 void compress(VectorOperation::values);
1113
1114 /** @} */
1115
1116 /**
1117 * @addtogroup Exceptions
1118 * @{
1119 */
1120
1121 /**
1122 * Exception
1123 */
1124 DeclException0(ExcEmptyMatrix);
1125
1126 /**
1127 * Exception
1128 */
1129 DeclException1(
1130 ExcNotRegular,
1131 number,
1132 << "The maximal pivot is " << arg1
1133 << ", which is below the threshold. The matrix may be singular.");
1134 /**
1135 * Exception
1136 */
1137 DeclException3(ExcInvalidDestination,
1138 size_type,
1139 size_type,
1140 size_type,
1141 << "Target region not in matrix: size in this direction="
1142 << arg1 << ", size of new matrix=" << arg2
1143 << ", offset=" << arg3);
1144 /**
1145 * Exception
1146 */
1147 DeclExceptionMsg(ExcSourceEqualsDestination,
1148 "You are attempting an operation on two vectors that "
1149 "are the same object, but the operation requires that the "
1150 "two objects are in fact different.");
1151 /**
1152 * Exception
1153 */
1154 DeclException0(ExcMatrixNotPositiveDefinite);
1155 /** @} */
1156 };
1157
1158 /** @} */
1159
1160 #ifndef DOXYGEN
1161 /*-------------------------Inline functions -------------------------------*/
1162
1163
1164
1165 template <typename number>
1166 inline typename FullMatrix<number>::size_type
1167 FullMatrix<number>::m() const
1168 {
1169 return this->n_rows();
1170 }
1171
1172
1173
1174 template <typename number>
1175 inline typename FullMatrix<number>::size_type
1176 FullMatrix<number>::n() const
1177 {
1178 return this->n_cols();
1179 }
1180
1181
1182
1183 template <typename number>
1184 FullMatrix<number> &
1185 FullMatrix<number>::operator=(const number d)
1186 {
1187 Assert(d == number(0), ExcScalarAssignmentOnlyForZeroValue());
1188
1189 if (this->n_elements() != 0)
1190 this->reset_values();
1191
1192 return *this;
1193 }
1194
1195
1196
1197 template <typename number>
1198 template <typename number2>
1199 inline void
1200 FullMatrix<number>::fill(const number2 *src)
1201 {
1202 Table<2, number>::fill(src);
1203 }
1204
1205
1206
1207 template <typename number>
1208 template <typename MatrixType>
1209 void
1210 FullMatrix<number>::copy_from(const MatrixType &M)
1211 {
1212 this->reinit(M.m(), M.n());
1213
1214 // loop over the elements of the argument matrix row by row, as suggested
1215 // in the documentation of the sparse matrix iterator class, and
1216 // copy them into the current object
1217 for (size_type row = 0; row < M.m(); ++row)
1218 {
1219 const typename MatrixType::const_iterator end_row = M.end(row);
1220 for (typename MatrixType::const_iterator entry = M.begin(row);
1221 entry != end_row;
1222 ++entry)
1223 this->el(row, entry->column()) = entry->value();
1224 }
1225 }
1226
1227
1228
1229 template <typename number>
1230 template <int dim>
1231 void
1232 FullMatrix<number>::copy_from(const Tensor<2, dim> &T,
1233 const unsigned int src_r_i,
1234 const unsigned int src_r_j,
1235 const unsigned int src_c_i,
1236 const unsigned int src_c_j,
1237 const size_type dst_r,
1238 const size_type dst_c)
1239 {
1240 Assert(!this->empty(), ExcEmptyMatrix());
1241 AssertIndexRange(src_r_j - src_r_i, this->m() - dst_r);
1242 AssertIndexRange(src_c_j - src_c_i, this->n() - dst_c);
1243 AssertIndexRange(src_r_j, dim);
1244 AssertIndexRange(src_c_j, dim);
1245 AssertIndexRange(src_r_i, src_r_j + 1);
1246 AssertIndexRange(src_c_i, src_c_j + 1);
1247
1248 for (size_type i = 0; i < src_r_j - src_r_i + 1; ++i)
1249 for (size_type j = 0; j < src_c_j - src_c_i + 1; ++j)
1250 {
1251 const unsigned int src_r_index = static_cast<unsigned int>(i + src_r_i);
1252 const unsigned int src_c_index = static_cast<unsigned int>(j + src_c_i);
1253 (*this)(i + dst_r, j + dst_c) = number(T[src_r_index][src_c_index]);
1254 }
1255 }
1256
1257
1258
1259 template <typename number>
1260 template <int dim>
1261 void
1262 FullMatrix<number>::copy_to(Tensor<2, dim> &T,
1263 const size_type src_r_i,
1264 const size_type src_r_j,
1265 const size_type src_c_i,
1266 const size_type src_c_j,
1267 const unsigned int dst_r,
1268 const unsigned int dst_c) const
1269 {
1270 Assert(!this->empty(), ExcEmptyMatrix());
1271 AssertIndexRange(src_r_j - src_r_i, dim - dst_r);
1272 AssertIndexRange(src_c_j - src_c_i, dim - dst_c);
1273 AssertIndexRange(src_r_j, this->m());
1274 AssertIndexRange(src_r_j, this->n());
1275 AssertIndexRange(src_r_i, src_r_j + 1);
1276 AssertIndexRange(src_c_j, src_c_j + 1);
1277
1278 for (size_type i = 0; i < src_r_j - src_r_i + 1; ++i)
1279 for (size_type j = 0; j < src_c_j - src_c_i + 1; ++j)
1280 {
1281 const unsigned int dst_r_index = static_cast<unsigned int>(i + dst_r);
1282 const unsigned int dst_c_index = static_cast<unsigned int>(j + dst_c);
1283 T[dst_r_index][dst_c_index] = double((*this)(i + src_r_i, j + src_c_i));
1284 }
1285 }
1286
1287
1288
1289 template <typename number>
1290 template <typename MatrixType>
1291 void
1292 FullMatrix<number>::copy_transposed(const MatrixType &M)
1293 {
1294 this->reinit(M.n(), M.m());
1295
1296 // loop over the elements of the argument matrix row by row, as suggested
1297 // in the documentation of the sparse matrix iterator class, and
1298 // copy them into the current object
1299 for (size_type row = 0; row < M.m(); ++row)
1300 {
1301 const typename MatrixType::const_iterator end_row = M.end(row);
1302 for (typename MatrixType::const_iterator entry = M.begin(row);
1303 entry != end_row;
1304 ++entry)
1305 this->el(entry->column(), row) = entry->value();
1306 }
1307 }
1308
1309
1310
1311 template <typename number>
1312 template <typename MatrixType, typename index_type>
1313 inline void
1314 FullMatrix<number>::extract_submatrix_from(
1315 const MatrixType &matrix,
1316 const std::vector<index_type> &row_index_set,
1317 const std::vector<index_type> &column_index_set)
1318 {
1319 AssertDimension(row_index_set.size(), this->n_rows());
1320 AssertDimension(column_index_set.size(), this->n_cols());
1321
1322 const size_type n_rows_submatrix = row_index_set.size();
1323 const size_type n_cols_submatrix = column_index_set.size();
1324
1325 for (size_type sub_row = 0; sub_row < n_rows_submatrix; ++sub_row)
1326 for (size_type sub_col = 0; sub_col < n_cols_submatrix; ++sub_col)
1327 (*this)(sub_row, sub_col) =
1328 matrix.el(row_index_set[sub_row], column_index_set[sub_col]);
1329 }
1330
1331
1332
1333 template <typename number>
1334 template <typename MatrixType, typename index_type>
1335 inline void
1336 FullMatrix<number>::scatter_matrix_to(
1337 const std::vector<index_type> &row_index_set,
1338 const std::vector<index_type> &column_index_set,
1339 MatrixType &matrix) const
1340 {
1341 AssertDimension(row_index_set.size(), this->n_rows());
1342 AssertDimension(column_index_set.size(), this->n_cols());
1343
1344 const size_type n_rows_submatrix = row_index_set.size();
1345 const size_type n_cols_submatrix = column_index_set.size();
1346
1347 for (size_type sub_row = 0; sub_row < n_rows_submatrix; ++sub_row)
1348 for (size_type sub_col = 0; sub_col < n_cols_submatrix; ++sub_col)
1349 matrix.set(row_index_set[sub_row],
1350 column_index_set[sub_col],
1351 (*this)(sub_row, sub_col));
1352 }
1353
1354
1355 template <typename number>
1356 inline void
1357 FullMatrix<number>::set(const size_type i,
1358 const size_type j,
1359 const number value)
1360 {
1361 (*this)(i, j) = value;
1362 }
1363
1364
1365
1366 template <typename number>
1367 template <typename number2>
1368 void
1369 FullMatrix<number>::vmult_add(Vector<number2> &w,
1370 const Vector<number2> &v) const
1371 {
1372 vmult(w, v, true);
1373 }
1374
1375
1376 template <typename number>
1377 template <typename number2>
1378 void
1379 FullMatrix<number>::Tvmult_add(Vector<number2> &w,
1380 const Vector<number2> &v) const
1381 {
1382 Tvmult(w, v, true);
1383 }
1384
1385
1386 //---------------------------------------------------------------------------
1387 template <typename number>
1388 inline typename FullMatrix<number>::iterator
1389 FullMatrix<number>::begin(const size_type r)
1390 {
1391 AssertIndexRange(r, m());
1392 return iterator(this, r, 0);
1393 }
1394
1395
1396
1397 template <typename number>
1398 inline typename FullMatrix<number>::iterator
1399 FullMatrix<number>::end(const size_type r)
1400 {
1401 AssertIndexRange(r, m());
1402 return iterator(this, r + 1, 0);
1403 }
1404
1405
1406
1407 template <typename number>
1408 inline typename FullMatrix<number>::const_iterator
1409 FullMatrix<number>::begin(const size_type r) const
1410 {
1411 AssertIndexRange(r, m());
1412 return const_iterator(this, r, 0);
1413 }
1414
1415
1416
1417 template <typename number>
1418 inline typename FullMatrix<number>::const_iterator
1419 FullMatrix<number>::end(const size_type r) const
1420 {
1421 AssertIndexRange(r, m());
1422 return const_iterator(this, r + 1, 0);
1423 }
1424
1425
1426
1427 template <typename number>
1428 inline void
1429 FullMatrix<number>::add(const size_type r, const size_type c, const number v)
1430 {
1431 AssertIndexRange(r, this->m());
1432 AssertIndexRange(c, this->n());
1433
1434 this->operator()(r, c) += v;
1435 }
1436
1437
1438
1439 template <typename number>
1440 template <typename number2, typename index_type>
1441 inline void
1442 FullMatrix<number>::add(const size_type row,
1443 const size_type n_cols,
1444 const index_type *col_indices,
1445 const number2 *values,
1446 const bool,
1447 const bool)
1448 {
1449 AssertIndexRange(row, this->m());
1450 for (size_type col = 0; col < n_cols; ++col)
1451 {
1452 AssertIndexRange(col_indices[col], this->n());
1453 this->operator()(row, col_indices[col]) += values[col];
1454 }
1455 }
1456
1457
1458 template <typename number>
1459 template <typename StreamType>
1460 inline void
1461 FullMatrix<number>::print(StreamType &s,
1462 const unsigned int w,
1463 const unsigned int p) const
1464 {
1465 Assert(!this->empty(), ExcEmptyMatrix());
1466
1467 // save the state of out stream
1468 const std::streamsize old_precision = s.precision(p);
1469 const std::streamsize old_width = s.width(w);
1470
1471 for (size_type i = 0; i < this->m(); ++i)
1472 {
1473 for (size_type j = 0; j < this->n(); ++j)
1474 {
1475 s.width(w);
1476 s.precision(p);
1477 s << this->el(i, j);
1478 }
1479 s << std::endl;
1480 }
1481
1482 // reset output format
1483 s.precision(old_precision);
1484 s.width(old_width);
1485 }
1486
1487
1488 #endif // DOXYGEN
1489
1490 DEAL_II_NAMESPACE_CLOSE
1491
1492 #endif