Debian Codegraph @

include/deal.II/lac/sparse_ilu.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 2025 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
16 #ifndef dealii_sparse_ilu_h
17 #define dealii_sparse_ilu_h
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/lac/exceptions.h>
23 #include <deal.II/lac/sparse_decomposition.h>
24 #include <deal.II/lac/sparse_matrix.h>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 /**
29 * @addtogroup Preconditioners
30 * @{
31 */
32
33 /**
34 * This class computes an Incomplete LU (ILU) decomposition of a sparse
35 * matrix, using either the same sparsity pattern or a different one. By
36 * incomplete we mean that unlike the exact decomposition, the incomplete one
37 * is also computed using sparse factors, and entries in the decomposition
38 * that do not fit into the given sparsity structure are discarded.
39 *
40 * The algorithm used by this class is essentially a copy of the algorithm
41 * given in the book Y. Saad: "Iterative methods for sparse linear systems",
42 * second edition, in section 10.3.2.
43 *
44 *
45 * <h3>Usage and state management</h3>
46 *
47 * Refer to SparseLUDecomposition documentation for suggested usage and state
48 * management. This class is used in the
49 * @ref step_22 "step-22"
50 * tutorial program.
51 *
52 * @note Instantiations for this template are provided for <tt>@<float@> and
53 * @<double@></tt>; others can be generated in application programs (see the
54 * section on
55 * @ref Instantiations
56 * in the manual).
57 */
58 template <typename number>
59 class SparseILU : public SparseLUDecomposition<number>
60 {
61 public:
62 /**
63 * Declare type for container size.
64 */
65 using size_type = typename SparseLUDecomposition<number>::size_type;
66
67 /**
68 * Constructor. Does nothing.
69 *
70 * Call the @p initialize function before using this object as
71 * preconditioner.
72 */
73 SparseILU() = default;
74
75 /**
76 * Make SparseLUDecomposition::AdditionalData accessible to this class as
77 * well.
78 */
79 using AdditionalData = typename SparseLUDecomposition<number>::AdditionalData;
80
81 /**
82 * Perform the incomplete LU factorization of the given matrix.
83 *
84 * This function needs to be called before an object of this class is used
85 * as preconditioner.
86 *
87 * For more details about possible parameters, see the class documentation
88 * of SparseLUDecomposition and the documentation of the @p
89 * SparseLUDecomposition::AdditionalData class.
90 *
91 * According to the @p parameters, this function creates a new
92 * SparsityPattern or keeps the previous sparsity or takes the sparsity
93 * given by the user to @p data. Then, this function performs the LU
94 * decomposition.
95 *
96 * After this function is called the preconditioner is ready to be used.
97 */
98 template <typename somenumber>
99 void
100 initialize(const SparseMatrix<somenumber> &matrix,
101 const AdditionalData &parameters = AdditionalData());
102
103 /**
104 * Apply the incomplete decomposition, i.e. do one forward-backward step
105 * $dst=(LU)^{-1}src$.
106 *
107 * The initialize() function needs to be called before.
108 */
109 template <typename somenumber>
110 void
111 vmult(Vector<somenumber> &dst, const Vector<somenumber> &src) const;
112
113
114 /**
115 * Apply the transpose of the incomplete decomposition, i.e. do one
116 * forward-backward step $dst=(LU)^{-T}src$.
117 *
118 * The initialize() function needs to be called before.
119 */
120 template <typename somenumber>
121 void
122 Tvmult(Vector<somenumber> &dst, const Vector<somenumber> &src) const;
123
124
125 /**
126 * Determine an estimate for the memory consumption (in bytes) of this
127 * object.
128 */
129 std::size_t
130 memory_consumption() const override;
131
132 /**
133 * @addtogroup Exceptions
134 * @{
135 */
136
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 DeclException1(ExcZeroPivot,
148 size_type,
149 << "While computing the ILU decomposition, the algorithm "
150 "found a zero entry on the diagonal of row "
151 << arg1
152 << ". The algorithm can not recover from this because it "
153 "wants to divide by this diagonal entry."
154 "\n\n"
155 "There are several reasons why this could be happening. "
156 "First, the matrix for which you try to compute a "
157 "decomposition might be singular. Second, the order in "
158 "which the algorithm considers might lead it to find "
159 "a zero diagonal entry even though different pivoting "
160 "strategies might not; the current implementation does "
161 "not do any pivoting (i.e., it works on rows/columns "
162 "in their natural order), and so you will trigger "
163 "this error if, for example, you have a zero in the "
164 "(0,0) entry of the matrix, even though this does "
165 "not imply that the matrix is singular."
166 "\n\n"
167 "It is possible that you can avoid the error if "
168 "you re-order degrees of freedom (using "
169 "the functions in namespace DoFRenumbering). You may "
170 "also want to consider \"strengthening the diagonal\", "
171 "using the AdditionalData::strengthen_diagonal parameter "
172 "you can set in the optional constructor argument of "
173 "this class.");
174 /** @} */
175 };
176
177 /** @} */
178 //---------------------------------------------------------------------------
179
180
181 DEAL_II_NAMESPACE_CLOSE
182
183 #endif // dealii_sparse_ilu_h