From 2baa2bea63e60ce8c4f8d3d6e91eff32b01dab74 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 3 May 2004 04:08:36 +0000 Subject: [PATCH] Doc updates. git-svn-id: https://svn.dealii.org/trunk@9136 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/lac/include/lac/block_sparse_matrix.h | 107 ++++++++------- deal.II/lac/include/lac/block_vector.h | 127 +++++++++--------- deal.II/lac/include/lac/vector.h | 2 +- 3 files changed, 128 insertions(+), 108 deletions(-) diff --git a/deal.II/lac/include/lac/block_sparse_matrix.h b/deal.II/lac/include/lac/block_sparse_matrix.h index 6100e0bd71..9cc422c38d 100644 --- a/deal.II/lac/include/lac/block_sparse_matrix.h +++ b/deal.II/lac/include/lac/block_sparse_matrix.h @@ -48,6 +48,16 @@ template class BlockVector; * Note that the numbers of blocks and rows are implicitly determined * by the sparsity pattern objects used. * + * Objects of this type are frequently used when a system of differential + * equations has solutions with variables that fall into different + * classes. For example, solutions of the Stokes or Navier-Stokes equations + * have @p dim velocity components and one pressure component. In this case, + * it may make sense to consider the linear system of equations as a system of + * 2x2 blocks, and one can construct preconditioners or solvers based on this + * 2x2 block structure. This class can help you in these cases, as it allows + * to view the matrix alternatively as one big matrix, or as a number of + * individual blocks. + * * @ref Instantiations: some (@ @) * * @author Wolfgang Bangerth, 2000 @@ -126,7 +136,8 @@ class BlockSparseMatrix : public Subscriptor const BlockSparseMatrix* matrix; /** - * Iterator of the underlying matrix class. + * Iterator of the underlying matrix + * class. */ typename SparseMatrix::const_iterator base_iterator; @@ -141,7 +152,8 @@ class BlockSparseMatrix : public Subscriptor unsigned int row_start; /** - * Number of block column where column lies in. + * Number of block column where + * column lies in. */ unsigned int col_block; @@ -162,58 +174,58 @@ class BlockSparseMatrix : public Subscriptor * STL conforming iterator. */ class const_iterator : private Accessor - { - public: - /** - * Constructor. - */ + { + public: + /** + * Constructor. + */ const_iterator(const BlockSparseMatrix*, unsigned int row, unsigned short index); - /** - * Prefix increment. - */ + /** + * Prefix increment. + */ const_iterator& operator++ (); - /** - * Postfix increment. - */ + /** + * Postfix increment. + */ const_iterator& operator++ (int); - /** - * Dereferencing operator. - */ + /** + * Dereferencing operator. + */ const Accessor& operator* () const; - /** - * Dereferencing operator. - */ + /** + * Dereferencing operator. + */ const Accessor* operator-> () const; - /** - * Comparison. True, if - * both iterators point to - * the same matrix - * position. - */ + /** + * Comparison. True, if + * both iterators point to + * the same matrix + * position. + */ bool operator == (const const_iterator&) const; - /** - * Inverse of operator==(). - */ + /** + * Inverse of operator==(). + */ bool operator != (const const_iterator&) const; - /** - * Comparison - * operator. Result is true - * if either the first row - * number is smaller or if - * the row numbers are - * equal and the first - * index is smaller. - */ + /** + * Comparison + * operator. Result is true + * if either the first row + * number is smaller or if + * the row numbers are + * equal and the first + * index is smaller. + */ bool operator < (const const_iterator&) const; - }; + }; /** * Constructor; initializes the @@ -996,20 +1008,24 @@ BlockSparseMatrix::const_iterator::operator++ () // Remember current row inside block unsigned int local_row = this->base_iterator->row(); - // Advance inside block + + // Advance inside block ++this->base_iterator; ++this->a_index; + // If end of row inside block, // advance to next block - if (this->base_iterator == this->matrix->block(this->row_block, this->col_block).end(local_row)) + if (this->base_iterator == + this->matrix->block(this->row_block, this->col_block).end(local_row)) { - if (this->col_blockmatrix->n_block_cols()-1) + if (this->col_block < this->matrix->n_block_cols()-1) { // Advance to next block in // row +//TODO: what if this row in that block is empty? ++this->col_block; this->col_start = this->matrix->sparsity_pattern - ->get_column_indices().local_to_global(this->col_block, 0); + ->get_column_indices().local_to_global(this->col_block, 0); } else { @@ -1019,7 +1035,7 @@ BlockSparseMatrix::const_iterator::operator++ () this->col_start = 0; this->a_index = 0; ++local_row; - if (local_row>=this->matrix->block(this->row_block,0).m()) + if (local_row >= this->matrix->block(this->row_block,0).m()) { // If final row in // block, go to next @@ -1028,7 +1044,7 @@ BlockSparseMatrix::const_iterator::operator++ () ++this->row_block; if (this->row_block < this->matrix->n_block_rows()) this->row_start = this->matrix->sparsity_pattern - ->get_row_indices().local_to_global(this->row_block, 0); + ->get_row_indices().local_to_global(this->row_block, 0); } } // Finally, set base_iterator @@ -1041,6 +1057,7 @@ BlockSparseMatrix::const_iterator::operator++ () // defined state for // comparison. This is the // end() state. +//TODO: this is a particularly bad choice, since it is actually a valid iterator. it should rather be something like the end iterator of the last block! this->base_iterator = this->matrix->block(0, 0).begin(); } return *this; @@ -1113,7 +1130,7 @@ bool BlockSparseMatrix::const_iterator:: operator < (const const_iterator& i) const { - if (this->row_blockrow_block) + if (this->row_block < i->row_block) return true; if (this->row_block == i->row_block) { diff --git a/deal.II/lac/include/lac/block_vector.h b/deal.II/lac/include/lac/block_vector.h index ed4aa2667d..391b3398a5 100644 --- a/deal.II/lac/include/lac/block_vector.h +++ b/deal.II/lac/include/lac/block_vector.h @@ -305,21 +305,21 @@ namespace internal Iterator & operator = (const Iterator &c); /** - * Dereferencing operator. If - * the template argument - * constness is true, - * then no writing to the - * result is possible, making + * Dereferencing operator. If the + * template argument + * constness is + * true, then no writing to + * the result is possible, making * this a const_iterator. */ reference operator * () const; /** - * Dereferencing operator. If - * the template argument - * constness is true, - * then no writing to the - * result is possible, making + * Dereferencing operator. If the + * template argument + * constness is + * true, then no writing to + * the result is possible, making * this a const_iterator. */ pointer operator -> () const; @@ -333,11 +333,10 @@ namespace internal reference operator [] (const difference_type d) const; /** - * Prefix increment operator. This operator - * advances the iterator to - * the next element and - * returns a reference to - * *this. + * Prefix increment operator. This + * operator advances the iterator to + * the next element and returns a + * reference to *this. */ Iterator & operator ++ (); @@ -352,11 +351,10 @@ namespace internal Iterator operator ++ (int); /** - * Prefix decrement operator. This operator - * retracts the iterator to - * the previous element and - * returns a reference to - * *this. + * Prefix decrement operator. This + * operator retracts the iterator to + * the previous element and returns a + * reference to *this. */ Iterator & operator -- (); @@ -376,7 +374,7 @@ namespace internal * checks whether the vectors * pointed to are the same, * and if not it throws an - * exception. + * exception. */ bool operator == (const Iterator &i) const; @@ -393,7 +391,7 @@ namespace internal * checks whether the vectors * pointed to are the same, * and if not it throws an - * exception. + * exception. */ bool operator != (const Iterator &i) const; @@ -604,12 +602,12 @@ namespace internal * block vector with constant block size is supported by constructor * and reinit() functions. * - * The functionality of BlockVector includes everything a Vector can - * do, plus the access to a single Vector inside the BlockVector by - * block(i). It also has a complete random access iterator, just as + * The functionality of BlockVector includes everything a Vector can do, plus + * the access to a single Vector inside the BlockVector by + * block(i). It also has a complete random access iterator, just as * the LAC Vector class or the standard C++ library template - * std::vector. Therefore, all algorithms working on - * iterators also work with objects of this class. + * std::vector. Therefore, all algorithms working on iterators also + * work with objects of this class. * * * @section BlockVectorAccess Accessing individual blocks, and resizing vectors @@ -818,10 +816,11 @@ class BlockVector /** * Set all entries to zero. Equivalent to - * v = 0, but more obvious and faster. - * Note that this function does not change - * the size of the vector, unlike the - * STL's vector<>::clear function. + * v=0, but more obvious and + * faster. Note that this function does + * not change the size of the vector, + * unlike the STL's + * vector<>::clear function. */ void clear (); @@ -923,28 +922,28 @@ class BlockVector Number norm_sqr () const; /** - * Return the mean value of the elements of - * this vector. + * Return the mean value of the elements + * of this vector. */ Number mean_value () const; /** - * Return the $l_1$-norm of the vector, i.e. - * the sum of the absolute values. + * Return the $l_1$-norm of the vector, + * i.e. the sum of the absolute values. */ Number l1_norm () const; /** - * Return the $l_2$-norm of the vector, i.e. - * the square root of the sum of the - * squares of the elements. + * Return the $l_2$-norm of the vector, + * i.e. the square root of the sum of + * the squares of the elements. */ Number l2_norm () const; /** - * Return the maximum absolute value of the - * elements of this vector, which is the - * $l_\infty$-norm of a vector. + * Return the maximum absolute value of + * the elements of this vector, which is + * the $l_\infty$-norm of a vector. */ Number linfty_norm () const; @@ -954,8 +953,9 @@ class BlockVector unsigned int n_blocks () const; /** - * Return dimension of the vector. This is the - * sum of the dimensions of all components. + * Return dimension of the vector. This + * is the sum of the dimensions of all + * components. */ unsigned int size () const; @@ -968,6 +968,7 @@ class BlockVector * some time. */ bool all_zero () const; + /** * Return @p true if the vector has no * negative entries, i.e. all entries are @@ -1026,23 +1027,24 @@ class BlockVector */ //@{ /** - * Addition operator. - * Fast equivalent to U.add(1, V). + * Addition operator. Fast equivalent to + * U.add(1, V). */ BlockVector & operator += (const BlockVector &V); /** - * Subtraction operator. - * Fast equivalent to U.add(-1, V). + * Subtraction operator. Fast equivalent + * to U.add(-1, V). */ BlockVector & operator -= (const BlockVector &V); /** - * $U(0-DIM)+=s$. - * Addition of s to all components. Note - * that s is a scalar and not a vector. + * $U(0-DIM)+=s$. Addition of s + * to all components. Note that + * s is a scalar and not a + * vector. */ void add (const Number s); @@ -1150,7 +1152,8 @@ class BlockVector */ //@{ /** - * Output of vector in user-defined format. + * Output of vector in user-defined + * format. */ void print (const char* format = 0) const; @@ -1163,21 +1166,21 @@ class BlockVector const bool across = true) const; /** - * Write the vector en bloc to a file. This - * is done in a binary mode, so the output - * is neither readable by humans nor - * (probably) by other computers using - * a different operating system of number - * format. + * Write the vector en bloc to a + * stream. This is done in a binary mode, + * so the output is neither readable by + * humans nor (probably) by other + * computers using a different operating + * system or number format. */ void block_write (std::ostream &out) const; /** - * Read a vector en block from a file. This - * is done using the inverse operations to - * the above function, so it is reasonably - * fast because the bitstream is not - * interpreted. + * Read a vector en block from a + * file. This is done using the inverse + * operations to the above function, so + * it is reasonably fast because the + * bitstream is not interpreted. * * The vector is resized if necessary. * diff --git a/deal.II/lac/include/lac/vector.h b/deal.II/lac/include/lac/vector.h index 5b0471cebe..343809e481 100644 --- a/deal.II/lac/include/lac/vector.h +++ b/deal.II/lac/include/lac/vector.h @@ -663,7 +663,7 @@ class Vector * readable by humans nor * (probably) by other computers * using a different operating - * system of number format. + * system or number format. */ void block_write (std::ostream &out) const; -- 2.39.5