* 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.
* 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
/**
* 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.
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;
template <typename number>
inline
-SparseMatrixEZ<number>::RowInfo::RowInfo(size_type start)
+SparseMatrixEZ<number>::RowInfo::RowInfo(const size_type start)
:
start(start),
length(0),