From: Matthias Maier Date: Fri, 28 Aug 2015 05:07:37 +0000 (-0500) Subject: Update documentation X-Git-Tag: v8.4.0-rc2~536^2~1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e43fb9b064f7d4a668da7c80ebe8d3bb822f6a11;p=dealii.git Update documentation --- diff --git a/include/deal.II/lac/block_linear_operator.h b/include/deal.II/lac/block_linear_operator.h index 690b132a0e..acfbdfba93 100644 --- a/include/deal.II/lac/block_linear_operator.h +++ b/include/deal.II/lac/block_linear_operator.h @@ -87,7 +87,43 @@ block_back_substitution(const BlockLinearOperator &, /** - * TODO: Description + * A class to store the concept of a block linear operator. + * + * This class increases the interface of LinearOperator (which encapsulates + * the @p Matrix interface) by three additional functions: + * @code + * std::function n_block_rows; + * std::function n_block_cols; + * std::function block; + * @endcode + * that describe the underlying block structure (of an otherwise opaque) + * linear operator. + * + * Objects of type BlockLinearOperator can be created similarly to + * LinearOperator with a wrapper function: + * @code + * dealii::BlockSparseMatrix A; + * const auto block_op_a = block_operator(A); + * @endcode + * + * A BlockLinearOperator can be sliced to a LinearOperator at any time. + * This removes all information about the underlying block structure + * (beacuse above std::function objects are no longer + * available) - the linear operator interface, however, remains intact. + * + * @note This class makes heavy use of std::function objects + * and lambda functions. This flexibiliy comes with a run-time penalty. + * Only use this object to encapsulate object with medium to large + * individual block sizes, and small block structure (as a rule of thumb, + * matrix blocks greater than $1000\times1000$). + * + * @note This class is only available if deal.II was configured with C++11 + * support, i.e., if DEAL_II_WITH_CXX11 is enabled during cmake + * configure. + * + * @author Matthias Maier, 2015 + * + * @ingroup LAOperators */ template class BlockLinearOperator : public LinearOperator @@ -210,17 +246,23 @@ public: } /** - * TODO: Description + * Return the number of blocks in a column (i.e, the number of "block + * rows", or the number $m$, if interpreted as a $m\times n$ block + * system). */ std::function n_block_rows; /** - * TODO: Description + * Return the number of blocks in a row (i.e, the number of "block + * columns", or the number $n$, if interpreted as a $m\times n$ block + * system). */ std::function n_block_cols; /** - * TODO: Description + * Access the block with the given coordinates. This + * std::function object returns a LinearOperator + * representing the $(i,j)$-th block of the BlockLinearOperator. */ std::function block; @@ -333,7 +375,7 @@ namespace internal //@{ /** - * @relates LinearOperator + * @relates BlockLinearOperator * * A function that encapsulates a @p block_matrix into a * BlockLinearOperator. @@ -383,7 +425,7 @@ block_operator(const BlockMatrix &block_matrix) /** - * @relates LinearOperator + * @relates BlockLinearOperator * * A variant of above function that encapsulates a given collection @p ops * of LinearOperators into a block structure. Here, it is assumed that @@ -444,7 +486,7 @@ block_operator(const std::array &block_opera return return_op; } + + /** * @relates LinearOperator + * @relates BlockLinearOperator * * This function implements back substitution to invert an upper block * triangular matrix. As arguments, it takes a BlockLinearOperator diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h index d1f83e535f..bc09bbf58d 100644 --- a/include/deal.II/lac/linear_operator.h +++ b/include/deal.II/lac/linear_operator.h @@ -98,6 +98,12 @@ null_operator(const LinearOperator &); * const auto op = (op_a + k * op_b) * op_c; * @endcode * + * @note This class makes heavy use of std::function objects + * and lambda functions. This flexibiliy comes with a run-time penalty. + * Only use this object to encapsulate matrix object of medium to large + * size (as a rule of thumb, sparse matrices with a size $1000\times1000$, + * or larger). + * * @note This class is only available if deal.II was configured with C++11 * support, i.e., if DEAL_II_WITH_CXX11 is enabled during cmake * configure.