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 <typename number, bool Constness>
class Accessor : public SparsityPatternIterators::Accessor
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<number> &get_matrix () const;
};
/**
- * 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 <typename number>
class Accessor<number,true> : 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<number> MatrixType;
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<number,false> &a);
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;
MatrixType *matrix;
/**
- * Make the advance function of the
- * base class available.
+ * Make the advance function of the base class available.
*/
using SparsityPatternIterators::Accessor::advance;
/**
- * 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 <typename number>
class Accessor<number,false> : 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
- * <tt>number</tt> (i.e., most
- * commonly a double) or to another
- * object of type
- * <tt>Reference</tt>. 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 <tt>number</tt> (i.e., most commonly a
+ * double) or to another object of type <tt>Reference</tt>. 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<number> MatrixType;
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;
MatrixType *matrix;
/**
- * Make the advance function of the
- * base class available.
+ * Make the advance function of the base class available.
*/
using SparsityPatternIterators::Accessor::advance;
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
- * <tt>Constness=false</tt>, this class
- * is for iterators to constant matrices.
+ * Since there is a specialization of this class for
+ * <tt>Constness=false</tt>, this class is for iterators to constant
+ * matrices.
*/
template <typename number, bool Constness>
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<number,Constness>::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<number,false> &i);
const Accessor<number,Constness> *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;
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<number,Constness> accessor;
};
{
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<number>::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
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<number,false>
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;
};
*/
//@{
/**
- * 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
- * <code>std::vector@<SparseMatrix@<double@>
- * @></code>: 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
+ * <code>std::vector@<SparseMatrix@<double@> @></code>: 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<number> &operator = (const SparseMatrix<number> &);
/**
- * 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<number> &
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
- * <tt>matrix=0</tt>, 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 <tt>matrix=0</tt>, 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 ();
*/
//@{
/**
- * 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
- * <tt>threshold</tt> 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 <tt>threshold</tt> 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 <tt>const</tt>, 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 <tt>const</tt>, 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;
*/
//@{
/**
- * Set the element (<i>i,j</i>)
- * to <tt>value</tt>. Throws an
- * error if the entry does not
- * exist or if <tt>value</tt> is
- * not a finite number. Still, it
- * is allowed to store zero
- * values in non-existent fields.
+ * Set the element (<i>i,j</i>) to <tt>value</tt>. Throws an error if the
+ * entry does not exist or if <tt>value</tt> 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
- * <tt>indices</tt>. In other words,
- * this function writes the elements
- * in <tt>full_matrix</tt> into the
- * calling matrix, using the
- * local-to-global indexing specified
- * by <tt>indices</tt> 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
- * <tt>elide_zero_values</tt> 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
- * <tt>false</tt>, i.e., even zero
- * values are treated.
+ * Set all elements given in a FullMatrix into the sparse matrix locations
+ * given by <tt>indices</tt>. In other words, this function writes the
+ * elements in <tt>full_matrix</tt> into the calling matrix, using the
+ * local-to-global indexing specified by <tt>indices</tt> 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 <tt>elide_zero_values</tt> 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 <tt>false</tt>, i.e., even zero values are
+ * treated.
*/
template <typename number2>
void set (const std::vector<unsigned int> &indices,
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 <typename number2>
void set (const std::vector<unsigned int> &row_indices,
const bool elide_zero_values = false);
/**
- * Set several elements in the
- * specified row of the matrix with
- * column indices as given by
- * <tt>col_indices</tt> to the
- * respective value.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> 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
- * <tt>false</tt>, i.e., even zero
- * values are treated.
+ * The optional parameter <tt>elide_zero_values</tt> 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 <tt>false</tt>, i.e., even zero values are
+ * treated.
*/
template <typename number2>
void set (const unsigned int row,
const bool elide_zero_values = false);
/**
- * Set several elements to values
- * given by <tt>values</tt> in a
- * given row in columns given by
- * col_indices into the sparse
- * matrix.
+ * Set several elements to values given by <tt>values</tt> in a given row in
+ * columns given by col_indices into the sparse matrix.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be inserted anyway
- * or they should be filtered
- * away. The default value is
- * <tt>false</tt>, i.e., even zero
- * values are inserted/replaced.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be inserted anyway or they should be filtered
+ * away. The default value is <tt>false</tt>, i.e., even zero values are
+ * inserted/replaced.
*/
template <typename number2>
void set (const unsigned int row,
const bool elide_zero_values = false);
/**
- * Add <tt>value</tt> to the
- * element (<i>i,j</i>). Throws
- * an error if the entry does not
- * exist or if <tt>value</tt> is
- * not a finite number. Still, it
- * is allowed to store zero
- * values in non-existent fields.
+ * Add <tt>value</tt> to the element (<i>i,j</i>). Throws an error if the
+ * entry does not exist or if <tt>value</tt> 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<double> into sparse
- * matrix locations given by
- * <tt>indices</tt>. In other words,
- * this function adds the elements in
- * <tt>full_matrix</tt> to the
- * respective entries in calling
- * matrix, using the local-to-global
- * indexing specified by
- * <tt>indices</tt> 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
- * <tt>elide_zero_values</tt> 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 <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * Add all elements given in a FullMatrix<double> into sparse matrix
+ * locations given by <tt>indices</tt>. In other words, this function adds
+ * the elements in <tt>full_matrix</tt> to the respective entries in calling
+ * matrix, using the local-to-global indexing specified by <tt>indices</tt>
+ * 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 <tt>elide_zero_values</tt> 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 <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number2>
void add (const std::vector<unsigned int> &indices,
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 <typename number2>
void add (const std::vector<unsigned int> &row_indices,
const bool elide_zero_values = true);
/**
- * Set several elements in the
- * specified row of the matrix with
- * column indices as given by
- * <tt>col_indices</tt> to the
- * respective value.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> 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 <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> 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 <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number2>
void add (const unsigned int row,
const bool elide_zero_values = true);
/**
- * Add an array of values given by
- * <tt>values</tt> in the given
- * global matrix row at columns
- * specified by col_indices in the
- * sparse matrix.
+ * Add an array of values given by <tt>values</tt> in the given global
+ * matrix row at columns specified by col_indices in the sparse matrix.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> 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 <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> 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 <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number2>
void add (const unsigned int row,
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 <tt>operator =</tt>,
- * 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
- * <tt>*this</tt>.
+ * 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
+ * <tt>operator =</tt>, 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 <tt>*this</tt>.
*/
template <typename somenumber>
SparseMatrix<number> &
copy_from (const SparseMatrix<somenumber> &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 <tt>std::pair<unsigned
- * int, value</tt>, where
- * <tt>value</tt> needs to be
- * convertible to the element
- * type of this class, as
- * specified by the
- * <tt>number</tt> 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 <tt>std::pair<unsigned int,
+ * value</tt>, where <tt>value</tt> needs to be convertible to the element
+ * type of this class, as specified by the <tt>number</tt> 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 <typename ForwardIterator>
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 <typename somenumber>
void copy_from (const FullMatrix<somenumber> &matrix);
/**
- * Add <tt>matrix</tt> scaled by
- * <tt>factor</tt> to this matrix,
- * i.e. the matrix <tt>factor*matrix</tt>
- * is added to <tt>this</tt>. 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 <tt>matrix</tt> scaled by <tt>factor</tt> to this matrix, i.e. the
+ * matrix <tt>factor*matrix</tt> is added to <tt>this</tt>. 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 <typename somenumber>
//@{
/**
- * Return the value of the entry
- * (<i>i,j</i>). 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>i,j</i>). 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>i,j</i>). 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>i,j</i>). 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 <i>i</i>th
- * row. This function throws an
- * error if the matrix is not
- * quadratic (see
+ * Return the main diagonal element in the <i>i</i>th 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 <tt>index</tt>th entry in
- * <tt>row</tt>. Here,
- * <tt>index</tt> 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
+ * <tt>index</tt>th entry in <tt>row</tt>. Here, <tt>index</tt> 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 <i>i</i>th 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 <i>i</i>th 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);
*/
//@{
/**
- * Matrix-vector multiplication:
- * let <i>dst = M*src</i> with
- * <i>M</i> being this matrix.
+ * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i> 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 <class OutVector, class InVector>
void vmult (OutVector &dst,
const InVector &src) const;
/**
- * Matrix-vector multiplication:
- * let <i>dst = M<sup>T</sup>*src</i> with
- * <i>M</i> 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 <i>dst = M<sup>T</sup>*src</i> with
+ * <i>M</i> 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 <class OutVector, class InVector>
void Tvmult (OutVector &dst,
const InVector &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add
- * <i>M*src</i> on <i>dst</i>
- * with <i>M</i> being this
- * matrix.
+ * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i> with
+ * <i>M</i> 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 <class OutVector, class InVector>
void vmult_add (OutVector &dst,
const InVector &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add
- * <i>M<sup>T</sup>*src</i> to
- * <i>dst</i> with <i>M</i> being
- * this matrix. This function
- * does the same as vmult_add()
- * but takes the transposed
- * matrix.
+ * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
+ * <i>dst</i> with <i>M</i> 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 <class OutVector, class InVector>
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 <typename somenumber>
somenumber matrix_norm_square (const Vector<somenumber> &v) const;
/**
- * Compute the matrix scalar
- * product $\left(u,Mv\right)$.
+ * Compute the matrix scalar product $\left(u,Mv\right)$.
*/
template <typename somenumber>
somenumber matrix_scalar_product (const Vector<somenumber> &u,
const Vector<somenumber> &v) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to be
- * <i>r=b-Mx</i>. Write the
- * residual into
- * <tt>dst</tt>. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into <tt>dst</tt>. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned.
*
- * Source <i>x</i> and destination
- * <i>dst</i> must not be the same
- * vector.
+ * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
*/
template <typename somenumber>
somenumber residual (Vector<somenumber> &dst,
const Vector<somenumber> &b) const;
/**
- * Perform the matrix-matrix
- * multiplication <tt>C = A * B</tt>,
- * or, if an optional vector argument
- * is given, <tt>C = A * diag(V) *
- * B</tt>, where <tt>diag(V)</tt>
- * defines a diagonal matrix with the
- * vector entries.
- *
- * This function assumes that the
- * calling matrix <tt>A</tt> and
- * <tt>B</tt> have compatible
- * sizes. The size of <tt>C</tt> 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
- * <tt>rebuild_sparsity_pattern</tt>
- * that can be used to bypass the
- * creation of a new sparsity pattern
- * and instead uses the sparsity
- * pattern stored in <tt>C</tt>. 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 <tt>C = A * B</tt>, or, if an
+ * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
+ * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
+ *
+ * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+ * have compatible sizes. The size of <tt>C</tt> 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 <tt>rebuild_sparsity_pattern</tt> that can be
+ * used to bypass the creation of a new sparsity pattern and instead uses
+ * the sparsity pattern stored in <tt>C</tt>. 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 <typename numberB, typename numberC>
void mmult (SparseMatrix<numberC> &C,
const bool rebuild_sparsity_pattern = true) const;
/**
- * Perform the matrix-matrix
- * multiplication with the transpose of
- * <tt>this</tt>, i.e., <tt>C =
- * A<sup>T</sup> * B</tt>, or, if an
- * optional vector argument is given,
- * <tt>C = A<sup>T</sup> * diag(V) *
- * B</tt>, where <tt>diag(V)</tt>
- * defines a diagonal matrix with the
- * vector entries.
- *
- * This function assumes that the
- * calling matrix <tt>A</tt> and
- * <tt>B</tt> have compatible
- * sizes. The size of <tt>C</tt> 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
- * <tt>rebuild_sparsity_pattern</tt>
- * that can be used to bypass the
- * creation of a new sparsity pattern
- * and instead uses the sparsity
- * pattern stored in <tt>C</tt>. 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
+ * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
+ * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>, where
+ * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
+ *
+ * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+ * have compatible sizes. The size of <tt>C</tt> 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 <tt>rebuild_sparsity_pattern</tt> that can be
+ * used to bypass the creation of a new sparsity pattern and instead uses
+ * the sparsity pattern stored in <tt>C</tt>. 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 <typename numberB, typename numberC>
void Tmmult (SparseMatrix<numberC> &C,
//@{
/**
- * 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;
//@}
//@{
/**
- * Apply the Jacobi
- * preconditioner, which
- * multiplies every element of
- * the <tt>src</tt> vector by the
- * inverse of the respective
- * diagonal element and
- * multiplies the result with the
- * relaxation factor <tt>omega</tt>.
+ * Apply the Jacobi preconditioner, which multiplies every element of the
+ * <tt>src</tt> vector by the inverse of the respective diagonal element and
+ * multiplies the result with the relaxation factor <tt>omega</tt>.
*/
template <typename somenumber>
void precondition_Jacobi (Vector<somenumber> &dst,
const number omega = 1.) const;
/**
- * Apply SSOR preconditioning to
- * <tt>src</tt> with damping
- * <tt>omega</tt>. The optional
- * argument
- * <tt>pos_right_of_diagonal</tt> 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 <tt>src</tt> with damping
+ * <tt>omega</tt>. The optional argument <tt>pos_right_of_diagonal</tt> is
+ * supposed to provide an array where each entry specifies the position just
+ * right of the diagonal in the global array of nonzeros.
*/
template <typename somenumber>
void precondition_SSOR (Vector<somenumber> &dst,
const std::vector<unsigned int> &pos_right_of_diagonal=std::vector<unsigned int>()) const;
/**
- * Apply SOR preconditioning
- * matrix to <tt>src</tt>.
+ * Apply SOR preconditioning matrix to <tt>src</tt>.
*/
template <typename somenumber>
void precondition_SOR (Vector<somenumber> &dst,
const number om = 1.) const;
/**
- * Apply transpose SOR
- * preconditioning matrix to
- * <tt>src</tt>.
+ * Apply transpose SOR preconditioning matrix to <tt>src</tt>.
*/
template <typename somenumber>
void precondition_TSOR (Vector<somenumber> &dst,
const number om = 1.) const;
/**
- * Perform SSOR preconditioning
- * in-place. Apply the
- * preconditioner matrix without
- * copying to a second vector.
- * <tt>omega</tt> is the relaxation
+ * Perform SSOR preconditioning in-place. Apply the preconditioner matrix
+ * without copying to a second vector. <tt>omega</tt> is the relaxation
* parameter.
*/
template <typename somenumber>
const number omega = 1.) const;
/**
- * Perform an SOR preconditioning
- * in-place. <tt>omega</tt> is
- * the relaxation parameter.
+ * Perform an SOR preconditioning in-place. <tt>omega</tt> is the
+ * relaxation parameter.
*/
template <typename somenumber>
void SOR (Vector<somenumber> &v,
const number om = 1.) const;
/**
- * Perform a transpose SOR
- * preconditioning in-place.
- * <tt>omega</tt> is the
+ * Perform a transpose SOR preconditioning in-place. <tt>omega</tt> is the
* relaxation parameter.
*/
template <typename somenumber>
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 <tt>permutation</tt>,
- * that is, first the row
- * <tt>permutation[0]</tt>, then
- * <tt>permutation[1]</tt> 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
+ * <tt>permutation</tt>, that is, first the row <tt>permutation[0]</tt>,
+ * then <tt>permutation[1]</tt> and so on. For efficiency reasons, the
+ * permutation as well as its inverse are required.
*
- * <tt>omega</tt> is the
- * relaxation parameter.
+ * <tt>omega</tt> is the relaxation parameter.
*/
template <typename somenumber>
void PSOR (Vector<somenumber> &v,
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
- * <tt>permutation</tt>, that is,
- * first the row
- * <tt>permutation[m()-1]</tt>,
- * then
- * <tt>permutation[m()-2]</tt>
- * 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
+ * <tt>permutation</tt>, that is, first the row <tt>permutation[m()-1]</tt>,
+ * then <tt>permutation[m()-2]</tt> and so on. For efficiency reasons, the
+ * permutation as well as its inverse are required.
*
- * <tt>omega</tt> is the
- * relaxation parameter.
+ * <tt>omega</tt> is the relaxation parameter.
*/
template <typename somenumber>
void TPSOR (Vector<somenumber> &v,
const number om = 1.) const;
/**
- * Do one Jacobi step on
- * <tt>v</tt>. Performs a direct
- * Jacobi step with right hand
- * side <tt>b</tt>. This function
- * will need an auxiliary vector,
- * which is acquired from
- * GrowingVectorMemory.
+ * Do one Jacobi step on <tt>v</tt>. Performs a direct Jacobi step with
+ * right hand side <tt>b</tt>. This function will need an auxiliary vector,
+ * which is acquired from GrowingVectorMemory.
*/
template <typename somenumber>
void Jacobi_step (Vector<somenumber> &v,
const number om = 1.) const;
/**
- * Do one SOR step on <tt>v</tt>.
- * Performs a direct SOR step
- * with right hand side
- * <tt>b</tt>.
+ * Do one SOR step on <tt>v</tt>. Performs a direct SOR step with right
+ * hand side <tt>b</tt>.
*/
template <typename somenumber>
void SOR_step (Vector<somenumber> &v,
const number om = 1.) const;
/**
- * Do one adjoint SOR step on
- * <tt>v</tt>. Performs a direct
- * TSOR step with right hand side
- * <tt>b</tt>.
+ * Do one adjoint SOR step on <tt>v</tt>. Performs a direct TSOR step with
+ * right hand side <tt>b</tt>.
*/
template <typename somenumber>
void TSOR_step (Vector<somenumber> &v,
const number om = 1.) const;
/**
- * Do one SSOR step on
- * <tt>v</tt>. Performs a direct
- * SSOR step with right hand side
- * <tt>b</tt> by performing TSOR
- * after SOR.
+ * Do one SSOR step on <tt>v</tt>. Performs a direct SSOR step with right
+ * hand side <tt>b</tt> by performing TSOR after SOR.
*/
template <typename somenumber>
void SSOR_step (Vector<somenumber> &v,
//@{
/**
- * 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 <tt>r</tt>. This is the version
- * for constant matrices.
+ * STL-like iterator with the first entry of row <tt>r</tt>. 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
- * <tt>end(r)</tt>. 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
+ * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
* that case.
*/
const_iterator begin (const unsigned int r) const;
/**
- * Final iterator of row <tt>r</tt>. 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 <tt>r</tt>. 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 <tt>r</tt>. This is the version
- * for non-constant matrices.
+ * STL-like iterator with the first entry of row <tt>r</tt>. 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
- * <tt>end(r)</tt>. 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
+ * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
* that case.
*/
iterator begin (const unsigned int r);
/**
- * Final iterator of row <tt>r</tt>. 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 <tt>r</tt>. 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);
//@}
//@{
/**
- * Print the matrix to the given
- * stream, using the format
- * <tt>(row,column) value</tt>,
- * 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 <tt>(row,column)
+ * value</tt>, 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 <class STREAM>
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: <tt>precision</tt> and
- * <tt>scientific</tt> are used
- * to determine the number
- * format, where <tt>scientific =
- * false</tt> means fixed point
- * notation. A zero entry for
- * <tt>width</tt> 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 <b>large</b> 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:
+ * <tt>precision</tt> and <tt>scientific</tt> are used to determine the
+ * number format, where <tt>scientific = false</tt> means fixed point
+ * notation. A zero entry for <tt>width</tt> 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 <b>large</b> amounts of output if
+ * applied to a large matrix!
*/
void print_formatted (std::ostream &out,
const unsigned int precision = 3,
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);
//@}
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<const SparsityPattern,SparseMatrix<number> > 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 <typename somenumber> friend class SparseMatrix;
template <typename somenumber> friend class SparseLUDecomposition;
template <typename> friend class SparseILU;
/**
- * To allow it calling private
- * prepare_add() and
- * prepare_set().
+ * To allow it calling private prepare_add() and prepare_set().
*/
template <typename> friend class BlockMatrixBase;
};
}
-// 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 <typename number>
inline
void
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) ||
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) ||
Assert (cols->optimize_diagonal(), ExcNotQuadratic());
Assert (i<m(), ExcInvalidIndex1(i));
- // Use that the first element in each
- // row of a quadratic matrix is the main
+ // Use that the first element in each row of a quadratic matrix is the main
// diagonal
return val[cols->rowstart[i]];
}
Assert (cols->optimize_diagonal(), ExcNotQuadratic());
Assert (i<m(), ExcInvalidIndex1(i));
- // Use that the first element in each
- // row of a quadratic matrix is the main
+ // Use that the first element in each row of a quadratic matrix is the main
// diagonal
return val[cols->rowstart[i]];
}
Assert (static_cast<unsigned int>(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<ForwardIterator>::value_type::const_iterator inner_iterator;
unsigned int row=0;
for (ForwardIterator i=begin; i!=end; ++i, ++row)
typename SparseMatrix<number>::const_iterator
SparseMatrix<number>::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<m(); ++r)
if (cols->row_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();
}
typename SparseMatrix<number>::iterator
SparseMatrix<number>::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; r<m(); ++r)
if (cols->row_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();
}
{
Assert (r<m(), ExcIndexRange(r,0,m()));
- // place the iterator on the first entry
- // past this line, or at the end of the
- // matrix
+ // place the iterator on the first entry past this line, or at the end of
+ // the matrix
for (unsigned int i=r+1; i<m(); ++i)
if (cols->row_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();
}
{
Assert (r<m(), ExcIndexRange(r,0,m()));
- // place the iterator on the first entry
- // past this line, or at the end of the
- // matrix
+ // place the iterator on the first entry past this line, or at the end of
+ // the matrix
for (unsigned int i=r+1; i<m(); ++i)
if (cols->row_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();
}
namespace SparsityPatternTools
{
/**
- * Helper function to get the
- * column index from a
- * dereferenced iterator in the
- * copy_from() function, if
- * the inner iterator type points
- * to plain unsigned integers.
+ * Helper function to get the column index from a dereferenced iterator in
+ * the copy_from() function, if the inner iterator type points to plain
+ * unsigned integers.
*/
unsigned int
get_column_index_from_iterator (const unsigned int i);
/**
- * Helper function to get the
- * column index from a
- * dereferenced iterator in the
- * copy_from() function, if
- * the inner iterator type points
- * to pairs of unsigned integers
- * and some other value.
+ * Helper function to get the column index from a dereferenced iterator in
+ * the copy_from() function, if the inner iterator type points to pairs of
+ * unsigned integers and some other value.
*/
template <typename value>
unsigned int
get_column_index_from_iterator (const std::pair<unsigned int, value> &i);
/**
- * Likewise, but sometimes needed
- * for certain types of
- * containers that make the first
- * element of the pair constant
- * (such as <tt>std::map</tt>).
+ * Likewise, but sometimes needed for certain types of containers that
+ * make the first element of the pair constant (such as
+ * <tt>std::map</tt>).
*/
template <typename value>
unsigned int
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;
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 ();
/**
- * 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,
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;
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;
};
{
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
/**
- * 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;
*/
// @{
/**
- * 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
- * <tt>v.push_back
- * (SparsityPattern());</tt>,
- * with <tt>v</tt> 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 <tt>v.push_back (SparsityPattern());</tt>, with
+ * <tt>v</tt> 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,
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,
const bool optimize_diagonal = true);
/**
- * Initialize a quadratic matrix
- * of dimension <tt>n</tt> with
- * at most <tt>max_per_row</tt>
- * nonzero entries per row.
+ * Initialize a quadratic matrix of dimension <tt>n</tt> with at most
+ * <tt>max_per_row</tt> 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);
* 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<unsigned int> &row_lengths,
/**
* 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
- * <tt>extra_off_diagonals</tt>
- * side-diagonals is provided on both
- * sides of the main diagonal.
- *
- * <tt>max_per_row</tt> 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 <tt>original</tt> 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
- * <tt>original</tt> 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
- * <tt>original</tt> 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 <tt>extra_off_diagonals</tt>
+ * side-diagonals is provided on both sides of the main diagonal.
+ *
+ * <tt>max_per_row</tt> 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 <tt>original</tt>
+ * 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
+ * <tt>original</tt> 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 <tt>original</tt> 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,
~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
- * <tt>m </tt>rows and <tt>n</tt> columns,
- * with at most <tt>max_per_row</tt>
+ * Reallocate memory and set up data structures for a new matrix with <tt>m
+ * </tt>rows and <tt>n</tt> columns, with at most <tt>max_per_row</tt>
* nonzero entries per row.
*
- * This function simply maps its
- * operations to the other
- * <tt>reinit</tt> function.
+ * This function simply maps its operations to the other <tt>reinit</tt>
+ * function.
*/
void reinit (const unsigned int m,
const unsigned int n,
const bool optimize_diagonal = true);
/**
- * Reallocate memory for a matrix
- * of size <tt>m x n</tt>. The
- * number of entries for each row
- * is taken from the array
- * <tt>row_lengths</tt> which has to
- * give this number of each row
- * <tt>i=1...m</tt>.
+ * Reallocate memory for a matrix of size <tt>m x n</tt>. The number of
+ * entries for each row is taken from the array <tt>row_lengths</tt> which
+ * has to give this number of each row <tt>i=1...m</tt>.
*
- * If <tt>m*n==0</tt> 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 <tt>m*n==0</tt> 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,
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,
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
- * <tt>std::vector</tt>,
- * <tt>std::list</tt>, 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 <tt>operator*</tt> or
- * <tt>operator-></tt> to one of these
- * iterators) must be a container
- * itself that provides functions
- * <tt>begin</tt> and <tt>end</tt>
- * 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 <tt>std::vector</tt>, <tt>std::list</tt>, 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 <tt>operator*</tt> or <tt>operator-></tt> to one of
+ * these iterators) must be a container itself that provides functions
+ * <tt>begin</tt> and <tt>end</tt> 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<std::vector<unsigned int> > column_indices (n_rows);
* for (unsigned int row=0; row<n_rows; ++row)
* column_indices.end());
* @endcode
*
- * Note that this example works
- * since the iterators
- * dereferenced yield containers
- * with functions <tt>begin</tt> and
- * <tt>end</tt> (namely
- * <tt>std::vector</tt>s), and the
- * inner iterators dereferenced
- * yield unsigned integers as
- * column indices. Note that we
- * could have replaced each of
- * the two <tt>std::vector</tt>
- * occurrences by <tt>std::list</tt>,
- * and the inner one by
- * <tt>std::set</tt> as well.
+ * Note that this example works since the iterators dereferenced yield
+ * containers with functions <tt>begin</tt> and <tt>end</tt> (namely
+ * <tt>std::vector</tt>s), and the inner iterators dereferenced yield
+ * unsigned integers as column indices. Note that we could have replaced
+ * each of the two <tt>std::vector</tt> occurrences by <tt>std::list</tt>,
+ * and the inner one by <tt>std::set</tt> 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<std::map<unsigned int,double> > entries (n_rows);
* for (unsigned int row=0; row<n_rows; ++row)
* column_indices.end());
* @endcode
*
- * 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 <tt>std::vector</tt>
- * could be replaced by
- * <tt>std::list</tt>, and the inner
- * <tt>std::map<unsigned int,double></tt>
- * could be replaced by
- * <tt>std::vector<std::pair<unsigned int,double> ></tt>,
- * 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 <tt>std::vector</tt> could
+ * be replaced by <tt>std::list</tt>, and the inner <tt>std::map<unsigned
+ * int,double></tt> could be replaced by <tt>std::vector<std::pair<unsigned
+ * int,double> ></tt>, or a list or set of such pairs, as they all return
+ * iterators that point to such pairs.
*/
template <typename ForwardIterator>
void copy_from (const unsigned int n_rows,
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 <typename CompressedSparsityType>
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 <typename number>
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 <typename ForwardIterator>
void add_entries (const unsigned int row,
// @{
/**
- * 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;
inline iterator end () const;
/**
- * STL-like iterator with the first entry
- * of row <tt>r</tt>.
+ * STL-like iterator with the first entry of row <tt>r</tt>.
*
- * Note that if the given row is empty,
- * i.e. does not contain any nonzero
- * entries, then the iterator returned by
- * this function equals
- * <tt>end(r)</tt>. 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
+ * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
* that case.
*/
inline iterator begin (const unsigned int r) const;
/**
- * Final iterator of row <tt>r</tt>. 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 <tt>r</tt>. 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 <tt>r</tt>.
+ * STL-like iterator with the first entry of row <tt>r</tt>.
*
- * Note that if the given row is empty,
- * i.e. does not contain any nonzero
- * entries, then the iterator returned by
- * this function equals
- * <tt>end(r)</tt>. 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
+ * <tt>end(r)</tt>. 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 <tt>r</tt>. 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 <tt>r</tt>. 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;
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;
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 <tt>true</tt> 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 <tt>true</tt> 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 <tt>false</tt> 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 <tt>false</tt> 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;
*/
// @{
/**
- * Return the index of the matrix
- * element with row number <tt>i</tt>
- * and column number <tt>j</tt>. If
- * the matrix element is not a
- * nonzero one, return
- * SparsityPattern::invalid_entry.
+ * Return the index of the matrix element with row number <tt>i</tt> and
+ * column number <tt>j</tt>. 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 <tt>m</tt> is the number of
- * entries in <tt>row</tt>, then the
- * complexity of this function is
- * <i>log(m)</i> if the sparsity
- * pattern is compressed.
+ * If <tt>m</tt> is the number of entries in <tt>row</tt>, then the
+ * complexity of this function is <i>log(m)</i> 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 <tt>N</tt> is the number of
- * rows of this matrix, then the
- * complexity of this function is
- * <i>log(N)</i>.
+ * If <tt>N</tt> is the number of rows of this matrix, then the complexity
+ * of this function is <i>log(N)</i>.
*/
std::pair<unsigned int, unsigned int>
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 <tt>j</tt>.
+ * 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
+ * <tt>j</tt>.
*/
unsigned int row_position(const unsigned int i,
const unsigned int j) const;
/**
- * Access to column number field.
- * Return the column number of
- * the <tt>index</tt>th entry in
- * <tt>row</tt>. 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
+ * <tt>index</tt>th entry in <tt>row</tt>. Note that if diagonal elements
+ * are optimized, the first element in each row is the diagonal element,
* i.e. <tt>column_number(row,0)==row</tt>.
*
- * If the sparsity pattern is
- * already compressed, then
- * (except for the diagonal
- * element), the entries are
- * sorted by columns,
- * i.e. <tt>column_number(row,i)</tt>
- * <tt><</tt> <tt>column_number(row,i+1)</tt>.
+ * If the sparsity pattern is already compressed, then (except for the
+ * diagonal element), the entries are sorted by columns,
+ * i.e. <tt>column_number(row,i)</tt> <tt><</tt>
+ * <tt>column_number(row,i+1)</tt>.
*/
unsigned int column_number (const unsigned int row,
const unsigned int index) 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.
+ * 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
- * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
- * is the row number and
- * <i>jn</i> are the allocated
- * columns in this row.
+ * Print the sparsity of the matrix. The output consists of one line per row
+ * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+ * <i>jn</i> are the allocated columns in this row.
*/
void print (std::ostream &out) const;
/**
- * Print the sparsity of the matrix
- * in a format that <tt>gnuplot</tt> understands
- * and which can be used to plot the
- * sparsity pattern in a graphical
- * way. The format consists of pairs
- * <tt>i j</tt> 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
- * <tt>(0,0)</tt> element is in the top left
- * rather than in the bottom left
- * corner.
+ * Print the sparsity of the matrix in a format that <tt>gnuplot</tt>
+ * understands and which can be used to plot the sparsity pattern in a
+ * graphical way. The format consists of pairs <tt>i j</tt> 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 <tt>(0,0)</tt>
+ * 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
- * <tt>plot</tt> command.
+ * Print the sparsity pattern in gnuplot by setting the data style to dots
+ * or points and use the <tt>plot</tt> 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 <class Archive>
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 <class Archive>
void load (Archive &ar, const unsigned int version);
*/
// @{
/**
- * @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<unsigned int> &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
- * <tt>const</tt>, 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 <tt>const</tt>, 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
- * <tt>const</tt>, 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 <tt>const</tt>, 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;
* @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,
<< "(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);
/**
*/
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);
/**
//@}
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
- * <tt>row</tt>=#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
- * <tt>for (i=rowstart[k];
- * i<rowstart[k+1]; ++i)</tt>
- * 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
+ * <tt>row</tt>=#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 <tt>for
+ * (i=rowstart[k]; i<rowstart[k+1]; ++i)</tt> 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 <i>r</i>
- * are stored within the index
- * range
- * #rowstart[<i>r</i>]...#rowstart[<i>r+1</i>]. Therefore
- * to find out whether a given
- * element (<i>r,c</i>) exists,
- * we have to check whether the
- * column number <i>c</i> exists
- * in the abovementioned range
- * within this array. If it
- * exists, say at position
- * <i>p</i> within this array,
- * the value of the respective
- * element in the sparse matrix
- * will also be at position
- * <i>p</i> 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
+ * <i>r</i> are stored within the index range
+ * #rowstart[<i>r</i>]...#rowstart[<i>r+1</i>]. Therefore to find out
+ * whether a given element (<i>r,c</i>) exists, we have to check whether the
+ * column number <i>c</i> exists in the abovementioned range within this
+ * array. If it exists, say at position <i>p</i> within this array, the
+ * value of the respective element in the sparse matrix will also be at
+ * position <i>p</i> 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 <typename number> friend class SparseMatrix;
template <typename number> friend class ChunkSparseMatrix;
++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;
}
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<n_rows(); ++r)
if (row_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();
}
{
Assert (r<n_rows(), ExcIndexRange(r,0,n_rows()));
- // place the iterator on the first entry
- // past this line, or at the end of the
- // matrix
+ // place the iterator on the first entry past this line, or at the end of
+ // the matrix
for (unsigned int i=r+1; i<n_rows(); ++i)
if (row_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();
}
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<const Subscriptor &>(*this);
ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed &diagonal_optimized;
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<Subscriptor &>(*this);
ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed &diagonal_optimized;
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 ||
Assert (static_cast<unsigned int>(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<unsigned int> row_lengths;
row_lengths.reserve(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<ForwardIterator>::value_type::const_iterator inner_iterator;
for (ForwardIterator i=begin; i!=end; ++i, ++row)
};
};
- // finally compress
- // everything. this also sorts the
- // entries within each row
+ // finally compress everything. this also sorts the entries within each row
compress ();
}
projects / dealii-svn.git / commitdiff