Debian Codegraph @

include/deal.II/lac/identity_matrix.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2006 - 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 #ifndef dealii_identity_matrix_h
16 #define dealii_identity_matrix_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/types.h>
22
23 #include <deal.II/lac/exceptions.h>
24
25 DEAL_II_NAMESPACE_OPEN
26
27 /**
28 * @addtogroup Matrix1
29 * @{
30 */
31
32
33 /**
34 * Implementation of a simple class representing the identity matrix of a
35 * given size, i.e. a matrix with entries $A_{ij}=\delta_{ij}$. While it has
36 * the most important ingredients of a matrix, in particular that one can ask
37 * for its size and perform matrix-vector products with it, a matrix of this
38 * type is really only useful in two contexts: preconditioning and
39 * initializing other matrices.
40 *
41 * <h4>Initialization</h4>
42 *
43 * The main usefulness of this class lies in its ability to initialize other
44 * matrix, like this:
45 * @code
46 * FullMatrix<double> identity (IdentityMatrix(10));
47 * @endcode
48 *
49 * This creates a $10\times 10$ matrix with ones on the diagonal and zeros
50 * everywhere else. Most matrix types, in particular FullMatrix and
51 * SparseMatrix, have conversion constructors and assignment operators for
52 * IdentityMatrix, and can therefore be filled rather easily with identity
53 * matrices.
54 *
55 *
56 * <h4>Preconditioning</h4>
57 *
58 * No preconditioning at all is equivalent to preconditioning with
59 * preconditioning with the identity matrix. deal.II has a specialized class
60 * for this purpose, PreconditionIdentity, than can be used in a context as
61 * shown in the documentation of that class. The present class can be used in
62 * much the same way, although without any additional benefit:
63 * @code
64 * SolverControl solver_control (1000, 1e-12);
65 * SolverCG<> cg (solver_control);
66 * cg.solve (system_matrix, solution, system_rhs,
67 * IdentityMatrix(solution.size()));
68 * @endcode
69 */
70 class IdentityMatrix
71 {
72 public:
73 /**
74 * Declare type for container size.
75 */
76 using size_type = types::global_dof_index;
77
78 /**
79 * Default constructor. Creates a zero-sized matrix that should be resized
80 * later on using the reinit() function.
81 */
82 IdentityMatrix();
83
84 /**
85 * Constructor. Creates a identity matrix of size #n.
86 */
87 explicit IdentityMatrix(const size_type n);
88
89 /**
90 * Resize the matrix to be of size #n by #n.
91 */
92 void
93 reinit(const size_type n);
94
95 /**
96 * Number of rows of this matrix. For the present matrix, the number of rows
97 * and columns are equal, of course.
98 */
99 size_type
100 m() const;
101
102 /**
103 * Number of columns of this matrix. For the present matrix, the number of
104 * rows and columns are equal, of course.
105 */
106 size_type
107 n() const;
108
109 /**
110 * Matrix-vector multiplication. For the present case, this of course
111 * amounts to simply copying the input vector to the output vector.
112 */
113 template <typename OutVectorType, typename InVectorType>
114 void
115 vmult(OutVectorType &out, const InVectorType &in) const;
116
117 /**
118 * Matrix-vector multiplication with addition to the output vector. For the
119 * present case, this of course amounts to simply adding the input vector to
120 * the output vector.
121 */
122 template <typename OutVectorType, typename InVectorType>
123 void
124 vmult_add(OutVectorType &out, const InVectorType &in) const;
125
126 /**
127 * Matrix-vector multiplication with the transpose matrix. For the present
128 * case, this of course amounts to simply copying the input vector to the
129 * output vector.
130 */
131 template <typename OutVectorType, typename InVectorType>
132 void
133 Tvmult(OutVectorType &out, const InVectorType &in) const;
134
135
136 /**
137 * Matrix-vector multiplication with the transpose matrix, with addition to
138 * the output vector. For the present case, this of course amounts to simply
139 * adding the input vector to the output vector.
140 */
141 template <typename OutVectorType, typename InVectorType>
142 void
143 Tvmult_add(OutVectorType &out, const InVectorType &in) const;
144
145 private:
146 /**
147 * Number of rows and columns of this matrix.
148 */
149 size_type size;
150 };
151
152
153
154 // ------------------------- inline and template functions -------------
155 #ifndef DOXYGEN
156
157
158 inline IdentityMatrix::IdentityMatrix()
159 : size(0)
160 {}
161
162
163
164 inline IdentityMatrix::IdentityMatrix(const size_type n)
165 : size(n)
166 {}
167
168
169
170 inline void
171 IdentityMatrix::reinit(const size_type n)
172 {
173 size = n;
174 }
175
176
177
178 inline IdentityMatrix::size_type
179 IdentityMatrix::m() const
180 {
181 return size;
182 }
183
184
185
186 inline IdentityMatrix::size_type
187 IdentityMatrix::n() const
188 {
189 return size;
190 }
191
192
193
194 template <typename OutVectorType, typename InVectorType>
195 inline void
196 IdentityMatrix::vmult(OutVectorType &out, const InVectorType &in) const
197 {
198 Assert(out.size() == size, ExcDimensionMismatch(out.size(), size));
199 Assert(in.size() == size, ExcDimensionMismatch(in.size(), size));
200
201 out = in;
202 }
203
204
205
206 template <typename OutVectorType, typename InVectorType>
207 inline void
208 IdentityMatrix::vmult_add(OutVectorType &out, const InVectorType &in) const
209 {
210 Assert(out.size() == size, ExcDimensionMismatch(out.size(), size));
211 Assert(in.size() == size, ExcDimensionMismatch(in.size(), size));
212
213 out += in;
214 }
215
216
217
218 template <typename OutVectorType, typename InVectorType>
219 inline void
220 IdentityMatrix::Tvmult(OutVectorType &out, const InVectorType &in) const
221 {
222 Assert(out.size() == size, ExcDimensionMismatch(out.size(), size));
223 Assert(in.size() == size, ExcDimensionMismatch(in.size(), size));
224
225 out = in;
226 }
227
228
229
230 template <typename OutVectorType, typename InVectorType>
231 inline void
232 IdentityMatrix::Tvmult_add(OutVectorType &out, const InVectorType &in) const
233 {
234 Assert(out.size() == size, ExcDimensionMismatch(out.size(), size));
235 Assert(in.size() == size, ExcDimensionMismatch(in.size(), size));
236
237 out += in;
238 }
239
240
241 #endif
242
243 /** @} */
244
245 DEAL_II_NAMESPACE_CLOSE
246
247 #endif