*/
typedef TrilinosScalar value_type;
+/**
+ * @name Constructors and initalization.
+ */
+//@{
/**
* Default constructor. Generates
* an empty (zero-size) matrix.
*/
virtual ~SparseMatrix ();
- /**
- * Copy the given matrix to this
- * one.
- *
- * The function returns a
- * reference to <tt>*this</tt>.
- */
- SparseMatrix &
- copy_from (const SparseMatrix &source);
-
/**
* This function initializes
* the Trilinos matrix with a
const ::dealii::SparseMatrix<double> &dealii_sparse_matrix,
const double drop_tolerance=1e-13);
+ /**
+ * This operator assigns a scalar
+ * to a matrix. Since this does
+ * usually not make much sense
+ * (should we set all matrix
+ * entries to this value? Only
+ * the nonzero entries of the
+ * sparsity pattern?), this
+ * operation is only allowed if
+ * the actual value to be
+ * assigned is zero. This
+ * operator only exists to allow
+ * for the obvious notation
+ * <tt>matrix=0</tt>, which sets
+ * all elements of the matrix to
+ * zero, but keeps the sparsity
+ * pattern previously used.
+ */
+ SparseMatrix &
+ operator = (const double d);
+
/**
* Release all memory and
* return to a state just like
* compress().
*/
bool is_compressed () const;
+//@}
+/**
+ * @name Information on the matrix
+ */
+//@{
+
+ /**
+ * Return the number of rows in
+ * this matrix.
+ */
+ unsigned int m () const;
/**
- * This operator assigns a scalar
- * to a matrix. Since this does
- * usually not make much sense
- * (should we set all matrix
- * entries to this value? Only
- * the nonzero entries of the
- * sparsity pattern?), this
- * operation is only allowed if
- * the actual value to be
- * assigned is zero. This
- * operator only exists to allow
- * for the obvious notation
- * <tt>matrix=0</tt>, which sets
- * all elements of the matrix to
- * zero, but keeps the sparsity
- * pattern previously used.
+ * Return the number of columns
+ * in this matrix.
*/
- SparseMatrix &
- operator = (const double d);
+ unsigned int n () const;
+ /**
+ * Return the local dimension
+ * of the matrix, i.e. the
+ * number of rows stored on the
+ * present MPI process. For
+ * sequential matrices, this
+ * number is the same as m(),
+ * but for parallel matrices it
+ * may be smaller.
+ *
+ * To figure out which elements
+ * exactly are stored locally,
+ * use local_range().
+ */
+ unsigned int local_size () const;
+
+ /**
+ * Return a pair of indices
+ * indicating which rows of
+ * this matrix are stored
+ * locally. The first number is
+ * the index of the first row
+ * stored, the second the index
+ * of the one past the last one
+ * that is stored locally. If
+ * this is a sequential matrix,
+ * then the result will be the
+ * pair (0,m()), otherwise it
+ * will be a pair (i,i+n),
+ * where
+ * <tt>n=local_size()</tt>.
+ */
+ std::pair<unsigned int, unsigned int>
+ local_range () const;
+
+ /**
+ * Return whether @p index is
+ * in the local range or not,
+ * see also local_range().
+ */
+ bool in_local_range (const unsigned int index) const;
+
+ /**
+ * Return the number of nonzero
+ * elements of this matrix.
+ */
+ unsigned int n_nonzero_elements () const;
+
+ /**
+ * Number of entries in a
+ * specific row.
+ */
+ unsigned int row_length (const unsigned int row) const;
+
+ /**
+ * Test whether a matrix is
+ * symmetric. Default
+ * tolerance is zero. TODO:
+ * Not implemented.
+ */
+ bool is_symmetric (const double tol = 0.0) const;
+
+ /**
+ * Test whether a matrix is
+ * Hermitian, i.e. it is the
+ * complex conjugate of its
+ * transpose. TODO: Not
+ * implemented.
+ */
+
+ bool is_hermitian () const;
+ /**
+ * Determine an estimate for the
+ * memory consumption (in bytes)
+ * of this object. Currently not
+ * implemented for this class.
+ */
+ unsigned int memory_consumption () const;
+
+//@}
+/**
+ * @name Modifying entries
+ */
+//@{
/**
* Set the element (<i>i,j</i>)
* to @p value.
void add (const unsigned int i,
const unsigned int j,
const TrilinosScalar value);
+
+ /**
+ * Multiply the entire matrix
+ * by a fixed factor.
+ */
+ SparseMatrix & operator *= (const TrilinosScalar factor);
+
+ /**
+ * Divide the entire matrix by
+ * a fixed factor.
+ */
+ SparseMatrix & operator /= (const TrilinosScalar factor);
+
+ /**
+ * Copy the given matrix to this
+ * one.
+ *
+ * The function returns a
+ * reference to <tt>*this</tt>.
+ */
+ SparseMatrix &
+ copy_from (const SparseMatrix &source);
+
+ /**
+ * 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>.
+ */
+ void add (const TrilinosScalar factor,
+ const SparseMatrix &matrix);
/**
* Remove all elements from
void clear_rows (const std::vector<unsigned int> &rows,
const TrilinosScalar new_diag_value = 0);
+ /**
+ * Make an in-place transpose
+ * of a matrix.
+ */
+ void transpose ();
+
+//@}
+/**
+ * @name Entry Access
+ */
+//@{
+
/**
* Return the value of the
* entry (<i>i,j</i>). This
* quadratic.
*/
TrilinosScalar diag_element (const unsigned int i) const;
-
- /**
- * Return the number of rows in
- * this matrix.
- */
- unsigned int m () const;
- /**
- * Return the number of columns
- * in this matrix.
- */
- unsigned int n () const;
-
- /**
- * Return the local dimension
- * of the matrix, i.e. the
- * number of rows stored on the
- * present MPI process. For
- * sequential matrices, this
- * number is the same as m(),
- * but for parallel matrices it
- * may be smaller.
- *
- * To figure out which elements
- * exactly are stored locally,
- * use local_range().
- */
- unsigned int local_size () const;
-
- /**
- * Return a pair of indices
- * indicating which rows of
- * this matrix are stored
- * locally. The first number is
- * the index of the first row
- * stored, the second the index
- * of the one past the last one
- * that is stored locally. If
- * this is a sequential matrix,
- * then the result will be the
- * pair (0,m()), otherwise it
- * will be a pair (i,i+n),
- * where
- * <tt>n=local_size()</tt>.
- */
- std::pair<unsigned int, unsigned int>
- local_range () const;
-
- /**
- * Return whether @p index is
- * in the local range or not,
- * see also local_range().
- */
- bool in_local_range (const unsigned int index) const;
-
- /**
- * Return the number of nonzero
- * elements of this matrix.
- */
- unsigned int n_nonzero_elements () const;
-
- /**
- * Number of entries in a
- * specific row.
- */
- unsigned int row_length (const unsigned int row) const;
-
- /**
- * Return the
- * <i>l</i><sub>1</sub>-norm of
- * the matrix, that is
- * $|M|_1=
- * \max_{\mathrm{all columns } j}
- * \sum_{\mathrm{all rows } i}
- * |M_{ij}|$, (max. sum
- * of columns). This is the
- * natural matrix norm that is
- * compatible to the l1-norm for
- * vectors, i.e. $|Mv|_1 \leq
- * |M|_1 |v|_1$.
- * (cf. Haemmerlin-Hoffmann:
- * Numerische Mathematik)
- */
- TrilinosScalar l1_norm () const;
-
- /**
- * Return the linfty-norm of the
- * matrix, that is
- * $|M|_\infty=\max_{\mathrm{all
- * rows} i}\sum_{\mathrm{all
- * columns} j} |M_{ij}|$,
- * (max. sum of rows). This is
- * the natural matrix norm that
- * is compatible to the
- * linfty-norm of vectors, i.e.
- * $|Mv|_\infty \leq |M|_\infty
- * |v|_\infty$.
- * (cf. Haemmerlin-Hoffmann:
- * Numerische Mathematik)
- */
- TrilinosScalar linfty_norm () const;
-
- /**
- * Return the frobenius norm of
- * the matrix, i.e. the square
- * root of the sum of squares
- * of all entries in the
- * matrix.
- */
- TrilinosScalar frobenius_norm () const;
-
- /**
- * Multiply the entire matrix
- * by a fixed factor.
- */
- SparseMatrix & operator *= (const TrilinosScalar factor);
-
- /**
- * Divide the entire matrix by
- * a fixed factor.
- */
- SparseMatrix & operator /= (const TrilinosScalar factor);
+//@}
+/**
+ * @name Matrix vector multiplications
+ */
+//@{
/**
* Matrix-vector multiplication:
const VectorBase &x,
const VectorBase &b) const;
- /**
- * 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>.
- */
- void add (const TrilinosScalar factor,
- const SparseMatrix &matrix);
+//@}
+/**
+ * @name Matrix norms
+ */
+//@{
+
+ /**
+ * Return the
+ * <i>l</i><sub>1</sub>-norm of
+ * the matrix, that is
+ * $|M|_1=
+ * \max_{\mathrm{all columns } j}
+ * \sum_{\mathrm{all rows } i}
+ * |M_{ij}|$, (max. sum
+ * of columns). This is the
+ * natural matrix norm that is
+ * compatible to the l1-norm for
+ * vectors, i.e. $|Mv|_1 \leq
+ * |M|_1 |v|_1$.
+ * (cf. Haemmerlin-Hoffmann:
+ * Numerische Mathematik)
+ */
+ TrilinosScalar l1_norm () const;
+
+ /**
+ * Return the linfty-norm of the
+ * matrix, that is
+ * $|M|_\infty=\max_{\mathrm{all
+ * rows} i}\sum_{\mathrm{all
+ * columns} j} |M_{ij}|$,
+ * (max. sum of rows). This is
+ * the natural matrix norm that
+ * is compatible to the
+ * linfty-norm of vectors, i.e.
+ * $|Mv|_\infty \leq |M|_\infty
+ * |v|_\infty$.
+ * (cf. Haemmerlin-Hoffmann:
+ * Numerische Mathematik)
+ */
+ TrilinosScalar linfty_norm () const;
+
+ /**
+ * Return the frobenius norm of
+ * the matrix, i.e. the square
+ * root of the sum of squares
+ * of all entries in the
+ * matrix.
+ */
+ TrilinosScalar frobenius_norm () const;
+
+//@}
+/**
+ * @name Iterators
+ */
+//@{
/**
* STL-like iterator with the
*/
const_iterator end (const unsigned int r) const;
- /**
- * Make an in-place transpose
- * of a matrix.
- */
- void transpose ();
-
- /**
- * Test whether a matrix is
- * symmetric. Default
- * tolerance is zero. TODO:
- * Not implemented.
- */
- bool is_symmetric (const double tol = 0.0);
-
- /**
- * Test whether a matrix is
- * Hermitian, i.e. it is the
- * complex conjugate of its
- * transpose. TODO: Not
- * implemented.
- */
- bool is_hermitian ();
+//@}
+/**
+ * @name Input/Output
+ */
+//@{
- /**
+ /**
* Abstract Trilinos object
* that helps view in ASCII
* other Trilinos
// object supports it, this should
// be very easy.
+//@}
+ /** @addtogroup Exceptions
+ * @{ */
/**
* Exception
*/
<< "/" << arg2 << ")"
<< " of a sparse matrix, but it appears to not"
<< " exist in the Trilinos sparsity pattern.");
-
+ //@}
private:
/**
* Epetra Trilinos
*/
-/**
+/**
* Base class for the two types of Trilinos vectors, the distributed
* memory vector MPI::Vector and a localized vector Vector. The latter
* is designed for use in either serial implementations or as a
typedef internal::VectorReference reference;
typedef const internal::VectorReference const_reference;
+ /**
+ * @name 1: Basic Object-handling
+ */
+ //@{
+
/**
* Default constructor that
* generates an empty (zero size)
*/
bool in_local_range (const unsigned int index) const;
+ /**
+ * Return the scalar (inner)
+ * product of two vectors. The
+ * vectors must have the same
+ * size.
+ */
+ TrilinosScalar operator * (const VectorBase &vec) const;
+
+ /**
+ * Return square of the
+ * $l_2$-norm.
+ */
+ real_type norm_sqr () const;
+
+ /**
+ * Mean value of the elements of
+ * this vector.
+ */
+ TrilinosScalar mean_value () const;
+
+ /**
+ * $l_1$-norm of the vector. The
+ * sum of the absolute values.
+ */
+ real_type l1_norm () const;
+
+ /**
+ * $l_2$-norm of the vector. The
+ * square root of the sum of the
+ * squares of the elements.
+ */
+ real_type l2_norm () const;
+
+ /**
+ * $l_p$-norm of the vector. The
+ * <i>p</i>th root of the sum of
+ * the <i>p</i>th powers of the
+ * absolute values of the
+ * elements.
+ */
+ real_type lp_norm (const TrilinosScalar p) const;
+
+ /**
+ * Maximum absolute value of the
+ * elements.
+ */
+ real_type linfty_norm () const;
+
+ /**
+ * Return whether the vector
+ * contains only elements with
+ * value zero. This function is
+ * mainly for internal
+ * consistency checks and should
+ * seldomly be used when not in
+ * debug mode since it uses quite
+ * some time.
+ */
+ bool all_zero () const;
+
+ /**
+ * Return @p true if the vector
+ * has no negative entries,
+ * i.e. all entries are zero or
+ * positive. This function is
+ * used, for example, to check
+ * whether refinement indicators
+ * are really all positive (or
+ * zero).
+ */
+ bool is_non_negative () const;
+ //@}
+
+
+ /**
+ * @name 2: Data-Access
+ */
+ //@{
+
/**
* Provide access to a given
* element, both read and write.
*/
void set (const std::vector<unsigned int> &indices,
const ::dealii::Vector<TrilinosScalar> &values);
+ //@}
+
+
+ /**
+ * @name 3: Modification of vectors
+ */
+ //@{
/**
* This collective set operation
const unsigned int *indices,
const TrilinosScalar *values);
- /**
- * Return the scalar (inner)
- * product of two vectors. The
- * vectors must have the same
- * size.
- */
- TrilinosScalar operator * (const VectorBase &vec) const;
-
- /**
- * Return square of the
- * $l_2$-norm.
- */
- real_type norm_sqr () const;
-
- /**
- * Mean value of the elements of
- * this vector.
- */
- TrilinosScalar mean_value () const;
-
- /**
- * $l_1$-norm of the vector. The
- * sum of the absolute values.
- */
- real_type l1_norm () const;
-
- /**
- * $l_2$-norm of the vector. The
- * square root of the sum of the
- * squares of the elements.
- */
- real_type l2_norm () const;
-
- /**
- * $l_p$-norm of the vector. The
- * <i>p</i>th root of the sum of
- * the <i>p</i>th powers of the
- * absolute values of the
- * elements.
- */
- real_type lp_norm (const TrilinosScalar p) const;
-
- /**
- * Maximum absolute value of the
- * elements.
- */
- real_type linfty_norm () const;
-
- /**
- * Return whether the vector
- * contains only elements with
- * value zero. This function is
- * mainly for internal
- * consistency checks and should
- * seldomly be used when not in
- * debug mode since it uses quite
- * some time.
- */
- bool all_zero () const;
-
- /**
- * Return @p true if the vector
- * has no negative entries,
- * i.e. all entries are zero or
- * positive. This function is
- * used, for example, to check
- * whether refinement indicators
- * are really all positive (or
- * zero).
- */
- bool is_non_negative () const;
-
/**
* Multiply the entire vector by
* a fixed factor.
*/
void ratio (const VectorBase &a,
const VectorBase &b);
+ //@}
+
- /**
- * Output of vector in
- * user-defined format in analogy
- * to the dealii::Vector<number>
- * class.
- */
+ /**
+ * @name 4: Mixed stuff
+ */
+ //@{
+
+ /**
+ * Output of vector in
+ * user-defined format in analogy
+ * to the dealii::Vector<number>
+ * class.
+ */
void print (const char* format = 0) const;
/**
* for this class).
*/
unsigned int memory_consumption () const;
+ //@}
/**
* Exception