From dc65490b40f0bde2b717590c66cf5c8b47c23e7e Mon Sep 17 00:00:00 2001 From: kronbichler Date: Sun, 9 Dec 2012 09:55:15 +0000 Subject: [PATCH] Reindent/refill comments in a few files to improve readability. git-svn-id: https://svn.dealii.org/trunk@27783 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/include/deal.II/lac/sparse_matrix.h | 1836 ++++++----------- .../deal.II/lac/sparse_matrix.templates.h | 14 +- .../include/deal.II/lac/sparsity_pattern.h | 1395 ++++--------- 3 files changed, 1053 insertions(+), 2192 deletions(-) diff --git a/deal.II/include/deal.II/lac/sparse_matrix.h b/deal.II/include/deal.II/lac/sparse_matrix.h index 6ec462b0f6..9092530630 100644 --- a/deal.II/include/deal.II/lac/sparse_matrix.h +++ b/deal.II/include/deal.II/lac/sparse_matrix.h @@ -43,21 +43,14 @@ namespace SparseMatrixIterators class Iterator; /** - * General template for sparse matrix - * accessors. The first template argument - * denotes the underlying numeric type, - * the second the constness of the + * General template for sparse matrix accessors. The first template argument + * denotes the underlying numeric type, the second the constness of the * matrix. * - * The general template is not - * implemented, only the - * specializations for the two - * possible values of the second - * template argument. Therefore, - * the interface listed here only - * serves as a template provided - * since doxygen does not link the - * specializations. + * The general template is not implemented, only the specializations for the + * two possible values of the second template argument. Therefore, the + * interface listed here only serves as a template provided since doxygen + * does not link the specializations. */ template class Accessor : public SparsityPatternIterators::Accessor @@ -74,11 +67,8 @@ namespace SparseMatrixIterators number &value(); /** - * Return a reference to the matrix - * into which this accessor - * points. Note that in the present - * case, this is a constant - * reference. + * Return a reference to the matrix into which this accessor points. Note + * that in the present case, this is a constant reference. */ const SparseMatrix &get_matrix () const; }; @@ -86,23 +76,18 @@ namespace SparseMatrixIterators /** - * Accessor class for constant matrices, - * used in the const_iterators. This - * class builds on the accessor classes - * used for sparsity patterns to loop - * over all nonzero entries, and only - * adds the accessor functions to gain - * access to the actual value stored at a - * certain location. + * Accessor class for constant matrices, used in the const_iterators. This + * class builds on the accessor classes used for sparsity patterns to loop + * over all nonzero entries, and only adds the accessor functions to gain + * access to the actual value stored at a certain location. */ template class Accessor : public SparsityPatternIterators::Accessor { public: /** - * Typedef for the type (including - * constness) of the matrix to be - * used here. + * Typedef for the type (including constness) of the matrix to be used + * here. */ typedef const SparseMatrix MatrixType; @@ -114,15 +99,12 @@ namespace SparseMatrixIterators const unsigned int index); /** - * Constructor. Construct the end - * accessor for the given matrix. + * Constructor. Construct the end accessor for the given matrix. */ Accessor (MatrixType *matrix); /** - * Copy constructor to get from a - * non-const accessor to a const - * accessor. + * Copy constructor to get from a non-const accessor to a const accessor. */ Accessor (const SparseMatrixIterators::Accessor &a); @@ -132,11 +114,8 @@ namespace SparseMatrixIterators number value() const; /** - * Return a reference to the matrix - * into which this accessor - * points. Note that in the present - * case, this is a constant - * reference. + * Return a reference to the matrix into which this accessor points. Note + * that in the present case, this is a constant reference. */ MatrixType &get_matrix () const; @@ -147,8 +126,7 @@ namespace SparseMatrixIterators MatrixType *matrix; /** - * Make the advance function of the - * base class available. + * Make the advance function of the base class available. */ using SparsityPatternIterators::Accessor::advance; @@ -161,126 +139,91 @@ namespace SparseMatrixIterators /** - * Accessor class for non-constant - * matrices, used in the iterators. This - * class builds on the accessor classes - * used for sparsity patterns to loop - * over all nonzero entries, and only - * adds the accessor functions to gain - * access to the actual value stored at a - * certain location. + * Accessor class for non-constant matrices, used in the iterators. This + * class builds on the accessor classes used for sparsity patterns to loop + * over all nonzero entries, and only adds the accessor functions to gain + * access to the actual value stored at a certain location. */ template class Accessor : public SparsityPatternIterators::Accessor { private: /** - * Reference class. This is what the - * accessor class returns when you - * call the value() function. The - * reference acts just as if it were - * a reference to the actual value of - * a matrix entry, i.e. you can read - * and write it, you can add and - * multiply to it, etc, but since the - * matrix does not give away the - * address of this matrix entry, we - * have to go through functions to do - * all this. + * Reference class. This is what the accessor class returns when you call + * the value() function. The reference acts just as if it were a reference + * to the actual value of a matrix entry, i.e. you can read and write it, + * you can add and multiply to it, etc, but since the matrix does not give + * away the address of this matrix entry, we have to go through functions + * to do all this. * - * The constructor takes a pointer to - * an accessor object that describes - * which element of the matrix it - * points to. This creates an - * ambiguity when one writes code - * like iterator->value()=0 (instead - * of iterator->value()=0.0), since - * the right hand side is an integer - * that can both be converted to a - * number (i.e., most - * commonly a double) or to another - * object of type - * Reference. The compiler - * then complains about not knowing - * which conversion to take. + * The constructor takes a pointer to an accessor object that describes + * which element of the matrix it points to. This creates an ambiguity + * when one writes code like iterator->value()=0 (instead of + * iterator->value()=0.0), since the right hand side is an integer that + * can both be converted to a number (i.e., most commonly a + * double) or to another object of type Reference. The compiler + * then complains about not knowing which conversion to take. * - * For some reason, adding another - * overload operator=(int) doesn't - * seem to cure the problem. We avoid - * it, however, by adding a second, - * dummy argument to the Reference - * constructor, that is unused, but - * makes sure there is no second - * matching conversion sequence using - * a one-argument right hand side. + * For some reason, adding another overload operator=(int) doesn't seem to + * cure the problem. We avoid it, however, by adding a second, dummy + * argument to the Reference constructor, that is unused, but makes sure + * there is no second matching conversion sequence using a one-argument + * right hand side. * - * The testcase oliver_01 checks that - * this actually works as intended. + * The testcase oliver_01 checks that this actually works as intended. */ class Reference { public: /** - * Constructor. For the second - * argument, see the general - * class documentation. + * Constructor. For the second argument, see the general class + * documentation. */ Reference (const Accessor *accessor, const bool dummy); /** - * Conversion operator to the - * data type of the matrix. + * Conversion operator to the data type of the matrix. */ operator number () const; /** - * Set the element of the matrix - * we presently point to to @p n. + * Set the element of the matrix we presently point to to @p n. */ const Reference &operator = (const number n) const; /** - * Add @p n to the element of the - * matrix we presently point to. + * Add @p n to the element of the matrix we presently point to. */ const Reference &operator += (const number n) const; /** - * Subtract @p n from the element - * of the matrix we presently - * point to. + * Subtract @p n from the element of the matrix we presently point to. */ const Reference &operator -= (const number n) const; /** - * Multiply the element of the - * matrix we presently point to - * by @p n. + * Multiply the element of the matrix we presently point to by @p n. */ const Reference &operator *= (const number n) const; /** - * Divide the element of the - * matrix we presently point to - * by @p n. + * Divide the element of the matrix we presently point to by @p n. */ const Reference &operator /= (const number n) const; private: /** - * Pointer to the accessor that - * denotes which element we - * presently point to. + * Pointer to the accessor that denotes which element we presently point + * to. */ const Accessor *accessor; }; public: /** - * Typedef for the type (including - * constness) of the matrix to be - * used here. + * Typedef for the type (including constness) of the matrix to be used + * here. */ typedef SparseMatrix MatrixType; @@ -292,24 +235,18 @@ namespace SparseMatrixIterators const unsigned int index); /** - * Constructor. Construct the end - * accessor for the given matrix. + * Constructor. Construct the end accessor for the given matrix. */ Accessor (MatrixType *matrix); /** - * Value of this matrix entry, - * returned as a read- and writable - * reference. + * Value of this matrix entry, returned as a read- and writable reference. */ Reference value() const; /** - * Return a reference to the matrix - * into which this accessor - * points. Note that in the present - * case, this is a non-constant - * reference. + * Return a reference to the matrix into which this accessor points. Note + * that in the present case, this is a non-constant reference. */ MatrixType &get_matrix () const; @@ -320,8 +257,7 @@ namespace SparseMatrixIterators MatrixType *matrix; /** - * Make the advance function of the - * base class available. + * Make the advance function of the base class available. */ using SparsityPatternIterators::Accessor::advance; @@ -332,59 +268,49 @@ namespace SparseMatrixIterators friend class Iterator; /** - * Make the inner reference class a - * friend if the compiler has a bug - * and requires this. + * Make the inner reference class a friend if the compiler has a bug and + * requires this. */ }; /** - * STL conforming iterator for constant - * and non-constant matrices. + * STL conforming iterator for constant and non-constant matrices. * - * The first template argument - * denotes the underlying numeric type, - * the second the constness of the - * matrix. + * The first template argument denotes the underlying numeric type, the + * second the constness of the matrix. * - * Since there is a specialization of - * this class for - * Constness=false, this class - * is for iterators to constant matrices. + * Since there is a specialization of this class for + * Constness=false, this class is for iterators to constant + * matrices. */ template class Iterator { public: /** - * Typedef for the matrix type - * (including constness) we are to - * operate on. + * Typedef for the matrix type (including constness) we are to operate on. */ typedef typename Accessor::MatrixType MatrixType; /** - * Constructor. Create an iterator - * into the matrix @p matrix for the - * given row and the index within it. + * Constructor. Create an iterator into the matrix @p matrix for the given + * row and the index within it. */ Iterator (MatrixType *matrix, const unsigned int row, const unsigned int index); /** - * Constructor. Create the end - * iterator for the given matrix. + * Constructor. Create the end iterator for the given matrix. */ Iterator (MatrixType *matrix); /** - * Conversion constructor to get from - * a non-const iterator to a const + * Conversion constructor to get from a non-const iterator to a const * iterator. */ Iterator (const SparseMatrixIterators::Iterator &i); @@ -410,10 +336,7 @@ namespace SparseMatrixIterators 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 Iterator &) const; @@ -423,29 +346,23 @@ namespace SparseMatrixIterators bool operator != (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. * - * This function is only valid if - * both iterators point into the same + * This function is only valid if both iterators point into the same * matrix. */ bool operator < (const Iterator &) const; /** - * Comparison operator. Works in the - * same way as above operator, just - * the other way round. + * Comparison operator. Works in the same way as above operator, just the + * other way round. */ bool operator > (const Iterator &) const; private: /** - * Store an object of the - * accessor class. + * Store an object of the accessor class. */ Accessor accessor; }; @@ -476,37 +393,24 @@ class SparseMatrix : public virtual Subscriptor { public: /** - * Type of matrix entries. In analogy to - * the STL container classes. + * Type of matrix entries. In analogy to the STL container classes. */ typedef number value_type; /** - * Declare a type that has holds - * real-valued numbers with the - * same precision as the template - * argument to this class. If the - * template argument of this - * class is a real data type, - * then real_type equals the - * template argument. If the - * template argument is a - * std::complex type then - * real_type equals the type - * underlying the complex - * numbers. - * - * This typedef is used to - * represent the return type of - * norms. + * Declare a type that has holds real-valued numbers with the same precision + * as the template argument to this class. If the template argument of this + * class is a real data type, then real_type equals the template + * argument. If the template argument is a std::complex type then real_type + * equals the type underlying the complex numbers. + * + * This typedef is used to represent the return type of norms. */ typedef typename numbers::NumberTraits::real_type real_type; /** - * Typedef of an STL conforming iterator - * class walking over all the nonzero - * entries of this matrix. This iterator - * cannot change the values of the + * Typedef of an STL conforming iterator class walking over all the nonzero + * entries of this matrix. This iterator cannot change the values of the * matrix. */ typedef @@ -514,34 +418,26 @@ public: const_iterator; /** - * Typedef of an STL conforming iterator - * class walking over all the nonzero - * entries of this matrix. This iterator - * @em can change the values of the - * matrix, but of course can't change the - * sparsity pattern as this is fixed once - * a sparse matrix is attached to it. + * Typedef of an STL conforming iterator class walking over all the nonzero + * entries of this matrix. This iterator @em can change the values of the + * matrix, but of course can't change the sparsity pattern as this is fixed + * once a sparse matrix is attached to it. */ typedef SparseMatrixIterators::Iterator iterator; /** - * A structure that describes some of the - * traits of this class in terms of its - * run-time behavior. Some other classes - * (such as the block matrix classes) - * that take one or other of the matrix - * classes as its template parameters can - * tune their behavior based on the - * variables in this class. + * A structure that describes some of the traits of this class in terms of + * its run-time behavior. Some other classes (such as the block matrix + * classes) that take one or other of the matrix classes as its template + * parameters can tune their behavior based on the variables in this class. */ struct Traits { /** - * It is safe to elide additions of - * zeros to individual elements of - * this matrix. + * It is safe to elide additions of zeros to individual elements of this + * matrix. */ static const bool zero_addition_can_be_elided = true; }; @@ -551,172 +447,106 @@ public: */ //@{ /** - * Constructor; initializes the matrix to - * be empty, without any structure, i.e. - * the matrix is not usable at all. This - * constructor is therefore only useful - * for matrices which are members of a - * class. All other matrices should be - * created at a point in the data flow - * where all necessary information is - * available. + * Constructor; initializes the matrix to be empty, without any structure, + * i.e. the matrix is not usable at all. This constructor is therefore only + * useful for matrices which are members of a class. All other matrices + * should be created at a point in the data flow where all necessary + * information is available. * - * You have to initialize - * the matrix before usage with - * reinit(const SparsityPattern&). + * You have to initialize the matrix before usage with reinit(const + * SparsityPattern&). */ SparseMatrix (); /** - * Copy constructor. This constructor is - * only allowed to be called if the matrix - * to be copied is empty. This is for the - * same reason as for the - * SparsityPattern, see there for the - * details. + * Copy constructor. This constructor is only allowed to be called if the + * matrix to be copied is empty. This is for the same reason as for the + * SparsityPattern, see there for the details. * - * If you really want to copy a whole - * matrix, you can do so by using the + * If you really want to copy a whole matrix, you can do so by using the * copy_from() function. */ SparseMatrix (const SparseMatrix &); /** - * Constructor. Takes the given - * matrix sparsity structure to - * represent the sparsity pattern - * of this matrix. You can change - * the sparsity pattern later on - * by calling the reinit(const - * SparsityPattern&) function. - * - * You have to make sure that the - * lifetime of the sparsity - * structure is at least as long - * as that of this matrix or as - * long as reinit(const - * SparsityPattern&) is not - * called with a new sparsity - * pattern. - * - * The constructor is marked - * explicit so as to disallow - * that someone passes a sparsity - * pattern in place of a sparse - * matrix to some function, where - * an empty matrix would be - * generated then. + * Constructor. Takes the given matrix sparsity structure to represent the + * sparsity pattern of this matrix. You can change the sparsity pattern + * later on by calling the reinit(const SparsityPattern&) function. + * + * You have to make sure that the lifetime of the sparsity structure is at + * least as long as that of this matrix or as long as reinit(const + * SparsityPattern&) is not called with a new sparsity pattern. + * + * The constructor is marked explicit so as to disallow that someone passes + * a sparsity pattern in place of a sparse matrix to some function, where an + * empty matrix would be generated then. */ explicit SparseMatrix (const SparsityPattern &sparsity); /** - * Copy constructor: initialize - * the matrix with the identity - * matrix. This constructor will - * throw an exception if the - * sizes of the sparsity pattern - * and the identity matrix do not - * coincide, or if the sparsity - * pattern does not provide for - * nonzero entries on the entire - * diagonal. + * Copy constructor: initialize the matrix with the identity matrix. This + * constructor will throw an exception if the sizes of the sparsity pattern + * and the identity matrix do not coincide, or if the sparsity pattern does + * not provide for nonzero entries on the entire diagonal. */ SparseMatrix (const SparsityPattern &sparsity, const IdentityMatrix &id); /** - * Destructor. Free all memory, but do not - * release the memory of the sparsity - * structure. + * Destructor. Free all memory, but do not release the memory of the + * sparsity structure. */ virtual ~SparseMatrix (); /** - * Copy operator. Since copying - * entire sparse matrices is a - * very expensive operation, we - * disallow doing so except for - * the special case of empty - * matrices of size zero. This - * doesn't seem particularly - * useful, but is exactly what - * one needs if one wanted to - * have a - * std::vector@ - * @>: in that case, one - * can create a vector (which - * needs the ability to copy - * objects) of empty matrices - * that are then later filled - * with something useful. + * Copy operator. Since copying entire sparse matrices is a very expensive + * operation, we disallow doing so except for the special case of empty + * matrices of size zero. This doesn't seem particularly useful, but is + * exactly what one needs if one wanted to have a + * std::vector@ @>: in that case, one + * can create a vector (which needs the ability to copy objects) of empty + * matrices that are then later filled with something useful. */ SparseMatrix &operator = (const SparseMatrix &); /** - * Copy operator: initialize - * the matrix with the identity - * matrix. This operator will - * throw an exception if the - * sizes of the sparsity pattern - * and the identity matrix do not - * coincide, or if the sparsity - * pattern does not provide for - * nonzero entries on the entire - * diagonal. + * Copy operator: initialize the matrix with the identity matrix. This + * operator will throw an exception if the sizes of the sparsity pattern and + * the identity matrix do not coincide, or if the sparsity pattern does not + * provide for nonzero entries on the entire diagonal. */ SparseMatrix & operator= (const IdentityMatrix &id); /** - * 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 keep the sparsity pattern + * 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 keep the sparsity pattern * previously used. */ SparseMatrix &operator = (const double d); /** - * Reinitialize the sparse matrix - * with the given sparsity - * pattern. The latter tells the - * matrix how many nonzero - * elements there need to be + * Reinitialize the sparse matrix with the given sparsity pattern. The + * latter tells the matrix how many nonzero elements there need to be * reserved. * - * Regarding memory allocation, - * the same applies as said - * above. - * - * You have to make sure that the - * lifetime of the sparsity - * structure is at least as long - * as that of this matrix or as - * long as reinit(const - * SparsityPattern &) is not - * called with a new sparsity - * structure. + * Regarding memory allocation, the same applies as said above. + * + * You have to make sure that the lifetime of the sparsity structure is at + * least as long as that of this matrix or as long as reinit(const + * SparsityPattern &) is not called with a new sparsity structure. * - * The elements of the matrix are - * set to zero by this function. + * The elements of the matrix are set to zero by this function. */ virtual void reinit (const SparsityPattern &sparsity); /** - * Release all memory and return - * to a state just like after - * having called the default - * constructor. It also forgets - * the sparsity pattern it was + * Release all memory and return to a state just like after having called + * the default constructor. It also forgets the sparsity pattern it was * previously tied to. */ virtual void clear (); @@ -726,83 +556,59 @@ public: */ //@{ /** - * Return whether the object is - * empty. It is empty if either - * both dimensions are zero or no - * SparsityPattern is - * associated. + * Return whether the object is empty. It is empty if either both dimensions + * are zero or no SparsityPattern is associated. */ bool empty () const; /** - * Return the dimension of the - * image space. To remember: the - * matrix is of dimension - * $m \times n$. + * Return the dimension of the image space. To remember: the matrix is of + * dimension $m \times n$. */ unsigned int m () const; /** - * Return the dimension of the - * range space. To remember: the - * matrix is of dimension - * $m \times n$. + * Return the dimension of the range space. To remember: the matrix is of + * dimension $m \times n$. */ unsigned int n () const; /** - * Return the number of entries - * in a specific row. + * Return the number of entries in a specific row. */ unsigned int get_row_length (const unsigned int row) const; /** - * Return the number of nonzero - * elements of this - * matrix. Actually, it returns - * the number of entries in the - * sparsity pattern; if any of - * the entries should happen to - * be zero, it is counted anyway. + * Return the number of nonzero elements of this matrix. Actually, it + * returns the number of entries in the sparsity pattern; if any of the + * entries should happen to be zero, it is counted anyway. */ unsigned int n_nonzero_elements () const; /** - * Return the number of actually - * nonzero elements of this matrix. It - * is possible to specify the parameter - * threshold in order to count - * only the elements that have absolute - * value greater than the threshold. + * Return the number of actually nonzero elements of this matrix. It is + * possible to specify the parameter threshold in order to count + * only the elements that have absolute value greater than the threshold. * - * Note, that this function does (in - * contrary to n_nonzero_elements()) - * not count all entries of the - * sparsity pattern but only the ones - * that are nonzero (or whose absolute - * value is greater than threshold). + * Note, that this function does (in contrary to n_nonzero_elements()) not + * count all entries of the sparsity pattern but only the ones that are + * nonzero (or whose absolute value is greater than threshold). */ unsigned int n_actually_nonzero_elements (const double threshold = 0.) const; /** - * Return a (constant) reference - * to the underlying sparsity - * pattern of this matrix. + * Return a (constant) reference to the underlying sparsity pattern of this + * matrix. * - * Though the return value is - * declared const, you - * should be aware that it may - * change if you call any - * nonconstant function of - * objects which operate on it. + * Though the return value is declared const, you should be aware + * that it may change if you call any nonconstant function of objects which + * operate on it. */ const SparsityPattern &get_sparsity_pattern () const; /** - * Determine an estimate for the - * memory consumption (in bytes) - * of this object. See - * MemoryConsumption. + * Determine an estimate for the memory consumption (in bytes) of this + * object. See MemoryConsumption. */ std::size_t memory_consumption () const; @@ -812,44 +618,28 @@ public: */ //@{ /** - * Set the element (i,j) - * to value. Throws an - * error if the entry does not - * exist or if value is - * not a finite number. Still, it - * is allowed to store zero - * values in non-existent fields. + * Set the element (i,j) to value. Throws an error if the + * entry does not exist or if value is not a finite number. Still, + * it is allowed to store zero values in non-existent fields. */ void set (const unsigned int i, const unsigned int j, const number value); /** - * Set all elements given in a - * FullMatrix into the sparse matrix - * locations given by - * indices. In other words, - * this function writes the elements - * in full_matrix into the - * calling matrix, using the - * local-to-global indexing specified - * by indices for both the - * rows and the columns of the - * matrix. This function assumes a - * quadratic sparse matrix and a - * quadratic full_matrix, the usual - * situation in FE calculations. - * - * The optional parameter - * elide_zero_values can be - * used to specify whether zero - * values should be set anyway or - * they should be filtered away (and - * not change the previous content in - * the respective element if it - * exists). The default value is - * false, i.e., even zero - * values are treated. + * Set all elements given in a FullMatrix into the sparse matrix locations + * given by indices. In other words, this function writes the + * elements in full_matrix into the calling matrix, using the + * local-to-global indexing specified by indices for both the rows + * and the columns of the matrix. This function assumes a quadratic sparse + * matrix and a quadratic full_matrix, the usual situation in FE + * calculations. + * + * The optional parameter elide_zero_values can be used to specify + * whether zero values should be set anyway or they should be filtered away + * (and not change the previous content in the respective element if it + * exists). The default value is false, i.e., even zero values are + * treated. */ template void set (const std::vector &indices, @@ -857,11 +647,9 @@ public: const bool elide_zero_values = false); /** - * Same function as before, but now - * including the possibility to use - * rectangular full_matrices and - * different local-to-global indexing - * on rows and columns, respectively. + * Same function as before, but now including the possibility to use + * rectangular full_matrices and different local-to-global indexing on rows + * and columns, respectively. */ template void set (const std::vector &row_indices, @@ -870,22 +658,14 @@ public: const bool elide_zero_values = false); /** - * Set several elements in the - * specified row of the matrix with - * column indices as given by - * col_indices to the - * respective value. + * Set several elements in the specified row of the matrix with column + * indices as given by col_indices to the respective value. * - * The optional parameter - * elide_zero_values can be - * used to specify whether zero - * values should be set anyway or - * they should be filtered away (and - * not change the previous content in - * the respective element if it - * exists). The default value is - * false, i.e., even zero - * values are treated. + * The optional parameter elide_zero_values can be used to specify + * whether zero values should be set anyway or they should be filtered away + * (and not change the previous content in the respective element if it + * exists). The default value is false, i.e., even zero values are + * treated. */ template void set (const unsigned int row, @@ -894,20 +674,13 @@ public: const bool elide_zero_values = false); /** - * Set several elements to values - * given by values in a - * given row in columns given by - * col_indices into the sparse - * matrix. + * Set several elements to values given by values in a given row in + * columns given by col_indices into the sparse matrix. * - * The optional parameter - * elide_zero_values can be - * used to specify whether zero - * values should be inserted anyway - * or they should be filtered - * away. The default value is - * false, i.e., even zero - * values are inserted/replaced. + * The optional parameter elide_zero_values can be used to specify + * whether zero values should be inserted anyway or they should be filtered + * away. The default value is false, i.e., even zero values are + * inserted/replaced. */ template void set (const unsigned int row, @@ -917,44 +690,27 @@ public: const bool elide_zero_values = false); /** - * Add value to the - * element (i,j). Throws - * an error if the entry does not - * exist or if value is - * not a finite number. Still, it - * is allowed to store zero - * values in non-existent fields. + * Add value to the element (i,j). Throws an error if the + * entry does not exist or if value is not a finite number. Still, + * it is allowed to store zero values in non-existent fields. */ void add (const unsigned int i, const unsigned int j, const number value); /** - * Add all elements given in a - * FullMatrix into sparse - * matrix locations given by - * indices. In other words, - * this function adds the elements in - * full_matrix to the - * respective entries in calling - * matrix, using the local-to-global - * indexing specified by - * indices for both the rows - * and the columns of the - * matrix. This function assumes a - * quadratic sparse matrix and a - * quadratic full_matrix, the usual - * situation in FE calculations. - * - * The optional parameter - * elide_zero_values can be - * used to specify whether zero - * values should be added anyway or - * these should be filtered away and - * only non-zero data is added. The - * default value is true, - * i.e., zero values won't be added - * into the matrix. + * Add all elements given in a FullMatrix into sparse matrix + * locations given by indices. In other words, this function adds + * the elements in full_matrix to the respective entries in calling + * matrix, using the local-to-global indexing specified by indices + * for both the rows and the columns of the matrix. This function assumes a + * quadratic sparse matrix and a quadratic full_matrix, the usual situation + * in FE calculations. + * + * The optional parameter elide_zero_values can be used to specify + * whether zero values should be added anyway or these should be filtered + * away and only non-zero data is added. The default value is true, + * i.e., zero values won't be added into the matrix. */ template void add (const std::vector &indices, @@ -962,11 +718,9 @@ public: const bool elide_zero_values = true); /** - * Same function as before, but now - * including the possibility to use - * rectangular full_matrices and - * different local-to-global indexing - * on rows and columns, respectively. + * Same function as before, but now including the possibility to use + * rectangular full_matrices and different local-to-global indexing on rows + * and columns, respectively. */ template void add (const std::vector &row_indices, @@ -975,21 +729,13 @@ public: const bool elide_zero_values = true); /** - * Set several elements in the - * specified row of the matrix with - * column indices as given by - * col_indices to the - * respective value. + * Set several elements in the specified row of the matrix with column + * indices as given by col_indices to the respective value. * - * The optional parameter - * elide_zero_values can be - * used to specify whether zero - * values should be added anyway or - * these should be filtered away and - * only non-zero data is added. The - * default value is true, - * i.e., zero values won't be added - * into the matrix. + * The optional parameter elide_zero_values can be used to specify + * whether zero values should be added anyway or these should be filtered + * away and only non-zero data is added. The default value is true, + * i.e., zero values won't be added into the matrix. */ template void add (const unsigned int row, @@ -998,21 +744,13 @@ public: const bool elide_zero_values = true); /** - * Add an array of values given by - * values in the given - * global matrix row at columns - * specified by col_indices in the - * sparse matrix. + * Add an array of values given by values in the given global + * matrix row at columns specified by col_indices in the sparse matrix. * - * The optional parameter - * elide_zero_values can be - * used to specify whether zero - * values should be added anyway or - * these should be filtered away and - * only non-zero data is added. The - * default value is true, - * i.e., zero values won't be added - * into the matrix. + * The optional parameter elide_zero_values can be used to specify + * whether zero values should be added anyway or these should be filtered + * away and only non-zero data is added. The default value is true, + * i.e., zero values won't be added into the matrix. */ template void add (const unsigned int row, @@ -1023,140 +761,83 @@ public: const bool col_indices_are_sorted = false); /** - * Multiply the entire matrix by a - * fixed factor. + * Multiply the entire matrix by a fixed factor. */ SparseMatrix &operator *= (const number factor); /** - * Divide the entire matrix by a - * fixed factor. + * Divide the entire matrix by a fixed factor. */ SparseMatrix &operator /= (const number factor); /** - * Symmetrize the matrix by - * forming the mean value between - * the existing matrix and its - * transpose, $A = \frac 12(A+A^T)$. - * - * This operation assumes that - * the underlying sparsity - * pattern represents a symmetric - * object. If this is not the - * case, then the result of this - * operation will not be a - * symmetric matrix, since it - * only explicitly symmetrizes - * by looping over the lower left - * triangular part for efficiency - * reasons; if there are entries - * in the upper right triangle, - * then these elements are missed - * in the - * symmetrization. Symmetrization - * of the sparsity pattern can be - * obtain by - * SparsityPattern::symmetrize(). + * Symmetrize the matrix by forming the mean value between the existing + * matrix and its transpose, $A = \frac 12(A+A^T)$. + * + * This operation assumes that the underlying sparsity pattern represents a + * symmetric object. If this is not the case, then the result of this + * operation will not be a symmetric matrix, since it only explicitly + * symmetrizes by looping over the lower left triangular part for efficiency + * reasons; if there are entries in the upper right triangle, then these + * elements are missed in the symmetrization. Symmetrization of the sparsity + * pattern can be obtain by SparsityPattern::symmetrize(). */ void symmetrize (); /** - * Copy the given matrix to this - * one. The operation throws an - * error if the sparsity patterns - * of the two involved matrices - * do not point to the same - * object, since in this case the - * copy operation is - * cheaper. Since this operation - * is notheless not for free, we - * do not make it available - * through operator =, - * since this may lead to - * unwanted usage, e.g. in copy - * arguments to functions, which - * should really be arguments by - * reference. - * - * The source matrix may be a matrix - * of arbitrary type, as long as its - * data type is convertible to the - * data type of this matrix. - * - * The function returns a reference to - * *this. + * Copy the given matrix to this one. The operation throws an error if the + * sparsity patterns of the two involved matrices do not point to the same + * object, since in this case the copy operation is cheaper. Since this + * operation is notheless not for free, we do not make it available through + * operator =, since this may lead to unwanted usage, e.g. in copy + * arguments to functions, which should really be arguments by reference. + * + * The source matrix may be a matrix of arbitrary type, as long as its data + * type is convertible to the data type of this matrix. + * + * The function returns a reference to *this. */ template SparseMatrix & copy_from (const SparseMatrix &source); /** - * This function is complete - * analogous to the - * SparsityPattern::copy_from() - * function in that it allows to - * initialize a whole matrix in - * one step. See there for more - * information on argument types - * and their meaning. You can - * also find a small example on - * how to use this function - * there. - * - * The only difference to the - * cited function is that the - * objects which the inner - * iterator points to need to be - * of type std::pair, where - * value needs to be - * convertible to the element - * type of this class, as - * specified by the - * number template + * This function is complete analogous to the SparsityPattern::copy_from() + * function in that it allows to initialize a whole matrix in one step. See + * there for more information on argument types and their meaning. You can + * also find a small example on how to use this function there. + * + * The only difference to the cited function is that the objects which the + * inner iterator points to need to be of type std::pair, where value needs to be convertible to the element + * type of this class, as specified by the number template * argument. * - * Previous content of the matrix - * is overwritten. Note that the - * entries specified by the input - * parameters need not - * necessarily cover all elements - * of the matrix. Elements not - * covered remain untouched. + * Previous content of the matrix is overwritten. Note that the entries + * specified by the input parameters need not necessarily cover all elements + * of the matrix. Elements not covered remain untouched. */ template void copy_from (const ForwardIterator begin, const ForwardIterator end); /** - * Copy the nonzero entries of a - * full matrix into this - * object. Previous content is - * deleted. Note that the - * underlying sparsity pattern - * must be appropriate to hold - * the nonzero entries of the - * full matrix. + * Copy the nonzero entries of a full matrix into this object. Previous + * content is deleted. Note that the underlying sparsity pattern must be + * appropriate to hold the nonzero entries of the full matrix. */ template void copy_from (const FullMatrix &matrix); /** - * Add matrix scaled by - * factor to this matrix, - * i.e. the matrix factor*matrix - * is added to this. This - * function throws an error if the - * sparsity patterns of the two involved - * matrices do not point to the same - * object, since in this case the - * operation is cheaper. - * - * The source matrix may be a sparse - * matrix over an arbitrary underlying - * scalar type, as long as its data type - * is convertible to the data type of + * Add matrix scaled by factor to this matrix, i.e. the + * matrix factor*matrix is added to this. This function + * throws an error if the sparsity patterns of the two involved matrices do + * not point to the same object, since in this case the operation is + * cheaper. + * + * The source matrix may be a sparse matrix over an arbitrary underlying + * scalar type, as long as its data type is convertible to the data type of * this matrix. */ template @@ -1170,134 +851,84 @@ public: //@{ /** - * Return the value of the entry - * (i,j). This may be an - * expensive operation and you - * should always take care where - * to call this function. In - * order to avoid abuse, this - * function throws an exception - * if the required element does - * not exist in the matrix. - * - * In case you want a function - * that returns zero instead (for - * entries that are not in the - * sparsity pattern of the - * matrix), use the el() - * function. + * Return the value of the entry (i,j). This may be an expensive + * operation and you should always take care where to call this function. + * In order to avoid abuse, this function throws an exception if the + * required element does not exist in the matrix. * - * If you are looping over all elements, - * consider using one of the iterator - * classes instead, since they are - * tailored better to a sparse matrix + * In case you want a function that returns zero instead (for entries that + * are not in the sparsity pattern of the matrix), use the el() function. + * + * If you are looping over all elements, consider using one of the iterator + * classes instead, since they are tailored better to a sparse matrix * structure. */ number operator () (const unsigned int i, const unsigned int j) const; /** - * This function is mostly like - * operator()() in that it - * returns the value of the - * matrix entry (i,j). The - * only difference is that if - * this entry does not exist in - * the sparsity pattern, then - * instead of raising an - * exception, zero is - * returned. While this may be - * convenient in some cases, note - * that it is simple to write - * algorithms that are slow - * compared to an optimal - * solution, since the sparsity - * of the matrix is not used. - * - * If you are looping over all elements, - * consider using one of the iterator - * classes instead, since they are - * tailored better to a sparse matrix + * This function is mostly like operator()() in that it returns the value of + * the matrix entry (i,j). The only difference is that if this entry + * does not exist in the sparsity pattern, then instead of raising an + * exception, zero is returned. While this may be convenient in some cases, + * note that it is simple to write algorithms that are slow compared to an + * optimal solution, since the sparsity of the matrix is not used. + * + * If you are looping over all elements, consider using one of the iterator + * classes instead, since they are tailored better to a sparse matrix * structure. */ number el (const unsigned int i, const unsigned int j) const; /** - * Return the main diagonal - * element in the ith - * row. This function throws an - * error if the matrix is not - * quadratic (see + * Return the main diagonal element in the ith row. This function + * throws an error if the matrix is not quadratic (see * SparsityPattern::optimize_diagonal()). * - * This function is considerably - * faster than the operator()(), - * since for quadratic matrices, the - * diagonal entry may be the - * first to be stored in each row - * and access therefore does not - * involve searching for the - * right column number. + * This function is considerably faster than the operator()(), since for + * quadratic matrices, the diagonal entry may be the first to be stored in + * each row and access therefore does not involve searching for the right + * column number. */ number diag_element (const unsigned int i) const; /** - * Same as above, but return a - * writeable reference. You're - * sure you know what you do? + * Same as above, but return a writeable reference. You're sure you know + * what you do? */ number &diag_element (const unsigned int i); /** - * Access to values in internal - * mode. Returns the value of - * the indexth entry in - * row. Here, - * index refers to the - * internal representation of the - * matrix, not the column. Be - * sure to understand what you - * are doing here. + * Access to values in internal mode. Returns the value of the + * indexth entry in row. Here, index refers to + * the internal representation of the matrix, not the column. Be sure to + * understand what you are doing here. * - * @deprecated Use iterator or - * const_iterator instead! + * @deprecated Use iterator or const_iterator instead! */ number raw_entry (const unsigned int row, const unsigned int index) const; /** - * This is for hackers. Get - * access to the ith element of - * this matrix. The elements are - * stored in a consecutive way, - * refer to the SparsityPattern - * class for more details. - * - * You should use this interface - * very carefully and only if you - * are absolutely sure to know - * what you do. You should also - * note that the structure of - * these arrays may change over - * time. If you change the - * layout yourself, you should - * also rename this function to - * avoid programs relying on - * outdated information! - * - * @internal @deprecated Use iterator or - * const_iterator instead! + * This is for hackers. Get access to the ith element of this + * matrix. The elements are stored in a consecutive way, refer to the + * SparsityPattern class for more details. + * + * You should use this interface very carefully and only if you are + * absolutely sure to know what you do. You should also note that the + * structure of these arrays may change over time. If you change the layout + * yourself, you should also rename this function to avoid programs relying + * on outdated information! + * + * @internal @deprecated Use iterator or const_iterator instead! */ number global_entry (const unsigned int i) const; /** - * Same as above, but with write - * access. You certainly know - * what you do? + * Same as above, but with write access. You certainly know what you do? * - * @internal @deprecated Use iterator or - * const_iterator instead! + * @internal @deprecated Use iterator or const_iterator instead! */ number &global_entry (const unsigned int i); @@ -1307,167 +938,106 @@ public: */ //@{ /** - * Matrix-vector multiplication: - * let dst = M*src with - * M being this matrix. + * Matrix-vector multiplication: let dst = M*src with M being + * this matrix. * - * Note that while this function can - * operate on all vectors that offer - * iterator classes, it is only really - * effective for objects of type @ref - * Vector. For all classes for which - * iterating over elements, or random - * member access is expensive, this - * function is not efficient. In - * particular, if you want to multiply - * with BlockVector objects, you should - * consider using a BlockSparseMatrix as - * well. - * - * Source and destination must - * not be the same vector. + * Note that while this function can operate on all vectors that offer + * iterator classes, it is only really effective for objects of type @ref + * Vector. For all classes for which iterating over elements, or random + * member access is expensive, this function is not efficient. In + * particular, if you want to multiply with BlockVector objects, you should + * consider using a BlockSparseMatrix as well. + * + * Source and destination must not be the same vector. */ template void vmult (OutVector &dst, const InVector &src) const; /** - * Matrix-vector multiplication: - * let dst = MT*src with - * M being this - * matrix. This function does the - * same as vmult() but takes - * the transposed matrix. - * - * Note that while this function can - * operate on all vectors that offer - * iterator classes, it is only really - * effective for objects of type @ref - * Vector. For all classes for which - * iterating over elements, or random - * member access is expensive, this - * function is not efficient. In - * particular, if you want to multiply - * with BlockVector objects, you should - * consider using a BlockSparseMatrix as - * well. - * - * Source and destination must - * not be the same vector. + * Matrix-vector multiplication: let dst = MT*src with + * M being this matrix. This function does the same as vmult() but + * takes the transposed matrix. + * + * Note that while this function can operate on all vectors that offer + * iterator classes, it is only really effective for objects of type @ref + * Vector. For all classes for which iterating over elements, or random + * member access is expensive, this function is not efficient. In + * particular, if you want to multiply with BlockVector objects, you should + * consider using a BlockSparseMatrix as well. + * + * Source and destination must not be the same vector. */ template void Tvmult (OutVector &dst, const InVector &src) const; /** - * Adding Matrix-vector - * multiplication. Add - * M*src on dst - * with M being this - * matrix. + * Adding Matrix-vector multiplication. Add M*src on dst with + * M being this matrix. + * + * Note that while this function can operate on all vectors that offer + * iterator classes, it is only really effective for objects of type @ref + * Vector. For all classes for which iterating over elements, or random + * member access is expensive, this function is not efficient. In + * particular, if you want to multiply with BlockVector objects, you should + * consider using a BlockSparseMatrix as well. * - * Note that while this function can - * operate on all vectors that offer - * iterator classes, it is only really - * effective for objects of type @ref - * Vector. For all classes for which - * iterating over elements, or random - * member access is expensive, this - * function is not efficient. In - * particular, if you want to multiply - * with BlockVector objects, you should - * consider using a BlockSparseMatrix as - * well. - * - * Source and destination must - * not be the same vector. + * Source and destination must not be the same vector. */ template void vmult_add (OutVector &dst, const InVector &src) const; /** - * Adding Matrix-vector - * multiplication. Add - * MT*src to - * dst with M being - * this matrix. This function - * does the same as vmult_add() - * but takes the transposed - * matrix. + * Adding Matrix-vector multiplication. Add MT*src to + * dst with M being this matrix. This function does the same + * as vmult_add() but takes the transposed matrix. + * + * Note that while this function can operate on all vectors that offer + * iterator classes, it is only really effective for objects of type @ref + * Vector. For all classes for which iterating over elements, or random + * member access is expensive, this function is not efficient. In + * particular, if you want to multiply with BlockVector objects, you should + * consider using a BlockSparseMatrix as well. * - * Note that while this function can - * operate on all vectors that offer - * iterator classes, it is only really - * effective for objects of type @ref - * Vector. For all classes for which - * iterating over elements, or random - * member access is expensive, this - * function is not efficient. In - * particular, if you want to multiply - * with BlockVector objects, you should - * consider using a BlockSparseMatrix as - * well. - * - * Source and destination must - * not be the same vector. + * Source and destination must not be the same vector. */ template void Tvmult_add (OutVector &dst, const InVector &src) const; /** - * Return the square of the norm - * of the vector $v$ with respect - * to the norm induced by this - * matrix, - * i.e. $\left(v,Mv\right)$. This - * is useful, e.g. in the finite - * element context, where the - * $L_2$ 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, and for - * the result to actually be a norm it - * also needs to be either real symmetric - * or complex hermitian. - * - * The underlying template types of both - * this matrix and the given vector - * should either both be real or - * complex-valued, but not mixed, for - * this function to make sense. + * Return the square of the norm of the vector $v$ with respect to the norm + * induced by this matrix, i.e. $\left(v,Mv\right)$. This is useful, e.g. in + * the finite element context, where the $L_2$ 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, and for + * the result to actually be a norm it also needs to be either real + * symmetric or complex hermitian. + * + * The underlying template types of both this matrix and the given vector + * should either both be real or complex-valued, but not mixed, for this + * function to make sense. */ template somenumber matrix_norm_square (const Vector &v) const; /** - * Compute the matrix scalar - * product $\left(u,Mv\right)$. + * Compute the matrix scalar product $\left(u,Mv\right)$. */ template somenumber matrix_scalar_product (const Vector &u, const Vector &v) const; /** - * Compute the residual of an - * equation Mx=b, where - * the residual is defined to be - * r=b-Mx. Write the - * residual into - * dst. The - * l2 norm of - * the residual vector is - * returned. + * Compute the residual of an equation Mx=b, where the residual is + * defined to be r=b-Mx. Write the residual into dst. The + * l2 norm of the residual vector is returned. * - * Source x and destination - * dst must not be the same - * vector. + * Source x and destination dst must not be the same vector. */ template somenumber residual (Vector &dst, @@ -1475,44 +1045,27 @@ public: const Vector &b) const; /** - * Perform the matrix-matrix - * multiplication C = A * B, - * or, if an optional vector argument - * is given, C = A * diag(V) * - * B, where diag(V) - * defines a diagonal matrix with the - * vector entries. - * - * This function assumes that the - * calling matrix A and - * B have compatible - * sizes. The size of C will - * be set within this function. - * - * The content as well as the sparsity - * pattern of the matrix C will be - * changed by this function, so make - * sure that the sparsity pattern is - * not used somewhere else in your - * program. This is an expensive - * operation, so think twice before you - * use this function. - * - * There is an optional flag - * rebuild_sparsity_pattern - * that can be used to bypass the - * creation of a new sparsity pattern - * and instead uses the sparsity - * pattern stored in C. In - * that case, make sure that it really - * fits. The default is to rebuild the - * sparsity pattern. - * - * @note Rebuilding the sparsity pattern - * requires changing it. This means that - * all other matrices that are associated - * with this sparsity pattern will - * then have invalid entries. + * Perform the matrix-matrix multiplication C = A * B, or, if an + * optional vector argument is given, C = A * diag(V) * B, where + * diag(V) defines a diagonal matrix with the vector entries. + * + * This function assumes that the calling matrix A and B + * have compatible sizes. The size of C will be set within this + * function. + * + * The content as well as the sparsity pattern of the matrix C will be + * changed by this function, so make sure that the sparsity pattern is not + * used somewhere else in your program. This is an expensive operation, so + * think twice before you use this function. + * + * There is an optional flag rebuild_sparsity_pattern that can be + * used to bypass the creation of a new sparsity pattern and instead uses + * the sparsity pattern stored in C. In that case, make sure that + * it really fits. The default is to rebuild the sparsity pattern. + * + * @note Rebuilding the sparsity pattern requires changing it. This means + * that all other matrices that are associated with this sparsity pattern + * will then have invalid entries. */ template void mmult (SparseMatrix &C, @@ -1521,46 +1074,28 @@ public: const bool rebuild_sparsity_pattern = true) const; /** - * Perform the matrix-matrix - * multiplication with the transpose of - * this, i.e., C = - * AT * B, or, if an - * optional vector argument is given, - * C = AT * diag(V) * - * B, where diag(V) - * defines a diagonal matrix with the - * vector entries. - * - * This function assumes that the - * calling matrix A and - * B have compatible - * sizes. The size of C will - * be set within this function. - * - * The content as well as the sparsity - * pattern of the matrix C will be - * changed by this function, so make - * sure that the sparsity pattern is - * not used somewhere else in your - * program. This is an expensive - * operation, so think twice before you - * use this function. - * - * There is an optional flag - * rebuild_sparsity_pattern - * that can be used to bypass the - * creation of a new sparsity pattern - * and instead uses the sparsity - * pattern stored in C. In - * that case, make sure that it really - * fits. The default is to rebuild the - * sparsity pattern. - * - * @note Rebuilding the sparsity pattern - * requires changing it. This means that - * all other matrices that are associated - * with this sparsity pattern will - * then have invalid entries. + * Perform the matrix-matrix multiplication with the transpose of + * this, i.e., C = AT * B, or, if an optional + * vector argument is given, C = AT * diag(V) * B, where + * diag(V) defines a diagonal matrix with the vector entries. + * + * This function assumes that the calling matrix A and B + * have compatible sizes. The size of C will be set within this + * function. + * + * The content as well as the sparsity pattern of the matrix C will be + * changed by this function, so make sure that the sparsity pattern is not + * used somewhere else in your program. This is an expensive operation, so + * think twice before you use this function. + * + * There is an optional flag rebuild_sparsity_pattern that can be + * used to bypass the creation of a new sparsity pattern and instead uses + * the sparsity pattern stored in C. In that case, make sure that + * it really fits. The default is to rebuild the sparsity pattern. + * + * @note Rebuilding the sparsity pattern requires changing it. This means + * that all other matrices that are associated with this sparsity pattern + * will then have invalid entries. */ template void Tmmult (SparseMatrix &C, @@ -1575,39 +1110,27 @@ public: //@{ /** - * Return the $l_1$-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 $l_1$-norm for vectors, i.e. - * $|Mv|_1\leq |M|_1 |v|_1$. - * (cf. Haemmerlin-Hoffmann : - * Numerische Mathematik) + * Return the $l_1$-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 + * $l_1$-norm for vectors, i.e. $|Mv|_1\leq |M|_1 |v|_1$. + * (cf. Haemmerlin-Hoffmann: Numerische Mathematik) */ real_type l1_norm () const; /** - * Return the $l_\infty$-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 $l_\infty$-norm of - * vectors, i.e. $|Mv|_\infty \leq - * |M|_\infty |v|_\infty$. - * (cf. Haemmerlin-Hoffmann : - * Numerische Mathematik) + * Return the $l_\infty$-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 $l_\infty$-norm of vectors, i.e. $|Mv|_\infty \leq + * |M|_\infty |v|_\infty$. (cf. Haemmerlin-Hoffmann: Numerische + * Mathematik) */ real_type 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. + * Return the frobenius norm of the matrix, i.e. the square root of the sum + * of squares of all entries in the matrix. */ real_type frobenius_norm () const; //@} @@ -1617,14 +1140,9 @@ public: //@{ /** - * 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 - * relaxation factor omega. + * 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 relaxation factor omega. */ template void precondition_Jacobi (Vector &dst, @@ -1632,15 +1150,10 @@ public: const number omega = 1.) const; /** - * Apply SSOR preconditioning to - * src with damping - * omega. The optional - * argument - * pos_right_of_diagonal is - * supposed to provide an array where - * each entry specifies the position - * just right of the diagonal in the - * global array of nonzeros. + * Apply SSOR preconditioning to src with damping + * omega. The optional argument pos_right_of_diagonal is + * supposed to provide an array where each entry specifies the position just + * right of the diagonal in the global array of nonzeros. */ template void precondition_SSOR (Vector &dst, @@ -1649,8 +1162,7 @@ public: const std::vector &pos_right_of_diagonal=std::vector()) const; /** - * Apply SOR preconditioning - * matrix to src. + * Apply SOR preconditioning matrix to src. */ template void precondition_SOR (Vector &dst, @@ -1658,9 +1170,7 @@ public: const number om = 1.) const; /** - * Apply transpose SOR - * preconditioning matrix to - * src. + * Apply transpose SOR preconditioning matrix to src. */ template void precondition_TSOR (Vector &dst, @@ -1668,11 +1178,8 @@ public: const number om = 1.) const; /** - * Perform SSOR preconditioning - * in-place. Apply the - * preconditioner matrix without - * copying to a second vector. - * omega is the relaxation + * Perform SSOR preconditioning in-place. Apply the preconditioner matrix + * without copying to a second vector. omega is the relaxation * parameter. */ template @@ -1680,18 +1187,15 @@ public: const number omega = 1.) const; /** - * Perform an SOR preconditioning - * in-place. omega is - * the relaxation parameter. + * Perform an SOR preconditioning in-place. omega is the + * relaxation parameter. */ template void SOR (Vector &v, const number om = 1.) const; /** - * Perform a transpose SOR - * preconditioning in-place. - * omega is the + * Perform a transpose SOR preconditioning in-place. omega is the * relaxation parameter. */ template @@ -1699,21 +1203,14 @@ public: const number om = 1.) const; /** - * Perform a permuted SOR - * preconditioning in-place. + * Perform a permuted SOR preconditioning in-place. * - * The standard SOR method is - * applied in the order - * prescribed by permutation, - * that is, first the row - * permutation[0], then - * permutation[1] and so - * on. For efficiency reasons, - * the permutation as well as its - * inverse are required. + * The standard SOR method is applied in the order prescribed by + * permutation, that is, first the row permutation[0], + * then permutation[1] and so on. For efficiency reasons, the + * permutation as well as its inverse are required. * - * omega is the - * relaxation parameter. + * omega is the relaxation parameter. */ template void PSOR (Vector &v, @@ -1722,24 +1219,14 @@ public: const number om = 1.) const; /** - * Perform a transposed permuted SOR - * preconditioning in-place. + * Perform a transposed permuted SOR preconditioning in-place. * - * The transposed SOR method is - * applied in the order - * prescribed by - * permutation, that is, - * first the row - * permutation[m()-1], - * then - * permutation[m()-2] - * and so on. For efficiency - * reasons, the permutation as - * well as its inverse are - * required. + * The transposed SOR method is applied in the order prescribed by + * permutation, that is, first the row permutation[m()-1], + * then permutation[m()-2] and so on. For efficiency reasons, the + * permutation as well as its inverse are required. * - * omega is the - * relaxation parameter. + * omega is the relaxation parameter. */ template void TPSOR (Vector &v, @@ -1748,13 +1235,9 @@ public: const number om = 1.) const; /** - * Do one Jacobi step on - * v. Performs a direct - * Jacobi step with right hand - * side b. This function - * will need an auxiliary vector, - * which is acquired from - * GrowingVectorMemory. + * Do one Jacobi step on v. Performs a direct Jacobi step with + * right hand side b. This function will need an auxiliary vector, + * which is acquired from GrowingVectorMemory. */ template void Jacobi_step (Vector &v, @@ -1762,10 +1245,8 @@ public: const number om = 1.) const; /** - * Do one SOR step on v. - * Performs a direct SOR step - * with right hand side - * b. + * Do one SOR step on v. Performs a direct SOR step with right + * hand side b. */ template void SOR_step (Vector &v, @@ -1773,10 +1254,8 @@ public: const number om = 1.) const; /** - * Do one adjoint SOR step on - * v. Performs a direct - * TSOR step with right hand side - * b. + * Do one adjoint SOR step on v. Performs a direct TSOR step with + * right hand side b. */ template void TSOR_step (Vector &v, @@ -1784,11 +1263,8 @@ public: const number om = 1.) const; /** - * Do one SSOR step on - * v. Performs a direct - * SSOR step with right hand side - * b by performing TSOR - * after SOR. + * Do one SSOR step on v. Performs a direct SSOR step with right + * hand side b by performing TSOR after SOR. */ template void SSOR_step (Vector &v, @@ -1801,86 +1277,68 @@ public: //@{ /** - * STL-like iterator with the first entry - * of the matrix. This is the version for - * constant matrices. + * STL-like iterator with the first entry of the matrix. This is the version + * for constant matrices. */ const_iterator begin () const; /** - * Final iterator. This is the version for - * constant matrices. + * Final iterator. This is the version for constant matrices. */ const_iterator end () const; /** - * STL-like iterator with the first entry - * of the matrix. This is the version for - * non-constant matrices. + * STL-like iterator with the first entry of the matrix. This is the version + * for non-constant matrices. */ iterator begin (); /** - * Final iterator. This is the version for - * non-constant matrices. + * Final iterator. This is the version for non-constant matrices. */ iterator end (); /** - * STL-like iterator with the first entry - * of row r. This is the version - * for constant matrices. + * STL-like iterator with the first entry of row r. This is the + * version for constant matrices. * - * Note that if the given row is empty, - * i.e. does not contain any nonzero - * entries, then the iterator returned by - * this function equals - * end(r). Note also that the - * iterator may not be dereferencable in + * Note that if the given row is empty, i.e. does not contain any nonzero + * entries, then the iterator returned by this function equals + * end(r). Note also that the iterator may not be dereferencable in * that case. */ const_iterator begin (const unsigned int r) const; /** - * Final iterator of row r. It - * points to the first element past the - * end of line @p r, or past the end of - * the entire sparsity pattern. This is + * Final iterator of row r. It points to the first element past the + * end of line @p r, or past the end of the entire sparsity pattern. This is * the version for constant matrices. * - * Note that the end iterator is not - * necessarily dereferencable. This is in - * particular the case if it is the end - * iterator for the last row of a matrix. + * Note that the end iterator is not necessarily dereferencable. This is in + * particular the case if it is the end iterator for the last row of a + * matrix. */ const_iterator end (const unsigned int r) const; /** - * STL-like iterator with the first entry - * of row r. This is the version - * for non-constant matrices. + * STL-like iterator with the first entry of row r. This is the + * version for non-constant matrices. * - * Note that if the given row is empty, - * i.e. does not contain any nonzero - * entries, then the iterator returned by - * this function equals - * end(r). Note also that the - * iterator may not be dereferencable in + * Note that if the given row is empty, i.e. does not contain any nonzero + * entries, then the iterator returned by this function equals + * end(r). Note also that the iterator may not be dereferencable in * that case. */ iterator begin (const unsigned int r); /** - * Final iterator of row r. It - * points to the first element past the - * end of line @p r, or past the end of - * the entire sparsity pattern. This is + * Final iterator of row r. It points to the first element past the + * end of line @p r, or past the end of the entire sparsity pattern. This is * the version for non-constant matrices. * - * Note that the end iterator is not - * necessarily dereferencable. This is in - * particular the case if it is the end - * iterator for the last row of a matrix. + * Note that the end iterator is not necessarily dereferencable. This is in + * particular the case if it is the end iterator for the last row of a + * matrix. */ iterator end (const unsigned int r); //@} @@ -1890,58 +1348,33 @@ public: //@{ /** - * Print the matrix to the given - * stream, using the format - * (row,column) value, - * i.e. one nonzero entry of the - * matrix per line. If @p across - * is true, print all entries on - * a single line, using the - * format row,column:value + * Print the matrix to the given stream, using the format (row,column) + * value, i.e. one nonzero entry of the matrix per line. If @p across + * is true, print all entries on a single line, using the format + * row,column:value */ template void print (STREAM &out, bool across=false) 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! + * 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 precision = 3, @@ -1951,69 +1384,40 @@ public: const double denominator = 1.) const; /** - * Print the actual pattern of - * the matrix. For each entry - * with an absolute value larger - * than threshold, a '*' is - * printed, a ':' for every value - * smaller and a '.' for every - * entry not allocated. + * Print the actual pattern of the matrix. For each entry with an absolute + * value larger than threshold, a '*' is printed, a ':' for every value + * smaller and a '.' for every entry not allocated. */ void print_pattern(std::ostream &out, const double threshold = 0.) const; /** - * Write the data of this object - * 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. - * - * The purpose of this function - * is that you can swap out - * matrices and sparsity pattern - * if you are short of memory, - * want to communicate between - * different programs, or allow - * objects to be persistent - * across different runs of the - * program. + * Write the data of this object 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. + * + * The purpose of this function is that you can swap out matrices and + * sparsity pattern if you are short of memory, want to communicate between + * different programs, or allow objects to be persistent across different + * runs of the program. */ void block_write (std::ostream &out) const; /** - * Read data that has previously - * been written by block_write() - * 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 - * except for a few numbers up - * front. - * - * The object is resized on this - * operation, and all previous - * contents are lost. Note, - * however, that no checks are - * performed whether new data and - * the underlying SparsityPattern - * object fit together. It is - * your responsibility to make - * sure that the sparsity pattern - * and the data to be read match. - * - * A primitive form of error - * checking is performed which - * will recognize the bluntest - * attempts to interpret some - * data as a matrix stored - * bitwise to a file that wasn't - * actually created that way, but - * not more. + * Read data that has previously been written by block_write() 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 except for + * a few numbers up front. + * + * The object is resized on this operation, and all previous contents are + * lost. Note, however, that no checks are performed whether new data and + * the underlying SparsityPattern object fit together. It is your + * responsibility to make sure that the sparsity pattern and the data to be + * read match. + * + * A primitive form of error checking is performed which will recognize the + * bluntest attempts to interpret some data as a matrix stored bitwise to a + * file that wasn't actually created that way, but not more. */ void block_read (std::istream &in); //@} @@ -2052,87 +1456,54 @@ public: protected: /** - * For some matrix storage - * formats, in particular for the - * PETSc distributed blockmatrices, - * set and add operations on - * individual elements can not be - * freely mixed. Rather, one has - * to synchronize operations when - * one wants to switch from - * setting elements to adding to - * elements. - * BlockMatrixBase automatically - * synchronizes the access by - * calling this helper function - * for each block. - * This function ensures that the - * matrix is in a state that - * allows adding elements; if it - * previously already was in this - * state, the function does - * nothing. + * For some matrix storage formats, in particular for the PETSc distributed + * blockmatrices, set and add operations on individual elements can not be + * freely mixed. Rather, one has to synchronize operations when one wants to + * switch from setting elements to adding to elements. BlockMatrixBase + * automatically synchronizes the access by calling this helper function for + * each block. This function ensures that the matrix is in a state that + * allows adding elements; if it previously already was in this state, the + * function does nothing. */ void prepare_add(); /** - * Same as prepare_add() but - * prepare the matrix for setting - * elements if the representation - * of elements in this class - * requires such an operation. + * Same as prepare_add() but prepare the matrix for setting elements if the + * representation of elements in this class requires such an operation. */ void prepare_set(); private: /** - * Pointer to the sparsity - * pattern used for this - * matrix. In order to guarantee - * that it is not deleted while - * still in use, we subscribe to - * it using the SmartPointer - * class. + * Pointer to the sparsity pattern used for this matrix. In order to + * guarantee that it is not deleted while still in use, we subscribe to it + * using the SmartPointer class. */ SmartPointer > cols; /** - * Array of values for all the - * nonzero entries. The position - * within the matrix, i.e. the - * row and column number for a - * given entry can only be - * deduced using the sparsity - * pattern. The same holds for - * the more common operation of - * finding an entry by its - * coordinates. + * Array of values for all the nonzero entries. The position within the + * matrix, i.e. the row and column number for a given entry can only be + * deduced using the sparsity pattern. The same holds for the more common + * operation of finding an entry by its coordinates. */ number *val; /** - * Allocated size of #val. This - * can be larger than the - * actually used part if the size - * of the matrix was reduced - * somewhen in the past by - * associating a sparsity pattern - * with a smaller size to this - * object, using the reinit() + * Allocated size of #val. This can be larger than the actually used part if + * the size of the matrix was reduced somewhen in the past by associating a + * sparsity pattern with a smaller size to this object, using the reinit() * function. */ std::size_t max_len; - // make all other sparse matrices - // friends + // make all other sparse matrices friends template friend class SparseMatrix; template friend class SparseLUDecomposition; template friend class SparseILU; /** - * To allow it calling private - * prepare_add() and - * prepare_set(). + * To allow it calling private prepare_add() and prepare_set(). */ template friend class BlockMatrixBase; }; @@ -2164,9 +1535,7 @@ unsigned int SparseMatrix::n () const } -// Inline the set() and add() -// functions, since they will be -// called frequently. +// Inline the set() and add() functions, since they will be called frequently. template inline void @@ -2178,10 +1547,8 @@ SparseMatrix::set (const unsigned int i, const unsigned int index = cols->operator()(i, j); - // it is allowed to set elements of - // the matrix that are not part of - // the sparsity pattern, if the - // value to which we set it is zero + // it is allowed to set elements of the matrix that are not part of the + // sparsity pattern, if the value to which we set it is zero if (index == SparsityPattern::invalid_entry) { Assert ((index != SparsityPattern::invalid_entry) || @@ -2267,10 +1634,8 @@ SparseMatrix::add (const unsigned int i, const unsigned int index = cols->operator()(i, j); - // it is allowed to add elements to - // the matrix that are not part of - // the sparsity pattern, if the - // value to which we set it is zero + // it is allowed to add elements to the matrix that are not part of the + // sparsity pattern, if the value to which we set it is zero if (index == SparsityPattern::invalid_entry) { Assert ((index != SparsityPattern::invalid_entry) || @@ -2420,8 +1785,7 @@ number SparseMatrix::diag_element (const unsigned int i) const Assert (cols->optimize_diagonal(), ExcNotQuadratic()); Assert (irowstart[i]]; } @@ -2436,8 +1800,7 @@ number &SparseMatrix::diag_element (const unsigned int i) Assert (cols->optimize_diagonal(), ExcNotQuadratic()); Assert (irowstart[i]]; } @@ -2494,9 +1857,8 @@ SparseMatrix::copy_from (const ForwardIterator begin, Assert (static_cast(std::distance (begin, end)) == m(), ExcIteratorRange (std::distance (begin, end), m())); - // for use in the inner loop, we - // define a typedef to the type of - // the inner iterators + // for use in the inner loop, we define a typedef to the type of the inner + // iterators typedef typename std::iterator_traits::value_type::const_iterator inner_iterator; unsigned int row=0; for (ForwardIterator i=begin; i!=end; ++i, ++row) @@ -2822,14 +2184,12 @@ inline typename SparseMatrix::const_iterator SparseMatrix::begin () const { - // search for the first line with a nonzero - // number of entries + // search for the first line with a nonzero number of entries for (unsigned int r=0; rrow_length(r) > 0) return const_iterator(this, r, 0); - // alright, this matrix is completely - // empty. that's strange but ok. simply + // alright, this matrix is completely empty. that's strange but ok. simply // return the end() iterator return end(); } @@ -2849,14 +2209,12 @@ inline typename SparseMatrix::iterator SparseMatrix::begin () { - // search for the first line with a nonzero - // number of entries + // search for the first line with a nonzero number of entries for (unsigned int r=0; rrow_length(r) > 0) return iterator(this, r, 0); - // alright, this matrix is completely - // empty. that's strange but ok. simply + // alright, this matrix is completely empty. that's strange but ok. simply // return the end() iterator return end(); } @@ -2893,15 +2251,13 @@ SparseMatrix::end (const unsigned int r) const { Assert (rrow_length(i) > 0) return const_iterator(this, i, 0); - // if there is no such line, then take the - // end iterator of the matrix + // if there is no such line, then take the end iterator of the matrix return end(); } @@ -2929,15 +2285,13 @@ SparseMatrix::end (const unsigned int r) { Assert (rrow_length(i) > 0) return iterator(this, i, 0); - // if there is no such line, then take the - // end iterator of the matrix + // if there is no such line, then take the end iterator of the matrix return end(); } diff --git a/deal.II/include/deal.II/lac/sparse_matrix.templates.h b/deal.II/include/deal.II/lac/sparse_matrix.templates.h index 60f3753857..f032403de4 100644 --- a/deal.II/include/deal.II/lac/sparse_matrix.templates.h +++ b/deal.II/include/deal.II/lac/sparse_matrix.templates.h @@ -374,20 +374,18 @@ SparseMatrix::add (const number factor, } + namespace internal { namespace SparseMatrix { /** - * Perform a vmult using the SparseMatrix - * data structures, but only using a - * subinterval for the row indices. + * Perform a vmult using the SparseMatrix data structures, but only using + * a subinterval for the row indices. * - * In the sequential case, this function - * is called on all rows, in the parallel - * case it may be called on a subrange, - * at the discretion of the task - * scheduler. + * In the sequential case, this function is called on all rows, in the + * parallel case it may be called on a subrange, at the discretion of the + * task scheduler. */ template unsigned int get_column_index_from_iterator (const std::pair &i); /** - * Likewise, but sometimes needed - * for certain types of - * containers that make the first - * element of the pair constant - * (such as std::map). + * Likewise, but sometimes needed for certain types of containers that + * make the first element of the pair constant (such as + * std::map). */ template unsigned int @@ -114,86 +105,57 @@ namespace SparsityPatternIterators const unsigned int index); /** - * Constructor. Construct the end - * accessor for the given sparsity - * pattern. + * Constructor. Construct the end accessor for the given sparsity pattern. */ Accessor (const SparsityPattern *matrix); /** - * Row number of the element - * represented by this object. This - * function can only be called for - * entries for which is_valid_entry() - * is true. + * Row number of the element represented by this object. This function can + * only be called for entries for which is_valid_entry() is true. */ unsigned int row () const; /** - * Index in row of the element - * represented by this object. This - * function can only be called for - * entries for which is_valid_entry() - * is true. + * Index in row of the element represented by this object. This function + * can only be called for entries for which is_valid_entry() is true. */ unsigned int index () const; /** - * Column number of the element - * represented by this object. This - * function can only be called for - * entries for which is_valid_entry() is - * true. + * Column number of the element represented by this object. This function + * can only be called for entries for which is_valid_entry() is true. */ unsigned int column () const; /** - * Return whether the sparsity - * pattern entry pointed to by this - * iterator is valid or not. Note - * that after compressing the - * sparsity pattern, all entries are - * valid. However, before - * compression, the sparsity pattern - * allocated some memory to be used - * while still adding new nonzero - * entries; if you create iterators - * in this phase of the sparsity - * pattern's lifetime, you will - * iterate over elements that are not - * valid. If this is so, then this - * function will return false. + * Return whether the sparsity pattern entry pointed to by this iterator + * is valid or not. Note that after compressing the sparsity pattern, all + * entries are valid. However, before compression, the sparsity pattern + * allocated some memory to be used while still adding new nonzero + * entries; if you create iterators in this phase of the sparsity + * pattern's lifetime, you will iterate over elements that are not + * valid. If this is so, then this function will return false. */ inline bool is_valid_entry () 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 Accessor &) 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. * - * This function is only valid if - * both iterators point into the same + * This function is only valid if both iterators point into the same * sparsity pattern. */ bool operator < (const Accessor &) const; protected: /** - * The sparsity pattern we operate on - * accessed. + * The sparsity pattern we operate on accessed. */ const SparsityPattern *sparsity_pattern; @@ -208,8 +170,7 @@ namespace SparsityPatternIterators unsigned int a_index; /** - * Move the accessor to the next - * nonzero entry in the matrix. + * Move the accessor to the next nonzero entry in the matrix. */ void advance (); @@ -222,15 +183,13 @@ namespace SparsityPatternIterators /** - * STL conforming iterator walking over - * the elements of a sparsity pattern. + * STL conforming iterator walking over the elements of a sparsity pattern. */ class Iterator { public: /** - * Constructor. Create an iterator - * into the sparsity pattern @p sp for the + * Constructor. Create an iterator into the sparsity pattern @p sp for the * given row and the index within it. */ Iterator (const SparsityPattern *sp, @@ -258,10 +217,7 @@ namespace SparsityPatternIterators 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 Iterator &) const; @@ -271,24 +227,17 @@ namespace SparsityPatternIterators bool operator != (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. * - * This function is only valid if - * both iterators point into the same + * This function is only valid if both iterators point into the same * matrix. */ bool operator < (const Iterator &) const; private: /** - * Store an object of the - * accessor class. + * Store an object of the accessor class. */ Accessor accessor; }; @@ -309,31 +258,26 @@ class SparsityPattern : public Subscriptor { public: /** - * Typedef an iterator class that allows - * to walk over all nonzero elements of a - * sparsity pattern. + * Typedef an iterator class that allows to walk over all nonzero elements + * of a sparsity pattern. */ typedef SparsityPatternIterators::Iterator const_iterator; /** - * Typedef an iterator class that allows - * to walk over the nonzero elements of a - * row of a sparsity pattern. + * Typedef an iterator class that allows to walk over the nonzero elements + * of a row of a sparsity pattern. */ typedef const unsigned int *row_iterator; /** - * Typedef an iterator class that allows - * to walk over all nonzero elements of a - * sparsity pattern. + * Typedef an iterator class that allows to walk over all nonzero elements + * of a sparsity pattern. * - * Since the iterator does not allow to - * modify the sparsity pattern, this type - * is the same as that for @p - * const_iterator. + * Since the iterator does not allow to modify the sparsity pattern, this + * type is the same as that for @p const_iterator. */ typedef SparsityPatternIterators::Iterator @@ -341,28 +285,18 @@ public: /** - * Define a value which is used - * to indicate that a certain - * value in the #colnums array - * is unused, i.e. does not - * represent a certain column - * number index. + * Define a value which is used to indicate that a certain value in the + * #colnums array is unused, i.e. does not represent a certain column number + * index. * - * Indices with this invalid - * value are used to insert new - * entries to the sparsity - * pattern using the add() member - * function, and are removed when + * Indices with this invalid value are used to insert new entries to the + * sparsity pattern using the add() member function, and are removed when * calling compress(). * - * You should not assume that the - * variable declared here has a - * certain value. The - * initialization is given here - * only to enable the compiler to - * perform some optimizations, - * but the actual value of the - * variable may change over time. + * You should not assume that the variable declared here has a certain + * value. The initialization is given here only to enable the compiler to + * perform some optimizations, but the actual value of the variable may + * change over time. */ static const unsigned int invalid_entry = numbers::invalid_unsigned_int; @@ -372,64 +306,37 @@ public: */ // @{ /** - * Initialize the matrix empty, - * that is with no memory - * allocated. This is useful if - * you want such objects as - * member variables in other - * classes. You can make the - * structure usable by calling - * the reinit() function. + * Initialize the matrix empty, that is with no memory allocated. This is + * useful if you want such objects as member variables in other classes. You + * can make the structure usable by calling the reinit() function. */ SparsityPattern (); /** - * Copy constructor. This - * constructor is only allowed to - * be called if the matrix - * structure to be copied is - * empty. This is so in order to - * prevent involuntary copies of - * objects for temporaries, which - * can use large amounts of - * computing time. However, copy - * constructors are needed if yo - * want to use the STL data types - * on classes like this, e.g. to - * write such statements like - * v.push_back - * (SparsityPattern());, - * with v a vector of - * SparsityPattern objects. + * Copy constructor. This constructor is only allowed to be called if the + * matrix structure to be copied is empty. This is so in order to prevent + * involuntary copies of objects for temporaries, which can use large + * amounts of computing time. However, copy constructors are needed if yo + * want to use the STL data types on classes like this, e.g. to write such + * statements like v.push_back (SparsityPattern());, with + * v a vector of SparsityPattern objects. * - * Usually, it is sufficient to - * use the explicit keyword to - * disallow unwanted temporaries, - * but for the STL vectors, this - * does not work. Since copying a - * structure like this is not - * useful anyway because multiple - * matrices can use the same - * sparsity structure, copies are - * only allowed for empty - * objects, as described above. + * Usually, it is sufficient to use the explicit keyword to disallow + * unwanted temporaries, but for the STL vectors, this does not work. Since + * copying a structure like this is not useful anyway because multiple + * matrices can use the same sparsity structure, copies are only allowed for + * empty objects, as described above. */ SparsityPattern (const SparsityPattern &); /** - * Initialize a rectangular - * matrix. + * Initialize a rectangular matrix. * * @arg m number of rows * @arg n number of columns - * @arg max_per_row maximum - * number of nonzero entries per row - * - * @arg optimize_diagonal store - * diagonal entries first in row; - * see optimize_diagonal(). This - * takes effect for quadratic - * matrices only. + * @arg max_per_row maximum number of nonzero entries per row + * @arg optimize_diagonal store diagonal entries first in row; see + * optimize_diagonal(). This takes effect for quadratic matrices only. */ SparsityPattern (const unsigned int m, const unsigned int n, @@ -437,22 +344,14 @@ public: const bool optimize_diagonal = true); /** - * Initialize a rectangular - * matrix. + * Initialize a rectangular matrix. * * @arg m number of rows * @arg n number of columns - * - * @arg row_lengths possible - * number of nonzero entries for - * each row. This vector must - * have one entry for each row. - * - * @arg optimize_diagonal store - * diagonal entries first in row; - * see optimize_diagonal(). This - * takes effect for quadratic - * matrices only. + * @arg row_lengths possible number of nonzero entries for each row. This + * vector must have one entry for each row. + * @arg optimize_diagonal store diagonal entries first in row; see + * optimize_diagonal(). This takes effect for quadratic matrices only. */ SparsityPattern (const unsigned int m, const unsigned int n, @@ -460,17 +359,12 @@ public: const bool optimize_diagonal = true); /** - * Initialize a quadratic matrix - * of dimension n with - * at most max_per_row - * nonzero entries per row. + * Initialize a quadratic matrix of dimension n with at most + * max_per_row nonzero entries per row. * - * This constructor automatically - * enables optimized storage of - * diagonal elements. To avoid - * this, use the constructor - * taking row and column numbers - * separately. + * This constructor automatically enables optimized storage of diagonal + * elements. To avoid this, use the constructor taking row and column + * numbers separately. */ SparsityPattern (const unsigned int n, const unsigned int max_per_row); @@ -479,15 +373,10 @@ public: * Initialize a quadratic matrix. * * @arg m number of rows and columns - * - * @arg row_lengths possible - * number of nonzero entries for - * each row. This vector must - * have one entry for each row. - * - * @arg optimize_diagonal store - * diagonal entries first in row; - * see optimize_diagonal(). + * @arg row_lengths possible number of nonzero entries for each row. This + * vector must have one entry for each row. + * @arg optimize_diagonal store diagonal entries first in row; see + * optimize_diagonal(). */ SparsityPattern (const unsigned int m, const std::vector &row_lengths, @@ -496,44 +385,24 @@ public: /** * Make a copy with extra off-diagonals. * - * This constructs objects intended for - * the application of the ILU(n)-method - * or other incomplete decompositions. - * Therefore, additional to the original - * entry structure, space for - * extra_off_diagonals - * side-diagonals is provided on both - * sides of the main diagonal. - * - * max_per_row is the - * maximum number of nonzero - * elements per row which this - * structure is to hold. It is - * assumed that this number is - * sufficiently large to - * accommodate both the elements - * in original as well - * as the new off-diagonal - * elements created by this - * constructor. You will usually - * want to give the same number - * as you gave for - * original plus the - * number of side diagonals times - * two. You may however give a - * larger value if you wish to - * add further nonzero entries - * for the decomposition based on - * other criteria than their - * being on side-diagonals. - * - * This function requires that - * original refers to a - * quadratic matrix structure. - * It must be compressed. The - * matrix structure is not - * compressed after this function - * finishes. + * This constructs objects intended for the application of the ILU(n)-method + * or other incomplete decompositions. Therefore, additional to the + * original entry structure, space for extra_off_diagonals + * side-diagonals is provided on both sides of the main diagonal. + * + * max_per_row is the maximum number of nonzero elements per row + * which this structure is to hold. It is assumed that this number is + * sufficiently large to accommodate both the elements in original + * as well as the new off-diagonal elements created by this constructor. You + * will usually want to give the same number as you gave for + * original plus the number of side diagonals times two. You may + * however give a larger value if you wish to add further nonzero entries + * for the decomposition based on other criteria than their being on + * side-diagonals. + * + * This function requires that original refers to a quadratic + * matrix structure. It must be compressed. The matrix structure is not + * compressed after this function finishes. */ SparsityPattern (const SparsityPattern &original, const unsigned int max_per_row, @@ -545,25 +414,19 @@ public: ~SparsityPattern (); /** - * Copy operator. For this the - * same holds as for the copy - * constructor: it is declared, - * defined and fine to be called, - * but the latter only for empty + * Copy operator. For this the same holds as for the copy constructor: it is + * declared, defined and fine to be called, but the latter only for empty * objects. */ SparsityPattern &operator = (const SparsityPattern &); /** - * Reallocate memory and set up data - * structures for a new matrix with - * m rows and n columns, - * with at most max_per_row + * Reallocate memory and set up data structures for a new matrix with m + * rows and n columns, with at most max_per_row * nonzero entries per row. * - * This function simply maps its - * operations to the other - * reinit function. + * This function simply maps its operations to the other reinit + * function. */ void reinit (const unsigned int m, const unsigned int n, @@ -571,29 +434,18 @@ public: const bool optimize_diagonal = true); /** - * Reallocate memory for a matrix - * of size m x n. The - * number of entries for each row - * is taken from the array - * row_lengths which has to - * give this number of each row - * i=1...m. + * Reallocate memory for a matrix of size m x n. The number of + * entries for each row is taken from the array row_lengths which + * has to give this number of each row i=1...m. * - * If m*n==0 all memory is freed, - * resulting in a total reinitialization - * of the object. If it is nonzero, new - * memory is only allocated if the new - * size extends the old one. This is done - * to save time and to avoid fragmentation - * of the heap. + * If m*n==0 all memory is freed, resulting in a total + * reinitialization of the object. If it is nonzero, new memory is only + * allocated if the new size extends the old one. This is done to save time + * and to avoid fragmentation of the heap. * - * If the number of rows equals - * the number of columns and the - * last parameter is true, - * diagonal elements are stored - * first in each row to allow - * optimized access in relaxation - * methods of SparseMatrix. + * If the number of rows equals the number of columns and the last parameter + * is true, diagonal elements are stored first in each row to allow + * optimized access in relaxation methods of SparseMatrix. */ void reinit (const unsigned int m, const unsigned int n, @@ -601,8 +453,7 @@ public: const bool optimize_diagonal = true); /** - * Same as above, but with a - * VectorSlice argument instead. + * Same as above, but with a VectorSlice argument instead. */ void reinit (const unsigned int m, const unsigned int n, @@ -610,103 +461,52 @@ public: const bool optimize_diagonal = true); /** - * This function compresses the sparsity - * structure that this object represents. - * It does so by eliminating unused - * entries and sorting the remaining ones - * to allow faster access by usage of - * binary search algorithms. A special - * sorting scheme is used for the - * diagonal entry of quadratic matrices, - * which is always the first entry of - * each row. + * This function compresses the sparsity structure that this object + * represents. It does so by eliminating unused entries and sorting the + * remaining ones to allow faster access by usage of binary search + * algorithms. A special sorting scheme is used for the diagonal entry of + * quadratic matrices, which is always the first entry of each row. * - * The memory which is no more - * needed is released. + * The memory which is no more needed is released. * - * SparseMatrix objects require the - * SparsityPattern objects they are - * initialized with to be compressed, to - * reduce memory requirements. + * SparseMatrix objects require the SparsityPattern objects they are + * initialized with to be compressed, to reduce memory requirements. */ void compress (); /** - * This function can be used as a - * replacement for reinit(), - * subsequent calls to add() and - * a final call to close() if you - * know exactly in advance the - * entries that will form the - * matrix sparsity pattern. - * - * The first two parameters - * determine the size of the - * matrix. For the two last ones, - * note that a sparse matrix can - * be described by a sequence of - * rows, each of which is - * represented by a sequence of - * pairs of column indices and - * values. In the present - * context, the begin() and - * end() parameters designate - * iterators (of forward iterator - * type) into a container, one - * representing one row. The - * distance between begin() - * and end() should therefore - * be equal to - * n_rows(). These iterators - * may be iterators of - * std::vector, - * std::list, pointers into a - * C-style array, or any other - * iterator satisfying the - * requirements of a forward - * iterator. The objects pointed - * to by these iterators - * (i.e. what we get after - * applying operator* or - * operator-> to one of these - * iterators) must be a container - * itself that provides functions - * begin and end - * designating a range of - * iterators that describe the - * contents of one - * line. Dereferencing these - * inner iterators must either - * yield a pair of an unsigned - * integer as column index and a - * value of arbitrary type (such - * a type would be used if we - * wanted to describe a sparse - * matrix with one such object), - * or simply an unsigned integer - * (of we only wanted to describe - * a sparsity pattern). The - * function is able to determine - * itself whether an unsigned - * integer or a pair is what we - * get after dereferencing the - * inner iterators, through some - * template magic. - * - * While the order of the outer - * iterators denotes the - * different rows of the matrix, - * the order of the inner - * iterator denoting the columns - * does not matter, as they are - * sorted internal to this - * function anyway. - * - * Since that all sounds very - * complicated, consider the - * following example code, which - * may be used to fill a sparsity - * pattern: + * This function can be used as a replacement for reinit(), subsequent calls + * to add() and a final call to close() if you know exactly in advance the + * entries that will form the matrix sparsity pattern. + * + * The first two parameters determine the size of the matrix. For the two + * last ones, note that a sparse matrix can be described by a sequence of + * rows, each of which is represented by a sequence of pairs of column + * indices and values. In the present context, the begin() and end() + * parameters designate iterators (of forward iterator type) into a + * container, one representing one row. The distance between begin() and + * end() should therefore be equal to n_rows(). These iterators may be + * iterators of std::vector, std::list, pointers into a + * C-style array, or any other iterator satisfying the requirements of a + * forward iterator. The objects pointed to by these iterators (i.e. what we + * get after applying operator* or operator-> to one of + * these iterators) must be a container itself that provides functions + * begin and end designating a range of iterators that + * describe the contents of one line. Dereferencing these inner iterators + * must either yield a pair of an unsigned integer as column index and a + * value of arbitrary type (such a type would be used if we wanted to + * describe a sparse matrix with one such object), or simply an unsigned + * integer (of we only wanted to describe a sparsity pattern). The function + * is able to determine itself whether an unsigned integer or a pair is what + * we get after dereferencing the inner iterators, through some template + * magic. + * + * While the order of the outer iterators denotes the different rows of the + * matrix, the order of the inner iterator denoting the columns does not + * matter, as they are sorted internal to this function anyway. + * + * Since that all sounds very complicated, consider the following example + * code, which may be used to fill a sparsity pattern: * @code * std::vector > column_indices (n_rows); * for (unsigned int row=0; rowbegin and - * end (namely - * std::vectors), and the - * inner iterators dereferenced - * yield unsigned integers as - * column indices. Note that we - * could have replaced each of - * the two std::vector - * occurrences by std::list, - * and the inner one by - * std::set as well. + * Note that this example works since the iterators dereferenced yield + * containers with functions begin and end (namely + * std::vectors), and the inner iterators dereferenced yield + * unsigned integers as column indices. Note that we could have replaced + * each of the two std::vector occurrences by std::list, + * and the inner one by std::set as well. * - * Another example would be as - * follows, where we initialize a - * whole matrix, not only a - * sparsity pattern: + * Another example would be as follows, where we initialize a whole matrix, + * not only a sparsity pattern: * @code * std::vector > entries (n_rows); * for (unsigned int row=0; rowstd::vector - * could be replaced by - * std::list, and the inner - * std::map - * could be replaced by - * std::vector >, - * or a list or set of such - * pairs, as they all return - * iterators that point to such - * pairs. + * This example works because dereferencing iterators of the inner type + * yields a pair of unsigned integers and a value, the first of which we + * take as column index. As previously, the outer std::vector could + * be replaced by std::list, and the inner std::map could be replaced by std::vector >, or a list or set of such pairs, as they all return + * iterators that point to such pairs. */ template void copy_from (const unsigned int n_rows, @@ -777,12 +558,9 @@ public: const bool optimize_diagonal = true); /** - * Copy data from an object of type - * CompressedSparsityPattern, - * CompressedSetSparsityPattern or - * CompressedSimpleSparsityPattern. - * Previous content of this object is - * lost, and the sparsity pattern is in + * Copy data from an object of type CompressedSparsityPattern, + * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. + * Previous content of this object is lost, and the sparsity pattern is in * compressed mode afterwards. */ template @@ -790,14 +568,10 @@ public: const bool optimize_diagonal = true); /** - * Take a full matrix and use its - * nonzero entries to generate a - * sparse matrix entry pattern - * for this object. + * Take a full matrix and use its nonzero entries to generate a sparse + * matrix entry pattern for this object. * - * Previous content of this - * object is lost, and the - * sparsity pattern is in + * Previous content of this object is lost, and the sparsity pattern is in * compressed mode afterwards. */ template @@ -805,37 +579,28 @@ public: const bool optimize_diagonal = true); /** - * Make the sparsity pattern - * symmetric by adding the - * sparsity pattern of the + * Make the sparsity pattern symmetric by adding the sparsity pattern of the * transpose object. * - * This function throws an - * exception if the sparsity - * pattern does not represent a - * quadratic matrix. + * This function throws an exception if the sparsity pattern does not + * represent a quadratic matrix. */ void symmetrize (); /** - * Add a nonzero entry to the matrix. - * This function may only be called - * for non-compressed sparsity patterns. - * - * If the entry already exists, nothing - * bad happens. - */ + * Add a nonzero entry to the matrix. This function may only be called for + * non-compressed sparsity patterns. + * + * If the entry already exists, nothing bad happens. + */ void add (const unsigned int i, const unsigned int j); /** - * Add several nonzero entries to the - * specified matrix row. This function - * may only be called for - * non-compressed sparsity patterns. + * Add several nonzero entries to the specified matrix row. This function + * may only be called for non-compressed sparsity patterns. * - * If some of the entries already - * exist, nothing bad happens. + * If some of the entries already exist, nothing bad happens. */ template void add_entries (const unsigned int row, @@ -850,10 +615,9 @@ public: // @{ /** - * STL-like iterator with the first entry - * of the matrix. The resulting iterator - * can be used to walk over all nonzero - * entries of the sparsity pattern. + * STL-like iterator with the first entry of the matrix. The resulting + * iterator can be used to walk over all nonzero entries of the sparsity + * pattern. */ inline iterator begin () const; @@ -863,56 +627,42 @@ public: inline iterator end () const; /** - * STL-like iterator with the first entry - * of row r. + * STL-like iterator with the first entry of row r. * - * Note that if the given row is empty, - * i.e. does not contain any nonzero - * entries, then the iterator returned by - * this function equals - * end(r). Note also that the - * iterator may not be dereferencable in + * Note that if the given row is empty, i.e. does not contain any nonzero + * entries, then the iterator returned by this function equals + * end(r). Note also that the iterator may not be dereferencable in * that case. */ inline iterator begin (const unsigned int r) const; /** - * Final iterator of row r. It - * points to the first element past the - * end of line @p r, or past the end of - * the entire sparsity pattern. + * Final iterator of row r. It points to the first element past the + * end of line @p r, or past the end of the entire sparsity pattern. * - * Note that the end iterator is not - * necessarily dereferencable. This is in - * particular the case if it is the end - * iterator for the last row of a matrix. + * Note that the end iterator is not necessarily dereferencable. This is in + * particular the case if it is the end iterator for the last row of a + * matrix. */ inline iterator end (const unsigned int r) const; /** - * STL-like iterator with the first entry - * of row r. + * STL-like iterator with the first entry of row r. * - * Note that if the given row is empty, - * i.e. does not contain any nonzero - * entries, then the iterator returned by - * this function equals - * end(r). Note also that the - * iterator may not be dereferencable in + * Note that if the given row is empty, i.e. does not contain any nonzero + * entries, then the iterator returned by this function equals + * end(r). Note also that the iterator may not be dereferencable in * that case. */ inline row_iterator row_begin (const unsigned int r) const; /** - * Final iterator of row r. It - * points to the first element past the - * end of line @p r, or past the end of - * the entire sparsity pattern. + * Final iterator of row r. It points to the first element past the + * end of line @p r, or past the end of the entire sparsity pattern. * - * Note that the end iterator is not - * necessarily dereferencable. This is in - * particular the case if it is the end - * iterator for the last row of a matrix. + * Note that the end iterator is not necessarily dereferencable. This is in + * particular the case if it is the end iterator for the last row of a + * matrix. */ inline row_iterator row_end (const unsigned int r) const; @@ -927,66 +677,50 @@ public: bool operator == (const SparsityPattern &) const; /** - * Return whether the object is empty. It - * is empty if no memory is allocated, - * which is the same as that both - * dimensions are zero. + * Return whether the object is empty. It is empty if no memory is + * allocated, which is the same as that both dimensions are zero. */ bool empty () const; /** - * Return the maximum number of entries per - * row. Before compression, this equals the - * number given to the constructor, while - * after compression, it equals the maximum - * number of entries actually allocated by - * the user. + * Return the maximum number of entries per row. Before compression, this + * equals the number given to the constructor, while after compression, it + * equals the maximum number of entries actually allocated by the user. */ unsigned int max_entries_per_row () const; /** - * Compute the bandwidth of the matrix - * represented by this structure. The - * bandwidth is the maximum of $|i-j|$ - * for which the index pair $(i,j)$ - * represents a nonzero entry of the - * matrix. Consequently, the maximum - * bandwidth a $n\times m$ matrix can - * have is $\max\{n-1,m-1\}$. + * Compute the bandwidth of the matrix represented by this structure. The + * bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$ + * represents a nonzero entry of the matrix. Consequently, the maximum + * bandwidth a $n\times m$ matrix can have is $\max\{n-1,m-1\}$. */ unsigned int bandwidth () const; /** - * Return the number of nonzero elements of - * this matrix. Actually, it returns the - * number of entries in the sparsity - * pattern; if any of the entries should - * happen to be zero, it is counted - * anyway. + * Return the number of nonzero elements of this matrix. Actually, it + * returns the number of entries in the sparsity pattern; if any of the + * entries should happen to be zero, it is counted anyway. * - * This function may only be called if the - * matrix struct is compressed. It does not - * make too much sense otherwise anyway. + * This function may only be called if the matrix struct is compressed. It + * does not make too much sense otherwise anyway. */ std::size_t n_nonzero_elements () const; /** - * Return whether the structure is - * compressed or not. + * Return whether the structure is compressed or not. */ bool is_compressed () const; /** - * Return number of rows of this - * matrix, which equals the dimension - * of the image space. + * Return number of rows of this matrix, which equals the dimension of the + * image space. */ inline unsigned int n_rows () const; /** - * Return number of columns of this - * matrix, which equals the dimension - * of the range space. + * Return number of columns of this matrix, which equals the dimension of + * the range space. */ inline unsigned int n_cols () const; @@ -996,66 +730,44 @@ public: unsigned int row_length (const unsigned int row) const; /** - * Determine whether the matrix - * uses special convention for - * quadratic matrices. + * Determine whether the matrix uses special convention for quadratic + * matrices. * - * A return value true means - * that diagonal elements are stored - * first in each row. A number of - * functions in this class and the - * library in general, for example - * relaxation methods like Jacobi() and - * SOR(), require this to make their - * operations more efficient, since they - * need to quickly access the diagonal - * elements and do not have to search for - * them if they are the first element of - * each row. A side effect of this scheme - * is that each row contains at least one - * element, even if the row is empty - * (i.e. the diagonal element exists, but - * has value zero). + * A return value true means that diagonal elements are stored + * first in each row. A number of functions in this class and the library in + * general, for example relaxation methods like Jacobi() and SOR(), require + * this to make their operations more efficient, since they need to quickly + * access the diagonal elements and do not have to search for them if they + * are the first element of each row. A side effect of this scheme is that + * each row contains at least one element, even if the row is empty + * (i.e. the diagonal element exists, but has value zero). * - * A return value false means - * that diagonal elements are stored - * anywhere in the row, or not at all. In - * particular, a row or even the whole - * matrix may be empty. This can be used - * if you have block matrices where the - * off-diagonal blocks are quadratic but - * are never used for operations like the - * ones mentioned above. In this case, - * some memory can be saved by not using - * the diagonal storage optimization. + * A return value false means that diagonal elements are stored + * anywhere in the row, or not at all. In particular, a row or even the + * whole matrix may be empty. This can be used if you have block matrices + * where the off-diagonal blocks are quadratic but are never used for + * operations like the ones mentioned above. In this case, some memory can + * be saved by not using the diagonal storage optimization. */ bool optimize_diagonal () const; /** - * Return whether this object stores only - * those entries that have been added - * explicitly, or if the sparsity pattern - * contains elements that have been added - * through other means (implicitly) while - * building it. For the current class, - * the result is true iff optimize_diag - * in the constructor or reinit() calls - * has been set to false, or if the - * represented matrix is not square. + * Return whether this object stores only those entries that have been added + * explicitly, or if the sparsity pattern contains elements that have been + * added through other means (implicitly) while building it. For the current + * class, the result is true iff optimize_diag in the constructor or + * reinit() calls has been set to false, or if the represented matrix is not + * square. * - * This function mainly serves the - * purpose of describing the current - * class in cases where several kinds of - * sparsity patterns can be passed as + * This function mainly serves the purpose of describing the current class + * in cases where several kinds of sparsity patterns can be passed as * template arguments. */ bool stores_only_added_elements () const; /** - * Determine an estimate for the - * memory consumption (in bytes) - * of this object. See - * MemoryConsumption. + * Determine an estimate for the memory consumption (in bytes) of this + * object. See MemoryConsumption. */ std::size_t memory_consumption () const; @@ -1065,97 +777,64 @@ public: */ // @{ /** - * Return the index of the matrix - * element with row number i - * and column number j. If - * the matrix element is not a - * nonzero one, return - * SparsityPattern::invalid_entry. + * Return the index of the matrix element with row number i and + * column number j. If the matrix element is not a nonzero one, + * return SparsityPattern::invalid_entry. * - * This function is usually - * called by the - * SparseMatrix::operator()(). It - * may only be called for - * compressed sparsity patterns, - * since in this case searching - * whether the entry exists can - * be done quite fast with a - * binary sort algorithm because - * the column numbers are sorted. + * This function is usually called by the SparseMatrix::operator()(). It may + * only be called for compressed sparsity patterns, since in this case + * searching whether the entry exists can be done quite fast with a binary + * sort algorithm because the column numbers are sorted. * - * If m is the number of - * entries in row, then the - * complexity of this function is - * log(m) if the sparsity - * pattern is compressed. + * If m is the number of entries in row, then the + * complexity of this function is log(m) if the sparsity pattern is + * compressed. * - * @deprecated Use - * SparseMatrix::const_iterator + * @deprecated Use SparseMatrix::const_iterator */ unsigned int operator() (const unsigned int i, const unsigned int j) const; /** - * This is the inverse operation - * to operator()(): given a - * global index, find out row and - * column of the matrix entry to - * which it belongs. The returned - * value is the pair composed of - * row and column index. + * This is the inverse operation to operator()(): given a global index, find + * out row and column of the matrix entry to which it belongs. The returned + * value is the pair composed of row and column index. * - * This function may only be - * called if the sparsity pattern - * is closed. The global index - * must then be between zero and - * n_nonzero_elements(). + * This function may only be called if the sparsity pattern is closed. The + * global index must then be between zero and n_nonzero_elements(). * - * If N is the number of - * rows of this matrix, then the - * complexity of this function is - * log(N). + * If N is the number of rows of this matrix, then the complexity + * of this function is log(N). */ std::pair matrix_position (const unsigned int global_index) const; /** - * Check if a value at a certain - * position may be non-zero. + * Check if a value at a certain position may be non-zero. */ bool exists (const unsigned int i, const unsigned int j) const; /** - * The index of a global matrix - * entry in its row. + * The index of a global matrix entry in its row. * - * This function is analogous to - * operator(), but it computes - * the index not with respect to - * the total field, but only with - * respect to the row j. + * This function is analogous to operator(), but it computes the index not + * with respect to the total field, but only with respect to the row + * j. */ unsigned int row_position(const unsigned int i, const unsigned int j) const; /** - * Access to column number field. - * Return the column number of - * the indexth entry in - * row. Note that if - * diagonal elements are - * optimized, the first element - * in each row is the diagonal - * element, + * Access to column number field. Return the column number of the + * indexth entry in row. Note that if diagonal elements + * are optimized, the first element in each row is the diagonal element, * i.e. column_number(row,0)==row. * - * If the sparsity pattern is - * already compressed, then - * (except for the diagonal - * element), the entries are - * sorted by columns, - * i.e. column_number(row,i) - * < column_number(row,i+1). + * If the sparsity pattern is already compressed, then (except for the + * diagonal element), the entries are sorted by columns, + * i.e. column_number(row,i) < + * column_number(row,i+1). */ unsigned int column_number (const unsigned int row, const unsigned int index) const; @@ -1167,98 +846,64 @@ public: */ // @{ /** - * Write the data of this object - * 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 data of this object 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. * - * The purpose of this function - * is that you can swap out - * matrices and sparsity pattern - * if you are short of memory, - * want to communicate between - * different programs, or allow - * objects to be persistent - * across different runs of the - * program. + * The purpose of this function is that you can swap out matrices and + * sparsity pattern if you are short of memory, want to communicate between + * different programs, or allow objects to be persistent across different + * runs of the program. */ void block_write (std::ostream &out) const; /** - * Read data that has previously - * been written by block_write() - * 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 - * except for a few numbers up - * front. + * Read data that has previously been written by block_write() 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 except for + * a few numbers up front. * - * The object is resized on this - * operation, and all previous - * contents are lost. + * The object is resized on this operation, and all previous contents are + * lost. * - * A primitive form of error - * checking is performed which - * will recognize the bluntest - * attempts to interpret some - * data as a vector stored - * bitwise to a file, but not - * more. + * A primitive form of error checking is performed which will recognize the + * bluntest attempts to interpret some data as a vector stored bitwise to a + * file, but not more. */ void block_read (std::istream &in); /** - * Print the sparsity of the - * matrix. The output consists of - * one line per row of the format - * [i,j1,j2,j3,...]. i - * is the row number and - * jn are the allocated - * columns in this row. + * Print the sparsity of the matrix. The output consists of one line per row + * of the format [i,j1,j2,j3,...]. i is the row number and + * jn are the allocated columns in this row. */ void print (std::ostream &out) const; /** - * Print the sparsity of the matrix - * in a format that gnuplot understands - * and which can be used to plot the - * sparsity pattern in a graphical - * way. The format consists of pairs - * i j of nonzero elements, each - * representing one entry of this - * matrix, one per line of the output - * file. Indices are counted from - * zero on, as usual. Since sparsity - * patterns are printed in the same - * way as matrices are displayed, we - * print the negative of the column - * index, which means that the - * (0,0) element is in the top left - * rather than in the bottom left - * corner. + * Print the sparsity of the matrix in a format that gnuplot + * understands and which can be used to plot the sparsity pattern in a + * graphical way. The format consists of pairs i j of nonzero + * elements, each representing one entry of this matrix, one per line of the + * output file. Indices are counted from zero on, as usual. Since sparsity + * patterns are printed in the same way as matrices are displayed, we print + * the negative of the column index, which means that the (0,0) + * element is in the top left rather than in the bottom left corner. * - * Print the sparsity pattern in - * gnuplot by setting the data style - * to dots or points and use the - * plot command. + * Print the sparsity pattern in gnuplot by setting the data style to dots + * or points and use the plot command. */ void print_gnuplot (std::ostream &out) const; + /** - * Write the data of this object to - * a stream for the purpose of serialization + * Write the data of this object to a stream for the purpose of + * serialization */ template void save (Archive &ar, const unsigned int version) const; /** - * Read the data of this object - * from a stream for the purpose of serialization + * Read the data of this object from a stream for the purpose of + * serialization */ template void load (Archive &ar, const unsigned int version); @@ -1269,123 +914,80 @@ public: */ // @{ /** - * @deprecated - * This function is deprecated. Use - * SparsityTools::partition instead. - * - * Use the METIS partitioner to generate - * a partitioning of the degrees of - * freedom represented by this sparsity - * pattern. In effect, we view this - * sparsity pattern as a graph of - * connections between various degrees of - * freedom, where each nonzero entry in - * the sparsity pattern corresponds to an - * edge between two nodes in the - * connection graph. The goal is then to - * decompose this graph into groups of - * nodes so that a minimal number of - * edges are cut by the boundaries - * between node groups. This partitioning - * is done by METIS. Note that METIS can - * only partition symmetric sparsity - * patterns, and that of course the - * sparsity pattern has to be square. We - * do not check for symmetry of the - * sparsity pattern, since this is an - * expensive operation, but rather leave - * this as the responsibility of caller - * of this function. - * - * After calling this function, the - * output array will have values between - * zero and @p n_partitions-1 for each - * node (i.e. row or column of the + * @deprecated This function is deprecated. Use SparsityTools::partition + * instead. + * + * Use the METIS partitioner to generate a partitioning of the degrees of + * freedom represented by this sparsity pattern. In effect, we view this + * sparsity pattern as a graph of connections between various degrees of + * freedom, where each nonzero entry in the sparsity pattern corresponds to + * an edge between two nodes in the connection graph. The goal is then to + * decompose this graph into groups of nodes so that a minimal number of + * edges are cut by the boundaries between node groups. This partitioning is + * done by METIS. Note that METIS can only partition symmetric sparsity + * patterns, and that of course the sparsity pattern has to be square. We do + * not check for symmetry of the sparsity pattern, since this is an + * expensive operation, but rather leave this as the responsibility of + * caller of this function. + * + * After calling this function, the output array will have values between + * zero and @p n_partitions-1 for each node (i.e. row or column of the * matrix). * - * This function will generate an error - * if METIS is not installed unless - * @p n_partitions is one. I.e., you can - * write a program so that it runs in the - * single-processor single-partition case - * without METIS installed, and only - * requires METIS when multiple - * partitions are required. + * This function will generate an error if METIS is not installed unless @p + * n_partitions is one. I.e., you can write a program so that it runs in the + * single-processor single-partition case without METIS installed, and only + * requires METIS when multiple partitions are required. * - * Note that the sparsity pattern itself - * is not changed by calling this - * function. However, you will likely use - * the information generated by calling - * this function to renumber degrees of - * freedom, after which you will of - * course have to regenerate the sparsity - * pattern. + * Note that the sparsity pattern itself is not changed by calling this + * function. However, you will likely use the information generated by + * calling this function to renumber degrees of freedom, after which you + * will of course have to regenerate the sparsity pattern. * - * This function will rarely be called - * separately, since in finite element - * methods you will want to partition the - * mesh, not the matrix. This can be done - * by calling - * @p GridTools::partition_triangulation. + * This function will rarely be called separately, since in finite element + * methods you will want to partition the mesh, not the matrix. This can be + * done by calling @p GridTools::partition_triangulation. */ void partition (const unsigned int n_partitions, std::vector &partition_indices) const; /** - * @deprecated This is kind of an expert mode. Get - * access to the rowstart array, but - * read-only. + * @deprecated This is kind of an expert mode. Get access to the rowstart + * array, but read-only. * - * Use of this function is highly - * deprecated. Use @p row_length and - * @p column_number instead. Also, using - * iterators may get you most of the + * Use of this function is highly deprecated. Use @p row_length and @p + * column_number instead. Also, using iterators may get you most of the * information you may want. * - * Though the return value is declared - * const, you should be aware that it - * may change if you call any nonconstant - * function of objects which operate on - * it. + * Though the return value is declared const, you should be aware + * that it may change if you call any nonconstant function of objects which + * operate on it. * - * You should use this interface very - * carefully and only if you are absolutely - * sure to know what you do. You should - * also note that the structure of these - * arrays may change over time. - * If you change the layout yourself, you - * should also rename this function to - * avoid programs relying on outdated - * information! + * You should use this interface very carefully and only if you are + * absolutely sure to know what you do. You should also note that the + * structure of these arrays may change over time. If you change the layout + * yourself, you should also rename this function to avoid programs relying + * on outdated information! */ inline const std::size_t *get_rowstart_indices () const; /** - * @deprecated. Use @p row_length and - * @p column_number instead. Also, using - * iterators may get you most of the - * information you may want. + * @deprecated. Use @p row_length and @p column_number instead. Also, using + * iterators may get you most of the information you may want. * - * This is kind of an expert mode: get - * access to the colnums array, but + * This is kind of an expert mode: get access to the colnums array, but * readonly. * - * Though the return value is declared - * const, you should be aware that it - * may change if you call any nonconstant - * function of objects which operate on - * it. + * Though the return value is declared const, you should be aware + * that it may change if you call any nonconstant function of objects which + * operate on it. * - * You should use this interface very - * carefully and only if you are absolutely - * sure to know what you do. You should - * also note that the structure of these - * arrays may change over time. - * If you change the layout yourself, you - * should also rename this function to - * avoid programs relying on outdated - * information! + * You should use this interface very carefully and only if you are + * absolutely sure to know what you do. You should also note that the + * structure of these arrays may change over time. If you change the layout + * yourself, you should also rename this function to avoid programs relying + * on outdated information! */ inline const unsigned int *get_column_numbers () const; @@ -1394,8 +996,7 @@ public: * @name Exceptions * @{ */ /** - * You tried to add an element to - * a row, but there was no space left. + * You tried to add an element to a row, but there was no space left. */ DeclException2 (ExcNotEnoughSpace, int, int, @@ -1404,18 +1005,13 @@ public: << "(Maximum number of entries for this row: " << arg2 << "; maybe the matrix is already compressed?)"); /** - * The operation is only allowed - * after the SparsityPattern has - * been set up and compress() was - * called. + * The operation is only allowed after the SparsityPattern has been set up + * and compress() was called. */ DeclException0 (ExcNotCompressed); /** - * This operation changes the - * structure of the - * SparsityPattern and is not - * possible after compress() has - * been called. + * This operation changes the structure of the SparsityPattern and is not + * possible after compress() has been called. */ DeclException0 (ExcMatrixIsCompressed); /** @@ -1423,13 +1019,9 @@ public: */ DeclException0 (ExcInvalidConstructorCall); /** - * This exception is thrown if - * the matrix does not follow the - * convention of storing diagonal - * elements first in row. Refer - * to - * SparityPattern::optimize_diagonal() - * for more information. + * This exception is thrown if the matrix does not follow the convention of + * storing diagonal elements first in row. Refer to + * SparityPattern::optimize_diagonal() for more information. */ DeclException0 (ExcDiagonalNotOptimized); /** @@ -1449,149 +1041,91 @@ public: //@} private: /** - * Maximum number of rows that can - * be stored in the #rowstart array. - * Since reallocation of that array - * only happens if the present one is - * too small, but never when the size - * of this matrix structure shrinks, - * #max_dim might be larger than - * #rows and in this case #rowstart - * has more elements than are used. + * Maximum number of rows that can be stored in the #rowstart array. Since + * reallocation of that array only happens if the present one is too small, + * but never when the size of this matrix structure shrinks, #max_dim might + * be larger than #rows and in this case #rowstart has more elements than + * are used. */ unsigned int max_dim; /** - * Number of rows that this sparsity - * structure shall represent. + * Number of rows that this sparsity structure shall represent. */ unsigned int rows; /** - * Number of columns that this sparsity - * structure shall represent. + * Number of columns that this sparsity structure shall represent. */ unsigned int cols; /** - * Size of the actually allocated array - * #colnums. Here, the same applies as - * for the #rowstart array, i.e. it - * may be larger than the actually used + * Size of the actually allocated array #colnums. Here, the same applies as + * for the #rowstart array, i.e. it may be larger than the actually used * part of the array. */ std::size_t max_vec_len; /** - * Maximum number of elements per - * row. This is set to the value - * given to the reinit() function - * (or to the constructor), or to - * the maximum row length - * computed from the vectors in - * case the more flexible - * constructors or reinit - * versions are called. Its value - * is more or less meaningless - * after compress() has been - * called. + * Maximum number of elements per row. This is set to the value given to the + * reinit() function (or to the constructor), or to the maximum row length + * computed from the vectors in case the more flexible constructors or + * reinit versions are called. Its value is more or less meaningless after + * compress() has been called. */ unsigned int max_row_length; /** - * Array which hold for each row - * which is the first element in - * #colnums belonging to that - * row. Note that the size of the - * array is one larger than the - * number of rows, because the - * last element is used for - * row=#rows, i.e. the - * row past the last used - * one. The value of - * #rowstart[#rows]} equals the - * index of the element past the - * end in #colnums; this way, we - * are able to write loops like - * for (i=rowstart[k]; - * i - * also for the last row. + * Array which hold for each row which is the first element in #colnums + * belonging to that row. Note that the size of the array is one larger than + * the number of rows, because the last element is used for + * row=#rows, i.e. the row past the last used one. The value of + * #rowstart[#rows]} equals the index of the element past the end in + * #colnums; this way, we are able to write loops like for + * (i=rowstart[k]; i also for the last row. * - * Note that the actual size of the - * allocated memory may be larger than - * the region that is used. The actual - * number of elements that was allocated - * is stored in #max_dim. + * Note that the actual size of the allocated memory may be larger than the + * region that is used. The actual number of elements that was allocated is + * stored in #max_dim. */ std::size_t *rowstart; /** - * Array of column numbers. In - * this array, we store for each - * non-zero element its column - * number. The column numbers for - * the elements in row r - * are stored within the index - * range - * #rowstart[r]...#rowstart[r+1]. Therefore - * to find out whether a given - * element (r,c) exists, - * we have to check whether the - * column number c exists - * in the abovementioned range - * within this array. If it - * exists, say at position - * p within this array, - * the value of the respective - * element in the sparse matrix - * will also be at position - * p of the values array - * of that class. - * - * At the beginning, all elements - * of this array are set to - * @p -1 indicating invalid - * (unused) column numbers - * (diagonal elements are preset - * if optimized storage is - * requested, though). Now, if - * nonzero elements are added, - * one column number in the row's - * respective range after the - * other is set to the column - * number of the added - * element. When compress is - * called, unused elements - * (indicated by column numbers - * @p -1) are eliminated by - * copying the column number of - * subsequent rows and the column - * numbers within each row (with - * possible exception of the - * diagonal element) are sorted, - * such that finding whether an - * element exists and determining - * its position can be done by a - * binary search. + * Array of column numbers. In this array, we store for each non-zero + * element its column number. The column numbers for the elements in row + * r are stored within the index range + * #rowstart[r]...#rowstart[r+1]. Therefore to find out + * whether a given element (r,c) exists, we have to check whether the + * column number c exists in the abovementioned range within this + * array. If it exists, say at position p within this array, the + * value of the respective element in the sparse matrix will also be at + * position p of the values array of that class. + * + * At the beginning, all elements of this array are set to @p -1 indicating + * invalid (unused) column numbers (diagonal elements are preset if + * optimized storage is requested, though). Now, if nonzero elements are + * added, one column number in the row's respective range after the other is + * set to the column number of the added element. When compress is called, + * unused elements (indicated by column numbers @p -1) are eliminated by + * copying the column number of subsequent rows and the column numbers + * within each row (with possible exception of the diagonal element) are + * sorted, such that finding whether an element exists and determining its + * position can be done by a binary search. */ unsigned int *colnums; /** - * Store whether the compress() - * function was called for this - * object. + * Store whether the compress() function was called for this object. */ bool compressed; /** - * Is special treatment of - * diagonals enabled? + * Is special treatment of diagonals enabled? */ bool diagonal_optimized; /** - * Make all sparse matrices - * friends of this class. + * Make all sparse matrices friends of this class. */ template friend class SparseMatrix; template friend class ChunkSparseMatrix; @@ -1707,16 +1241,14 @@ namespace SparsityPatternIterators ++a_index; - // if at end of line: cycle until we - // find a row with a nonzero number of + // if at end of line: cycle until we find a row with a nonzero number of // entries while (a_index >= sparsity_pattern->row_length(a_row)) { a_index = 0; ++a_row; - // if we happened to find the end - // of the matrix, then stop here + // if we happened to find the end of the matrix, then stop here if (a_row == sparsity_pattern->n_rows()) break; } @@ -1804,14 +1336,12 @@ inline SparsityPattern::iterator SparsityPattern::begin () const { - // search for the first line with a nonzero - // number of entries + // search for the first line with a nonzero number of entries for (unsigned int r=0; r 0) return iterator(this, r, 0); - // alright, this matrix is completely - // empty. that's strange but ok. simply + // alright, this matrix is completely empty. that's strange but ok. simply // return the end() iterator return end(); } @@ -1846,15 +1376,13 @@ SparsityPattern::end (const unsigned int r) const { Assert (r 0) return iterator(this, i, 0); - // if there is no such line, then take the - // end iterator of the matrix + // if there is no such line, then take the end iterator of the matrix return end(); } @@ -1980,8 +1508,7 @@ inline void SparsityPattern::save (Archive &ar, const unsigned int) const { - // forward to serialization - // function in the base class. + // forward to serialization function in the base class. ar &static_cast(*this); ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed &diagonal_optimized; @@ -1997,8 +1524,7 @@ inline void SparsityPattern::load (Archive &ar, const unsigned int) { - // forward to serialization - // function in the base class. + // forward to serialization function in the base class. ar &static_cast(*this); ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed &diagonal_optimized; @@ -2016,15 +1542,10 @@ inline bool SparsityPattern::operator == (const SparsityPattern &sp2) const { - // it isn't quite necessary to - // compare *all* member - // variables. by only comparing the - // essential ones, we can say that - // two sparsity patterns are equal - // even if one is compressed and - // the other is not (in which case - // some of the member variables are - // not yet set correctly) + // it isn't quite necessary to compare *all* member variables. by only + // comparing the essential ones, we can say that two sparsity patterns are + // equal even if one is compressed and the other is not (in which case some + // of the member variables are not yet set correctly) if (rows != sp2.rows || cols != sp2.cols || compressed != sp2.compressed || @@ -2090,16 +1611,10 @@ SparsityPattern::copy_from (const unsigned int n_rows, Assert (static_cast(std::distance (begin, end)) == n_rows, ExcIteratorRange (std::distance (begin, end), n_rows)); - // first determine row lengths for - // each row. if the matrix is - // quadratic, then we might have to - // add an additional entry for the - // diagonal, if that is not yet - // present. as we have to call - // compress anyway later on, don't - // bother to check whether that - // diagonal entry is in a certain - // row or not + // first determine row lengths for each row. if the matrix is quadratic, + // then we might have to add an additional entry for the diagonal, if that + // is not yet present. as we have to call compress anyway later on, don't + // bother to check whether that diagonal entry is in a certain row or not const bool is_square = optimize_diag && (n_rows == n_cols); std::vector row_lengths; row_lengths.reserve(n_rows); @@ -2109,15 +1624,11 @@ SparsityPattern::copy_from (const unsigned int n_rows, (is_square ? 1 : 0)); reinit (n_rows, n_cols, row_lengths, is_square); - // now enter all the elements into - // the matrix. note that if the - // matrix is quadratic, then we - // already have the diagonal - // element preallocated + // now enter all the elements into the matrix. note that if the matrix is + // quadratic, then we already have the diagonal element preallocated // - // for use in the inner loop, we - // define a typedef to the type of - // the inner iterators + // for use in the inner loop, we define a typedef to the type of the inner + // iterators unsigned int row = 0; typedef typename std::iterator_traits::value_type::const_iterator inner_iterator; for (ForwardIterator i=begin; i!=end; ++i, ++row) @@ -2135,9 +1646,7 @@ SparsityPattern::copy_from (const unsigned int n_rows, }; }; - // finally compress - // everything. this also sorts the - // entries within each row + // finally compress everything. this also sorts the entries within each row compress (); } -- 2.39.5