Debian Codegraph @

include/deal.II/base/signaling_nan.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 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_signaling_nan_h
16 #define dealii_signaling_nan_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/derivative_form.h>
21 #include <deal.II/base/point.h>
22 #include <deal.II/base/symmetric_tensor.h>
23 #include <deal.II/base/tensor.h>
24
25 #include <limits>
26
27
28 DEAL_II_NAMESPACE_OPEN
29
30 namespace numbers
31 {
32 namespace internal
33 {
34 /**
35 * A namespace for the implementation of functions that create signaling
36 * NaN objects. This is where the numbers::signaling_nan() function
37 * calls into.
38 */
39 namespace SignalingNaN
40 {
41 /**
42 * A general template for classes that know how to initialize objects of
43 * type @p T with signaling NaNs to denote invalid values.
44 *
45 * The real implementation of this class happens in (partial)
46 * specializations for particular values of the template argument @p T.
47 */
48 template <typename T>
49 struct NaNInitializer;
50
51
52 /**
53 * A specialization of the general NaNInitializer class that provides a
54 * function that returns a @p float value equal to the invalid signaling
55 * NaN.
56 */
57 template <>
58 struct NaNInitializer<float>
59 {
60 static float
61 invalid_element()
62 {
63 return std::numeric_limits<float>::signaling_NaN();
64 }
65 };
66
67
68 /**
69 * A specialization of the general NaNInitializer class that provides a
70 * function that returns a @p double value equal to the invalid
71 * signaling NaN.
72 */
73 template <>
74 struct NaNInitializer<double>
75 {
76 static double
77 invalid_element()
78 {
79 return std::numeric_limits<double>::signaling_NaN();
80 }
81 };
82
83
84 template <typename T, std::size_t width>
85 struct NaNInitializer<VectorizedArray<T, width>>
86 {
87 static VectorizedArray<T, width>
88 invalid_element()
89 {
90 return VectorizedArray<T, width>(
91 NaNInitializer<T>::invalid_element());
92 }
93 };
94
95
96 /**
97 * A specialization of the general NaNInitializer class that provides a
98 * function that returns a Tensor<1,dim> value whose components are
99 * invalid signaling NaN values.
100 */
101 template <int dim, typename T>
102 struct NaNInitializer<Tensor<1, dim, T>>
103 {
104 static Tensor<1, dim, T>
105 invalid_element()
106 {
107 Tensor<1, dim, T> nan_tensor;
108
109 for (unsigned int i = 0; i < dim; ++i)
110 nan_tensor[i] = NaNInitializer<T>::invalid_element();
111
112 return nan_tensor;
113 }
114 };
115
116
117
118 /**
119 * A specialization of the general NaNInitializer class that provides a
120 * function that returns a Tensor<rank,dim> value whose components are
121 * invalid signaling NaN values.
122 */
123 template <int rank, int dim, typename T>
124 struct NaNInitializer<Tensor<rank, dim, T>>
125 {
126 static Tensor<rank, dim, T>
127 invalid_element()
128 {
129 Tensor<rank, dim, T> nan_tensor;
130
131 // recursively initialize sub-tensors with invalid elements
132 for (unsigned int i = 0; i < dim; ++i)
133 nan_tensor[i] =
134 NaNInitializer<Tensor<rank - 1, dim, T>>::invalid_element();
135
136 return nan_tensor;
137 }
138 };
139
140
141
142 /**
143 * A specialization of the general NaNInitializer class that provides a
144 * function that returns a Tensor<rank,dim> value whose components are
145 * invalid signaling NaN values.
146 */
147 template <int dim, typename T>
148 struct NaNInitializer<Point<dim, T>>
149 {
150 static Point<dim, T>
151 invalid_element()
152 {
153 Point<dim, T> nan_point;
154
155 for (unsigned int i = 0; i < dim; ++i)
156 nan_point[i] = NaNInitializer<T>::invalid_element();
157
158 return nan_point;
159 }
160 };
161
162
163
164 /**
165 * A specialization of the general NaNInitializer class that provides a
166 * function that returns a SymmetricTensor<rank,dim> value whose
167 * components are invalid signaling NaN values.
168 */
169 template <int rank, int dim, typename T>
170 struct NaNInitializer<SymmetricTensor<rank, dim, T>>
171 {
172 static SymmetricTensor<rank, dim, T>
173 invalid_element()
174 {
175 // initialize symmetric tensors via the unrolled list of elements
176 T initializers
177 [SymmetricTensor<rank, dim, T>::n_independent_components];
178 for (unsigned int i = 0;
179 i < SymmetricTensor<rank, dim, T>::n_independent_components;
180 ++i)
181 initializers[i] = NaNInitializer<T>::invalid_element();
182
183 return SymmetricTensor<rank, dim, T>(initializers);
184 }
185 };
186
187
188
189 /**
190 * A specialization of the general NaNInitializer class that provides a
191 * function that returns a DerivativeForm<order,dim,spacedim> value
192 * whose components are invalid signaling NaN values.
193 */
194 template <int order, int dim, int spacedim, typename T>
195 struct NaNInitializer<DerivativeForm<order, dim, spacedim, T>>
196 {
197 static DerivativeForm<order, dim, spacedim, T>
198 invalid_element()
199 {
200 DerivativeForm<order, dim, spacedim, T> form;
201
202 // recursively initialize sub-tensors with invalid elements
203 for (unsigned int i = 0; i < spacedim; ++i)
204 form[i] = NaNInitializer<Tensor<order, dim, T>>::invalid_element();
205
206 return form;
207 }
208 };
209 } // namespace SignalingNaN
210 } // namespace internal
211
212
213
214 /**
215 * Provide an object of type @p T filled with a signaling NaN that will
216 * cause an exception when used in a computation. The content of these
217 * objects is a "signaling NaN" ("NaN" stands for "not a number", and
218 * "signaling" implies that at least on platforms where this is supported,
219 * any arithmetic operation using them terminates the program). The purpose
220 * of such objects is to use them as markers for invalid objects and
221 * arrays that are required to be initialized to valid values at some point,
222 * and to trigger an error when this later initialization does not happen
223 * before the first use. An example is code such as this:
224 * @code
225 * double x = numbers::signaling_nan<double>();
226 * if (some condition)
227 * {
228 * ...much code computing a,b,c...
229 * x = f(a,b,c);
230 * }
231 * else
232 * {
233 * ...more code...
234 * // bug: we forgot to assign a value to 'x'.
235 * }
236 *
237 * return std::sin(x);
238 * @endcode
239 * The bug is that the `else` branch forgot to write a value into the `x`
240 * variable. If your platform supports signaling NaNs, then this mistake
241 * will become apparent in the last line above because the program is
242 * going to be terminated by a floating point exception: The processor
243 * realizes that the code is attempting to do an operation on the signaling
244 * NaN still stored in `x` and aborts the program, thereby facilitating
245 * an easy way to find what the problem is. This would not have been an easy
246 * bug to find if one had just initialized `x` to zero in the first line
247 * (or just left it uninitialized altogether): In that case, the call to
248 * `std::sin` in the last line would have simply computed the sine of
249 * "something" if `some condition == false`, but this invalid results may
250 * not have been obvious to the calling site and would have required
251 * a substantial amount of debugging to uncover because downstream
252 * computations would simply have been wrong, without any indication of
253 * *why* they are wrong.
254 *
255 * @tparam T The type of the returned invalid object. This type can either
256 * be a scalar, or of type Tensor, SymmetricTensor, or DerivativeForm. Other
257 * types may be supported if there is a corresponding specialization of the
258 * internal::SignalingNaN::NaNInitializer class for this type.
259 *
260 * @note Because the type @p T is not used as a function argument, the
261 * compiler cannot deduce it from the type of arguments. Consequently, you
262 * have to provide it explicitly. For example, the line
263 * @code
264 * Tensor<1,dim> tensor = Utilities::signaling_nan<Tensor<1,dim> >();
265 * @endcode
266 * initializes a tensor with invalid values.
267 */
268 template <class T>
269 T
270 signaling_nan()
271 {
272 // dispatch to the classes in the internal namespace because there
273 // we can do partial specializations, which is not possible for
274 // template functions such as the current one
275 return internal::SignalingNaN::NaNInitializer<T>::invalid_element();
276 }
277 } // namespace numbers
278
279
280 DEAL_II_NAMESPACE_CLOSE
281
282 #endif