]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Group the comments in a better way.
authorkronbichler <kronbichler@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 25 Sep 2008 16:18:40 +0000 (16:18 +0000)
committerkronbichler <kronbichler@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 25 Sep 2008 16:18:40 +0000 (16:18 +0000)
git-svn-id: https://svn.dealii.org/trunk@17008 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/lac/include/lac/trilinos_sparse_matrix.h
deal.II/lac/include/lac/trilinos_vector_base.h

index 6639ae82c2c8513a5e6fd45585b7757f6a8885e4..315f6e3d1b5e3e99c32c397428b938151c660f4a 100755 (executable)
@@ -328,6 +328,10 @@ namespace TrilinosWrappers
                                         */
       typedef TrilinosScalar value_type;
       
+/**
+ * @name Constructors and initalization.
+ */
+//@{
                                        /**
                                         * Default constructor. Generates
                                         * an empty (zero-size) matrix.
@@ -445,16 +449,6 @@ namespace TrilinosWrappers
                                         */
       virtual ~SparseMatrix ();
 
-                                      /**
-                                       * Copy the given matrix to this
-                                       * one.
-                                       *
-                                       * The function returns a
-                                       * reference to <tt>*this</tt>.
-                                       */
-      SparseMatrix &
-       copy_from (const SparseMatrix &source);
-
                                        /**
                                         * This function initializes
                                        * the Trilinos matrix with a
@@ -603,6 +597,27 @@ namespace TrilinosWrappers
                   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
@@ -652,28 +667,108 @@ namespace TrilinosWrappers
                                        * compress().
                                        */
       bool is_compressed () const;
+//@}
+/**
+ * @name Information on the matrix
+ */
+//@{
+      
+                                       /**
+                                        * Return the number of rows in
+                                        * this matrix.
+                                        */
+      unsigned int m () const;
 
                                        /**
-                                        * This operator assigns a scalar
-                                        * to a matrix. Since this does
-                                        * usually not make much sense
-                                        * (should we set all matrix
-                                        * entries to this value? Only
-                                        * the nonzero entries of the
-                                        * sparsity pattern?), this
-                                        * operation is only allowed if
-                                        * the actual value to be
-                                        * assigned is zero. This
-                                        * operator only exists to allow
-                                        * for the obvious notation
-                                        * <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.
@@ -711,6 +806,38 @@ namespace TrilinosWrappers
       void add (const unsigned int i,
                 const unsigned int j,
                 const TrilinosScalar value);
+      
+                                       /**
+                                        * Multiply the entire matrix
+                                        * by a fixed factor.
+                                        */
+      SparseMatrix & operator *= (const TrilinosScalar factor);
+    
+                                       /**
+                                        * Divide the entire matrix by
+                                        * a fixed factor.
+                                        */
+      SparseMatrix & operator /= (const TrilinosScalar factor);
+
+                                      /**
+                                       * Copy the given matrix to this
+                                       * one.
+                                       *
+                                       * The function returns a
+                                       * reference to <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
@@ -773,6 +900,18 @@ namespace TrilinosWrappers
       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
@@ -820,128 +959,12 @@ namespace TrilinosWrappers
                                         * quadratic.
                                         */
       TrilinosScalar diag_element (const unsigned int i) const;
-      
-                                       /**
-                                        * Return the number of rows in
-                                        * this matrix.
-                                        */
-      unsigned int m () const;
 
-                                       /**
-                                        * Return the number of columns
-                                        * in this matrix.
-                                        */
-      unsigned int n () const;
-
-                                       /**
-                                        * Return the local dimension
-                                        * of the matrix, i.e. the
-                                        * number of rows stored on the
-                                        * present MPI process. For
-                                        * sequential matrices, this
-                                        * number is the same as m(),
-                                        * but for parallel matrices it
-                                        * may be smaller.
-                                       *
-                                       * To figure out which elements
-                                       * exactly are stored locally,
-                                       * use local_range().
-                                        */
-      unsigned int local_size () const;
-
-                                       /**
-                                       * Return a pair of indices
-                                       * indicating which rows of
-                                       * this matrix are stored
-                                       * locally. The first number is
-                                       * the index of the first row
-                                       * stored, the second the index
-                                       * of the one past the last one
-                                       * that is stored locally. If
-                                       * this is a sequential matrix,
-                                       * then the result will be the
-                                       * pair (0,m()), otherwise it
-                                       * will be a pair (i,i+n),
-                                       * where
-                                       * <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:
@@ -1205,15 +1228,61 @@ namespace TrilinosWrappers
                               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
@@ -1258,30 +1327,13 @@ namespace TrilinosWrappers
                                         */
       const_iterator end (const unsigned int r) const;
 
-                                       /**  
-                                       * Make an in-place transpose
-                                       * of a matrix.
-                                       */
-      void transpose ();
-
-                                       /**  
-                                       * Test whether a matrix is
-                                       * symmetric.  Default
-                                       * tolerance is zero.  TODO:
-                                       * Not implemented.
-                                       */
-      bool is_symmetric (const double tol = 0.0);
-
-                                       /** 
-                                       * Test whether a matrix is
-                                       * Hermitian, i.e. it is the
-                                       * complex conjugate of its
-                                       * transpose.  TODO: Not
-                                       * implemented.
-                                       */
-      bool is_hermitian ();
+//@}
+/**
+ * @name Input/Output
+ */
+//@{
 
