// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2005 - 2025 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_lapack_full_matrix_h #define dealii_lapack_full_matrix_h #include #include #include #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN // forward declarations #ifndef DOXYGEN template class Vector; template class BlockVector; template class FullMatrix; template class SparseMatrix; #endif /** * A variant of FullMatrix using LAPACK functions wherever possible. In order * to do this, the matrix is stored in transposed order. The element access * functions hide this fact by reverting the transposition. * * @note In order to perform LAPACK functions, the class contains a lot of * auxiliary data in the private section. The names of these data vectors are * usually the names chosen for the arguments in the LAPACK documentation. * * @ingroup Matrix1 */ template class LAPACKFullMatrix : public TransposeTable { public: /** * Declare type for container size. */ using size_type = std::make_unsigned_t; /** * Constructor. Initialize the matrix as a square matrix with dimension * @p size. * * In order to avoid the implicit conversion of integers and other types to * a matrix, this constructor is declared explicit. * * By default, no memory is allocated. */ explicit LAPACKFullMatrix(const size_type size = 0); /** * Constructor. Initialize the matrix as a rectangular matrix $\rm{rows} * \times \rm{cols}$. */ LAPACKFullMatrix(const size_type rows, const size_type cols); /** * Copy constructor. This constructor does a deep copy of the matrix. * Therefore, it poses a possible efficiency problem, if for example, * function arguments are passed by value rather than by reference. * Unfortunately, we can't mark this copy constructor explicit, * since that prevents the use of this class in containers, such as * std::vector. The responsibility to check performance of * programs must therefore remain with the user of this class. */ LAPACKFullMatrix(const LAPACKFullMatrix &); /** * Assignment operator. */ LAPACKFullMatrix & operator=(const LAPACKFullMatrix &); /** * Assignment operator from a regular FullMatrix. * * @note Since LAPACK expects matrices in transposed order, this * transposition is included here. */ template LAPACKFullMatrix & operator=(const FullMatrix &); /** * Assignment operator from a regular SparseMatrix. * * @note Since LAPACK expects matrices in transposed order, this * transposition is included here. */ template LAPACKFullMatrix & operator=(const SparseMatrix &); /** * This operator assigns a scalar to a matrix. To avoid confusion with * constructors, zero (when cast to the @p number type) is the only * value allowed for @p d. */ LAPACKFullMatrix & operator=(const number d); /** * This operator multiplies all entries by a fixed @p factor. */ LAPACKFullMatrix & operator*=(const number factor); /** * This operator divides all entries by a fixed @p factor. */ LAPACKFullMatrix & operator/=(const number factor); /** * Set a particular entry of the matrix to a @p value. * Thus, calling A.set(1,2,3.141); is entirely equivalent to the * operation A(1,2) = 3.141;. This function exists for * compatibility with the various sparse matrix objects. * * @param i The row index of the element to be set. * @param j The column index of the element to be set. * @param value The value to be written into the element. */ void set(const size_type i, const size_type j, const number value); /** * Simple addition of a scaled matrix, i.e. $\mathbf A \mathrel{+}= a \, * \mathbf B$. */ void add(const number a, const LAPACKFullMatrix &B); /** * Perform a rank-1 update of a symmetric matrix * $ \mathbf A \leftarrow \mathbf A + a \, \mathbf v \mathbf v^T $. * * This function also works for Cholesky factorization. * In that case, updating ($a>0$) is * performed via Givens rotations, whereas downdating ($a<0$) via hyperbolic * rotations. Note that the latter case might lead to a negative definite * matrix in which case the error will be thrown (because Cholesky * factorizations are only valid for symmetric and positive definite * matrices). */ void rank1_update(const number a, const Vector &v); /** * Apply Givens * rotation * @p csr (a triplet of cosine, sine and radius, see * Utilities::LinearAlgebra::givens_rotation() for the definition of the * rotation matrix $\mathbf G$) * to this matrix in the plane spanned by the @p i'th and @p k'th unit vectors. * If @p left is true, the rotation is applied from left * $\mathbf A \leftarrow \mathbf G \mathbf A$ * and only rows @p i and @p k are affected. * Otherwise, transpose of the rotation matrix is applied from right * $\mathbf A \leftarrow \mathbf A \mathbf G^T$ * and only columns @p i and @p k are affected. */ void apply_givens_rotation(const std::array &csr, const size_type i, const size_type k, const bool left = true); /** * Assignment from different matrix classes, performing the usual conversion * to the transposed format expected by LAPACK. This assignment operator * uses iterators of the typename MatrixType. Therefore, sparse matrices are * possible sources. */ template void copy_from(const MatrixType &); /** * Regenerate the current matrix by one that has the same properties as if * it were created by the constructor of this class with the same argument * list as this present function. */ void reinit(const size_type size); /** * Same as above but will preserve the values of matrix upon resizing. * The original values * of the matrix are kept on increasing the size * \f[ * \mathbf A \rightarrow * \left( * \begin{array}{cc} * \mathbf A & \mathbf 0 \\ * \mathbf 0 & \mathbf 0 * \end{array} * \right) * \f] * Whereas if the new size is smaller, the matrix will contain the upper left * block of the original one \f[ \left( \begin{array}{cc} * \mathbf A_{11} & \mathbf A_{12} \\ * \mathbf A_{21} & \mathbf A_{22} * \end{array} * \right) * \rightarrow \mathbf A_{11} * \f] */ void grow_or_shrink(const size_type size); /** * Remove row @p row and column @p col from the matrix. * \f[ * \left( * \begin{array}{ccc} * \mathbf A_{11} & \mathbf a_{12} & \mathbf A_{13} \\ * \mathbf a_{21}^T & a_{22} & \mathbf a_{23}^T \\ * \mathbf A_{31} & \mathbf a_{32} & \mathbf A_{33} * \end{array} * \right) * \rightarrow * \left( * \begin{array}{cc} * \mathbf A_{11} & \mathbf A_{13} \\ * \mathbf A_{31} & \mathbf A_{33} * \end{array} * \right) * \f] */ void remove_row_and_column(const size_type row, const size_type col); /** * Regenerate the current matrix by one that has the same properties as if * it were created by the constructor of this class with the same argument * list as this present function. */ void reinit(const size_type rows, const size_type cols); /** * Assign @p property to this matrix. */ void set_property(const LAPACKSupport::Property property); /** * Return the dimension of the codomain (or range) space. * * @note The matrix is of dimension $m \times n$. */ size_type m() const; /** * Return the dimension of the domain space. * * @note The matrix is of dimension $m \times n$. */ size_type n() const; /** * Fill rectangular block. * * A rectangular block of the matrix src is copied into * this. The upper left corner of the block being copied is * (src_offset_i,src_offset_j). The upper left corner of the * copied block is (dst_offset_i,dst_offset_j). The size of the * rectangular block being copied is the maximum size possible, determined * either by the size of this or src. * * The final two arguments allow to enter a multiple of the source or its * transpose. */ template void fill(const MatrixType &src, const size_type dst_offset_i = 0, const size_type dst_offset_j = 0, const size_type src_offset_i = 0, const size_type src_offset_j = 0, const number factor = 1., const bool transpose = false); /** * Matrix-vector-multiplication. * * Depending on previous transformations recorded in #state, the result of * this function is one of *
    *
  • If #state is LAPACKSupport::matrix or LAPACKSupport::inverse_matrix, * this will be a regular matrix vector product using LAPACK gemv(). *
  • If #state is LAPACKSupport::svd or LAPACKSupport::inverse_svd, this * function first multiplies with the right transformation matrix, then with * the diagonal matrix of singular values or their reciprocal values, and * finally with the left transformation matrix. *
