From e18bb50edc5782ba6f4fefaaffa252d1be7d04a9 Mon Sep 17 00:00:00 2001 From: bangerth Date: Fri, 14 Feb 2014 19:46:35 +0000 Subject: [PATCH] Add some documentation. git-svn-id: https://svn.dealii.org/trunk@32490 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/include/deal.II/lac/matrix_lib.h | 49 +++++++++++++------- deal.II/include/deal.II/lac/pointer_matrix.h | 16 +++---- 2 files changed, 40 insertions(+), 25 deletions(-) diff --git a/deal.II/include/deal.II/lac/matrix_lib.h b/deal.II/include/deal.II/lac/matrix_lib.h index 2a438f0271..589ea82620 100644 --- a/deal.II/include/deal.II/lac/matrix_lib.h +++ b/deal.II/include/deal.II/lac/matrix_lib.h @@ -38,9 +38,12 @@ template class SparseMatrix; * quadratic matrices #m1 and #m2 of arbitrary types and implements * matrix-vector multiplications for the product * M1M2 by performing multiplication with - * both factors consecutively. + * both factors consecutively. Because the types of the matrices are + * opaque (i.e., they can be arbitrary), you can stack products of three + * or more matrices by making one of the two matrices an object of the + * current type handles be a ProductMatrix itself. * - * Here an example multiplying two different FullMatrix objects: + * Here is an example multiplying two different FullMatrix objects: * @include product_matrix.cc * * @author Guido Kanschat, 2000, 2001, 2002, 2005 @@ -75,6 +78,11 @@ public: const MATRIX2 &m2, VectorMemory &mem); + /** + * Destructor. + */ + ~ProductMatrix(); + /** * Change the matrices. */ @@ -88,11 +96,6 @@ public: void initialize(const MATRIX1 &m1, const MATRIX2 &m2, VectorMemory &mem); - /** - * Destructor. - */ - ~ProductMatrix(); - // Doc in PointerMatrixBase void clear(); @@ -104,7 +107,7 @@ public: const VECTOR &v) const; /** - * Tranposed matrix-vector + * Transposed matrix-vector * product w = m2T * * m1T * v. */ @@ -119,7 +122,7 @@ public: const VECTOR &v) const; /** - * Adding, tranposed + * Adding, transposed * matrix-vector product w += * m2T * * m1T * v. @@ -142,6 +145,7 @@ private: * Memory for auxiliary vector. */ SmartPointer,ProductMatrix > mem; + /** * Return some kind of * identifier. @@ -151,10 +155,11 @@ private: /** - * A matrix that is the scaled version of another matrix. + * A matrix that is the multiple of another matrix. * * Matrix-vector products of this matrix are composed of those of the - * original matrix and scaling by a constant factor. + * original matrix with the vector and then scaling of the result by + * a constant factor. * * @author Guido Kanschat, 2007 */ @@ -252,7 +257,7 @@ public: /** * Constructor leaving an - * unitialized + * uninitialized * matrix. initialize() must be * called, before the matrix can * be used. @@ -274,7 +279,7 @@ public: const VectorType &v) const; /** - * Tranposed matrix-vector + * Transposed matrix-vector * product w = m2T * * m1T * v. */ @@ -289,7 +294,7 @@ public: const VectorType &v) const; /** - * Adding, tranposed + * Adding, transposed * matrix-vector product w += * m2T * * m1T * v. @@ -326,6 +331,16 @@ private: * BlockVector, then an additional parameter selects a single * component for this operation. * + * In mathematical terms, this class acts as if it was the matrix + * $I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T$ where ${\mathbf 1}_n$ is + * a vector of size $n$ that has only ones as its entries. Thus, + * taking the dot product between a vector $\mathbf v$ and + * $\frac 1n {\mathbf 1}_n$ yields the mean value of the entries + * of ${\mathbf v}$. Consequently, + * $ \left[I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T\right] \mathbf v + * = \mathbf v - \left[\frac 1n \mathbf v} \cdot {\mathbf 1}_n\right]{\mathbf 1}_n$ + * subtracts from every vector element the mean value of all elements. + * * @author Guido Kanschat, 2002, 2003 */ class MeanValueFilter : public Subscriptor @@ -340,7 +355,7 @@ public: * Constructor, optionally * selecting a component. */ - MeanValueFilter(size_type component = numbers::invalid_size_type); + MeanValueFilter(const size_type component = numbers::invalid_size_type); /** * Subtract mean value from @p v. @@ -405,7 +420,7 @@ private: /** * Component for filtering block vectors. */ - size_type component; + const size_type component; }; @@ -416,7 +431,7 @@ private: * SolverRichardson::Tsolve() allows for the implementation of * transpose matrix vector products. * - * The functions vmult() and Tvmult() appoximate the inverse + * The functions vmult() and Tvmult() approximate the inverse * iteratively starting with the vector dst. Functions * vmult_add() and Tvmult_add() start the iteration with a zero * vector. diff --git a/deal.II/include/deal.II/lac/pointer_matrix.h b/deal.II/include/deal.II/lac/pointer_matrix.h index 6c0d5ca692..b53d6bab4b 100644 --- a/deal.II/include/deal.II/lac/pointer_matrix.h +++ b/deal.II/include/deal.II/lac/pointer_matrix.h @@ -127,7 +127,7 @@ public: const VECTOR &src) const = 0; /** - * Tranposed matrix-vector product. + * Transposed matrix-vector product. */ virtual void Tvmult (VECTOR &dst, const VECTOR &src) const = 0; @@ -140,7 +140,7 @@ public: const VECTOR &src) const = 0; /** - * Tranposed matrix-vector product, + * Transposed matrix-vector product, * adding to dst. */ virtual void Tvmult_add (VECTOR &dst, @@ -222,7 +222,7 @@ public: const VECTOR &src) const; /** - * Tranposed matrix-vector product. + * Transposed matrix-vector product. */ virtual void Tvmult (VECTOR &dst, const VECTOR &src) const; @@ -235,7 +235,7 @@ public: const VECTOR &src) const; /** - * Tranposed matrix-vector product, + * Transposed matrix-vector product, * adding to dst. */ virtual void Tvmult_add (VECTOR &dst, @@ -344,7 +344,7 @@ public: const VECTOR &src) const; /** - * Tranposed matrix-vector product. + * Transposed matrix-vector product. */ virtual void Tvmult (VECTOR &dst, const VECTOR &src) const; @@ -357,7 +357,7 @@ public: const VECTOR &src) const; /** - * Tranposed matrix-vector product, + * Transposed matrix-vector product, * adding to dst. */ virtual void Tvmult_add (VECTOR &dst, @@ -468,7 +468,7 @@ public: const Vector &src) const; /** - * Tranposed matrix-vector + * Transposed matrix-vector * product, actually the * multiplication of the vector * representing this matrix with @@ -497,7 +497,7 @@ public: const Vector &src) const; /** - * Tranposed matrix-vector product, + * Transposed matrix-vector product, * adding to dst. * * The dimension of src -- 2.39.5