Debian Codegraph @

include/deal.II/lac/lapack_support.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2005 - 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_lapack_support_h
16 #define dealii_lapack_support_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/types.h>
23
24 DEAL_II_NAMESPACE_OPEN
25
26 namespace types
27 {
28 #ifdef LAPACK_WITH_64BIT_BLAS_INDICES
29 /**
30 * Integer type in BLAS.
31 */
32 using blas_int = long long;
33 #else
34 /**
35 * Integer type in BLAS.
36 */
37 using blas_int = int;
38 #endif
39 } // namespace types
40
41 /**
42 * A namespace containing constants, exceptions, enumerations, and other
43 * utilities used by the deal.II LAPACK bindings.
44 */
45 namespace LAPACKSupport
46 {
47 /**
48 * Most of the LAPACK functions one can apply to a matrix (e.g., by calling
49 * the member functions of this class) change its content in some ways. For
50 * example, they may invert the matrix, or may replace it by a matrix whose
51 * columns represent the eigenvectors of the original content of the matrix.
52 * The elements of this enumeration are therefore used to track what is
53 * currently being stored by this object.
54 */
55 enum State
56 {
57 /// Contents is actually a matrix.
58 matrix,
59 /// Contents is the inverse of a matrix.
60 inverse_matrix,
61 /// Contents is an LU decomposition.
62 lu,
63 /// Contents is a Cholesky decomposition.
64 cholesky,
65 /// Eigenvalue vector is filled
66 eigenvalues,
67 /// Matrix contains singular value decomposition,
68 svd,
69 /// Matrix is the inverse of a singular value decomposition
70 inverse_svd,
71 /// Contents is something useless.
72 unusable = 0x8000
73 };
74
75 /**
76 * %Function printing the name of a State.
77 */
78 inline const char *
79 state_name(State s)
80 {
81 switch (s)
82 {
83 case matrix:
84 return "matrix";
85 case inverse_matrix:
86 return "inverse matrix";
87 case lu:
88 return "lu decomposition";
89 case cholesky:
90 return "cholesky decomposition";
91 case eigenvalues:
92 return "eigenvalues";
93 case svd:
94 return "svd";
95 case inverse_svd:
96 return "inverse_svd";
97 case unusable:
98 return "unusable";
99 default:
100 return "unknown";
101 }
102 }
103
104 /**
105 * A matrix can have certain features allowing for optimization, but hard to
106 * test. These are listed here.
107 */
108 enum Property
109 {
110 /// No special properties
111 general = 0,
112 /// Matrix is symmetric
113 symmetric = 1,
114 /// Matrix is upper triangular
115 upper_triangular = 2,
116 /// Matrix is lower triangular
117 lower_triangular = 4,
118 /// Matrix is diagonal
119 diagonal = 6,
120 /// Matrix is in upper Hessenberg form
121 hessenberg = 8
122 };
123
124 /**
125 * %Function printing the name of a Property.
126 */
127 inline const char *
128 property_name(const Property s)
129 {
130 switch (s)
131 {
132 case general:
133 return "general";
134 case symmetric:
135 return "symmetric";
136 case upper_triangular:
137 return "upper triangular";
138 case lower_triangular:
139 return "lower triangular";
140 case diagonal:
141 return "diagonal";
142 case hessenberg:
143 return "Hessenberg";
144 }
145
146 DEAL_II_NOT_IMPLEMENTED();
147 return "invalid";
148 }
149
150 /**
151 * Character constant.
152 */
153 constexpr char A = 'A';
154 /**
155 * Character constant.
156 */
157 constexpr char N = 'N';
158 /**
159 * Character constant.
160 */
161 constexpr char O = 'O';
162 /**
163 * Character constant.
164 */
165 constexpr char T = 'T';
166 /**
167 * Character constant.
168 */
169 constexpr char U = 'U';
170 /**
171 * Character constant.
172 */
173 constexpr char L = 'L';
174 /**
175 * Character constant.
176 */
177 constexpr char V = 'V';
178 /**
179 * Integer constant.
180 */
181 constexpr types::blas_int zero = 0;
182 /**
183 * Integer constant.
184 */
185 constexpr types::blas_int one = 1;
186
187 /**
188 * A LAPACK function returned an error code.
189 */
190 DeclException2(ExcErrorCode,
191 std::string,
192 types::blas_int,
193 << "The function " << arg1 << " returned with an error code "
194 << arg2);
195
196 /**
197 * Exception thrown when a matrix is not in a suitable state for an
198 * operation. For instance, a LAPACK routine may have left the matrix in an
199 * unusable state, then vmult does not make sense anymore.
200 */
201 DeclException1(
202 ExcState,
203 State,
204 << "The function cannot be called while the matrix is in state "
205 << state_name(arg1));
206
207 /**
208 * Exception thrown when a matrix does not have suitable properties for an
209 * operation.
210 */
211 DeclException1(ExcProperty,
212 Property,
213 << "The function cannot be called with a "
214 << property_name(arg1) << " matrix.");
215
216 /**
217 * This exception is thrown if a certain LAPACK function is not available
218 * because no LAPACK installation was detected during configuration.
219 */
220 DeclException1(
221 ExcMissing,
222 std::string,
223 << "When you ran 'cmake' during installation of deal.II, no suitable "
224 << "installation of the BLAS or LAPACK library could be found. "
225 << "Consequently, the function <" << arg1 << "> can not be called. "
226 << "Refer to the readme at https://dealii.org/current/readme.html for "
227 << "information on how to ensure that deal.II picks up an existing "
228 << "BLAS and LAPACK installation at configuration time.");
229 } // namespace LAPACKSupport
230
231
232 DEAL_II_NAMESPACE_CLOSE
233
234 #endif