From f00f06e812c092bd5bc09a218c3945fef763424e Mon Sep 17 00:00:00 2001 From: kronbichler Date: Thu, 25 Sep 2008 16:18:40 +0000 Subject: [PATCH] Group the comments in a better way. git-svn-id: https://svn.dealii.org/trunk@17008 0785d39b-7218-0410-832d-ea1e28bc413d --- .../lac/include/lac/trilinos_sparse_matrix.h | 419 ++++++++++-------- .../lac/include/lac/trilinos_vector_base.h | 185 ++++---- 2 files changed, 343 insertions(+), 261 deletions(-) diff --git a/deal.II/lac/include/lac/trilinos_sparse_matrix.h b/deal.II/lac/include/lac/trilinos_sparse_matrix.h index 6639ae82c2..315f6e3d1b 100755 --- a/deal.II/lac/include/lac/trilinos_sparse_matrix.h +++ b/deal.II/lac/include/lac/trilinos_sparse_matrix.h @@ -328,6 +328,10 @@ namespace TrilinosWrappers */ typedef TrilinosScalar value_type; +/** + * @name Constructors and initalization. + */ +//@{ /** * Default constructor. Generates * an empty (zero-size) matrix. @@ -445,16 +449,6 @@ namespace TrilinosWrappers */ virtual ~SparseMatrix (); - /** - * Copy the given matrix to this - * one. - * - * The function returns a - * reference to *this. - */ - SparseMatrix & - copy_from (const SparseMatrix &source); - /** * This function initializes * the Trilinos matrix with a @@ -603,6 +597,27 @@ namespace TrilinosWrappers const ::dealii::SparseMatrix &dealii_sparse_matrix, const double drop_tolerance=1e-13); + /** + * This operator assigns a scalar + * to a matrix. Since this does + * usually not make much sense + * (should we set all matrix + * entries to this value? Only + * the nonzero entries of the + * sparsity pattern?), this + * operation is only allowed if + * the actual value to be + * assigned is zero. This + * operator only exists to allow + * for the obvious notation + * matrix=0, which sets + * all elements of the matrix to + * zero, but keeps the sparsity + * pattern previously used. + */ + SparseMatrix & + operator = (const double d); + /** * Release all memory and * return to a state just like @@ -652,28 +667,108 @@ namespace TrilinosWrappers * compress(). */ bool is_compressed () const; +//@} +/** + * @name Information on the matrix + */ +//@{ + + /** + * Return the number of rows in + * this matrix. + */ + unsigned int m () const; /** - * This operator assigns a scalar - * to a matrix. Since this does - * usually not make much sense - * (should we set all matrix - * entries to this value? Only - * the nonzero entries of the - * sparsity pattern?), this - * operation is only allowed if - * the actual value to be - * assigned is zero. This - * operator only exists to allow - * for the obvious notation - * matrix=0, which sets - * all elements of the matrix to - * zero, but keeps the sparsity - * pattern previously used. + * Return the number of columns + * in this matrix. */ - SparseMatrix & - operator = (const double d); + unsigned int n () const; + /** + * Return the local dimension + * of the matrix, i.e. the + * number of rows stored on the + * present MPI process. For + * sequential matrices, this + * number is the same as m(), + * but for parallel matrices it + * may be smaller. + * + * To figure out which elements + * exactly are stored locally, + * use local_range(). + */ + unsigned int local_size () const; + + /** + * Return a pair of indices + * indicating which rows of + * this matrix are stored + * locally. The first number is + * the index of the first row + * stored, the second the index + * of the one past the last one + * that is stored locally. If + * this is a sequential matrix, + * then the result will be the + * pair (0,m()), otherwise it + * will be a pair (i,i+n), + * where + * n=local_size(). + */ + std::pair + local_range () const; + + /** + * Return whether @p index is + * in the local range or not, + * see also local_range(). + */ + bool in_local_range (const unsigned int index) const; + + /** + * Return the number of nonzero + * elements of this matrix. + */ + unsigned int n_nonzero_elements () const; + + /** + * Number of entries in a + * specific row. + */ + unsigned int row_length (const unsigned int row) const; + + /** + * Test whether a matrix is + * symmetric. Default + * tolerance is zero. TODO: + * Not implemented. + */ + bool is_symmetric (const double tol = 0.0) const; + + /** + * Test whether a matrix is + * Hermitian, i.e. it is the + * complex conjugate of its + * transpose. TODO: Not + * implemented. + */ + + bool is_hermitian () const; + /** + * Determine an estimate for the + * memory consumption (in bytes) + * of this object. Currently not + * implemented for this class. + */ + unsigned int memory_consumption () const; + +//@} +/** + * @name Modifying entries + */ +//@{ /** * Set the element (i,j) * to @p value. @@ -711,6 +806,38 @@ namespace TrilinosWrappers void add (const unsigned int i, const unsigned int j, const TrilinosScalar value); + + /** + * Multiply the entire matrix + * by a fixed factor. + */ + SparseMatrix & operator *= (const TrilinosScalar factor); + + /** + * Divide the entire matrix by + * a fixed factor. + */ + SparseMatrix & operator /= (const TrilinosScalar factor); + + /** + * Copy the given matrix to this + * one. + * + * The function returns a + * reference to *this. + */ + SparseMatrix & + copy_from (const SparseMatrix &source); + + /** + * Add matrix scaled + * by factor to this + * matrix, i.e. the matrix + * factor*matrix is + * added to this. + */ + void add (const TrilinosScalar factor, + const SparseMatrix &matrix); /** * Remove all elements from @@ -773,6 +900,18 @@ namespace TrilinosWrappers void clear_rows (const std::vector &rows, const TrilinosScalar new_diag_value = 0); + /** + * Make an in-place transpose + * of a matrix. + */ + void transpose (); + +//@} +/** + * @name Entry Access + */ +//@{ + /** * Return the value of the * entry (i,j). This @@ -820,128 +959,12 @@ namespace TrilinosWrappers * quadratic. */ TrilinosScalar diag_element (const unsigned int i) const; - - /** - * Return the number of rows in - * this matrix. - */ - unsigned int m () const; - /** - * Return the number of columns - * in this matrix. - */ - unsigned int n () const; - - /** - * Return the local dimension - * of the matrix, i.e. the - * number of rows stored on the - * present MPI process. For - * sequential matrices, this - * number is the same as m(), - * but for parallel matrices it - * may be smaller. - * - * To figure out which elements - * exactly are stored locally, - * use local_range(). - */ - unsigned int local_size () const; - - /** - * Return a pair of indices - * indicating which rows of - * this matrix are stored - * locally. The first number is - * the index of the first row - * stored, the second the index - * of the one past the last one - * that is stored locally. If - * this is a sequential matrix, - * then the result will be the - * pair (0,m()), otherwise it - * will be a pair (i,i+n), - * where - * n=local_size(). - */ - std::pair - local_range () const; - - /** - * Return whether @p index is - * in the local range or not, - * see also local_range(). - */ - bool in_local_range (const unsigned int index) const; - - /** - * Return the number of nonzero - * elements of this matrix. - */ - unsigned int n_nonzero_elements () const; - - /** - * Number of entries in a - * specific row. - */ - unsigned int row_length (const unsigned int row) const; - - /** - * Return the - * l1-norm of - * the matrix, that is - * $|M|_1= - * \max_{\mathrm{all columns } j} - * \sum_{\mathrm{all rows } i} - * |M_{ij}|$, (max. sum - * of columns). This is the - * natural matrix norm that is - * compatible to the l1-norm for - * vectors, i.e. $|Mv|_1 \leq - * |M|_1 |v|_1$. - * (cf. Haemmerlin-Hoffmann: - * Numerische Mathematik) - */ - TrilinosScalar l1_norm () const; - - /** - * Return the linfty-norm of the - * matrix, that is - * $|M|_\infty=\max_{\mathrm{all - * rows} i}\sum_{\mathrm{all - * columns} j} |M_{ij}|$, - * (max. sum of rows). This is - * the natural matrix norm that - * is compatible to the - * linfty-norm of vectors, i.e. - * $|Mv|_\infty \leq |M|_\infty - * |v|_\infty$. - * (cf. Haemmerlin-Hoffmann: - * Numerische Mathematik) - */ - TrilinosScalar linfty_norm () const; - - /** - * Return the frobenius norm of - * the matrix, i.e. the square - * root of the sum of squares - * of all entries in the - * matrix. - */ - TrilinosScalar frobenius_norm () const; - - /** - * Multiply the entire matrix - * by a fixed factor. - */ - SparseMatrix & operator *= (const TrilinosScalar factor); - - /** - * Divide the entire matrix by - * a fixed factor. - */ - SparseMatrix & operator /= (const TrilinosScalar factor); +//@} +/** + * @name Matrix vector multiplications + */ +//@{ /** * Matrix-vector multiplication: @@ -1205,15 +1228,61 @@ namespace TrilinosWrappers const VectorBase &x, const VectorBase &b) const; - /** - * Add matrix scaled - * by factor to this - * matrix, i.e. the matrix - * factor*matrix is - * added to this. - */ - void add (const TrilinosScalar factor, - const SparseMatrix &matrix); +//@} +/** + * @name Matrix norms + */ +//@{ + + /** + * Return the + * l1-norm of + * the matrix, that is + * $|M|_1= + * \max_{\mathrm{all columns } j} + * \sum_{\mathrm{all rows } i} + * |M_{ij}|$, (max. sum + * of columns). This is the + * natural matrix norm that is + * compatible to the l1-norm for + * vectors, i.e. $|Mv|_1 \leq + * |M|_1 |v|_1$. + * (cf. Haemmerlin-Hoffmann: + * Numerische Mathematik) + */ + TrilinosScalar l1_norm () const; + + /** + * Return the linfty-norm of the + * matrix, that is + * $|M|_\infty=\max_{\mathrm{all + * rows} i}\sum_{\mathrm{all + * columns} j} |M_{ij}|$, + * (max. sum of rows). This is + * the natural matrix norm that + * is compatible to the + * linfty-norm of vectors, i.e. + * $|Mv|_\infty \leq |M|_\infty + * |v|_\infty$. + * (cf. Haemmerlin-Hoffmann: + * Numerische Mathematik) + */ + TrilinosScalar linfty_norm () const; + + /** + * Return the frobenius norm of + * the matrix, i.e. the square + * root of the sum of squares + * of all entries in the + * matrix. + */ + TrilinosScalar frobenius_norm () const; + +//@} +/** + * @name Iterators + */ +//@{ /** * STL-like iterator with the @@ -1258,30 +1327,13 @@ namespace TrilinosWrappers */ const_iterator end (const unsigned int r) const; - /** - * Make an in-place transpose - * of a matrix. - */ - void transpose (); - - /** - * Test whether a matrix is - * symmetric. Default - * tolerance is zero. TODO: - * Not implemented. - */ - bool is_symmetric (const double tol = 0.0); - - /** - * Test whether a matrix is - * Hermitian, i.e. it is the - * complex conjugate of its - * transpose. TODO: Not - * implemented. - */ - bool is_hermitian (); +//@} +/** + * @name Input/Output + */ +//@{ - /** + /** * Abstract Trilinos object * that helps view in ASCII * other Trilinos @@ -1308,6 +1360,9 @@ namespace TrilinosWrappers // object supports it, this should // be very easy. +//@} + /** @addtogroup Exceptions + * @{ */ /** * Exception */ @@ -1349,7 +1404,7 @@ namespace TrilinosWrappers << "/" << arg2 << ")" << " of a sparse matrix, but it appears to not" << " exist in the Trilinos sparsity pattern."); - + //@} private: /** * Epetra Trilinos diff --git a/deal.II/lac/include/lac/trilinos_vector_base.h b/deal.II/lac/include/lac/trilinos_vector_base.h index 5b64b1ca24..7bffc8adb8 100644 --- a/deal.II/lac/include/lac/trilinos_vector_base.h +++ b/deal.II/lac/include/lac/trilinos_vector_base.h @@ -211,7 +211,7 @@ namespace TrilinosWrappers */ -/** +/** * Base class for the two types of Trilinos vectors, the distributed * memory vector MPI::Vector and a localized vector Vector. The latter * is designed for use in either serial implementations or as a @@ -261,6 +261,11 @@ namespace TrilinosWrappers typedef internal::VectorReference reference; typedef const internal::VectorReference const_reference; + /** + * @name 1: Basic Object-handling + */ + //@{ + /** * Default constructor that * generates an empty (zero size) @@ -427,6 +432,85 @@ namespace TrilinosWrappers */ bool in_local_range (const unsigned int index) const; + /** + * Return the scalar (inner) + * product of two vectors. The + * vectors must have the same + * size. + */ + TrilinosScalar operator * (const VectorBase &vec) const; + + /** + * Return square of the + * $l_2$-norm. + */ + real_type norm_sqr () const; + + /** + * Mean value of the elements of + * this vector. + */ + TrilinosScalar mean_value () const; + + /** + * $l_1$-norm of the vector. The + * sum of the absolute values. + */ + real_type l1_norm () const; + + /** + * $l_2$-norm of the vector. The + * square root of the sum of the + * squares of the elements. + */ + real_type l2_norm () const; + + /** + * $l_p$-norm of the vector. The + * pth root of the sum of + * the pth powers of the + * absolute values of the + * elements. + */ + real_type lp_norm (const TrilinosScalar p) const; + + /** + * Maximum absolute value of the + * elements. + */ + real_type linfty_norm () const; + + /** + * Return whether the vector + * contains only elements with + * value zero. This function is + * mainly for internal + * consistency checks and should + * seldomly be used when not in + * debug mode since it uses quite + * some time. + */ + bool all_zero () const; + + /** + * Return @p true if the vector + * has no negative entries, + * i.e. all entries are zero or + * positive. This function is + * used, for example, to check + * whether refinement indicators + * are really all positive (or + * zero). + */ + bool is_non_negative () const; + //@} + + + /** + * @name 2: Data-Access + */ + //@{ + /** * Provide access to a given * element, both read and write. @@ -478,6 +562,13 @@ namespace TrilinosWrappers */ void set (const std::vector &indices, const ::dealii::Vector &values); + //@} + + + /** + * @name 3: Modification of vectors + */ + //@{ /** * This collective set operation @@ -527,78 +618,6 @@ namespace TrilinosWrappers const unsigned int *indices, const TrilinosScalar *values); - /** - * Return the scalar (inner) - * product of two vectors. The - * vectors must have the same - * size. - */ - TrilinosScalar operator * (const VectorBase &vec) const; - - /** - * Return square of the - * $l_2$-norm. - */ - real_type norm_sqr () const; - - /** - * Mean value of the elements of - * this vector. - */ - TrilinosScalar mean_value () const; - - /** - * $l_1$-norm of the vector. The - * sum of the absolute values. - */ - real_type l1_norm () const; - - /** - * $l_2$-norm of the vector. The - * square root of the sum of the - * squares of the elements. - */ - real_type l2_norm () const; - - /** - * $l_p$-norm of the vector. The - * pth root of the sum of - * the pth powers of the - * absolute values of the - * elements. - */ - real_type lp_norm (const TrilinosScalar p) const; - - /** - * Maximum absolute value of the - * elements. - */ - real_type linfty_norm () const; - - /** - * Return whether the vector - * contains only elements with - * value zero. This function is - * mainly for internal - * consistency checks and should - * seldomly be used when not in - * debug mode since it uses quite - * some time. - */ - bool all_zero () const; - - /** - * Return @p true if the vector - * has no negative entries, - * i.e. all entries are zero or - * positive. This function is - * used, for example, to check - * whether refinement indicators - * are really all positive (or - * zero). - */ - bool is_non_negative () const; - /** * Multiply the entire vector by * a fixed factor. @@ -746,13 +765,20 @@ namespace TrilinosWrappers */ void ratio (const VectorBase &a, const VectorBase &b); + //@} + - /** - * Output of vector in - * user-defined format in analogy - * to the dealii::Vector - * class. - */ + /** + * @name 4: Mixed stuff + */ + //@{ + + /** + * Output of vector in + * user-defined format in analogy + * to the dealii::Vector + * class. + */ void print (const char* format = 0) const; /** @@ -807,6 +833,7 @@ namespace TrilinosWrappers * for this class). */ unsigned int memory_consumption () const; + //@} /** * Exception -- 2.39.5