From: Wolfgang Bangerth Date: Mon, 2 Oct 2017 22:16:50 +0000 (-0600) Subject: Update documentation of SparseMatrixEZ. X-Git-Tag: v9.0.0-rc1~1007^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F5186%2Fhead;p=dealii.git Update documentation of SparseMatrixEZ. --- diff --git a/include/deal.II/lac/sparse_matrix_ez.h b/include/deal.II/lac/sparse_matrix_ez.h index 5f5228b77d..cf146636d6 100644 --- a/include/deal.II/lac/sparse_matrix_ez.h +++ b/include/deal.II/lac/sparse_matrix_ez.h @@ -38,39 +38,43 @@ template 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 all 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 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::Entry::Entry() template inline -SparseMatrixEZ::RowInfo::RowInfo(size_type start) +SparseMatrixEZ::RowInfo::RowInfo(const size_type start) : start(start), length(0),