Debian Codegraph @

include/deal.II/lac/sparse_mic.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2002 - 2023 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_sparse_mic_h
16 #define dealii_sparse_mic_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/lac/sparse_decomposition.h>
21 #include <deal.II/lac/sparse_matrix.h>
22
23 DEAL_II_NAMESPACE_OPEN
24
25 /**
26 * @addtogroup Preconditioners
27 * @{
28 */
29
30 /**
31 * Implementation of the Modified Incomplete Cholesky (MIC(0)) preconditioner
32 * for symmetric matrices. This class conforms to the state and usage
33 * specification in SparseLUDecomposition.
34 *
35 *
36 * <h3>The decomposition</h3>
37 *
38 * Let a symmetric, positive-definite, sparse matrix $A$ be in the form $A = D
39 * - L - L^T$, where $D$ is the diagonal part of $A$ and $-L$ is a strictly
40 * lower triangular matrix. The MIC(0) decomposition of the matrix $A$ is
41 * defined by $B = (X-L)X^{-1}(X-L^T)$, where $X$ is a diagonal matrix defined
42 * by the condition $\text{rowsum}(A) = \text{rowsum}(B)$.
43 */
44 template <typename number>
45 class SparseMIC : public SparseLUDecomposition<number>
46 {
47 public:
48 /**
49 * Declare type for container size.
50 */
51 using size_type = types::global_dof_index;
52
53 /**
54 * Constructor. Does nothing, so you have to call @p decompose sometimes
55 * afterwards.
56 */
57 SparseMIC() = default;
58
59 /**
60 * Destructor.
61 */
62 virtual ~SparseMIC() override;
63
64 /**
65 * Deletes all member variables. Leaves the class in the state that it had
66 * directly after calling the constructor
67 */
68 virtual void
69 clear() override;
70
71 /**
72 * Make the @p AdditionalData type in the base class accessible to this
73 * class as well.
74 */
75 using AdditionalData = typename SparseLUDecomposition<number>::AdditionalData;
76
77 /**
78 * Perform the incomplete LU factorization of the given matrix.
79 *
80 * This function needs to be called before an object of this class is used
81 * as preconditioner.
82 *
83 * For more details about possible parameters, see the class documentation
84 * of SparseLUDecomposition and the documentation of the @p
85 * SparseLUDecomposition::AdditionalData class.
86 *
87 * According to the @p parameters, this function creates a new
88 * SparsityPattern or keeps the previous sparsity or takes the sparsity
89 * given by the user to @p data. Then, this function performs the MIC
90 * decomposition.
91 *
92 * After this function is called the preconditioner is ready to be used.
93 */
94 template <typename somenumber>
95 void
96 initialize(const SparseMatrix<somenumber> &matrix,
97 const AdditionalData &parameters = AdditionalData());
98
99 /**
100 * Apply the incomplete decomposition, i.e. do one forward-backward step
101 * $dst=(LU)^{-1}src$.
102 *
103 * Call @p initialize before calling this function.
104 */
105 template <typename somenumber>
106 void
107 vmult(Vector<somenumber> &dst, const Vector<somenumber> &src) const;
108
109 /**
110 * Apply the transpose of the incomplete decomposition, i.e. do one
111 * forward-backward step $dst=(LU)^{-1}src$.
112 *
113 * Call @p initialize before calling this function.
114 *
115 * @note This function has not yet been implemented
116 */
117 template <typename somenumber>
118 void
119 Tvmult(Vector<somenumber> &dst, const Vector<somenumber> &src) const;
120
121 /**
122 * Determine an estimate for the memory consumption (in bytes) of this
123 * object.
124 */
125 std::size_t
126 memory_consumption() const override;
127
128 /**
129 * @addtogroup Exceptions
130 * @{
131 */
132
133 /**
134 * Exception
135 */
136 DeclException0(ExcStrengthenDiagonalTooSmall);
137 /**
138 * Exception
139 */
140 DeclException1(ExcInvalidStrengthening,
141 double,
142 << "The strengthening parameter " << arg1
143 << " is not greater or equal than zero!");
144 /**
145 * Exception
146 */
147 DeclException2(ExcDecompositionNotStable,
148 int,
149 double,
150 << "The diagonal element (" << arg1 << ',' << arg1 << ") is "
151 << arg2 << ", but must be positive");
152
153 /** @} */
154 private:
155 /**
156 * Values of the computed diagonal.
157 */
158 std::vector<number> diag;
159
160 /**
161 * Inverses of the diagonal: precomputed for faster vmult.
162 */
163 std::vector<number> inv_diag;
164
165 /**
166 * Values of the computed "inner sums", i.e. per-row sums of the elements
167 * laying on the right side of the diagonal.
168 */
169 std::vector<number> inner_sums;
170
171 /**
172 * Compute the row-th "inner sum".
173 */
174 number
175 get_rowsum(const size_type row) const;
176 };
177
178 /** @} */
179
180 DEAL_II_NAMESPACE_CLOSE
181
182 #endif // dealii_