]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Update documentation of SparseMatrixEZ. 5186/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Mon, 2 Oct 2017 22:16:50 +0000 (16:16 -0600)
committerWolfgang Bangerth <bangerth@colostate.edu>
Mon, 2 Oct 2017 22:16:50 +0000 (16:16 -0600)
include/deal.II/lac/sparse_matrix_ez.h

index 5f5228b77d50fb49f4d2b709b2b4c013e60d87af..cf146636d613ee4a04f0e58021968e389f1d1bd7 100644 (file)
@@ -38,39 +38,43 @@ template <typename number> class FullMatrix;
  * Sparse matrix without sparsity pattern.
  *
  * Instead of using a pre-assembled sparsity pattern, this matrix builds the
- * pattern on the fly. Filling the matrix may consume more time as with @p
- * SparseMatrix, since large memory movements may be involved. To help
- * optimizing things, an expected row-length may be provided to the
+ * pattern on the fly. Filling the matrix may consume more time than for
+ * @p SparseMatrix, since large memory movements may be involved when new
+ * matrix elements are inserted somewhere in the middle of the matrix and no
+ * currently unused memory locations are available for the row into which
+ * the new entry is to be inserted. To help
+ * optimize things, an expected row-length may be provided to the
  * constructor, as well as an increment size for rows.
  *
- * The storage structure: like with the usual sparse matrix, it is attempted
- * to store only non-zero elements. these are stored in a single data array @p
- * data. They are ordered by row and inside each row by column number. Each
- * row is described by its starting point in the data array and its length.
- * These are stored in the @p row_info array, together with additional useful
- * information.
+ * This class uses a storage structure that, similar to the usual sparse matrix
+ * format, only stores non-zero elements. These are stored in a single data array
+ * for the entire matrix, and are ordered by row and, within each row, by column
+ * number. A separate array describes where in the long data array each row
+ * starts and how long it is.
  *
- * Due to the structure, gaps may occur between rows. Whenever a new entry
- * must be created, an attempt is made to use the gap in its row. If the gap
- * is full, the row must be extended and all subsequent rows must be shifted
- * backwards. This is a very expensive operation and should be avoided as much
- * as possible.
+ * Due to this structure, gaps may occur between rows. Whenever a new entry
+ * must be created, an attempt is made to use the gap in its row. If no gap
+ * is left, the row must be extended and all subsequent rows must be shifted
+ * backwards. This is a very expensive operation and explains the inefficiency
+ * of this data structure and why it is useful to pre-allocate a sparsity
+ * pattern as the SparseMatrix class does.
  *
- * This is, where the optimization parameters, provided to the constructor or
- * to the function @p reinit come in. @p default_row_length is the amount of
+ * This is where the optimization parameters, provided to the constructor or
+ * to the reinit() functions come in. @p default_row_length is the number of
  * entries that will be allocated for each row on initialization (the actual
  * length of the rows is still zero). This means, that @p default_row_length
- * entries can be added to this row without shifting other rows. If less
- * entries are added, the additional memory will be wasted.
+ * entries can be added to this row without shifting other rows. If fewer
+ * entries are added, the additional memory will of course be wasted.
  *
- * If the space for a row is not sufficient, then it is enlarged by @p
- * default_increment entries. This way, the subsequent rows are not shifted by
+ * If the space for a row is not sufficient, then it is enlarged by
+ * @p default_increment entries. This way, subsequent rows are not shifted by
  * single entries very often.
  *
  * Finally, the @p default_reserve allocates extra space at the end of the
- * data array. This space is used whenever a row must be enlarged. Since @p
- * std::vector doubles the capacity every time it must increase it, this value
- * should allow for all the growth needed.
+ * data array. This space is used whenever any row must be enlarged. It is
+ * important because otherwise not only the following rows must be moved, but
+ * in fact <i>all</i> rows after allocating sufficiently much space for the
+ * entire data array.
  *
  * Suggested settings: @p default_row_length should be the length of a typical
  * row, for instance the size of the stencil in regular parts of the grid.
@@ -80,16 +84,14 @@ template <typename number> class FullMatrix;
  * then be an estimate for the number of hanging nodes times @p
  * default_increment.
  *
- * Letting @p default_increment zero causes an exception whenever a row
+ * Letting @p default_increment be zero causes an exception whenever a row
  * overflows.
  *
  * If the rows are expected to be filled more or less from first to last,
  * using a @p default_row_length of zero may not be such a bad idea.
  *
- * The name of this matrix is in reference to a publication of the Internal
- * Revenue Service of the United States of America. I hope some other aliens
- * will appreciate it. By the way, the suffix makes sense by pronouncing it
- * the American way.
+ * @note The name of the class makes sense by pronouncing it the American way,
+ *   where "EZ" is pronounced the same way as the word "easy".
  *
  * @author Guido Kanschat
  * @date 2002, 2010
@@ -145,7 +147,7 @@ public:
     /**
      * Constructor.
      */
-    RowInfo (size_type start = Entry::invalid);
+    RowInfo (const size_type start = Entry::invalid);
 
     /**
      * Index of first entry of the row in the data field.
@@ -324,8 +326,7 @@ public:
                            const unsigned int default_increment = 1);
 
   /**
-   * Destructor. Free all memory, but do not release the memory of the
-   * sparsity structure.
+   * Destructor. Free all memory.
    */
   ~SparseMatrixEZ () = default;
 
@@ -893,7 +894,7 @@ SparseMatrixEZ<number>::Entry::Entry()
 
 template <typename number>
 inline
-SparseMatrixEZ<number>::RowInfo::RowInfo(size_type start)
+SparseMatrixEZ<number>::RowInfo::RowInfo(const size_type start)
   :
   start(start),
   length(0),

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.