-                                       /** 
+                                       /**
                                        * Abstract Trilinos object
                                        * that helps view in ASCII
                                        * other Trilinos
@@ -1308,6 +1360,9 @@ namespace TrilinosWrappers
                                         // object supports it, this should 
                                         // be very easy.
 
+//@}
+                                    /** @addtogroup Exceptions
+                                     * @{ */
                                        /**
                                         * Exception
                                         */
@@ -1349,7 +1404,7 @@ namespace TrilinosWrappers
                      << "/" << arg2 << ")"
                      << " of a sparse matrix, but it appears to not"
                      << " exist in the Trilinos sparsity pattern.");
-
+                                    //@}    
     private:
                                        /**
                                        * Epetra Trilinos
index 5b64b1ca24dccd5526c5ee4b2a6d66e6a6fe5c2f..7bffc8adb8e7cdbff7339060c805eeb817fa966a 100644 (file)
@@ -211,7 +211,7 @@ namespace TrilinosWrappers
                                        */
 
 
-/** 
+/**
  * Base class for the two types of Trilinos vectors, the distributed
  * memory vector MPI::Vector and a localized vector Vector. The latter
  * is designed for use in either serial implementations or as a
@@ -261,6 +261,11 @@ namespace TrilinosWrappers
       typedef internal::VectorReference reference;
       typedef const internal::VectorReference const_reference;
 
+                                      /**
+                                       * @name 1: Basic Object-handling 
+                                       */
+                                      //@{
+
                                        /**
                                         * Default constructor that
                                         * generates an empty (zero size)
@@ -427,6 +432,85 @@ namespace TrilinosWrappers
                                        */
       bool in_local_range (const unsigned int index) const;
 
+                                       /**
+                                        * Return the scalar (inner)
+                                        * product of two vectors. The
+                                        * vectors must have the same
+                                        * size.
+                                        */
+      TrilinosScalar operator * (const VectorBase &vec) const;
+
+                                       /**
+                                        * Return square of the
+                                        * $l_2$-norm.
+                                        */
+      real_type norm_sqr () const;
+
+                                       /**
+                                        * Mean value of the elements of
+                                        * this vector.
+                                        */
+      TrilinosScalar mean_value () const;
+
+                                       /**
+                                        * $l_1$-norm of the vector.  The
+                                        * sum of the absolute values.
+                                        */
+      real_type l1_norm () const;
+
+                                       /**
+                                        * $l_2$-norm of the vector.  The
+                                        * square root of the sum of the
+                                        * squares of the elements.
+                                        */
+      real_type l2_norm () const;
+
+                                       /**
+                                        * $l_p$-norm of the vector. The
+                                        * <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.
@@ -478,6 +562,13 @@ namespace TrilinosWrappers
                                        */
       void set (const std::vector<unsigned int>        &indices,
                const ::dealii::Vector<TrilinosScalar> &values);
+                                      //@}
+
+
+                                      /**
+                                       * @name 3: Modification of vectors
+                                       */
+                                      //@{
 
                                        /**
                                        * This collective set operation
@@ -527,78 +618,6 @@ namespace TrilinosWrappers
                const unsigned int   *indices,
                const TrilinosScalar *values);
 
-                                       /**
-                                        * Return the scalar (inner)
-                                        * product of two vectors. The
-                                        * vectors must have the same
-                                        * size.
-                                        */
-      TrilinosScalar operator * (const VectorBase &vec) const;
-
-                                       /**
-                                        * Return square of the
-                                        * $l_2$-norm.
-                                        */
-      real_type norm_sqr () const;
-
-                                       /**
-                                        * Mean value of the elements of
-                                        * this vector.
-                                        */
-      TrilinosScalar mean_value () const;
-
-                                       /**
-                                        * $l_1$-norm of the vector.  The
-                                        * sum of the absolute values.
-                                        */
-      real_type l1_norm () const;
-
-                                       /**
-                                        * $l_2$-norm of the vector.  The
-                                        * square root of the sum of the
-                                        * squares of the elements.
-                                        */
-      real_type l2_norm () const;
-
-                                       /**
-                                        * $l_p$-norm of the vector. The
-                                        * <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.
@@ -746,13 +765,20 @@ namespace TrilinosWrappers
                                         */
       void ratio (const VectorBase &a,
                  const VectorBase &b);
+                                      //@}
+
 
-                                    /**
-                                     *  Output of vector in
-                                     *  user-defined format in analogy
-                                     *  to the dealii::Vector<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;
 
                                        /**
@@ -807,6 +833,7 @@ namespace TrilinosWrappers
                                        * for this class).
                                        */
       unsigned int memory_consumption () const;
+                                      //@}
 
                                       /**
                                        * Exception

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.