From 0d6f9a79a0fcd7d01844257577f389d64bc41bac Mon Sep 17 00:00:00 2001 From: Timo Heister Date: Fri, 24 Jan 2014 21:06:34 +0000 Subject: [PATCH] put deprecated functions into own doxygen group, fix doxygen formatting git-svn-id: https://svn.dealii.org/trunk@32306 0785d39b-7218-0410-832d-ea1e28bc413d --- .../include/deal.II/lac/sparsity_pattern.h | 494 +++++++++--------- 1 file changed, 255 insertions(+), 239 deletions(-) diff --git a/deal.II/include/deal.II/lac/sparsity_pattern.h b/deal.II/include/deal.II/lac/sparsity_pattern.h index 414e6ea92b..e53b7184c6 100644 --- a/deal.II/include/deal.II/lac/sparsity_pattern.h +++ b/deal.II/include/deal.II/lac/sparsity_pattern.h @@ -429,22 +429,6 @@ public: */ SparsityPattern (const SparsityPattern &); - /** - * Initialize a rectangular matrix. - * - * @arg m number of rows - * @arg n number of columns - * @arg max_per_row maximum number of nonzero entries per row - * @arg optimize_diagonal This parameter is ignored. - * - * @deprecated Use the constructor without the last argument since - * it is ignored. - */ - SparsityPattern (const size_type m, - const size_type n, - const unsigned int max_per_row, - const bool optimize_diagonal) DEAL_II_DEPRECATED; - /** * Initialize a rectangular matrix. * @@ -456,22 +440,6 @@ public: const size_type n, const unsigned int max_per_row); - /** - * Initialize a rectangular matrix. - * - * @arg m number of rows - * @arg n number of columns - * @arg row_lengths possible number of nonzero entries for each row. This - * vector must have one entry for each row. - * @arg optimize_diagonal This argument is ignored. - * - * @deprecated Use the constructor without the last argument since - * it is ignored. - */ - SparsityPattern (const size_type m, - const size_type n, - const std::vector &row_lengths, - const bool optimize_diagonal) DEAL_II_DEPRECATED; /** * Initialize a rectangular matrix. @@ -496,21 +464,6 @@ public: SparsityPattern (const size_type n, const unsigned int max_per_row); - /** - * Initialize a quadratic matrix. - * - * @arg m number of rows and columns - * @arg row_lengths possible number of nonzero entries for each row. This - * vector must have one entry for each row. - * @arg optimize_diagonal This argument is ignored. - * - * @deprecated Use the constructor without the last argument since - * it is ignored. - */ - SparsityPattern (const size_type m, - const std::vector &row_lengths, - const bool optimize_diagonal) DEAL_II_DEPRECATED; - /** * Initialize a quadratic matrix. * @@ -559,22 +512,6 @@ public: */ SparsityPattern &operator = (const SparsityPattern &); - /** - * Reallocate memory and set up data structures for a new matrix with m - * rows and n columns, with at most max_per_row - * nonzero entries per row. - * - * This function simply maps its operations to the other reinit - * function. - * - * @deprecated The last argument of this function is ignored. Use the - * version of this function without the last argument. - */ - void reinit (const size_type m, - const size_type n, - const unsigned int max_per_row, - const bool optimize_diagonal) DEAL_II_DEPRECATED; - /** * Reallocate memory and set up data structures for a new matrix with m * rows and n columns, with at most max_per_row @@ -587,27 +524,6 @@ public: const size_type n, const unsigned int max_per_row); - /** - * Reallocate memory for a matrix of size m x n. The number of - * entries for each row is taken from the array row_lengths which - * has to give this number of each row i=1...m. - * - * If m*n==0 all memory is freed, resulting in a total - * reinitialization of the object. If it is nonzero, new memory is only - * allocated if the new size extends the old one. This is done to save time - * and to avoid fragmentation of the heap. - * - * If the number of rows equals the number of columns and the last parameter - * is true, diagonal elements are stored first in each row to allow - * optimized access in relaxation methods of SparseMatrix. - * - * @deprecated The last argument of this function is ignored. Use the - * version of this function without the last argument. - */ - void reinit (const size_type m, - const size_type n, - const std::vector &row_lengths, - const bool optimize_diagonal) DEAL_II_DEPRECATED; /** * Reallocate memory for a matrix of size m x n. The number of @@ -627,16 +543,6 @@ public: const size_type n, const std::vector &row_lengths); - /** - * Same as above, but with a VectorSlice argument instead. - * - * @deprecated The last argument of this function is ignored. Use the - * version of this function without the last argument. - */ - void reinit (const size_type m, - const size_type n, - const VectorSlice > &row_lengths, - const bool optimize_diagonal) DEAL_II_DEPRECATED; /** * Same as above, but with a VectorSlice argument instead. @@ -659,91 +565,6 @@ public: */ void compress (); - /** - * This function can be used as a replacement for reinit(), subsequent calls - * to add() and a final call to close() if you know exactly in advance the - * entries that will form the matrix sparsity pattern. - * - * The first two parameters determine the size of the matrix. For the two - * last ones, note that a sparse matrix can be described by a sequence of - * rows, each of which is represented by a sequence of pairs of column - * indices and values. In the present context, the begin() and end() - * parameters designate iterators (of forward iterator type) into a - * container, one representing one row. The distance between begin() and - * end() should therefore be equal to n_rows(). These iterators may be - * iterators of std::vector, std::list, pointers into a - * C-style array, or any other iterator satisfying the requirements of a - * forward iterator. The objects pointed to by these iterators (i.e. what we - * get after applying operator* or operator-> to one of - * these iterators) must be a container itself that provides functions - * begin and end designating a range of iterators that - * describe the contents of one line. Dereferencing these inner iterators - * must either yield a pair of an unsigned integer as column index and a - * value of arbitrary type (such a type would be used if we wanted to - * describe a sparse matrix with one such object), or simply an unsigned - * integer (of we only wanted to describe a sparsity pattern). The function - * is able to determine itself whether an unsigned integer or a pair is what - * we get after dereferencing the inner iterators, through some template - * magic. - * - * While the order of the outer iterators denotes the different rows of the - * matrix, the order of the inner iterator denoting the columns does not - * matter, as they are sorted internal to this function anyway. - * - * Since that all sounds very complicated, consider the following example - * code, which may be used to fill a sparsity pattern: - * @code - * std::vector > column_indices (n_rows); - * for (unsigned int row=0; rowbegin and end (namely - * std::vectors), and the inner iterators dereferenced yield - * unsigned integers as column indices. Note that we could have replaced - * each of the two std::vector occurrences by std::list, - * and the inner one by std::set as well. - * - * Another example would be as follows, where we initialize a whole matrix, - * not only a sparsity pattern: - * @code - * std::vector > entries (n_rows); - * for (unsigned int row=0; rowstd::vector could - * be replaced by std::list, and the inner std::map could be replaced by std::vector >, or a list or set of such pairs, as they all return - * iterators that point to such pairs. - * - * @deprecated The last argument of this function is ignored. Use the - * version of this function without the last argument. - */ - template - void copy_from (const size_type n_rows, - const size_type n_cols, - const ForwardIterator begin, - const ForwardIterator end, - const bool optimize_diagonal) DEAL_II_DEPRECATED; /** * This function can be used as a replacement for reinit(), subsequent calls @@ -827,19 +648,6 @@ public: const ForwardIterator begin, const ForwardIterator end); - /** - * Copy data from an object of type CompressedSparsityPattern, - * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. - * Previous content of this object is lost, and the sparsity pattern is in - * compressed mode afterwards. - * - * @deprecated The last argument of this function is ignored. Use the - * version of this function without the last argument. - */ - template - void copy_from (const CompressedSparsityType &csp, - const bool optimize_diagonal) DEAL_II_DEPRECATED; - /** * Copy data from an object of type CompressedSparsityPattern, * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. Although @@ -851,19 +659,6 @@ public: template void copy_from (const CompressedSparsityType &csp); - /** - * Take a full matrix and use its nonzero entries to generate a sparse - * matrix entry pattern for this object. - * - * Previous content of this object is lost, and the sparsity pattern is in - * compressed mode afterwards. - * - * @deprecated The last argument of this function is ignored. Use the - * version of this function without the last argument. - */ - template - void copy_from (const FullMatrix &matrix, - const bool optimize_diagonal) DEAL_II_DEPRECATED; /** * Take a full matrix and use its nonzero entries to generate a sparse @@ -906,6 +701,10 @@ public: const bool indices_are_sorted = false); // @} + + + + /** * @name Iterators */ @@ -949,31 +748,6 @@ public: */ iterator end (const size_type r) const; - /** - * STL-like iterator with the first entry of row r. - * - * Note that if the given row is empty, i.e. does not contain any nonzero - * entries, then the iterator returned by this function equals - * end(r). Note also that the iterator may not be dereferencable in - * that case. - * - * @deprecated Use the iterators provided by the begin() and end() - * functions instead. - */ - row_iterator row_begin (const size_type r) const DEAL_II_DEPRECATED; - - /** - * Final iterator of row r. It points to the first element past the - * end of line @p r, or past the end of the entire sparsity pattern. - * - * Note that the end iterator is not necessarily dereferencable. This is in - * particular the case if it is the end iterator for the last row of a - * matrix. - * - * @deprecated Use the iterators provided by the begin() and end() - * functions instead. - */ - row_iterator row_end (const size_type r) const DEAL_II_DEPRECATED; // @} /** @@ -1038,15 +812,6 @@ public: */ unsigned int row_length (const size_type row) const; - /** - * Determine whether the matrix uses the special convention for quadratic - * matrices that the diagonal entries are stored first in each row. - * - * @deprecated The function always returns true if the matrix is - * square and false if it is not. - */ - bool optimize_diagonal () const DEAL_II_DEPRECATED; - /** * Return whether this object stores only those entries that have been added * explicitly, or if the sparsity pattern contains elements that have been @@ -1215,6 +980,255 @@ public: * @name Deprecated functions */ // @{ + + /** + * Initialize a rectangular matrix. + * + * @arg m number of rows + * @arg n number of columns + * @arg max_per_row maximum number of nonzero entries per row + * @arg optimize_diagonal This parameter is ignored. + * + * @deprecated Use the constructor without the last argument since + * it is ignored. + */ + SparsityPattern (const size_type m, + const size_type n, + const unsigned int max_per_row, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + /** + * Initialize a rectangular matrix. + * + * @arg m number of rows + * @arg n number of columns + * @arg row_lengths possible number of nonzero entries for each row. This + * vector must have one entry for each row. + * @arg optimize_diagonal This argument is ignored. + * + * @deprecated Use the constructor without the last argument since + * it is ignored. + */ + SparsityPattern (const size_type m, + const size_type n, + const std::vector &row_lengths, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + /** + * Initialize a quadratic matrix. + * + * @arg m number of rows and columns + * @arg row_lengths possible number of nonzero entries for each row. This + * vector must have one entry for each row. + * @arg optimize_diagonal This argument is ignored. + * + * @deprecated Use the constructor without the last argument since + * it is ignored. + */ + SparsityPattern (const size_type m, + const std::vector &row_lengths, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + + /** + * Reallocate memory for a matrix of size m x n. The number of + * entries for each row is taken from the array row_lengths which + * has to give this number of each row i=1...m. + * + * If m*n==0 all memory is freed, resulting in a total + * reinitialization of the object. If it is nonzero, new memory is only + * allocated if the new size extends the old one. This is done to save time + * and to avoid fragmentation of the heap. + * + * If the number of rows equals the number of columns and the last parameter + * is true, diagonal elements are stored first in each row to allow + * optimized access in relaxation methods of SparseMatrix. + * + * @deprecated The last argument of this function is ignored. Use the + * version of this function without the last argument. + */ + void reinit (const size_type m, + const size_type n, + const std::vector &row_lengths, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + + /** + * Same as above, but with a VectorSlice argument instead. + * + * @deprecated The last argument of this function is ignored. Use the + * version of this function without the last argument. + */ + void reinit (const size_type m, + const size_type n, + const VectorSlice > &row_lengths, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + /** + * Reallocate memory and set up data structures for a new matrix with m + * rows and n columns, with at most max_per_row + * nonzero entries per row. + * + * This function simply maps its operations to the other reinit + * function. + * + * @deprecated The last argument of this function is ignored. Use the + * version of this function without the last argument. + */ + void reinit (const size_type m, + const size_type n, + const unsigned int max_per_row, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + /** + * This function can be used as a replacement for reinit(), subsequent calls + * to add() and a final call to close() if you know exactly in advance the + * entries that will form the matrix sparsity pattern. + * + * The first two parameters determine the size of the matrix. For the two + * last ones, note that a sparse matrix can be described by a sequence of + * rows, each of which is represented by a sequence of pairs of column + * indices and values. In the present context, the begin() and end() + * parameters designate iterators (of forward iterator type) into a + * container, one representing one row. The distance between begin() and + * end() should therefore be equal to n_rows(). These iterators may be + * iterators of std::vector, std::list, pointers into a + * C-style array, or any other iterator satisfying the requirements of a + * forward iterator. The objects pointed to by these iterators (i.e. what we + * get after applying operator* or operator-> to one of + * these iterators) must be a container itself that provides functions + * begin and end designating a range of iterators that + * describe the contents of one line. Dereferencing these inner iterators + * must either yield a pair of an unsigned integer as column index and a + * value of arbitrary type (such a type would be used if we wanted to + * describe a sparse matrix with one such object), or simply an unsigned + * integer (of we only wanted to describe a sparsity pattern). The function + * is able to determine itself whether an unsigned integer or a pair is what + * we get after dereferencing the inner iterators, through some template + * magic. + * + * While the order of the outer iterators denotes the different rows of the + * matrix, the order of the inner iterator denoting the columns does not + * matter, as they are sorted internal to this function anyway. + * + * Since that all sounds very complicated, consider the following example + * code, which may be used to fill a sparsity pattern: + * @code + * std::vector > column_indices (n_rows); + * for (unsigned int row=0; rowbegin and end (namely + * std::vectors), and the inner iterators dereferenced yield + * unsigned integers as column indices. Note that we could have replaced + * each of the two std::vector occurrences by std::list, + * and the inner one by std::set as well. + * + * Another example would be as follows, where we initialize a whole matrix, + * not only a sparsity pattern: + * @code + * std::vector > entries (n_rows); + * for (unsigned int row=0; rowstd::vector could + * be replaced by std::list, and the inner std::map could be replaced by std::vector >, or a list or set of such pairs, as they all return + * iterators that point to such pairs. + * + * @deprecated The last argument of this function is ignored. Use the + * version of this function without the last argument. + */ + template + void copy_from (const size_type n_rows, + const size_type n_cols, + const ForwardIterator begin, + const ForwardIterator end, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + /** + * Copy data from an object of type CompressedSparsityPattern, + * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. + * Previous content of this object is lost, and the sparsity pattern is in + * compressed mode afterwards. + * + * @deprecated The last argument of this function is ignored. Use the + * version of this function without the last argument. + */ + template + void copy_from (const CompressedSparsityType &csp, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + + /** + * Take a full matrix and use its nonzero entries to generate a sparse + * matrix entry pattern for this object. + * + * Previous content of this object is lost, and the sparsity pattern is in + * compressed mode afterwards. + * + * @deprecated The last argument of this function is ignored. Use the + * version of this function without the last argument. + */ + template + void copy_from (const FullMatrix &matrix, + const bool optimize_diagonal) DEAL_II_DEPRECATED; + + /** + * STL-like iterator with the first entry of row r. + * + * Note that if the given row is empty, i.e. does not contain any nonzero + * entries, then the iterator returned by this function equals + * end(r). Note also that the iterator may not be dereferencable in + * that case. + * + * @deprecated Use the iterators provided by the begin() and end() + * functions instead. + */ + row_iterator row_begin (const size_type r) const DEAL_II_DEPRECATED; + + /** + * Final iterator of row r. It points to the first element past the + * end of line @p r, or past the end of the entire sparsity pattern. + * + * Note that the end iterator is not necessarily dereferencable. This is in + * particular the case if it is the end iterator for the last row of a + * matrix. + * + * @deprecated Use the iterators provided by the begin() and end() + * functions instead. + */ + row_iterator row_end (const size_type r) const DEAL_II_DEPRECATED; + + /** + * Determine whether the matrix uses the special convention for quadratic + * matrices that the diagonal entries are stored first in each row. + * + * @deprecated The function always returns true if the matrix is + * square and false if it is not. + */ + bool optimize_diagonal () const DEAL_II_DEPRECATED; + /** * @deprecated This function is deprecated. Use SparsityTools::partition * instead. @@ -1293,6 +1307,8 @@ public: */ const size_type *get_column_numbers () const DEAL_II_DEPRECATED; +// @} + BOOST_SERIALIZATION_SPLIT_MEMBER() /** @addtogroup Exceptions * @name Exceptions -- 2.39.5