| 1 |
// SPDX-FileCopyrightText: Copyright © DUNE Project contributors, see file LICENSE.md in module root |
| 2 |
// SPDX-License-Identifier: LicenseRef-GPL-2.0-only-with-DUNE-exception |
| 3 |
// -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- |
| 4 |
// vi: set et ts=4 sw=2 sts=2: |
| 5 |
#ifndef DUNE_ISTL_PRECONDITIONER_HH |
| 6 |
#define DUNE_ISTL_PRECONDITIONER_HH |
| 7 |
|
| 8 |
#include <dune-istl-config.hh> // DUNE_ISTL_SUPPORT_OLD_CATEGORY_INTERFACE |
| 9 |
#include <dune/common/exceptions.hh> |
| 10 |
|
| 11 |
#include "solvercategory.hh" |
| 12 |
|
| 13 |
namespace Dune { |
| 14 |
/** |
| 15 |
* @addtogroup ISTL_Prec |
| 16 |
* @{ |
| 17 |
*/ |
| 18 |
//===================================================================== |
| 19 |
/*! \brief Base class for matrix free definition of preconditioners. |
| 20 |
|
| 21 |
Note that the operator, which is the basis for the preconditioning, |
| 22 |
is supplied to the preconditioner from the outside in the |
| 23 |
constructor or some other method. |
| 24 |
|
| 25 |
This interface allows the encapsulation of all parallelization |
| 26 |
aspects into the preconditioners. |
| 27 |
|
| 28 |
\tparam X Type of the update |
| 29 |
\tparam Y Type of the defect |
| 30 |
*/ |
| 31 |
//===================================================================== |
| 32 |
template<class X, class Y> |
| 33 |
class Preconditioner { |
| 34 |
public: |
| 35 |
//! \brief The domain type of the preconditioner. |
| 36 |
typedef X domain_type; |
| 37 |
//! \brief The range type of the preconditioner. |
| 38 |
typedef Y range_type; |
| 39 |
//! \brief The field type of the preconditioner. |
| 40 |
typedef typename X::field_type field_type; |
| 41 |
|
| 42 |
/*! \brief Prepare the preconditioner. |
| 43 |
|
| 44 |
A solver solves a linear operator equation A(x)=b by applying |
| 45 |
one or several steps of the preconditioner. The method pre() |
| 46 |
is called before the first apply operation. |
| 47 |
b and x are right hand side and solution vector of the linear |
| 48 |
system respectively. It may. e.g., scale the system, allocate memory or |
| 49 |
compute a (I)LU decomposition. |
| 50 |
Note: The ILU decomposition could also be computed in the constructor |
| 51 |
or with a separate method of the derived method if several |
| 52 |
linear systems with the same matrix are to be solved. |
| 53 |
|
| 54 |
\note if a preconditioner is copied (e.g. for a second thread) |
| 55 |
again the pre() method has to be called to ensure proper memory |
| 56 |
management. |
| 57 |
|
| 58 |
\code |
| 59 |
X x(0.0); |
| 60 |
Y b = ...; // rhs |
| 61 |
Preconditioner<X,Y> prec(...); |
| 62 |
prec.pre(x,b); // prepare the preconditioner |
| 63 |
prec.apply(x,b); // can be called multiple times now... |
| 64 |
prec.post(x); // cleanup internal state |
| 65 |
\endcode |
| 66 |
|
| 67 |
\param x The left hand side of the equation. |
| 68 |
\param b The right hand side of the equation. |
| 69 |
*/ |
| 70 |
virtual void pre (X& x, Y& b) = 0; |
| 71 |
|
| 72 |
/*! \brief Apply one step of the preconditioner to the system A(v)=d. |
| 73 |
|
| 74 |
On entry v=0 and d=b-A(x) (although this might not be |
| 75 |
computed in that way. On exit v contains the update, i.e |
| 76 |
one step computes \f$ v = M^{-1} d \f$ where \f$ M \f$ is the |
| 77 |
approximate inverse of the operator \f$ A \f$ characterizing |
| 78 |
the preconditioner. |
| 79 |
\param[out] v The update to be computed |
| 80 |
\param d The current defect. |
| 81 |
*/ |
| 82 |
virtual void apply (X& v, const Y& d) = 0; |
| 83 |
|
| 84 |
/*! \brief Clean up. |
| 85 |
|
| 86 |
This method is called after the last apply call for the |
| 87 |
linear system to be solved. Memory may be deallocated safely |
| 88 |
here. x is the solution of the linear equation. |
| 89 |
|
| 90 |
\param x The right hand side of the equation. |
| 91 |
*/ |
| 92 |
virtual void post (X& x) = 0; |
| 93 |
|
| 94 |
//! Category of the preconditioner (see SolverCategory::Category) |
| 95 |
virtual SolverCategory::Category category() const |
| 96 |
#if DUNE_ISTL_SUPPORT_OLD_CATEGORY_INTERFACE |
| 97 |
{ |
| 98 |
DUNE_THROW(Dune::Exception,"It is necessary to implement the category method in a derived classes, in the future this method will pure virtual."); |
| 99 |
} |
| 100 |
#else |
| 101 |
= 0; |
| 102 |
#endif |
| 103 |
|
| 104 |
//! every abstract base class has a virtual destructor |
| 105 |
virtual ~Preconditioner () {} |
| 106 |
|
| 107 |
}; |
| 108 |
|
| 109 |
/** |
| 110 |
* @} |
| 111 |
*/ |
| 112 |
} |
| 113 |
#endif |