From 3860db0e525435e61270376de66cf7f2811fd6e2 Mon Sep 17 00:00:00 2001 From: guido Date: Thu, 16 Sep 2004 09:44:36 +0000 Subject: [PATCH] documentation structure git-svn-id: https://svn.dealii.org/trunk@9622 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/lac/include/lac/full_matrix.h | 666 +++++++++++++------------- 1 file changed, 341 insertions(+), 325 deletions(-) diff --git a/deal.II/lac/include/lac/full_matrix.h b/deal.II/lac/include/lac/full_matrix.h index 6bb359b3aa..8638e83b76 100644 --- a/deal.II/lac/include/lac/full_matrix.h +++ b/deal.II/lac/include/lac/full_matrix.h @@ -32,7 +32,7 @@ template class Vector; /** - * Rectangular/quadratic full matrix. + * @brief Rectangular/quadratic full matrix. * * Implementation of a classical rectangular scheme of numbers. The * data type of the entries is provided in the template argument @@ -181,7 +181,12 @@ class FullMatrix : public Table<2,number> */ Accessor accessor; }; - +/** + * @name Constructors Constructors and initalization. + * See also the base class Table. + */ +//@{ + /** * Constructor. Initialize the * matrix as a square matrix with @@ -271,17 +276,6 @@ class FullMatrix : public Table<2,number> template void copy_from (const MATRIX&); - /** - * Comparison operator. Be - * careful with this thing, it - * may eat up huge amounts of - * computing time! It is most - * commonly used for internal - * consistency checks of - * programs. - */ - bool operator == (const FullMatrix &) const; - /** * Fill rectangular block. * @@ -337,7 +331,22 @@ class FullMatrix : public Table<2,number> void fill_permutation (const FullMatrix &src, const std::vector &p_rows, const std::vector &p_cols); + +//@} +///@name Non-modifying operators +//@{ + /** + * Comparison operator. Be + * careful with this thing, it + * may eat up huge amounts of + * computing time! It is most + * commonly used for internal + * consistency checks of + * programs. + */ + bool operator == (const FullMatrix &) const; + /** * Number of rows of this matrix. * To remember: this matrix is an @@ -364,6 +373,170 @@ class FullMatrix : public Table<2,number> */ bool all_zero () const; + /** + * Return the square of the norm + * of the vector v with + * respect to the norm induced by + * this matrix, + * i.e. (v,Mv). This is + * useful, e.g. in the finite + * element context, where the + * L2 norm of a + * function equals the matrix + * norm with respect to the mass + * matrix of the vector + * representing the nodal values + * of the finite element + * function. + * + * Obviously, the matrix needs to + * be quadratic for this operation. + */ + template + number2 matrix_norm_square (const Vector &v) const; + + /** + * Build the matrix scalar product + * u^T M v. This function is mostly + * useful when building the cellwise + * scalar product of two functions in + * the finite element context. + */ + template + number2 matrix_scalar_product (const Vector &u, + const Vector &v) const; + + /** + * Return the $l_1$-norm of the matrix, i.e. + * $|M|_1=max_{all columns j}\sum_{all + * rows i} |M_ij|$, + * (max. sum of columns). This is the + * natural matrix norm that is compatible + * to the $l_1$-norm for vectors, i.e. + * $|Mv|_1\leq |M|_1 |v|_1$. + * (cf. Rannacher Numerik0) + */ + number l1_norm () const; + + /** + * Return the $l_\infty$-norm of the + * matrix, i.e. + * $|M|_\infty=\max_{all rows i}\sum_{all + * columns j} |M_{ij}|$, + * (max. sum of rows). + * This is the + * natural matrix norm that is compatible + * to the $l_\infty$-norm of vectors, i.e. + * $|Mv|_\infty \leq |M|_\infty |v|_\infty$. + * (cf. Rannacher Numerik0) + */ + number linfty_norm () const; + + /** + * Compute the quadratic matrix norm. + * Return value is the root of the square + * sum of all matrix entries. Also called + * Frobenius norm. + * + * This norm is compatible with the $l_2$ + * vector norm. But it is not a natural + * matrix norm (cf Rannacher Numeric0), + * therefore it is not called $l_2$-norm. + */ + number norm2 () const; + + /** + * Compute the relative norm of + * the skew-symmetric part. The + * return value is the Frobenius + * norm of the skew-symmetric + * part of the matrix divided by + * that of the matrix. + * + * Main purpose of this function + * is to check, if a matrix is + * symmetric within a certain + * accuracy, or not. + */ + number relative_symmetry_norm2 () const; + + /** + * Computes the determinant of a + * matrix. This is only + * implemented for one, two, and + * three dimensions, since for + * higher dimensions the + * numerical work explodes. + * Obviously, the matrix needs to + * be quadratic for this function. + */ + double determinant () const; + + /** + * Output of the matrix in + * user-defined format. + */ + void print (std::ostream &s, + const unsigned int width=5, + const unsigned int precision=2) const; + + /** + * Print the matrix in the usual + * format, i.e. as a matrix and + * not as a list of nonzero + * elements. For better + * readability, elements not in + * the matrix are displayed as + * empty space, while matrix + * elements which are explicitly + * set to zero are displayed as + * such. + * + * The parameters allow for a + * flexible setting of the output + * format: precision and + * scientific are used to + * determine the number format, + * where scientific = false + * means fixed point notation. A + * zero entry for width makes + * the function compute a width, + * but it may be changed to a + * positive value, if output is + * crude. + * + * Additionally, a character for + * an empty value may be + * specified. + * + * Finally, the whole matrix can + * be multiplied with a common + * denominator to produce more + * readable output, even + * integers. + * + * @attention This function + * may produce large amounts of + * output if applied to a large matrix! + */ + void print_formatted (std::ostream &out, + const unsigned int presicion=3, + const bool scientific = true, + const unsigned int width = 0, + const char *zero_string = " ", + const double denominator = 1.) const; + + /** + * Determine an estimate for the + * memory consumption (in bytes) + * of this object. + */ + unsigned int memory_consumption () const; + +//@} +///@name Iterator functions +//@{ + /** * STL-like iterator with the * first entry. @@ -385,6 +558,10 @@ class FullMatrix : public Table<2,number> * Final iterator of row r. */ const_iterator end (const unsigned int r) const; + +//@} +///@name Modifying operators +//@{ /** * Scale the entire matrix by a @@ -492,121 +669,69 @@ class FullMatrix : public Table<2,number> const unsigned int dst_offset_j = 0, const unsigned int src_offset_i = 0, const unsigned int src_offset_j = 0); - + /** - * Matrix-matrix-multiplication. - * - * The optional parameter - * adding determines, whether the - * result is stored in C or added - * to C. - * - * if (adding) - * $C += A*B$ - * - * if (!adding) - * $C = A*B$ - * - * Assumes that A and B have - * compatible sizes and that C - * already has the right size. + * $A(i,1...n)+=s*A(j,1...n)$. + * Simple addition of rows of this */ - template - void mmult (FullMatrix &C, - const FullMatrix &B, - const bool adding=false) const; - + void add_row (const unsigned int i, + const number s, + const unsigned int j); + /** - * Matrix-matrix-multiplication using - * transpose of this. - * - * The optional parameter - * adding determines, whether the - * result is stored in C or added - * to C. - * - * if (adding) - * $C += A^T*B$ - * - * if (!adding) - * $C = A^T*B$ - * - * Assumes that A and B have - * compatible sizes and that C - * already has the right size. + * $A(i,1...n)+=s*A(j,1...n)+t*A(k,1...n)$. + * Multiple addition of rows of this. */ - template - void Tmmult (FullMatrix &C, - const FullMatrix &B, - const bool adding=false) const; - + void add_row (const unsigned int i, + const number s, const unsigned int j, + const number t, const unsigned int k); + /** - * Matrix-vector-multiplication. - * - * The optional parameter - * adding determines, whether the - * result is stored in w or added - * to w. - * - * if (adding) - * $w += A*v$ - * - * if (!adding) - * $w = A*v$ - * - * Source and destination must - * not be the same vector. + * $A(1...n,i)+=s*A(1...n,j)$. + * Simple addition of columns of this. */ - template - void vmult (Vector &w, - const Vector &v, - const bool adding=false) const; - + void add_col (const unsigned int i, + const number s, + const unsigned int j); + /** - * Transpose - * matrix-vector-multiplication. - * See vmult() above. - * - * Source and destination must - * not be the same vector. + * $A(1...n,i)+=s*A(1...n,j)+t*A(1...n,k)$. + * Multiple addition of columns of this. */ - template - void Tvmult (Vector &w, - const Vector &v, - const bool adding=false) const; + void add_col (const unsigned int i, + const number s, const unsigned int j, + const number t, const unsigned int k); /** - * Return the square of the norm - * of the vector v with - * respect to the norm induced by - * this matrix, - * i.e. (v,Mv). This is - * useful, e.g. in the finite - * element context, where the - * L2 norm of a - * function equals the matrix - * norm with respect to the mass - * matrix of the vector - * representing the nodal values - * of the finite element - * function. - * - * Obviously, the matrix needs to - * be quadratic for this operation. + * Swap A(i,1...n) <-> A(j,1...n). + * Swap rows i and j of this */ - template - number2 matrix_norm_square (const Vector &v) const; + void swap_row (const unsigned int i, + const unsigned int j); /** - * Build the matrix scalar product - * u^T M v. This function is mostly - * useful when building the cellwise - * scalar product of two functions in - * the finite element context. + * Swap A(1...n,i) <-> A(1...n,j). + * Swap columns i and j of this + */ + void swap_col (const unsigned int i, + const unsigned int j); + + /** + * A(i,i)+=B(i,1...n). Addition of complete + * rows of B to diagonal-elements of this ;

