--- /dev/null
+// ---------------------------------------------------------------------
+//
+// Copyright (C) 2015 by the deal.II authors
+//
+// This file is part of the deal.II library.
+//
+// The deal.II library is free software; you can use it, redistribute
+// it, and/or modify it under the terms of the GNU Lesser General
+// Public License as published by the Free Software Foundation; either
+// version 2.1 of the License, or (at your option) any later version.
+// The full text of the license can be found in the file LICENSE at
+// the top level of the deal.II distribution.
+//
+// ---------------------------------------------------------------------
+
+
+
+/**
+ * @defgroup LAOperators Linear Operators
+ *
+ * <h3>Linear Operator</h3>
+ *
+ * If deal.II is configured with C++11 support (i.e.,
+ * <code>DEAL_II_WITH_CXX11=on</code> during configuration) a versatile
+ * mechanism for storing the concept of a linear operator is available.
+ *
+ * This is done with a LinearOperator class that, similarly to the abstract
+ * MATRIX interface, defines a minimal interface for <i>applying</i> a
+ * linear operation on a vector.
+ * @code
+ * std::function<void(Range &, const Domain &)> vmult;
+ * std::function<void(Range &, const Domain &)> vmult_add;
+ * std::function<void(Domain &, const Range &)> Tvmult;
+ * std::function<void(Domain &, const Range &)> Tvmult_add;
+ * @endcode
+ *
+ * Thus, such an object can be used as a matrix object in all
+ * @ref Solvers "iterative solver" classes, either as a matrix object, or as
+ * @ref Preconditioners "preconditioner".
+ *
+ * The big advantage of the LinearOperator class is that it provides
+ * syntactic sugar for complex matrix-vector operations. As an example
+ * consider the operation $(A+k\,B)\,C$, where $A$, $B$ and $C$ denote
+ * (possibly different) SparseMatrix objects. In order to construct a
+ * LinearOperator <code>op</code> that performs above computation when
+ * applied on a vector, one can write:
+ * @code
+ * dealii::SparseMatrix<double> A, B, C;
+ * // Setup and assembly...
+ * const double k = ...;
+ *
+ * const auto op_a = linear_operator(A);
+ * const auto op_b = linear_operator(B);
+ * const auto op_c = linear_operator(C);
+ *
+ * const auto op = (op_a + k * op_b) * op_c;
+ * @endcode
+ * Now, <code>op</code> can be used as a matrix object for further
+ * computation.
+ *
+ * The linear_operator() function can be used to wrap an ordinary matrix or
+ * preconditioner object into a LinearOperator. A linear operator can be
+ * transposed with transpose_operator(), or inverted by using the
+ * inverse_operator() together with an iterative solver.
+ *
+ * For objects of type LinearOperator, all vector space operations, i.e.,
+ * addition and subtraction, scalar multiplication and composition (of
+ * compatible linear operators) are implemented.
+ *
+ * block_operator() and block_diagonal_operator() provide further
+ * encapsulation of individual linear operators into blocked linear
+ * operator variants.
+ *
+ * @note The LinearOperator facility obsoletes some of the @ref Matrix2
+ * "derived matrix" classes, such as BlockDiagonalMatrix, IterativeInverse,
+ * ProductMatrix, ScaledMatrix, ProductSparseMatrix,
+ * InverseMatrixRichardson, SchurMatrix, ShiftedMatrix,
+ * ShiftedMatrixGeneralized, TransposeMatrix
+ *
+ * @ingroup LAC
+ * @ingroup MATRICES
+ */
// ---------------------------------------------------------------------
//
-// Copyright (C) 2000 - 2014 by the deal.II authors
+// Copyright (C) 2000 - 2015 by the deal.II authors
//
// This file is part of the deal.II library.
//
* One special application is a one by one block matrix, allowing to apply the
* @p vmult of the original matrix (or preconditioner) to a block vector.
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @see
* @ref GlossBlockLA "Block (linear algebra)"
* @author Guido Kanschat, 2000
// ---------------------------------------------------------------------
//
-// Copyright (C) 1999 - 2014 by the deal.II authors
+// Copyright (C) 1999 - 2015 by the deal.II authors
//
// This file is part of the deal.II library.
//
* from machine accuracy, even if the errors of the outer loop are in the
* range of machine accuracy.
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @ingroup Matrix2
* @author Guido Kanschat
* @date 2010
* that store the knowledge of how to apply the linear operator by
* implementing the abstract @ref Matrix interface:
* @code
- * std::function<const void(Range &, const Domain &)> vmult;
- * std::function<const void(Range &, const Domain &)> vmult_add;
- * std::function<const void(Domain &, const Range &)> Tvmult;
- * std::function<const void(Domain &, const Range &)> Tvmult_add;
+ * std::function<void(Range &, const Domain &)> vmult;
+ * std::function<void(Range &, const Domain &)> vmult_add;
+ * std::function<void(Domain &, const Range &)> Tvmult;
+ * std::function<void(Domain &, const Range &)> Tvmult_add;
* @endcode
*
* But, in contrast to a usual matrix object, the domain and range of the
* const auto op = (op_a + k * op_b) * op_c;
* @endcode
*
- * @note: This class is only available if deal.II was configured with C++11
+ * @note This class is only available if deal.II was configured with C++11
* support, i.e., if <code>DEAL_II_WITH_CXX11</code> is enabled during
* cmake configure.
*
* @author Luca Heltai, Matthias Maier, 2015
+ *
+ * @ingroup LAOperators
*/
template <typename Range, typename Domain> class LinearOperator
{
*
* Addition of two linear operators @p first_op and @p second_op given
* by $(\text{first_op}+\text{second_op})x:=\text{first_op}(x)+\text{second_op}(x)$
+ *
+ * @ingroup LAOperators
*/
template <typename Range, typename Domain>
LinearOperator<Range, Domain>
*
* Subtraction of two linear operators @p first_op and @p second_op given
* by $(\text{first_op}-\text{second_op})x:=\text{first_op}(x)-\text{second_op}(x)$
+ *
+ * @ingroup LAOperators
*/
template <typename Range, typename Domain>
LinearOperator<Range, Domain>
*
* Concatenation of two linear operators @p first_op and @p second_op given
* by $(\text{first_op}*\text{second_op})x:=\text{first_op}(\text{second_op}(x))$
+ *
+ * @ingroup LAOperators
*/
template <typename Range, typename Intermediate, typename Domain>
LinearOperator<Range, Domain>
* Domain & operator *=(Domain::value_type);
* Range & operator *=(Range::value_type);
* @endcode
+ *
+ * @ingroup LAOperators
*/
template <typename Range, typename Domain>
LinearOperator<Range, Domain>
* Domain & operator *=(Domain::value_type);
* Range & operator *=(Range::value_type);
* @endcode
+ *
+ * @ingroup LAOperators
*/
template <typename Range, typename Domain>
LinearOperator<Range, Domain>
* \relates LinearOperator
*
* Returns the transpose linear operations of @ref op.
+ *
+ * @ingroup LAOperators
*/
template <typename Range, typename Domain>
LinearOperator<Domain, Range>
* reinit_vector as an argument to initialize the
* <code>reinit_range_vector</code> and <code>reinit_domain_vector</code>
* objects of the LinearOperator object.
+ *
+ * @ingroup LAOperators
*/
template <typename Range>
LinearOperator<Range, Range>
* reference for the whole lifetime of the LinearOperator object. Internal
* data structures of the @p solver object will be modified upon
* invocation of <code>vmult</code> or <code>Tvmult</code>.
+ *
+ * @ingroup LAOperators
*/
template <typename Solver, typename Preconditioner>
LinearOperator<typename Solver::vector_type, typename Solver::vector_type>
* @code
* block_operator<2, 2, BlockVector<double>>({op_a00, op_a01, op_a10, op_a11});
* @endcode
+ *
+ * @ingroup LAOperators
*/
template <unsigned int m, unsigned int n,
typename Range = BlockVector<double>,
* @code
* block_diagonal_operator<m, BlockVector<double>>({op_00, op_a1, ..., op_am});
* @endcode
+ *
+ * @ingroup LAOperators
*/
template <unsigned int m,
typename Range = BlockVector<double>,
* A variant of above function that only takes a single LinearOperator
* argument @p op and creates a blockdiagonal linear operator with @p m
* copies of it.
+ *
+ * @ingroup LAOperators
*/
template <unsigned int m,
typename Range = BlockVector<double>,
* storage).
*
* @author Matthias Maier, 2015
+ *
+ * @ingroup LAOperators
*/
template <typename Range = Vector<double>,
typename Domain = Range,
* matrix).
*
* @author Matthias Maier, 2015
+ *
+ * @ingroup LAOperators
*/
template <typename Range = Vector<double>,
typename Domain = Range,
// ---------------------------------------------------------------------
//
-// Copyright (C) 2002 - 2014 by the deal.II authors
+// Copyright (C) 2002 - 2015 by the deal.II authors
//
// This file is part of the deal.II library.
//
* Here is an example multiplying two different FullMatrix objects:
* @include product_matrix.cc
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @author Guido Kanschat, 2000, 2001, 2002, 2005
*/
template<class VECTOR>
* Matrix-vector products of this matrix are composed of those of the original
* matrix with the vector and then scaling of the result by a constant factor.
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @author Guido Kanschat, 2007
*/
template<class VECTOR>
* The documentation of ProductMatrix applies with exception that these
* matrices here may be rectangular.
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @author Guido Kanschat, 2000, 2001, 2002, 2005
*/
template<typename number, typename vector_number>
* @ref Instantiations
* in the manual).
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @author Guido Kanschat, 2005
*/
template<class VECTOR>
// ---------------------------------------------------------------------
//
-// Copyright (C) 2001 - 2014 by the deal.II authors
+// Copyright (C) 2001 - 2015 by the deal.II authors
//
// This file is part of the deal.II library.
//
* Given a matrix <tt>A</tt>, this class implements a matrix-vector product
* with <i>A+s I</i>, where <i>s</i> is a provided shift parameter.
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on @ref LAOperators "linear
+ * operators" for further details.
+ *
* @author Guido Kanschat, 2000, 2001
*/
template<class MATRIX>
* with <i>A+s M</i>, where <i>s</i> is a provided shift parameter and
* <tt>M</tt> is the matrix representing the identity
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @author Guido Kanschat, 2001
*/
template<class MATRIX, class MASSMATRIX, class VECTOR>
// ---------------------------------------------------------------------
//
-// Copyright (C) 2002 - 2014 by the deal.II authors
+// Copyright (C) 2002 - 2015 by the deal.II authors
//
// This file is part of the deal.II library.
//
* @note The transposed matrix is never actually assembled. Instead, only the
* matrix vector multiplication is performed in a transposed way.
*
+ * @deprecated If deal.II was configured with C++11 support, use the
+ * LinearOperator class instead, see the module on
+ * @ref LAOperators "linear operators" for further details.
+ *
* @ingroup Matrix2
* @author Guido Kanschat, 2006
*/