* * The optional parameter @p adding determines, whether the result is * stored in the vector * $\mathbf w = \mathbf A \cdot \mathbf v$ * or added to it * $\mathbf w \mathrel{+}= \mathbf A \cdot \mathbf v$. * * @note Source and destination must not be the same vector. * * @note The template with @p number2 only exists for compile-time * compatibility with FullMatrix. Only the case @p number2 = @p number is * implemented due to limitations in the underlying LAPACK interface. All * other variants throw an error upon invocation. */ template void vmult(Vector &w, const Vector &v, const bool adding = false) const; /** * Specialization of above function for compatible Vector::value_type. */ void vmult(Vector &w, const Vector &v, const bool adding = false) const; /** * Adding Matrix-vector-multiplication $\mathbf w \mathrel{+}= \mathbf A \cdot * \mathbf v$. * * See the documentation of vmult() for details on the implementation. */ template void vmult_add(Vector &w, const Vector &v) const; /** * Specialization of above function for compatible Vector::value_type. */ void vmult_add(Vector &w, const Vector &v) const; /** * Transpose matrix-vector-multiplication. * * The optional parameter @p adding determines, whether the result is * stored in the vector * $\mathbf w = \mathbf A^T \cdot \mathbf v$ * or added to it * $\mathbf w \mathrel{+}= \mathbf A^T \cdot \mathbf v$. * * See the documentation of vmult() for details on the implementation. */ template void Tvmult(Vector &w, const Vector &v, const bool adding = false) const; /** * Specialization of above function for compatible Vector::value_type. */ void Tvmult(Vector &w, const Vector &v, const bool adding = false) const; /** * Adding transpose matrix-vector-multiplication $\mathbf w \mathrel{+}= * \mathbf A^T \cdot \mathbf v$. * * See the documentation of vmult() for details on the implementation. */ template void Tvmult_add(Vector &w, const Vector &v) const; /** * Specialization of above function for compatible Vector::value_type. */ void Tvmult_add(Vector &w, const Vector &v) const; /** * Matrix-matrix-multiplication. * * The optional parameter @p adding determines, whether the result is * stored in the matrix * $\mathbf C = \mathbf A \cdot \mathbf B$ * or added to it * $\mathbf C \mathrel{+}= \mathbf A \cdot \mathbf B$. * * @note It is assumed that @p A and @p B have compatible sizes and that * @p C already has the right size. * * @p This function uses the BLAS function Xgemm. */ void mmult(LAPACKFullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Same as before, but stores the result in a FullMatrix, not in a * LAPACKFullMatrix. */ void mmult(FullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Matrix-matrix-multiplication using transpose of this. * * The optional parameter @p adding determines, whether the result is * stored in the matrix * $\mathbf C = \mathbf A^T \cdot \mathbf B$ * or added to it * $\mathbf C \mathrel{+}= \mathbf A^T \cdot \mathbf B$. * * @note It is assumed that @p A and @p B have compatible sizes and that * @p C already has the right size. * * @note This function uses the BLAS function Xgemm. */ void Tmmult(LAPACKFullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Same as before, but stores the result in a FullMatrix, not in a * LAPACKFullMatrix. */ void Tmmult(FullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Matrix-matrix-multiplication using transpose of this and a * diagonal vector @p V. * * If the adding=false then the result is stored in the matrix * $\mathbf C = \mathbf A^T \cdot \rm{diag}(\mathbf V) \cdot \mathbf B$ * otherwise it is added $\mathbf C \mathrel{+}= \mathbf A^T \cdot * \rm{diag}(\mathbf V) \cdot \mathbf B$. * * @note It is assumed that @p A, @p B and @p V have compatible sizes and that * @p C already has the right size. * * @note This function is not provided by LAPACK. The function first forms * $\rm{diag}(\mathbf V) \cdot \mathbf B$ product and then uses the Xgemm * function. */ void Tmmult(LAPACKFullMatrix &C, const LAPACKFullMatrix &B, const Vector &V, const bool adding = false) const; /** * Matrix-matrix-multiplication using transpose of @p B. * * The optional parameter @p adding determines, whether the result is * stored in the matrix * $\mathbf C = \mathbf A \cdot \mathbf B^T$ * or added to it * $\mathbf C \mathrel{+}= \mathbf A \cdot \mathbf B^T$. * * @note It is assumed that @p A and @p B have compatible sizes and that * @p C already has the right size. * * @note This function uses the BLAS function Xgemm. */ void mTmult(LAPACKFullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Same as before, but stores the result in a FullMatrix, not in a * LAPACKFullMatrix. */ void mTmult(FullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Matrix-matrix-multiplication using transpose of this and * @p B. * * The optional parameter @p adding determines, whether the result is * stored in the matrix * $\mathbf C = \mathbf A^T \cdot \mathbf B^T$ * or added to it * $\mathbf C \mathrel{+}= \mathbf A^T \cdot \mathbf B^T$. * * @note It is assumed that @p A and @p B have compatible sizes and that * @p C already has the right size. * * @note This function uses the BLAS function Xgemm. */ void TmTmult(LAPACKFullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Same as before, but stores the result in a FullMatrix, not in a * LAPACKFullMatrix. */ void TmTmult(FullMatrix &C, const LAPACKFullMatrix &B, const bool adding = false) const; /** * Performs out-place transposition. * Matrix @p B should be appropriately sized. * * @note for complex number types, conjugate transpose will be performed. * * @note If deal.II is configured with Intel-MKL, `mkl_?omatcopy` will be used, * otherwise transposition is done element by element. */ void transpose(LAPACKFullMatrix &B) const; /** * Scale rows of this matrix by @p V . This is equivalent to premultiplication * with a diagonal matrix $\mathbf A\leftarrow {\rm diag}(\mathbf V)\mathbf * A$. */ void scale_rows(const Vector &V); /** * Compute the LU factorization of the matrix using LAPACK function Xgetrf. */ void compute_lu_factorization(); /** * Compute the Cholesky factorization of the matrix using LAPACK function * Xpotrf. * * @note The factorization is stored in the lower-triangular part of the matrix. */ void compute_cholesky_factorization(); /** * Estimate the reciprocal of the condition number $1/k(\mathbf A)$ in $L_1$ * norm ($1/(||\mathbf A||_1 \, ||\mathbf A^{-1}||_1)$) of a symmetric * positive definite matrix using Cholesky factorization. This function can * only be called if the matrix is already factorized. * * @note The condition number $k(\mathbf A)$ can be used to estimate the numerical * error related to the matrix inversion or the solution of the * system of linear algebraic equations as * error = std::numeric_limits::epsilon * k. * Alternatively one can get the number of accurate digits * std::floor(std::log10(k)). * * @note The function computes reciprocal of the condition number to * avoid possible overflow if the matrix is nearly singular. * * @param[in] l1_norm Is the $L_1$ norm of the matrix before calling Cholesky * factorization. It can be obtained by calling l1_norm(). */ number reciprocal_condition_number(const number l1_norm) const; /** * Estimate the reciprocal of the condition number $1/k(\mathbf A)$ in $L_1$ * norm for triangular matrices. The matrix has to have the * LAPACKSupport::Property set to either * LAPACKSupport::Property::upper_triangular or * LAPACKSupport::Property::lower_triangular, see set_property(). */ number reciprocal_condition_number() const; /** * Compute the determinant of a matrix. As it requires the LU factorization of * the matrix, this function can only be called after * compute_lu_factorization() has been called. */ number determinant() const; /** * Compute $L_1$ norm. */ number l1_norm() const; /** * Compute $L_\infty$ norm. */ number linfty_norm() const; /** * Compute Frobenius norm */ number frobenius_norm() const; /** * Compute trace of the matrix, i.e. the sum of the diagonal values. * Obviously, the matrix needs to be quadratic for this function. */ number trace() const; /** * Invert the matrix by first computing an LU/Cholesky factorization with the * LAPACK function Xgetrf/Xpotrf and then building the actual inverse using * Xgetri/Xpotri. */ void invert(); /** * Solve the linear system with right hand side @p v and put the solution * back to @p v. The matrix should be either triangular or LU/Cholesky * factorization should be previously computed. * * The flag transposed indicates whether the solution of the transposed * system is to be performed. */ void solve(Vector &v, const bool transposed = false) const; /** * Same as above but for multiple right hand sides (as many as there * are columns in the matrix @p B). */ void solve(LAPACKFullMatrix &B, const bool transposed = false) const; /** * Compute eigenvalues of the matrix. After this routine has been called, * eigenvalues can be retrieved using the eigenvalue() function. The matrix * itself will be LAPACKSupport::unusable after this operation. * * The optional arguments allow to compute left and right eigenvectors as * well. * * Note that the function does not return the computed eigenvalues right * away since that involves copying data around between the output arrays of * the LAPACK functions and any return array. This is often unnecessary * since one may not be interested in all eigenvalues at once, but for * example only the extreme ones. In that case, it is cheaper to just have * this function compute the eigenvalues and have a separate function that * returns whatever eigenvalue is requested. * * @note Calls the LAPACK function Xgeev. */ void compute_eigenvalues(const bool right_eigenvectors = false, const bool left_eigenvectors = false); /** * Compute eigenvalues and eigenvectors of a real symmetric matrix. Only * eigenvalues in the interval $(\rm{lower\_bound}, \rm{upper\_bound}]$ are * computed with the absolute tolerance $\rm abs\_accuracy$. An approximate * eigenvalue is accepted as converged when it is determined to lie in an * interval $[a,b]$ of width less than or equal to $\rm{abs\_accuracy} + eps * * \rm{max}(|a|,|b|)$, where $eps$ is the machine precision. If * $\rm{abs\_accuracy}$ is less than or equal to zero, then * $eps\,|\mathbf{T}|_1$ will be used in its place, where $|\mathbf{T}|_1$ is * the 1-norm of the tridiagonal matrix obtained by reducing $\mathbf A$ to * tridiagonal form. Eigenvalues will be computed most accurately when * $\rm{abs\_accuracy}$ is set to twice the underflow threshold, not zero. * After this routine has been called, all eigenvalues in $(\rm{lower\_bound}, * \rm{upper\_bound}]$ will be stored in eigenvalues and the corresponding * eigenvectors will be stored in the columns of eigenvectors, whose dimension * is set accordingly. * * @note Calls the LAPACK function Xsyevx. */ void compute_eigenvalues_symmetric(const number lower_bound, const number upper_bound, const number abs_accuracy, Vector &eigenvalues, FullMatrix &eigenvectors); /** * Compute generalized eigenvalues and eigenvectors of a real generalized * symmetric eigenproblem of the form * - itype = 1: $\mathbf A \cdot \mathbf x=\lambda \mathbf B \cdot \mathbf x$ * - itype = 2: $\mathbf A \cdot \mathbf B \cdot \mathbf x=\lambda \mathbf x$ * - itype = 3: $\mathbf B \cdot \mathbf A \cdot \mathbf x=\lambda \mathbf x$ * * where $\mathbf A$ is this matrix. $\mathbf A$ * and $\mathbf B$ are assumed to be symmetric, and $\mathbf B$ has to be * positive definite. Only eigenvalues in the interval $(\rm{lower\_bound}, * \rm{upper\_bound}]$ are computed with the absolute tolerance * $\rm{abs\_accuracy}$. An approximate eigenvalue is accepted as converged * when it is determined to lie in an interval $[a,b]$ of width less than or * equal to $\rm{abs\_accuracy} + eps * \rm{max}( |a|,|b| )$, where $eps$ is * the machine precision. If $\rm{abs\_accuracy}$ is less than or equal to * zero, then $eps \, |\mathbf{T}|_1$ will be used in its place, where * $|\mathbf{T}|_1$ is the 1-norm of the tridiagonal matrix obtained by * reducing $\mathbf A$ to tridiagonal form. Eigenvalues will be computed most * accurately when $\rm{abs\_accuracy}$ is set to twice the underflow * threshold, not zero. After this routine has been called, all eigenvalues in * $(\rm{lower\_bound}, \rm{upper\_bound}]$ will be stored in eigenvalues and * the corresponding eigenvectors will be stored in eigenvectors, whose * dimension is set accordingly. * * @note Calls the LAPACK function Xsygvx. */ void compute_generalized_eigenvalues_symmetric( LAPACKFullMatrix &B, const number lower_bound, const number upper_bound, const number abs_accuracy, Vector &eigenvalues, std::vector> &eigenvectors, const types::blas_int itype = 1); /** * Same as the other compute_generalized_eigenvalues_symmetric function * except that all eigenvalues are computed and the tolerance is set * automatically. Note that this function does not return the computed * eigenvalues right away since that involves copying data around between * the output arrays of the LAPACK functions and any return array. This is * often unnecessary since one may not be interested in all eigenvalues at * once, but for example only the extreme ones. In that case, it is cheaper * to just have this function compute the eigenvalues and have a separate * function that returns whatever eigenvalue is requested. Eigenvalues can * be retrieved using the eigenvalue() function. The number of computed * eigenvectors is equal to `eigenvectors.size()`. * * @note Calls the LAPACK function Xsygv. */ void compute_generalized_eigenvalues_symmetric( LAPACKFullMatrix &B, std::vector> &eigenvectors, const types::blas_int itype = 1); /** * Compute the singular value decomposition of the matrix using LAPACK * function Xgesdd. * * Requires that the #state is LAPACKSupport::matrix, fills the data members * #wr, #svd_u, and #svd_vt, and leaves the object in the #state * LAPACKSupport::svd. * * The singular value decomposition factorizes the provided matrix (A) into * three parts: U, sigma, and the transpose of V (V^T), such that A = U sigma * V^T. Sigma is a MxN matrix which contains the singular values of A on * the diagonal while all the other elements are zero. U is a MxM orthogonal * matrix containing the left singular vectors corresponding to the singular * values of A. V is a NxN orthonal matrix containing the right singular * vectors corresponding the singular values of A. * * Note that the variable #svd_vt contains the transpose of V and can be * accessed by get_svd_vt(), while U is accessed with get_svd_u(). */ void compute_svd(); /** * Compute the inverse of the matrix by singular value decomposition. * * Requires that #state is either LAPACKSupport::matrix or * LAPACKSupport::svd. In the first case, this function calls compute_svd(). * After this function, the object will have the #state * LAPACKSupport::inverse_svd. * * For a singular value decomposition, the inverse is simply computed by * replacing all singular values by their reciprocal values. If the matrix * does not have maximal rank, singular values 0 are not touched, thus * computing the minimal norm right inverse of the matrix. * * The parameter @p threshold determines, when a singular value should * be considered zero. It is the ratio of the smallest to the largest * nonzero singular value $s_{max}$. Thus, the inverses of all * singular values less than $s_{max}/\rm{threshold}$ will * be set to zero. */ void compute_inverse_svd(const double threshold = 0.); /** * Same as above but provide the size of the kernel instead of a threshold, * i.e. the @p kernel_size smallest eigenvalues. */ void compute_inverse_svd_with_kernel(const unsigned int kernel_size); /** * Retrieve eigenvalue after compute_eigenvalues() was called. The return * type is always a complex number: In case the underlying matrix is * real-valued, the type `std::complex` is returned, whereas * `number` is returned for complex numbers. */ std::complex::real_type> eigenvalue(const size_type i) const; /** * After a call to compute_eigenvalues(), this function returns the $n\times * n$ matrix of (right) eigenvectors in a decomposition of the form $A V = V * \Lambda$. Note that this function constructs the associated matrix on the * fly, since LAPACK packs complex-conjugate eigenvalue/eigenvector pairs of * real-valued matrices into a real-valued return matrix. This call only * succeeds in case the respective flag `right_eigenvectors` in * compute_eigenvalues() has been set to true. */ FullMatrix::real_type>> get_right_eigenvectors() const; /** * Return the matrix of left eigenvectors after a call to * compute_eigenvalues(), following the same principles as * get_right_eigenvectors(). */ FullMatrix::real_type>> get_left_eigenvectors() const; /** * Retrieve singular values after compute_svd() or compute_inverse_svd() was * called. */ number singular_value(const size_type i) const; /** * Retrieve the matrix #svd_u after compute_svd() or compute_inverse_svd() was * called. */ inline const LAPACKFullMatrix & get_svd_u() const; /** * Retrieve the matrix #svd_vt after compute_svd() or compute_inverse_svd() * was called. */ inline const LAPACKFullMatrix & get_svd_vt() const; /** * Print the matrix and allow formatting of entries. * * The parameters allow for a flexible setting of the output format: * * @param out This specifies the stream to write to. * * @param precision denotes the number of trailing digits. * * @param scientific is used to determine the number format, where * scientific = false means fixed point notation. * * @param width denotes the with of each column. A zero entry for * @p width makes the function compute a width, but it may be changed * to a positive value, if output is crude. * * @param zero_string specifies a string printed for zero entries. * * @param denominator Multiply the whole matrix by this common * denominator to get nicer numbers. * * @param threshold all entries with absolute value smaller than * this are considered zero. * * @param separator specifies a string printed to separate row entries. * * @note The entries stored resemble a matrix only if the state is either * LAPACKSupport::matrix or LAPACK::inverse_matrix. Otherwise, calling this * function is not allowed. */ void print_formatted(std::ostream &out, const unsigned int precision = 3, const bool scientific = true, const unsigned int width = 0, const char *zero_string = " ", const double denominator = 1., const double threshold = 0., const char *separator = " ") const; /** * Return current state after the last operation here. */ LAPACKSupport::State get_state() const; private: /** * Internal function to compute various norms. */ number norm(const char type) const; /** * Since LAPACK operations notoriously change the meaning of the matrix * entries, we record the current state after the last operation here. */ LAPACKSupport::State state; /** * Additional property of the matrix which may help to select more * efficient LAPACK functions. */ LAPACKSupport::Property property; /** * The working array used for some LAPACK functions. */ mutable std::vector work; /** * Integer working array used for some LAPACK functions. */ mutable std::vector iwork; /** * The vector storing the permutations applied for pivoting in the LU- * factorization. * * Also used as the scratch array IWORK for LAPACK functions needing it. */ std::vector ipiv; /** * Workspace for calculating the inverse matrix from an LU factorization. */ std::vector inv_work; /** * Real parts of eigenvalues or the singular values. Filled by * compute_eigenvalues() or compute_svd(). */ std::vector::real_type> wr; /** * Imaginary parts of eigenvalues, or, in the complex scalar case, the * eigenvalues themselves. Filled by compute_eigenvalues. */ std::vector wi; /** * Space where left eigenvectors can be stored. */ std::vector vl; /** * Space where right eigenvectors can be stored. */ std::vector vr; /** * The matrix $\mathbf U$ in the singular value decomposition * $\mathbf U \cdot \mathbf S \cdot \mathbf V^T$. */ std::unique_ptr> svd_u; /** * The matrix $\mathbf V^T$ in the singular value decomposition * $\mathbf U \cdot \mathbf S \cdot \mathbf V^T$. */ std::unique_ptr> svd_vt; /** * Thread mutex. */ mutable Threads::Mutex mutex; }; /** * A preconditioner based on the LU-factorization of LAPACKFullMatrix. * * @ingroup Preconditioners */ template class PreconditionLU : public EnableObserverPointer { public: void initialize(const LAPACKFullMatrix &); void initialize(const LAPACKFullMatrix &, VectorMemory> &); void vmult(Vector &, const Vector &) const; void Tvmult(Vector &, const Vector &) const; void vmult(BlockVector &, const BlockVector &) const; void Tvmult(BlockVector &, const BlockVector &) const; private: ObserverPointer, PreconditionLU> matrix; ObserverPointer>, PreconditionLU> mem; }; /*---------------------- Inline functions -----------------------------------*/ template inline void LAPACKFullMatrix::set(const size_type i, const size_type j, const number value) { (*this)(i, j) = value; } template inline typename LAPACKFullMatrix::size_type LAPACKFullMatrix::m() const { return static_cast(this->n_rows()); } template inline typename LAPACKFullMatrix::size_type LAPACKFullMatrix::n() const { return static_cast(this->n_cols()); } template template inline void LAPACKFullMatrix::copy_from(const MatrixType &M) { this->reinit(M.m(), M.n()); // loop over the elements of the argument matrix row by row, as suggested // in the documentation of the sparse matrix iterator class, and // copy them into the current object for (size_type row = 0; row < M.m(); ++row) { const typename MatrixType::const_iterator end_row = M.end(row); for (typename MatrixType::const_iterator entry = M.begin(row); entry != end_row; ++entry) this->el(row, entry->column()) = entry->value(); } state = LAPACKSupport::matrix; } template template inline void LAPACKFullMatrix::fill(const MatrixType &M, const size_type dst_offset_i, const size_type dst_offset_j, const size_type src_offset_i, const size_type src_offset_j, const number factor, const bool transpose) { // loop over the elements of the argument matrix row by row, as suggested // in the documentation of the sparse matrix iterator class for (size_type row = src_offset_i; row < M.m(); ++row) { const typename MatrixType::const_iterator end_row = M.end(row); for (typename MatrixType::const_iterator entry = M.begin(row); entry != end_row; ++entry) { const size_type i = transpose ? entry->column() : row; const size_type j = transpose ? row : entry->column(); const size_type dst_i = dst_offset_i + i - src_offset_i; const size_type dst_j = dst_offset_j + j - src_offset_j; if (dst_i < this->n_rows() && dst_j < this->n_cols()) (*this)(dst_i, dst_j) = factor * entry->value(); } } state = LAPACKSupport::matrix; } template template void LAPACKFullMatrix::vmult(Vector &, const Vector &, const bool) const { Assert(false, ExcMessage("LAPACKFullMatrix::vmult must be called with a " "matching Vector vector type.")); } template template void LAPACKFullMatrix::vmult_add(Vector &, const Vector &) const { Assert(false, ExcMessage("LAPACKFullMatrix::vmult_add must be called with a " "matching Vector vector type.")); } template template void LAPACKFullMatrix::Tvmult(Vector &, const Vector &, const bool) const { Assert(false, ExcMessage("LAPACKFullMatrix::Tvmult must be called with a " "matching Vector vector type.")); } template template void LAPACKFullMatrix::Tvmult_add(Vector &, const Vector &) const { Assert(false, ExcMessage("LAPACKFullMatrix::Tvmult_add must be called " "with a matching Vector vector type.")); } namespace internal { namespace LAPACKFullMatrixImplementation { template std::complex pack_complex(const RealNumber &real_part, const RealNumber &imaginary_part) { return std::complex(real_part, imaginary_part); } // The eigenvalues in LAPACKFullMatrix with complex-valued matrices are // contained in the 'wi' array, ignoring the 'wr' array. template std::complex pack_complex(const Number &, const std::complex &complex_number) { return complex_number; } } // namespace LAPACKFullMatrixImplementation } // namespace internal template inline std::complex::real_type> LAPACKFullMatrix::eigenvalue(const size_type i) const { Assert(state & LAPACKSupport::eigenvalues, ExcInvalidState()); Assert(wr.size() == this->n_rows(), ExcInternalError()); Assert(wi.size() == this->n_rows(), ExcInternalError()); AssertIndexRange(i, this->n_rows()); return internal::LAPACKFullMatrixImplementation::pack_complex(wr[i], wi[i]); } template inline number LAPACKFullMatrix::singular_value(const size_type i) const { Assert(state == LAPACKSupport::svd || state == LAPACKSupport::inverse_svd, LAPACKSupport::ExcState(state)); AssertIndexRange(i, wr.size()); return wr[i]; } template inline const LAPACKFullMatrix & LAPACKFullMatrix::get_svd_u() const { Assert(state == LAPACKSupport::svd || state == LAPACKSupport::inverse_svd, LAPACKSupport::ExcState(state)); return *svd_u; } template inline const LAPACKFullMatrix & LAPACKFullMatrix::get_svd_vt() const { Assert(state == LAPACKSupport::svd || state == LAPACKSupport::inverse_svd, LAPACKSupport::ExcState(state)); return *svd_vt; } DEAL_II_NAMESPACE_CLOSE #endif