Debian Codegraph @

include/deal.II/base/utilities.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_utilities_h
16 #define dealii_utilities_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21 #include <deal.II/base/types.h>
22
23 #include <boost/archive/binary_iarchive.hpp>
24 #include <boost/archive/binary_oarchive.hpp>
25 #include <boost/core/demangle.hpp>
26 #include <boost/iostreams/device/array.hpp>
27 #include <boost/iostreams/device/back_inserter.hpp>
28 #include <boost/iostreams/filtering_streambuf.hpp>
29 #include <boost/serialization/array.hpp>
30 #include <boost/serialization/complex.hpp>
31 #include <boost/serialization/vector.hpp>
32
33 #include <cstddef>
34 #include <functional>
35 #include <string>
36 #include <tuple>
37 #include <type_traits>
38 #include <typeinfo>
39 #include <utility>
40 #include <vector>
41
42 #ifdef DEAL_II_WITH_ZLIB
43 # include <boost/iostreams/filter/gzip.hpp>
44 #endif
45
46 DEAL_II_NAMESPACE_OPEN
47
48 // forward declare Point
49 #ifndef DOXYGEN
50 template <int dim, typename Number>
51 DEAL_II_CXX20_REQUIRES(dim >= 0)
52 class Point;
53 #endif
54
55 /**
56 * A namespace for utility functions that are not particularly specific to
57 * finite element computing or numerical programs, but nevertheless are needed
58 * in various contexts when writing applications.
59 *
60 * @ingroup utilities
61 */
62 namespace Utilities
63 {
64 /**
65 * Return a string of the form "deal.II version x.y.z" where "x.y.z"
66 * identifies the version of deal.II you are using. This information
67 * is also provided by the DEAL_II_PACKAGE_NAME and
68 * DEAL_II_PACKAGE_VERSION preprocessor variables.
69 */
70 std::string
71 dealii_version_string();
72
73 /**
74 * Assign to each point in @p points an index using the Hilbert space filling curve.
75 * To that end, a bounding box for @p points will be determined, based on which their
76 * integer coordinates are calculated.
77 * The linear index is given as a dim-collection of bits, from high to low.
78 * This is done in order to keep the maximum resolution in terms of bit depth
79 * along each axis. Note that this dim-integer index can still be easily used
80 * for sorting and ordering, for example using the lexicographic ordering of
81 * tuples of integers.
82 *
83 * The depth of the Hilbert curve (i.e. the number of bits per dimension) by
84 * default is equal to <code>64</code>.
85 *
86 * @note This function can also handle degenerate cases, e.g. when the bounding
87 * box has zero size in one of the dimensions.
88 */
89 template <int dim, typename Number>
90 std::vector<std::array<std::uint64_t, dim>>
91 inverse_Hilbert_space_filling_curve(
92 const std::vector<Point<dim, Number>> &points,
93 const int bits_per_dim = 64);
94
95 /**
96 * Same as above, but for points in integer coordinates.
97 */
98 template <int dim>
99 std::vector<std::array<std::uint64_t, dim>>
100 inverse_Hilbert_space_filling_curve(
101 const std::vector<std::array<std::uint64_t, dim>> &points,
102 const int bits_per_dim = 64);
103
104 /**
105 * Pack the least significant @p bits_per_dim bits from each element of @p index
106 * (starting from last) into a single unsigned integer. The last element
107 * of @p index will be used to set the first @p bits_per_dim bits in the
108 * resulting integer, the second to last element is used to set the next @p bits_per_dim bits,
109 * etc.. To fit all the data into the output, the following should hold
110 * <code>bits\_per\_dim * dim <= 64</code>.
111 *
112 * The function is useful in debugging and visualization of indices returned
113 * by inverse_Hilbert_space_filling_curve().
114 *
115 * @note There is no need to use this function in order to compare indices
116 * returned by inverse_Hilbert_space_filling_curve(), as that can easily be
117 * done via <code>std::lexicographical_compare()</code>.
118 */
119 template <int dim>
120 std::uint64_t
121 pack_integers(const std::array<std::uint64_t, dim> &index,
122 const int bits_per_dim);
123
124 /**
125 * If the library is configured with ZLIB, then this function compresses the
126 * input string and returns a non-zero terminated string containing the
127 * compressed input.
128 *
129 * If the library was not configured with ZLIB enabled, the returned string
130 * is identical to the input string.
131 *
132 * @param[in] input The string to compress
133 *
134 * @return A compressed version of the input string
135 */
136 std::string
137 compress(const std::string &input);
138
139 /**
140 * If the library is configured with ZLIB, then this function assumes that the
141 * input string has been compressed using the compress() function, and returns
142 * the original decompressed string.
143 *
144 * If the library was not configured with ZLIB enabled, the returned string
145 * is identical to the input string.
146 *
147 * @param[in] compressed_input A compressed string, as returned by the
148 * function compress()
149 *
150 * @return The original uncompressed string.
151 */
152 std::string
153 decompress(const std::string &compressed_input);
154
155 /**
156 * Encodes the binary input as a base64 string.
157 *
158 * Base64 is a group of binary-to-text encoding schemes that represent binary
159 * data in an ASCII string format by translating it into a radix-64
160 * representation. Base64 is designed to carry data stored in binary formats
161 * across channels that only reliably support text content. It is used also
162 * to store binary formats in a machine independent way.
163 *
164 * @param binary_input A vector of characters, representing your input as
165 * binary data.
166 * @return A string containing the binary input as a base64 string.
167 */
168 std::string
169 encode_base64(const std::vector<unsigned char> &binary_input);
170
171 /**
172 * Decodes a base64 string into a binary output.
173 *
174 * This is the inverse of the encode_base64() function above.
175 *
176 * @param base64_input A string that contains the input in base64 format.
177 * @return A vector of characters that represents your input as binary data.
178 */
179 std::vector<unsigned char>
180 decode_base64(const std::string &base64_input);
181
182 /**
183 * Convert a number @p value to a string, with as many digits as given to
184 * fill with leading zeros.
185 *
186 * If the second parameter is left at its default value, the number is not
187 * padded with leading zeros. The result is then the same as if the standard
188 * C++ `std::to_string` (or the older C function `itoa()`) had been called.
189 *
190 * This function takes an `unsigned int` as argument. As a consequence,
191 * if you call it with a `signed int` (which is of course the same
192 * type as `int`), the argument is implicitly converted to
193 * unsigned integers and negative numbers may not be printed as you had
194 * hoped. Similarly, if you call the function with a `long int`, the
195 * printed result might show the effects of an overflow upon conversion
196 * to `unsigned int`.
197 *
198 * @note The use of this function is discouraged and users should use
199 * <code>Utilities::to_string()</code> instead. In its current
200 * implementation the function simply calls <code>to_string@<unsigned
201 * int@>()</code>.
202 */
203 std::string
204 int_to_string(const unsigned int value,
205 const unsigned int digits = numbers::invalid_unsigned_int);
206
207 /**
208 * Convert a number @p value to a string, with @p digits characters. The
209 * string is padded with leading zeros, after a possible minus sign.
210 * Therefore the total number of padding zeros is @p digits minus any signs,
211 * decimal points and digits of @p value.
212 *
213 * If the second parameter is left at its default value, the number is not
214 * padded with leading zeros. The result is then the same as if the C++
215 * function `std::to_string()` had been called (for integral types),
216 * or if `boost::lexical_cast()` had been called (for all other types).
217 */
218 template <typename number>
219 std::string
220 to_string(const number value,
221 const unsigned int digits = numbers::invalid_unsigned_int);
222
223 /**
224 * Determine how many digits are needed to represent numbers at most as
225 * large as the given number.
226 */
227 unsigned int
228 needed_digits(const unsigned int max_number);
229
230 /**
231 * This function allows to cut off a floating point number @p number
232 * after @p n_digits of accuracy, i.e., after @p n_digits decimal places
233 * in scientific floating point notation. When interpreted as rounding
234 * operation, this function reduces the absolute value of a floating point
235 * number and always rounds towards zero, since decimal places are simply
236 * cut off.
237 */
238 template <typename Number>
239 Number
240 truncate_to_n_digits(const Number number, const unsigned int n_digits);
241
242 /**
243 * Given a string, convert it to an integer. Throw an assertion if that is
244 * not possible.
245 */
246 int
247 string_to_int(const std::string &s);
248
249 /**
250 * Return a string describing the dimensions of the object. Often, functions
251 * in the deal.II library as well as in user codes need to define a string
252 * containing the template dimensions of some objects defined using two
253 * template parameters: dim (the topological dimension of the object) and
254 * spacedim (the dimension of the embedding Euclidean space). Since in all
255 * deal.II classes, by default spacedim is equal to dimension, the above
256 * string is usually contracted to "<dim>", instead of "<dim,spacedim>".
257 * This function returns a string containing "dim" if dim is equal to
258 * spacedim, otherwise it returns "dim,spacedim".
259 */
260 std::string
261 dim_string(const int dim, const int spacedim);
262
263 /**
264 * Given a list of strings, convert it to a list of integers. Throw an
265 * assertion if that is not possible.
266 */
267 std::vector<int>
268 string_to_int(const std::vector<std::string> &s);
269
270 /**
271 * Given a string, convert it to an double. Throw an assertion if that is
272 * not possible.
273 */
274 double
275 string_to_double(const std::string &s);
276
277
278 /**
279 * Given a list of strings, convert it to a list of doubles. Throw an
280 * assertion if that is not possible.
281 */
282 std::vector<double>
283 string_to_double(const std::vector<std::string> &s);
284
285
286 /**
287 * Given a string that contains text separated by a @p delimiter, split it
288 * into its components; for each component, remove leading and trailing
289 * spaces. The default value of the delimiter is a comma, so that the
290 * function splits comma separated lists of strings.
291 *
292 * To make data input from tables simpler, if the input string ends in a
293 * delimiter (possibly followed by an arbitrary amount of whitespace), then
294 * this last delimiter is ignored. For example,
295 * @code
296 * Utilities::split_string_list("abc; def; ghi; ", ';');
297 * @endcode
298 * yields the same 3-element list of output <code>{"abc","def","ghi"}</code>
299 * as you would get if the input had been
300 * @code
301 * Utilities::split_string_list("abc; def; ghi", ';');
302 * @endcode
303 * or
304 * @code
305 * Utilities::split_string_list("abc; def; ghi;", ';');
306 * @endcode
307 * As a consequence of this rule, a call like
308 * @code
309 * Utilities::split_string_list(" ; ", ';');
310 * @endcode
311 * yields a one-element list. Because of the trimming of whitespace, the
312 * single element is the empty string.
313 *
314 * This function can digest the case that the delimiter is a space. In this
315 * case, it returns all words in the string. Combined with the rules above,
316 * this implies that
317 * @code
318 * Utilities::split_string_list("abc def ghi ", ' ');
319 * @endcode
320 * yields again the 3-element list of output
321 * <code>{"abc","def","ghi"}</code> from above despite the presence of space
322 * at the end of the string. Furthermore,
323 * @code
324 * Utilities::split_string_list(" ", ' ');
325 * @endcode
326 * yields an empty list regardless of the number of spaces in the string.
327 */
328 std::vector<std::string>
329 split_string_list(const std::string &s, const std::string &delimiter = ",");
330
331
332 /**
333 * Specialization of split_string_list() for the case where the delimiter
334 * is a single char.
335 */
336 std::vector<std::string>
337 split_string_list(const std::string &s, const char delimiter);
338
339
340 /**
341 * Take a text, usually a documentation or something, and try to break it
342 * into individual lines of text at most @p width characters wide, by
343 * breaking at positions marked by @p delimiter in the text. If this is not
344 * possible, return the shortest lines that are longer than @p width. The
345 * default value of the delimiter is a space character. If original_text
346 * contains newline characters (\n), the string is split at these locations,
347 * too.
348 */
349 std::vector<std::string>
350 break_text_into_lines(const std::string &original_text,
351 const unsigned int width,
352 const char delimiter = ' ');
353
354 /**
355 * Return true if the given pattern string appears in the first position of
356 * the string.
357 */
358 bool
359 match_at_string_start(const std::string &name, const std::string &pattern);
360
361 /**
362 * Read a (signed) integer starting at the position in @p name indicated by
363 * the second argument, and return this integer as a pair together with how
364 * many characters it takes up in the string.
365 *
366 * If no integer can be read at the indicated position, return
367 * (-1,numbers::invalid_unsigned_int)
368 */
369 std::pair<int, unsigned int>
370 get_integer_at_position(const std::string &name, const unsigned int position);
371
372 /**
373 * Return a string with all occurrences of @p from in @p input replaced by
374 * @p to.
375 */
376 std::string
377 replace_in_string(const std::string &input,
378 const std::string &from,
379 const std::string &to);
380
381 /**
382 * Return a string with all standard whitespace characters (including
383 * '<tt>\\t</tt>', '<tt>\\n</tt>', and '<tt>\\r</tt>') at the beginning and
384 * end of @p input removed.
385 */
386 std::string
387 trim(const std::string &input);
388
389 /**
390 * Generate a random number from a normalized Gaussian probability
391 * distribution centered around @p a and with standard deviation @p sigma.
392 * The returned number will be different every time the function is called.
393 *
394 * This function is reentrant, i.e., it can safely be called from multiple
395 * threads at the same time. In addition, each thread will get the same
396 * sequence of numbers every time. On the other hand, if you run
397 * Threads::Task objects via the Threading Building Blocks, then tasks will
398 * be assigned to mostly random threads, and may get a different sequence of
399 * random numbers in different runs of the program, since a previous task
400 * may already have consumed the first few random numbers generated for the
401 * thread you're on. If this is a problem, you need to create your own
402 * random number generator objects every time you want to start from a
403 * defined point.
404 *
405 * @note Like the system function rand(), this function produces the same
406 * sequence of random numbers every time a program is started. This is an
407 * important property for debugging codes, but it makes it impossible to
408 * really verify statistical properties of a code. For `rand()`, you can call
409 * `srand()` to "seed" the random number generator to get different sequences
410 * of random numbers every time a program is called. However, this function
411 * does not allow seeding the random number generator. If you need this, as
412 * above, use one of the C++ or BOOST facilities.
413 */
414 double
415 generate_normal_random_number(const double a, const double sigma);
416
417 /**
418 * Return a string description of the type of the variable @p t.
419 *
420 * In general, C++ uses mangled names to identify types. This function
421 * uses boost::core::demangle to return a human readable string describing
422 * the type of the variable passed as argument.
423 *
424 * While the function takes the argument `t`, it does not actually use
425 * its value but only the type of `t` for its output.
426 */
427 template <class T>
428 std::string
429 type_to_string(const T &t);
430
431 /**
432 * Calculate a fixed power, provided as a template argument, of a number.
433 *
434 * This function provides an efficient way to calculate things like
435 * $t^N$ where <code>N</code> is a known number at compile time.
436 * The function computes the power of $t$ via the "recursive doubling"
437 * approach in which, for example, $t^7$ is computed as
438 * @f{align*}{
439 * t^7 = (tttt)(tt)(t)
440 * @f}
441 * where computing $tt$ requires one product, computing $tttt$ is
442 * achieved by multiplying the previously computed $tt$ by itself
443 * (requiring another multiplication), and then the product is computed
444 * via two more multiplications for a total of 4 multiplications
445 * instead of the naively necessary 6.
446 *
447 * The major savings this function generates result, however, from the
448 * fact that it exploits that we have an integer power of the argument $t$.
449 * The alternative to computing such powers, `std::pow(t,7)` uses the
450 * `std::pow` function that takes the exponent as a floating point number
451 * and, because it has to cater to the complexities of the general situation,
452 * is vastly slower.
453 *
454 * Use this function as in `fixed_power<dim> (t)` or `fixed_power<7> (t)`.
455 */
456 template <int N, typename T>
457 constexpr T
458 fixed_power(const T t);
459
460 /**
461 * A replacement for <code>std::pow</code> that allows compile-time
462 * calculations for constant expression arguments and if the exponent
463 * is a positive integer. The @p base must be an arithmetic type
464 * (i.e., an integer or floating point type),
465 * and the exponent @p iexp must not be negative.
466 */
467 template <typename T, typename = std::enable_if_t<std::is_arithmetic_v<T>>>
468 constexpr DEAL_II_HOST_DEVICE T
469 pow(const T base, const int iexp);
470
471 /**
472 * Optimized replacement for <tt>std::lower_bound</tt> for searching within
473 * the range of column indices. Slashes execution time by approximately one
474 * half for the present application, partly because the binary search is
475 * replaced by a linear search for small loop lengths.
476 *
477 * Another reason for this function is rather obscure: when using the GCC
478 * libstdc++ function std::lower_bound, complexity is O(log(N)) as required.
479 * However, when using the debug version of the GCC libstdc++ as we do when
480 * running the testsuite, then std::lower_bound tests whether the sequence
481 * is in fact partitioned with respect to the pivot 'value' (i.e. in essence
482 * that the sequence is sorted as required for binary search to work).
483 * However, verifying this means that the complexity of std::lower_bound
484 * jumps to O(N); we call this function O(N) times below, making the overall
485 * complexity O(N**2). The consequence is that a few tests with big meshes
486 * completely run off the wall time limit for tests and fail with the
487 * libstdc++ debug mode
488 *
489 * This function simply makes the assumption that the sequence is sorted,
490 * and we simply don't do the additional check.
491 */
492 template <typename Iterator, typename T>
493 Iterator
494 lower_bound(Iterator first, Iterator last, const T &val);
495
496 /**
497 * The same function as above, but taking an argument that is used to
498 * compare individual elements of the sequence of objects pointed to by the
499 * iterators.
500 */
501 template <typename Iterator, typename T, typename Comp>
502 Iterator
503 lower_bound(Iterator first, Iterator last, const T &val, const Comp comp);
504
505 /**
506 * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
507 * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the reverse
508 * permutation $q_i=N-1-p_i$.
509 */
510 template <typename Integer>
511 std::vector<Integer>
512 reverse_permutation(const std::vector<Integer> &permutation);
513
514 /**
515 * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
516 * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the inverse
517 * permutation $q_0\ldots q_{N-1}$ so that $q_{p_i}=p_{q_i}=i$.
518 */
519 template <typename Integer>
520 std::vector<Integer>
521 invert_permutation(const std::vector<Integer> &permutation);
522
523 /**
524 * Given an arbitrary object of type `T`, use boost::serialization utilities
525 * to pack the object into a vector of characters and append it to the
526 * given buffer. The number of elements that have been added to the buffer
527 * will be returned. The object can be unpacked using the Utilities::unpack
528 * function below.
529 *
530 * If the library has been compiled with ZLIB enabled, then the output buffer
531 * can be compressed. This can be triggered with the parameter
532 * @p allow_compression, and is only of effect if ZLIB is enabled.
533 *
534 * If many consecutive calls with the same buffer are considered, it is
535 * recommended for reasons of performance to ensure that its capacity is
536 * sufficient.
537 *
538 * This function considers a number of special cases for which packing (and
539 * unpacking) can be simplified. These are:
540 * - If the object of type `T` is relatively small (less than 256 bytes) and
541 * if `T` satisfies `std::is_trivially_copyable`, then it is copied bit
542 * by bit into the output buffer.
543 * - If no compression is requested, and if the object is a vector of objects
544 * whose type `T` satisfies `std::is_trivially_copyable`, then packing
545 * implies copying the length of the vector into the destination buffer
546 * followed by a bit-by-bit copy of the contents of the vector. A
547 * similar process is used for vectors of vectors of objects whose type
548 * `T` satisfies `std::is_trivially_copyable`.
549 * - Finally, if the type `T` of the object to be packed is std::tuple<>
550 * (i.e., a tuple without any elements as indicated by the empty argument
551 * list) and if no compression is requested, then this
552 * type is considered an "empty" type and it is packed
553 * into a zero byte buffer. Using empty types is occasionally useful when
554 * sending messages to other processes if the important part about the
555 * message is that it is *sent*, not what it *contains* -- in other words,
556 * it puts the receiver on notice of something, without having to provide
557 * any details. In such cases, it is helpful if the message body can be
558 * empty -- that is, have length zero -- and using std::tuple<> facilitates
559 * this by providing a type which the present function packs into an
560 * empty output buffer, given that many deal.II functions send objects
561 * only after calling pack() to serialize them.
562 *
563 * In several of the special cases above, the `std::is_trivially_copyable`
564 * property is important, see
565 * https://en.cppreference.com/w/cpp/types/is_trivially_copyable .
566 * For a type `T` to satisfy this property essentially means that an object
567 * `t2` of this type can be initialized by copying another object `t1`
568 * bit-by-bit into the memory space of `t2`. In particular, this is the case
569 * for built-in types such as `int`, `double`, or `char`, as well as
570 * structures and classes that only consist of such types and that have
571 * neither user-defined constructors nor `virtual` functions. In practice,
572 * and together with the fact that vectors and vector-of-vectors of these
573 * types are also special-cased, this covers many of the most common kinds of
574 * messages one sends around with MPI or one wants to serialize (the two
575 * most common use cases for this function).
576 */
577 template <typename T>
578 std::size_t
579 pack(const T &object,
580 std::vector<char> &dest_buffer,
581 const bool allow_compression = true);
582
583 /**
584 * Creates and returns a buffer solely for the given object, using the
585 * above mentioned pack function (including all of its special cases).
586 *
587 * If the library has been compiled with ZLIB enabled, then the output buffer
588 * can be compressed. This can be triggered with the parameter
589 * @p allow_compression, and is only of effect if ZLIB is enabled.
590 */
591 template <typename T>
592 std::vector<char>
593 pack(const T &object, const bool allow_compression = true);
594
595 /**
596 * Given a vector of characters, obtained through a call to the function
597 * Utilities::pack, restore its content in an object of type `T`.
598 *
599 * This function uses boost::serialization utilities to unpack the object
600 * from a vector of characters, and it is the inverse of the function
601 * Utilities::pack(). It considers the same set of special cases as
602 * documented with the pack() function.
603 *
604 * The @p allow_compression parameter denotes if the buffer to
605 * read from could have been previously compressed with ZLIB, and
606 * is only of effect if ZLIB is enabled.
607 *
608 * @note Since no arguments to this function depend on the template type
609 * @p T, you must manually specify the template argument when calling
610 * this function.
611 *
612 * @note If you want to pack() or unpack() arrays of objects, then the
613 * following works:
614 * @code
615 * double array[3] = {1,2,3};
616 * std::vector<char> buffer = Utilities::pack(array);
617 * @endcode
618 * However, the converse does not:
619 * @code
620 * array = Utilities::unpack<double[3]>(buffer);
621 * @endcode
622 * This is because C++ does not allow functions to return arrays.
623 * Consequently, there is a separate unpack() function for arrays, see
624 * below.
625 */
626 template <typename T>
627 T
628 unpack(const std::vector<char> &buffer, const bool allow_compression = true);
629
630 /**
631 * Same unpack function as above, but takes constant iterators on
632 * (a fraction of) a given packed buffer of type std::vector<char> instead.
633 *
634 * The @p allow_compression parameter denotes if the buffer to
635 * read from could have been previously compressed with ZLIB, and
636 * is only of effect if ZLIB is enabled.
637 */
638 template <typename T>
639 T
640 unpack(const std::vector<char>::const_iterator &cbegin,
641 const std::vector<char>::const_iterator &cend,
642 const bool allow_compression = true);
643
644 /**
645 * Given a vector of characters, obtained through a call to the function
646 * Utilities::pack, restore its content in an array of type T.
647 *
648 * This function uses boost::serialization utilities to unpack the object
649 * from a vector of characters, and it is the inverse of the function
650 * Utilities::pack().
651 *
652 * The @p allow_compression parameter denotes if the buffer to
653 * read from could have been previously compressed with ZLIB, and
654 * is only of effect if ZLIB is enabled.
655 *
656 * @note This function exists due to a quirk of C++. Specifically,
657 * if you want to pack() or unpack() arrays of objects, then the
658 * following works:
659 * @code
660 * double array[3] = {1,2,3};
661 * std::vector<char> buffer = Utilities::pack(array);
662 * @endcode
663 * However, the converse does not:
664 * @code
665 * array = Utilities::unpack<double[3]>(buffer);
666 * @endcode
667 * This is because C++ does not allow functions to return arrays.
668 * The current function therefore allows to write
669 * @code
670 * Utilities::unpack(buffer, array);
671 * @endcode
672 * Note that unlike the other unpack() function, it is not necessary
673 * to explicitly specify the template arguments since they can be
674 * deduced from the second argument.
675 */
676 template <typename T, int N>
677 void
678 unpack(const std::vector<char> &buffer,
679 T (&unpacked_object)[N],
680 const bool allow_compression = true);
681
682 /**
683 * Same unpack function as above, but takes constant iterators on
684 * (a fraction of) a given packed buffer of type std::vector<char> instead.
685 *
686 * The @p allow_compression parameter denotes if the buffer to
687 * read from could have been previously compressed with ZLIB, and
688 * is only of effect if ZLIB is enabled.
689 */
690 template <typename T, int N>
691 void
692 unpack(const std::vector<char>::const_iterator &cbegin,
693 const std::vector<char>::const_iterator &cend,
694 T (&unpacked_object)[N],
695 const bool allow_compression = true);
696
697 /**
698 * Check if the bit at position @p n in @p number is set.
699 */
700 bool
701 get_bit(const unsigned char number, const unsigned int n);
702
703
704 /**
705 * Set the bit at position @p n in @p number to value @p x.
706 */
707 void
708 set_bit(unsigned char &number, const unsigned int n, const bool x);
709
710
711 /**
712 * Convert an object of type `std::unique_ptr<From>` to an object of
713 * type `std::unique_ptr<To>`, where it is assumed that we can cast
714 * the pointer to `From` to a pointer to `To` using a `dynamic_cast`
715 * -- in other words, we assume that `From` and `To` are connected
716 * through a class hierarchy, and that the object pointed to is in
717 * fact of a type that contains both a `From` and a `To`. An example
718 * is if either `To` is derived from `From` or the other way around.
719 *
720 * The function throws an exception of type `std::bad_cast` if the
721 * `dynamic_cast` does not succeed. This is the same exception you
722 * would get if a regular `dynamic_cast` between object types (but not
723 * pointer types) does not succeed.
724 *
725 * An example of how this function works is as follows:
726 * @code
727 * // A base class. Assume that it has virtual
728 * // functions so that dynamic_cast can work.
729 * class B
730 * {
731 * ...
732 * };
733 *
734 * // A derived class
735 * class D : public B
736 * {
737 * ...
738 * };
739 *
740 * // A factory function
741 * std::unique_ptr<B> create_object (...)
742 * {
743 * ...
744 * }
745 *
746 * void foo (...)
747 * {
748 * std::unique_ptr<B> b = create_object (...);
749 *
750 * // Assume that we know for some reason that the object above must
751 * // have created a D object but returned it as a std::unique_ptr<B>.
752 * // In order to access the D functionality, we need to cast the
753 * // pointer. Use the equivalent to dynamic_cast:
754 * std::unique_ptr<D> d = dynamic_unique_cast<D>(std::move(b));
755 *
756 * // If the object really was a D, then 'd' now points to it. Note
757 * // also that in accordance with the semantics of std::unique_ptr,
758 * // it was necessary to std::move the 'b' object, and indeed 'b'
759 * // now no longer points to anything -- ownership has been
760 * // transferred to 'd'!
761 * @endcode
762 *
763 * @note This function does not try to convert the `Deleter` objects stored
764 * by `std::unique_ptr` objects. The function therefore only works if the
765 * deleter objects are at their defaults, i.e., if they are of type
766 * `std::default_delete<To>` and `std::default_delete<From>`.
767 */
768 template <typename To, typename From>
769 std::unique_ptr<To>
770 dynamic_unique_cast(std::unique_ptr<From> &&p);
771
772 /**
773 * Return underlying value. Default: return input.
774 */
775 template <typename T>
776 T &
777 get_underlying_value(T &p);
778
779 /**
780 * Return underlying value. Specialization for std::shared_ptr<T>.
781 */
782 template <typename T>
783 T &
784 get_underlying_value(std::shared_ptr<T> &p);
785
786 /**
787 * Return underlying value. Specialization for const std::shared_ptr<T>.
788 */
789 template <typename T>
790 T &
791 get_underlying_value(const std::shared_ptr<T> &p);
792
793 /**
794 * Return underlying value. Specialization for std::unique_ptr<T>.
795 */
796 template <typename T>
797 T &
798 get_underlying_value(std::unique_ptr<T> &p);
799
800 /**
801 * Return underlying value. Specialization for const std::unique_ptr<T>.
802 */
803 template <typename T>
804 T &
805 get_underlying_value(const std::unique_ptr<T> &p);
806
807 /**
808 * A namespace for utility functions that probe system properties.
809 *
810 * @ingroup utilities
811 */
812 namespace System
813 {
814 /**
815 * Return the CPU load as returned by "uptime". Note that the
816 * interpretation of this number depends on the actual number of
817 * processors in the machine. This is presently only implemented on Linux,
818 * using the /proc/loadavg pseudo-file, on other systems we simply return
819 * zero.
820 */
821 double
822 get_cpu_load();
823
824 /**
825 * Return the instruction set extension for vectorization as described by
826 * DEAL_II_VECTORIZATION_WIDTH_IN_BITS in vectorization.h as a string. The
827 * list of possible return values is:
828 *
829 * <table>
830 * <tr>
831 * <td><tt>VECTORIZATION_LEVEL</tt></td>
832 * <td>Return Value</td>
833 * <td>Width in bits</td>
834 * </tr>
835 * <tr>
836 * <td>0</td>
837 * <td>disabled</td>
838 * <td>64</td>
839 * </tr>
840 * <tr>
841 * <td>1</td>
842 * <td>SSE2/AltiVec</td>
843 * <td>128</td>
844 * </tr>
845 * <tr>
846 * <td>2</td>
847 * <td>AVX</td>
848 * <td>256</td>
849 * </tr>
850 * <tr>
851 * <td>3</td>
852 * <td>AVX512</td>
853 * <td>512</td>
854 * </tr>
855 * </table>
856 */
857 std::string
858 get_current_vectorization_level();
859
860 /**
861 * Structure that hold information about memory usage in kB. Used by
862 * get_memory_stats(). See man 5 proc entry /status for details.
863 */
864 struct MemoryStats
865 {
866 /**
867 * Peak virtual memory size in kB.
868 */
869 unsigned long int VmPeak;
870
871 /**
872 * Current virtual memory size in kB.
873 */
874 unsigned long int VmSize;
875
876 /**
877 * Peak resident memory size in kB. Also known as "high water mark" (HWM).
878 */
879 unsigned long int VmHWM;
880
881 /**
882 * Current resident memory size in kB. Also known as "resident set size"
883 * (RSS).
884 */
885 unsigned long int VmRSS;
886 };
887
888
889 /**
890 * Fill the @p stats structure with information about the memory
891 * consumption of this process. This is only implemented on Linux.
892 */
893 void
894 get_memory_stats(MemoryStats &stats);
895
896
897 /**
898 * Return the name of the host this process runs on.
899 */
900 std::string
901 get_hostname();
902
903
904 /**
905 * Return the present time as HH:MM:SS.
906 */
907 std::string
908 get_time();
909
910 /**
911 * Return the present date as YYYY/MM/DD. MM and DD may be either one or
912 * two digits.
913 */
914 std::string
915 get_date();
916
917 /**
918 * Call the system function posix_memalign, or a replacement function if
919 * not available, to allocate memory with a certain minimal alignment. The
920 * first argument will then return a pointer to this memory block that can
921 * be released later on through a standard <code>free</code> call.
922 *
923 * @param memptr The address of a pointer variable that will after this
924 * call point to the allocated memory.
925 * @param alignment The minimal alignment of the memory block, in bytes.
926 * @param size The size of the memory block to be allocated, in bytes.
927 *
928 * @note This function checks internally for error codes, rather than
929 * leaving this task to the calling site.
930 */
931 void
932 posix_memalign(void **memptr, std::size_t alignment, std::size_t size);
933 } // namespace System
934 } // namespace Utilities
935
936
937 // --------------------- inline functions
938
939 namespace Utilities
940 {
941 template <int N, typename T>
942 inline constexpr T
943 fixed_power(const T x)
944 {
945 Assert(((std::is_integral_v<T> == true) && (N >= 0)) ||
946 (std::is_integral_v<T> == false),
947 ExcMessage("If the type of the argument, T, is an integer type, "
948 "then the exponent N must be a non-negative integer "
949 "because the result would otherwise not be an integer."));
950
951 if (N == 0)
952 return T(1.);
953 else if (N < 0)
954 // For negative exponents, turn things into a positive exponent
955 return T(1.) / fixed_power<-N>(x);
956 else
957 // If we get here, we have a positive exponent. Compute the result
958 // by repeated squaring:
959 return ((N % 2 == 1) ? x * fixed_power<N / 2>(x * x) :
960 fixed_power<N / 2>(x * x));
961 }
962
963
964
965 template <typename T, typename>
966 constexpr DEAL_II_HOST_DEVICE T
967 pow(const T base, const int iexp)
968 {
969 #if defined(DEBUG) && !defined(DEAL_II_CXX14_CONSTEXPR_BUG)
970 // Up to __builtin_expect this is the same code as in the 'Assert' macro.
971 // The call to __builtin_expect turns out to be problematic.
972 # if DEAL_II_KOKKOS_VERSION_GTE(3, 6, 0)
973 KOKKOS_IF_ON_HOST(({
974 if (!(iexp >= 0))
975 ::dealii::deal_II_exceptions::internals::issue_error_noreturn(
976 ::dealii::deal_II_exceptions::internals::ExceptionHandling::
977 abort_or_throw_on_exception,
978 __FILE__,
979 __LINE__,
980 __PRETTY_FUNCTION__,
981 "iexp>=0",
982 "ExcMessage(\"The exponent must not be negative!\")",
983 ExcMessage("The exponent must not be negative!"));
984 }))
985 # else
986 # ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST
987 if (!(iexp >= 0))
988 ::dealii::deal_II_exceptions::internals::issue_error_noreturn(
989 ::dealii::deal_II_exceptions::internals::ExceptionHandling::
990 abort_or_throw_on_exception,
991 __FILE__,
992 __LINE__,
993 __PRETTY_FUNCTION__,
994 "iexp>=0",
995 "ExcMessage(\"The exponent must not be negative!\")",
996 ExcMessage("The exponent must not be negative!"));
997 # endif
998 # endif
999 #endif
1000 // The "exponentiation by squaring" algorithm used below has to be expressed
1001 // in an iterative version since SYCL doesn't allow recursive functions used
1002 // in device code.
1003
1004 if (iexp <= 0)
1005 return 1;
1006
1007 int exp = iexp;
1008 T x = base;
1009 T y = 1;
1010 while (exp > 1)
1011 {
1012 if (exp % 2 == 1)
1013 y *= x;
1014 x *= x;
1015 exp /= 2;
1016 }
1017 return x * y;
1018 }
1019
1020
1021
1022 template <class T>
1023 inline std::string
1024 type_to_string(const T &t)
1025 {
1026 return boost::core::demangle(typeid(t).name());
1027 }
1028
1029
1030
1031 template <typename Iterator, typename T>
1032 inline Iterator
1033 lower_bound(Iterator first, Iterator last, const T &val)
1034 {
1035 return Utilities::lower_bound(first, last, val, std::less<T>());
1036 }
1037
1038
1039
1040 template <typename Iterator, typename T, typename Comp>
1041 inline Iterator
1042 lower_bound(Iterator first, Iterator last, const T &val, const Comp comp)
1043 {
1044 // verify that the two iterators are properly ordered. since
1045 // we need operator- for the iterator type anyway, do the
1046 // test as follows, rather than via 'last >= first'
1047 Assert(last - first >= 0,
1048 ExcMessage(
1049 "The given iterators do not satisfy the proper ordering."));
1050
1051 unsigned int len = static_cast<unsigned int>(last - first);
1052
1053 if (len == 0)
1054 return first;
1055
1056 while (true)
1057 {
1058 // if length equals 8 or less,
1059 // then do a rolled out
1060 // search. use a switch without
1061 // breaks for that and roll-out
1062 // the loop somehow
1063 if (len < 8)
1064 {
1065 switch (len)
1066 {
1067 case 7:
1068 if (!comp(*first, val))
1069 return first;
1070 ++first;
1071 DEAL_II_FALLTHROUGH;
1072 case 6:
1073 if (!comp(*first, val))
1074 return first;
1075 ++first;
1076 DEAL_II_FALLTHROUGH;
1077 case 5:
1078 if (!comp(*first, val))
1079 return first;
1080 ++first;
1081 DEAL_II_FALLTHROUGH;
1082 case 4:
1083 if (!comp(*first, val))
1084 return first;
1085 ++first;
1086 DEAL_II_FALLTHROUGH;
1087 case 3:
1088 if (!comp(*first, val))
1089 return first;
1090 ++first;
1091 DEAL_II_FALLTHROUGH;
1092 case 2:
1093 if (!comp(*first, val))
1094 return first;
1095 ++first;
1096 DEAL_II_FALLTHROUGH;
1097 case 1:
1098 if (!comp(*first, val))
1099 return first;
1100 return first + 1;
1101 default:
1102 // indices seem
1103 // to not be
1104 // sorted
1105 // correctly!? or
1106 // did len
1107 // become==0
1108 // somehow? that
1109 // shouldn't have
1110 // happened
1111 DEAL_II_ASSERT_UNREACHABLE();
1112 }
1113 }
1114
1115
1116
1117 const unsigned int half = len >> 1;
1118 const Iterator middle = first + half;
1119
1120 // if the value is larger than
1121 // that pointed to by the
1122 // middle pointer, then the
1123 // insertion point must be
1124 // right of it
1125 if (comp(*middle, val))
1126 {
1127 first = middle + 1;
1128 len -= half + 1;
1129 }
1130 else
1131 len = half;
1132 }
1133 }
1134
1135
1136 // --------------------- non-inline functions
1137
1138 namespace internal
1139 {
1140 /**
1141 * A structure that is used to identify whether a template argument is a
1142 * std::vector<T> or std::vector<std::vector<T>> where T is a type that
1143 * satisfies std::is_trivially_copyable_v<T> == true.
1144 */
1145 template <typename T>
1146 struct IsVectorOfTriviallyCopyable
1147 {
1148 static constexpr bool value = false;
1149 };
1150
1151
1152
1153 template <typename T>
1154 struct IsVectorOfTriviallyCopyable<std::vector<T>>
1155 {
1156 static constexpr bool value =
1157 std::is_trivially_copyable_v<T> && !std::is_same_v<T, bool>;
1158 };
1159
1160
1161
1162 template <typename T>
1163 struct IsVectorOfTriviallyCopyable<std::vector<std::vector<T>>>
1164 {
1165 static constexpr bool value =
1166 std::is_trivially_copyable_v<T> && !std::is_same_v<T, bool>;
1167 };
1168
1169
1170
1171 /**
1172 * A function that is used to append the contents of a std::vector<T>
1173 * (where T is a type that satisfies std::is_trivially_copyable_v<T>
1174 * == true but not T==bool) bit for bit to a character array.
1175 *
1176 * If the type is not such a vector of T, then the function
1177 * throws an exception.
1178 */
1179 template <typename T>
1180 inline void
1181 append_vector_of_trivially_copyable_to_buffer(const T &,
1182 std::vector<char> &)
1183 {
1184 // We shouldn't get here:
1185 DEAL_II_ASSERT_UNREACHABLE();
1186 }
1187
1188
1189
1190 template <typename T,
1191 typename = std::enable_if_t<!std::is_same_v<T, bool> &&
1192 std::is_trivially_copyable_v<T>>>
1193 inline void
1194 append_vector_of_trivially_copyable_to_buffer(
1195 const std::vector<T> &object,
1196 std::vector<char> &dest_buffer)
1197 {
1198 const typename std::vector<T>::size_type vector_size = object.size();
1199
1200 // Reserve for the buffer so that it can store the size of 'object' as
1201 // well as all of its elements.
1202 dest_buffer.reserve(dest_buffer.size() + sizeof(vector_size) +
1203 vector_size * sizeof(T));
1204
1205 // Copy the size into the vector
1206 dest_buffer.insert(dest_buffer.end(),
1207 reinterpret_cast<const char *>(&vector_size),
1208 reinterpret_cast<const char *>(&vector_size + 1));
1209
1210 // Insert the elements at the end of the vector:
1211 if (vector_size > 0)
1212 dest_buffer.insert(dest_buffer.end(),
1213 reinterpret_cast<const char *>(object.data()),
1214 reinterpret_cast<const char *>(object.data() +
1215 vector_size));
1216 }
1217
1218
1219
1220 template <typename T,
1221 typename = std::enable_if_t<!std::is_same_v<T, bool> &&
1222 std::is_trivially_copyable_v<T>>>
1223 inline void
1224 append_vector_of_trivially_copyable_to_buffer(
1225 const std::vector<std::vector<T>> &object,
1226 std::vector<char> &dest_buffer)
1227 {
1228 using size_type = typename std::vector<T>::size_type;
1229 const size_type vector_size = object.size();
1230
1231 typename std::vector<T>::size_type aggregated_size = 0;
1232 std::vector<size_type> sizes;
1233 sizes.reserve(vector_size);
1234 for (const auto &a : object)
1235 {
1236 aggregated_size += a.size();
1237 sizes.push_back(a.size());
1238 }
1239
1240 // Reserve for the buffer so that it can store the size of 'object' as
1241 // well as all of its elements.
1242 dest_buffer.reserve(dest_buffer.size() +
1243 sizeof(vector_size) * (1 + vector_size) +
1244 aggregated_size * sizeof(T));
1245
1246 // Copy the size into the vector
1247 dest_buffer.insert(dest_buffer.end(),
1248 reinterpret_cast<const char *>(&vector_size),
1249 reinterpret_cast<const char *>(&vector_size + 1));
1250
1251 // Copy the sizes of the individual chunks into the vector
1252 if (vector_size > 0)
1253 dest_buffer.insert(dest_buffer.end(),
1254 reinterpret_cast<const char *>(sizes.data()),
1255 reinterpret_cast<const char *>(sizes.data() +
1256 vector_size));
1257
1258 // Insert the elements at the end of the vector:
1259 for (const auto &a : object)
1260 dest_buffer.insert(dest_buffer.end(),
1261 reinterpret_cast<const char *>(a.data()),
1262 reinterpret_cast<const char *>(a.data() + a.size()));
1263 }
1264
1265
1266
1267 template <typename T>
1268 inline void
1269 create_vector_of_trivially_copyable_from_buffer(
1270 const std::vector<char>::const_iterator &,
1271 const std::vector<char>::const_iterator &,
1272 T &)
1273 {
1274 // We shouldn't get here:
1275 DEAL_II_ASSERT_UNREACHABLE();
1276 }
1277
1278
1279
1280 template <typename T,
1281 typename = std::enable_if_t<!std::is_same_v<T, bool> &&
1282 std::is_trivially_copyable_v<T>>>
1283 inline void
1284 create_vector_of_trivially_copyable_from_buffer(
1285 const std::vector<char>::const_iterator &cbegin,
1286 const std::vector<char>::const_iterator &cend,
1287 std::vector<T> &object)
1288 {
1289 // The size of the object vector can be found in cbegin of the buffer.
1290 // The data starts at cbegin + sizeof(vector_size).
1291
1292 // Get the size of the vector
1293 typename std::vector<T>::size_type vector_size;
1294 std::memcpy(&vector_size, &*cbegin, sizeof(vector_size));
1295
1296 Assert(static_cast<std::ptrdiff_t>(cend - cbegin) ==
1297 static_cast<std::ptrdiff_t>(sizeof(vector_size) +
1298 vector_size * sizeof(T)),
1299 ExcMessage("The given buffer has the wrong size."));
1300 (void)cend;
1301
1302 // Resize the output array and copy the elements into it. We need
1303 // to make sure that we don't access the buffer via a
1304 // reinterpret_cast<T*> because the T objects in the buffer may
1305 // not be aligned properly. Rather, use memcpy, which doesn't care
1306 // about alignment and is correct in this situation because we
1307 // are dealing with trivially copyable objects.
1308 //
1309 // (Strictly speaking, this writes into the output object twice, once
1310 // for the resize() operation and once during memcpy. This could be
1311 // avoided by (i) checking whether the point is aligned, using for
1312 // example boost::alignment::is_aligned(), and (ii) if the data
1313 // is aligned, re-create the output vector using
1314 // object.clear();
1315 // object.insert (object.end(),
1316 // (T*)(&*cbegin + sizeof(vector_size)),
1317 // (T*)(&*cbegin + sizeof(vector_size)) + vector_size);
1318 // In practice, the difference is likely rather small, assuming the
1319 // compiler does not already optimize away the first initialization.
1320 object.resize(vector_size);
1321 if (vector_size > 0)
1322 std::memcpy(object.data(),
1323 &*cbegin + sizeof(vector_size),
1324 vector_size * sizeof(T));
1325 }
1326
1327
1328
1329 template <typename T,
1330 typename = std::enable_if_t<!std::is_same_v<T, bool> &&
1331 std::is_trivially_copyable_v<T>>>
1332 inline void
1333 create_vector_of_trivially_copyable_from_buffer(
1334 const std::vector<char>::const_iterator &cbegin,
1335 const std::vector<char>::const_iterator &cend,
1336 std::vector<std::vector<T>> &object)
1337 {
1338 // First get the size of the vector, and resize the output object
1339 using size_type = typename std::vector<T>::size_type;
1340 std::vector<char>::const_iterator iterator = cbegin;
1341 size_type vector_size;
1342 std::memcpy(&vector_size, &*iterator, sizeof(vector_size));
1343 object.clear();
1344 object.resize(vector_size);
1345 std::vector<size_type> sizes(vector_size);
1346 if (vector_size > 0)
1347 std::memcpy(sizes.data(),
1348 &*iterator + sizeof(vector_size),
1349 vector_size * sizeof(size_type));
1350
1351 iterator += sizeof(vector_size) * (1 + vector_size);
1352 size_type aggregated_size = 0;
1353 for (const auto a : sizes)
1354 aggregated_size += a;
1355
1356 Assert(static_cast<std::ptrdiff_t>(cend - iterator) ==
1357 static_cast<std::ptrdiff_t>(aggregated_size * sizeof(T)),
1358 ExcMessage("The given buffer has the wrong size."));
1359 (void)cend;
1360
1361 // Then copy the elements. As for the previous function, use memcpy
1362 // rather than accessing the data via reinterpret_cast<T*> to
1363 // avoid alignment issues.
1364 for (unsigned int i = 0; i < vector_size; ++i)
1365 if (sizes[i] > 0)
1366 {
1367 object[i].resize(sizes[i]);
1368 std::memcpy(object[i].data(), &*iterator, sizes[i] * sizeof(T));
1369 iterator += sizes[i] * sizeof(T);
1370 }
1371
1372 Assert(iterator == cend,
1373 ExcMessage("The given buffer has the wrong size."));
1374 }
1375
1376 } // namespace internal
1377
1378
1379
1380 template <typename T>
1381 std::size_t
1382 pack(const T &object,
1383 std::vector<char> &dest_buffer,
1384 const bool allow_compression)
1385 {
1386 std::size_t size = 0;
1387
1388
1389 // see if the object is small and copyable via memcpy. if so, use
1390 // this fast path. otherwise, we have to go through the BOOST
1391 // serialization machinery
1392 if constexpr (std::is_trivially_copyable<T>() && sizeof(T) < 256)
1393 {
1394 // Determine the size. There are places where we would like to use a
1395 // truly empty type, for which we use std::tuple<> (i.e., a tuple
1396 // of zero elements). For this class, the compiler reports a nonzero
1397 // sizeof(...) because that is the minimum possible for objects --
1398 // objects need to have distinct addresses, so they need to have a size
1399 // of at least one. But we can special case this situation.
1400 size = (std::is_same_v<T, std::tuple<>> ? 0 : sizeof(T));
1401
1402 (void)allow_compression;
1403 const std::size_t previous_size = dest_buffer.size();
1404 dest_buffer.resize(previous_size + size);
1405
1406 if (size > 0)
1407 std::memcpy(dest_buffer.data() + previous_size, &object, size);
1408 }
1409 // Next try if we have a vector of trivially copyable objects.
1410 // If that is the case, we can shortcut the whole BOOST serialization
1411 // machinery and just copy the content of the vector bit for bit
1412 // into the output buffer, assuming that we are not asked to compress
1413 // the data.
1414 else if (internal::IsVectorOfTriviallyCopyable<T>::value &&
1415 (allow_compression == false))
1416 {
1417 const std::size_t previous_size = dest_buffer.size();
1418
1419 // When we have DEAL_II_HAVE_CXX17 set by default, we can just
1420 // inline the code of the following function here and make the 'if'
1421 // above a 'if constexpr'. Without the 'constexpr', we need to keep
1422 // the general template of the function that throws an exception.
1423 internal::append_vector_of_trivially_copyable_to_buffer(object,
1424 dest_buffer);
1425
1426 size = dest_buffer.size() - previous_size;
1427 }
1428 else
1429 {
1430 // use buffer as the target of a compressing
1431 // stream into which we serialize the current object
1432 const std::size_t previous_size = dest_buffer.size();
1433 {
1434 boost::iostreams::filtering_ostreambuf fosb;
1435 #ifdef DEAL_II_WITH_ZLIB
1436 if (allow_compression)
1437 fosb.push(boost::iostreams::gzip_compressor());
1438 #else
1439 (void)allow_compression;
1440 #endif
1441 fosb.push(boost::iostreams::back_inserter(dest_buffer));
1442
1443 boost::archive::binary_oarchive boa(fosb);
1444 boa << object;
1445 // the stream object has to be destroyed before the return statement
1446 // to ensure that all data has been written in the buffer
1447 }
1448 size = dest_buffer.size() - previous_size;
1449 }
1450
1451 return size;
1452 }
1453
1454
1455 template <typename T>
1456 std::vector<char>
1457 pack(const T &object, const bool allow_compression)
1458 {
1459 std::vector<char> buffer;
1460 pack<T>(object, buffer, allow_compression);
1461 return buffer;
1462 }
1463
1464
1465
1466 template <typename T>
1467 T
1468 unpack(const std::vector<char>::const_iterator &cbegin,
1469 const std::vector<char>::const_iterator &cend,
1470 const bool allow_compression)
1471 {
1472 // see if the object is small and copyable via memcpy. if so, use
1473 // this fast path. otherwise, we have to go through the BOOST
1474 // serialization machinery
1475 if constexpr (std::is_trivially_copyable<T>() && sizeof(T) < 256)
1476 {
1477 // Determine the size. There are places where we would like to use a
1478 // truly empty type, for which we use std::tuple<> (i.e., a tuple
1479 // of zero elements). For this class, the compiler reports a nonzero
1480 // sizeof(...) because that is the minimum possible for objects --
1481 // objects need to have distinct addresses, so they need to have a size
1482 // of at least one. But we can special case this situation.
1483 const std::size_t size =
1484 (std::is_same_v<T, std::tuple<>> ? 0 : sizeof(T));
1485
1486 T object;
1487
1488 (void)allow_compression;
1489 Assert(std::distance(cbegin, cend) == size, ExcInternalError());
1490
1491 if (size > 0)
1492 std::memcpy(&object, &*cbegin, size);
1493
1494 return object;
1495 }
1496 // Next try if we have a vector of trivially copyable objects.
1497 // If that is the case, we can shortcut the whole BOOST serialization
1498 // machinery and just copy the content of the buffer bit for bit
1499 // into an appropriately sized output vector, assuming that we
1500 // are not asked to compress the data.
1501 else if (internal::IsVectorOfTriviallyCopyable<T>::value &&
1502 (allow_compression == false))
1503 {
1504 // When we have DEAL_II_HAVE_CXX17 set by default, we can just
1505 // inline the code of the following function here and make the 'if'
1506 // above a 'if constexpr'. Without the 'constexpr', we need to keep
1507 // the general template of the function that throws an exception.
1508 T object;
1509 internal::create_vector_of_trivially_copyable_from_buffer(cbegin,
1510 cend,
1511 object);
1512 return object;
1513 }
1514 else
1515 {
1516 // decompress the buffer section into the object
1517 boost::iostreams::filtering_istreambuf fisb;
1518 #ifdef DEAL_II_WITH_ZLIB
1519 if (allow_compression)
1520 fisb.push(boost::iostreams::gzip_decompressor());
1521 #else
1522 (void)allow_compression;
1523 #endif
1524 fisb.push(boost::iostreams::array_source(&*cbegin, cend - cbegin));
1525
1526 boost::archive::binary_iarchive bia(fisb);
1527
1528 T object;
1529 bia >> object;
1530 return object;
1531 }
1532
1533 return T();
1534 }
1535
1536
1537 template <typename T>
1538 T
1539 unpack(const std::vector<char> &buffer, const bool allow_compression)
1540 {
1541 return unpack<T>(buffer.cbegin(), buffer.cend(), allow_compression);
1542 }
1543
1544
1545 template <typename T, int N>
1546 void
1547 unpack(const std::vector<char>::const_iterator &cbegin,
1548 const std::vector<char>::const_iterator &cend,
1549 T (&unpacked_object)[N],
1550 const bool allow_compression)
1551 {
1552 // see if the object is small and copyable via memcpy. if so, use
1553 // this fast path. otherwise, we have to go through the BOOST
1554 // serialization machinery
1555 if constexpr (std::is_trivially_copyable<T>() && sizeof(T) * N < 256)
1556 {
1557 Assert(std::distance(cbegin, cend) == sizeof(T) * N,
1558 ExcInternalError());
1559 std::memcpy(unpacked_object, &*cbegin, sizeof(T) * N);
1560 }
1561 else
1562 {
1563 // decompress the buffer section into the object
1564 boost::iostreams::filtering_istreambuf fisb;
1565 #ifdef DEAL_II_WITH_ZLIB
1566 if (allow_compression)
1567 fisb.push(boost::iostreams::gzip_decompressor());
1568 #else
1569 (void)allow_compression;
1570 #endif
1571 fisb.push(boost::iostreams::array_source(&*cbegin, cend - cbegin));
1572
1573 boost::archive::binary_iarchive bia(fisb);
1574 bia >> unpacked_object;
1575 }
1576 }
1577
1578
1579 template <typename T, int N>
1580 void
1581 unpack(const std::vector<char> &buffer,
1582 T (&unpacked_object)[N],
1583 const bool allow_compression)
1584 {
1585 unpack<T, N>(buffer.cbegin(),
1586 buffer.cend(),
1587 unpacked_object,
1588 allow_compression);
1589 }
1590
1591
1592
1593 inline bool
1594 get_bit(const unsigned char number, const unsigned int n)
1595 {
1596 AssertIndexRange(n, 8);
1597
1598 // source:
1599 // https://stackoverflow.com/questions/47981/how-do-you-set-clear-and-toggle-a-single-bit
1600 // "Checking a bit"
1601 return ((number >> n) & 1U) != 0u;
1602 }
1603
1604
1605
1606 inline void
1607 set_bit(unsigned char &number, const unsigned int n, const bool x)
1608 {
1609 AssertIndexRange(n, 8);
1610
1611 // source:
1612 // https://stackoverflow.com/questions/47981/how-do-you-set-clear-and-toggle-a-single-bit
1613 // "Changing the nth bit to x"
1614 number ^= (-static_cast<unsigned char>(x) ^ number) & (1U << n);
1615 }
1616
1617
1618
1619 template <typename To, typename From>
1620 inline std::unique_ptr<To>
1621 dynamic_unique_cast(std::unique_ptr<From> &&p)
1622 {
1623 // Let's see if we can cast from 'From' to 'To'. If so, do the cast,
1624 // and then release the pointer from the old
1625 // owner
1626 if (To *cast = dynamic_cast<To *>(p.get()))
1627 {
1628 std::unique_ptr<To> result(cast);
1629 p.release();
1630 return result;
1631 }
1632 else
1633 throw std::bad_cast();
1634 }
1635
1636
1637
1638 template <typename T>
1639 inline T &
1640 get_underlying_value(T &p)
1641 {
1642 return p;
1643 }
1644
1645
1646
1647 template <typename T>
1648 inline T &
1649 get_underlying_value(std::shared_ptr<T> &p)
1650 {
1651 return *p;
1652 }
1653
1654
1655
1656 template <typename T>
1657 inline T &
1658 get_underlying_value(const std::shared_ptr<T> &p)
1659 {
1660 return *p;
1661 }
1662
1663
1664
1665 template <typename T>
1666 inline T &
1667 get_underlying_value(std::unique_ptr<T> &p)
1668 {
1669 return *p;
1670 }
1671
1672
1673
1674 template <typename T>
1675 inline T &
1676 get_underlying_value(const std::unique_ptr<T> &p)
1677 {
1678 return *p;
1679 }
1680
1681
1682
1683 template <typename Integer>
1684 std::vector<Integer>
1685 reverse_permutation(const std::vector<Integer> &permutation)
1686 {
1687 const std::size_t n = permutation.size();
1688
1689 std::vector<Integer> out(n);
1690 for (std::size_t i = 0; i < n; ++i)
1691 out[i] = n - 1 - permutation[i];
1692
1693 return out;
1694 }
1695
1696
1697
1698 template <typename Integer>
1699 std::vector<Integer>
1700 invert_permutation(const std::vector<Integer> &permutation)
1701 {
1702 const std::size_t n = permutation.size();
1703
1704 std::vector<Integer> out(n, numbers::invalid_unsigned_int);
1705
1706 for (std::size_t i = 0; i < n; ++i)
1707 {
1708 AssertIndexRange(permutation[i], n);
1709 out[permutation[i]] = i;
1710 }
1711
1712 // check that we have actually reached
1713 // all indices
1714 for (std::size_t i = 0; i < n; ++i)
1715 Assert(out[i] != numbers::invalid_unsigned_int,
1716 ExcMessage("The given input permutation had duplicate entries!"));
1717
1718 return out;
1719 }
1720 } // namespace Utilities
1721
1722
1723 DEAL_II_NAMESPACE_CLOSE
1724
1725 #ifndef DOXYGEN
1726 namespace boost
1727 {
1728 namespace serialization
1729 {
1730 // Provides boost and c++11 with a way to serialize tuples and pairs
1731 // automatically.
1732 template <int N>
1733 struct Serialize
1734 {
1735 template <class Archive, typename... Args>
1736 static void
1737 serialize(Archive &ar, std::tuple<Args...> &t, const unsigned int version)
1738 {
1739 ar &std::get<N - 1>(t);
1740 Serialize<N - 1>::serialize(ar, t, version);
1741 }
1742 };
1743
1744 template <>
1745 struct Serialize<0>
1746 {
1747 template <class Archive, typename... Args>
1748 static void
1749 serialize(Archive &ar, std::tuple<Args...> &t, const unsigned int version)
1750 {
1751 (void)ar;
1752 (void)t;
1753 (void)version;
1754 }
1755 };
1756
1757 template <class Archive, typename... Args>
1758 void
1759 serialize(Archive &ar, std::tuple<Args...> &t, const unsigned int version)
1760 {
1761 Serialize<sizeof...(Args)>::serialize(ar, t, version);
1762 }
1763 } // namespace serialization
1764 } // namespace boost
1765 #endif
1766
1767 #endif