+ * ( i = 1 ... m ) */ template - number2 matrix_scalar_product (const Vector &u, - const Vector &v) const; + void add_diag (const number s, + const FullMatrix &B); + + /** + * Add constant to diagonal + * elements of this, i.e. add a + * multiple of the identity + * matrix. + */ + void diagadd (const number s); /** * Symmetrize the matrix by @@ -618,62 +743,8 @@ class FullMatrix : public Table<2,number> * quadratic for this operation. */ void symmetrize (); - - /** - * Return the $l_1$-norm of the matrix, i.e. - * $|M|_1=max_{all columns j}\sum_{all - * rows i} |M_ij|$, - * (max. sum of columns). This is the - * natural matrix norm that is compatible - * to the $l_1$-norm for vectors, i.e. - * $|Mv|_1\leq |M|_1 |v|_1$. - * (cf. Rannacher Numerik0) - */ - number l1_norm () const; /** - * Return the $l_\infty$-norm of the - * matrix, i.e. - * $|M|_\infty=\max_{all rows i}\sum_{all - * columns j} |M_{ij}|$, - * (max. sum of rows). - * This is the - * natural matrix norm that is compatible - * to the $l_\infty$-norm of vectors, i.e. - * $|Mv|_\infty \leq |M|_\infty |v|_\infty$. - * (cf. Rannacher Numerik0) - */ - number linfty_norm () const; - - /** - * Compute the quadratic matrix norm. - * Return value is the root of the square - * sum of all matrix entries. Also called - * Frobenius norm. - * - * This norm is compatible with the $l_2$ - * vector norm. But it is not a natural - * matrix norm (cf Rannacher Numeric0), - * therefore it is not called $l_2$-norm. - */ - number norm2 () const; - - /** - * Compute the relative norm of - * the skew-symmetric part. The - * return value is the Frobenius - * norm of the skew-symmetric - * part of the matrix divided by - * that of the matrix. - * - * Main purpose of this function - * is to check, if a matrix is - * symmetric within a certain - * accuracy, or not. - */ - number relative_symmetry_norm2 () const; - - /** * A=Inverse(A). Inversion of * this matrix by Gauss-Jordan * algorithm with partial @@ -689,18 +760,6 @@ class FullMatrix : public Table<2,number> */ void gauss_jordan (); - /** - * Computes the determinant of a - * matrix. This is only - * implemented for one, two, and - * three dimensions, since for - * higher dimensions the - * numerical work explodes. - * Obviously, the matrix needs to - * be quadratic for this function. - */ - double determinant () const; - /** * Assign the inverse of the * given matrix to @@ -716,84 +775,124 @@ class FullMatrix : public Table<2,number> template void invert (const FullMatrix &M); - /** - * Apply the Jacobi - * preconditioner, which - * multiplies every element of - * the src vector by the - * inverse of the respective - * diagonal element and - * multiplies the result with the - * damping factor omega. - */ - template - void precondition_Jacobi (Vector &dst, - const Vector &src, - const number omega = 1.) const; - - /** - * $A(i,1...n)+=s*A(j,1...n)$. - * Simple addition of rows of this - */ - void add_row (const unsigned int i, - const number s, - const unsigned int j); - - /** - * $A(i,1...n)+=s*A(j,1...n)+t*A(k,1...n)$. - * Multiple addition of rows of this. - */ - void add_row (const unsigned int i, - const number s, const unsigned int j, - const number t, const unsigned int k); /** - * $A(1...n,i)+=s*A(1...n,j)$. - * Simple addition of columns of this. + * QR-factorization of a matrix. + * The orthogonal transformation + * Q is applied to the vector y + * and this matrix. + * + * After execution of + * householder, the upper + * triangle contains the + * resulting matrix R, the lower + * the incomplete factorization + * matrices. */ - void add_col (const unsigned int i, - const number s, - const unsigned int j); + template + void householder (Vector &y); +//@} +///@name Multiplications +//@{ + /** - * $A(1...n,i)+=s*A(1...n,j)+t*A(1...n,k)$. - * Multiple addition of columns of this. + * Matrix-matrix-multiplication. + * + * The optional parameter + * adding determines, whether the + * result is stored in C or added + * to C. + * + * if (adding) + * $C += A*B$ + * + * if (!adding) + * $C = A*B$ + * + * Assumes that A and B have + * compatible sizes and that C + * already has the right size. */ - void add_col (const unsigned int i, - const number s, const unsigned int j, - const number t, const unsigned int k); - + template + void mmult (FullMatrix &C, + const FullMatrix &B, + const bool adding=false) const; + /** - * Swap A(i,1...n) <-> A(j,1...n). - * Swap rows i and j of this + * Matrix-matrix-multiplication using + * transpose of this. + * + * The optional parameter + * adding determines, whether the + * result is stored in C or added + * to C. + * + * if (adding) + * $C += A^T*B$ + * + * if (!adding) + * $C = A^T*B$ + * + * Assumes that A and B have + * compatible sizes and that C + * already has the right size. */ - void swap_row (const unsigned int i, - const unsigned int j); - + template + void Tmmult (FullMatrix &C, + const FullMatrix &B, + const bool adding=false) const; + /** - * Swap A(1...n,i) <-> A(1...n,j). - * Swap columns i and j of this + * Matrix-vector-multiplication. + * + * The optional parameter + * adding determines, whether the + * result is stored in w or added + * to w. + * + * if (adding) + * $w += A*v$ + * + * if (!adding) + * $w = A*v$ + * + * Source and destination must + * not be the same vector. */ - void swap_col (const unsigned int i, - const unsigned int j); - + template + void vmult (Vector &w, + const Vector &v, + const bool adding=false) const; + /** - * A(i,i)+=B(i,1...n). Addition of complete - * rows of B to diagonal-elements of this ;

