| 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 |