- * ( i = 1 ... m ) + * Transpose + * matrix-vector-multiplication. + * See vmult() above. + * + * Source and destination must + * not be the same vector. */ template - void add_diag (const number s, - const FullMatrix &B); + void Tvmult (Vector &w, + const Vector &v, + const bool adding=false) const; /** - * Add constant to diagonal - * elements of this, i.e. add a - * multiple of the identity - * matrix. + * Apply the Jacobi + * preconditioner, which + * multiplies every element of + * the src vector by the + * inverse of the respective + * diagonal element and + * multiplies the result with the + * damping factor omega. */ - void diagadd (const number s); - + template + void precondition_Jacobi (Vector &dst, + const Vector &src, + const number omega = 1.) const; + /** * dst=b-A*x. Residual calculation, * returns the l2-norm @@ -858,22 +957,6 @@ class FullMatrix : public Table<2,number> void backward (Vector &dst, const Vector &src) const; - /** - * QR-factorization of a matrix. - * The orthogonal transformation - * Q is applied to the vector y - * and this matrix. - * - * After execution of - * householder, the upper - * triangle contains the - * resulting matrix R, the lower - * the incomplete factorization - * matrices. - */ - template - void householder (Vector &y); - /** * Least-Squares-Approximation by * QR-factorization. The return @@ -883,68 +966,8 @@ class FullMatrix : public Table<2,number> template double least_squares (Vector &dst, Vector &src); +//@} - /** - * Output of the matrix in - * user-defined format. - */ - void print (std::ostream &s, - const unsigned int width=5, - const unsigned int precision=2) const; - - /** - * Print the matrix in the usual - * format, i.e. as a matrix and - * not as a list of nonzero - * elements. For better - * readability, elements not in - * the matrix are displayed as - * empty space, while matrix - * elements which are explicitly - * set to zero are displayed as - * such. - * - * The parameters allow for a - * flexible setting of the output - * format: precision and - * scientific are used to - * determine the number format, - * where scientific = false - * means fixed point notation. A - * zero entry for width makes - * the function compute a width, - * but it may be changed to a - * positive value, if output is - * crude. - * - * Additionally, a character for - * an empty value may be - * specified. - * - * Finally, the whole matrix can - * be multiplied with a common - * denominator to produce more - * readable output, even - * integers. - * - * @attention This function - * may produce large amounts of - * output if applied to a large matrix! - */ - void print_formatted (std::ostream &out, - const unsigned int presicion=3, - const bool scientific = true, - const unsigned int width = 0, - const char *zero_string = " ", - const double denominator = 1.) const; - - /** - * Determine an estimate for the - * memory consumption (in bytes) - * of this object. - */ - unsigned int memory_consumption () const; - /** * Exception */ @@ -952,13 +975,6 @@ class FullMatrix : public Table<2,number> /** * Exception */ - DeclException2 (ExcDimensionMismatch, - int, int, - << "The two dimensions " << arg1 << " and " << arg2 - << " do not match here."); - /** - * Exception - */ DeclException0 (ExcNotQuadratic); /** * Exception -- 2.39.5