utilities.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 2005 - 2024 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Part of the source code is dual licensed under Apache-2.0 WITH
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information
// governing the source code and code contributions can be found in
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
//
// ------------------------------------------------------------------------
 
#ifndef dealii_utilities_h
#define dealii_utilities_h
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
 
#include <boost/archive/binary_iarchive.hpp>
#include <boost/archive/binary_oarchive.hpp>
#include <boost/core/demangle.hpp>
#include <boost/iostreams/device/array.hpp>
#include <boost/iostreams/device/back_inserter.hpp>
#include <boost/iostreams/filtering_streambuf.hpp>
#include <boost/serialization/array.hpp>
#include <boost/serialization/complex.hpp>
#include <boost/serialization/vector.hpp>
 
#include <cstddef>
#include <functional>
#include <string>
#include <tuple>
#include <type_traits>
#include <typeinfo>
#include <utility>
#include <vector>
 
#ifdef DEAL_II_WITH_ZLIB
#  include <boost/iostreams/filter/gzip.hpp>
#endif
 
DEAL_II_NAMESPACE_OPEN
 
// forward declare Point
#ifndef DOXYGEN
template <int dim, typename Number>
DEAL_II_CXX20_REQUIRES(dim >= 0)
class Point;
#endif
 
namespace Utilities
{
  std::string
  dealii_version_string();
 
  template <int dim, typename Number>
  std::vector<std::array<std::uint64_t, dim>>
  inverse_Hilbert_space_filling_curve(
    const std::vector<Point<dim, Number>> &points,
    const int                              bits_per_dim = 64);
 
  template <int dim>
  std::vector<std::array<std::uint64_t, dim>>
  inverse_Hilbert_space_filling_curve(
    const std::vector<std::array<std::uint64_t, dim>> &points,
    const int                                          bits_per_dim = 64);
 
  template <int dim>
  std::uint64_t
  pack_integers(const std::array<std::uint64_t, dim> &index,
                const int                             bits_per_dim);
 
  std::string
  compress(const std::string &input);
 
  std::string
  decompress(const std::string &compressed_input);
 
  std::string
  encode_base64(const std::vector<unsigned char> &binary_input);
 
  std::vector<unsigned char>
  decode_base64(const std::string &base64_input);
 
  std::string
  int_to_string(const unsigned int value,
                const unsigned int digits = numbers::invalid_unsigned_int);
 
  template <typename number>
  std::string
  to_string(const number       value,
            const unsigned int digits = numbers::invalid_unsigned_int);
 
  unsigned int
  needed_digits(const unsigned int max_number);
 
  template <typename Number>
  Number
  truncate_to_n_digits(const Number number, const unsigned int n_digits);
 
  int
  string_to_int(const std::string &s);
 
  std::string
  dim_string(const int dim, const int spacedim);
 
  std::vector<int>
  string_to_int(const std::vector<std::string> &s);
 
  double
  string_to_double(const std::string &s);
 
 
  std::vector<double>
  string_to_double(const std::vector<std::string> &s);
 
 
  std::vector<std::string>
  split_string_list(const std::string &s, const std::string &delimiter = ",");
 
 
  std::vector<std::string>
  split_string_list(const std::string &s, const char delimiter);
 
 
  std::vector<std::string>
  break_text_into_lines(const std::string &original_text,
                        const unsigned int width,
                        const char         delimiter = ' ');
 
  bool
  match_at_string_start(const std::string &name, const std::string &pattern);
 
  std::pair<int, unsigned int>
  get_integer_at_position(const std::string &name, const unsigned int position);
 
  std::string
  replace_in_string(const std::string &input,
                    const std::string &from,
                    const std::string &to);
 
  std::string
  trim(const std::string &input);
 
  double
  generate_normal_random_number(const double a, const double sigma);
 
  template <class T>
  std::string
  type_to_string(const T &t);
 
  template <int N, typename T>
  constexpr T
  fixed_power(const T t);
 
  template <typename T, typename = std::enable_if_t<std::is_arithmetic_v<T>>>
  constexpr DEAL_II_HOST_DEVICE T
  pow(const T base, const int iexp);
 
  template <typename Iterator, typename T>
  Iterator
  lower_bound(Iterator first, Iterator last, const T &val);
 
  template <typename Iterator, typename T, typename Comp>
  Iterator
  lower_bound(Iterator first, Iterator last, const T &val, const Comp comp);
 
  template <typename Integer>
  std::vector<Integer>
  reverse_permutation(const std::vector<Integer> &permutation);
 
  template <typename Integer>
  std::vector<Integer>
  invert_permutation(const std::vector<Integer> &permutation);
 
  template <typename T>
  size_t
  pack(const T           &object,
       std::vector<char> &dest_buffer,
       const bool         allow_compression = true);
 
  template <typename T>
  std::vector<char>
  pack(const T &object, const bool allow_compression = true);
 
  template <typename T>
  T
  unpack(const std::vector<char> &buffer, const bool allow_compression = true);
 
  template <typename T>
  T
  unpack(const std::vector<char>::const_iterator &cbegin,
         const std::vector<char>::const_iterator &cend,
         const bool                               allow_compression = true);
 
  template <typename T, int N>
  void
  unpack(const std::vector<char> &buffer,
         T (&unpacked_object)[N],
         const bool allow_compression = true);
 
  template <typename T, int N>
  void
  unpack(const std::vector<char>::const_iterator &cbegin,
         const std::vector<char>::const_iterator &cend,
         T (&unpacked_object)[N],
         const bool allow_compression = true);
 
  bool
  get_bit(const unsigned char number, const unsigned int n);
 
 
  void
  set_bit(unsigned char &number, const unsigned int n, const bool x);
 
 
  template <typename To, typename From>
  std::unique_ptr<To>
  dynamic_unique_cast(std::unique_ptr<From> &&p);
 
  template <typename T>
  T &
  get_underlying_value(T &p);
 
  template <typename T>
  T &
  get_underlying_value(std::shared_ptr<T> &p);
 
  template <typename T>
  T &
  get_underlying_value(const std::shared_ptr<T> &p);
 
  template <typename T>
  T &
  get_underlying_value(std::unique_ptr<T> &p);
 
  template <typename T>
  T &
  get_underlying_value(const std::unique_ptr<T> &p);
 
  namespace System
  {
    double
    get_cpu_load();
 
    std::string
    get_current_vectorization_level();
 
    struct MemoryStats
    {
      unsigned long int VmPeak;
 
      unsigned long int VmSize;
 
      unsigned long int VmHWM;
 
      unsigned long int VmRSS;
    };
 
 
    void
    get_memory_stats(MemoryStats &stats);
 
 
    std::string
    get_hostname();
 
 
    std::string
    get_time();
 
    std::string
    get_date();
 
    void
    posix_memalign(void **memptr, std::size_t alignment, std::size_t size);
  } // namespace System
} // namespace Utilities
 
 
// --------------------- inline functions
 
namespace Utilities
{
  template <int N, typename T>
  inline constexpr T
  fixed_power(const T x)
  {
    Assert(((std::is_integral_v<T> == true) && (N >= 0)) ||
             (std::is_integral_v<T> == false),
           ExcMessage("If the type of the argument, T, is an integer type, "
                      "then the exponent N must be a non-negative integer "
                      "because the result would otherwise not be an integer."));
 
    if (N == 0)
      return T(1.);
    else if (N < 0)
      // For negative exponents, turn things into a positive exponent
      return T(1.) / fixed_power<-N>(x);
    else
      // If we get here, we have a positive exponent. Compute the result
      // by repeated squaring:
      return ((N % 2 == 1) ? x * fixed_power<N / 2>(x * x) :
                             fixed_power<N / 2>(x * x));
  }
 
 
 
  template <typename T, typename>
  constexpr DEAL_II_HOST_DEVICE T
  pow(const T base, const int iexp)
  {
#if defined(DEBUG) && !defined(DEAL_II_CXX14_CONSTEXPR_BUG)
    // Up to __builtin_expect this is the same code as in the 'Assert' macro.
    // The call to __builtin_expect turns out to be problematic.
#  if KOKKOS_VERSION >= 30600
    KOKKOS_IF_ON_HOST(({
      if (!(iexp >= 0))
        ::deal_II_exceptions::internals::issue_error_noreturn(
          ::deal_II_exceptions::internals::ExceptionHandling::
            abort_or_throw_on_exception,
          __FILE__,
          __LINE__,
          __PRETTY_FUNCTION__,
          "iexp>=0",
          "ExcMessage(\"The exponent must not be negative!\")",
          ExcMessage("The exponent must not be negative!"));
    }))
#  else
#    ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST
    if (!(iexp >= 0))
      ::deal_II_exceptions::internals::issue_error_noreturn(
        ::deal_II_exceptions::internals::ExceptionHandling::
          abort_or_throw_on_exception,
        __FILE__,
        __LINE__,
        __PRETTY_FUNCTION__,
        "iexp>=0",
        "ExcMessage(\"The exponent must not be negative!\")",
        ExcMessage("The exponent must not be negative!"));
#    endif
#  endif
#endif
    // The "exponentiation by squaring" algorithm used below has to be expressed
    // in an iterative version since SYCL doesn't allow recursive functions used
    // in device code.
 
    if (iexp <= 0)
      return 1;
 
    int exp = iexp;
    T   x   = base;
    T   y   = 1;
    while (exp > 1)
      {
        if (exp % 2 == 1)
          y *= x;
        x *= x;
        exp /= 2;
      }
    return x * y;
  }
 
 
 
  template <class T>
  inline std::string
  type_to_string(const T &t)
  {
    return boost::core::demangle(typeid(t).name());
  }
 
 
 
  template <typename Iterator, typename T>
  inline Iterator
  lower_bound(Iterator first, Iterator last, const T &val)
  {
    return Utilities::lower_bound(first, last, val, std::less<T>());
  }
 
 
 
  template <typename Iterator, typename T, typename Comp>
  inline Iterator
  lower_bound(Iterator first, Iterator last, const T &val, const Comp comp)
  {
    // verify that the two iterators are properly ordered. since
    // we need operator- for the iterator type anyway, do the
    // test as follows, rather than via 'last >= first'
    Assert(last - first >= 0,
           ExcMessage(
             "The given iterators do not satisfy the proper ordering."));
 
    unsigned int len = static_cast<unsigned int>(last - first);
 
    if (len == 0)
      return first;
 
    while (true)
      {
        // if length equals 8 or less,
        // then do a rolled out
        // search. use a switch without
        // breaks for that and roll-out
        // the loop somehow
        if (len < 8)
          {
            switch (len)
              {
                case 7:
                  if (!comp(*first, val))
                    return first;
                  ++first;
                  DEAL_II_FALLTHROUGH;
                case 6:
                  if (!comp(*first, val))
                    return first;
                  ++first;
                  DEAL_II_FALLTHROUGH;
                case 5:
                  if (!comp(*first, val))
                    return first;
                  ++first;
                  DEAL_II_FALLTHROUGH;
                case 4:
                  if (!comp(*first, val))
                    return first;
                  ++first;
                  DEAL_II_FALLTHROUGH;
                case 3:
                  if (!comp(*first, val))
                    return first;
                  ++first;
                  DEAL_II_FALLTHROUGH;
                case 2:
                  if (!comp(*first, val))
                    return first;
                  ++first;
                  DEAL_II_FALLTHROUGH;
                case 1:
                  if (!comp(*first, val))
                    return first;
                  return first + 1;
                default:
                  // indices seem
                  // to not be
                  // sorted
                  // correctly!? or
                  // did len
                  // become==0
                  // somehow? that
                  // shouldn't have
                  // happened
                  DEAL_II_ASSERT_UNREACHABLE();
              }
          }
 
 
 
        const unsigned int half   = len >> 1;
        const Iterator     middle = first + half;
 
        // if the value is larger than
        // that pointed to by the
        // middle pointer, then the
        // insertion point must be
        // right of it
        if (comp(*middle, val))
          {
            first = middle + 1;
            len -= half + 1;
          }
        else
          len = half;
      }
  }
 
 
  // --------------------- non-inline functions
 
  namespace internal
  {
    template <typename T>
    struct IsVectorOfTriviallyCopyable
    {
      static constexpr bool value = false;
    };
 
 
 
    template <typename T>
    struct IsVectorOfTriviallyCopyable<std::vector<T>>
    {
      static constexpr bool value =
        std::is_trivially_copyable_v<T> && !std::is_same_v<T, bool>;
    };
 
 
 
    template <typename T>
    struct IsVectorOfTriviallyCopyable<std::vector<std::vector<T>>>
    {
      static constexpr bool value =
        std::is_trivially_copyable_v<T> && !std::is_same_v<T, bool>;
    };
 
 
 
    template <typename T>
    inline void
    append_vector_of_trivially_copyable_to_buffer(const T &,
                                                  std::vector<char> &)
    {
      // We shouldn't get here:
      DEAL_II_ASSERT_UNREACHABLE();
    }
 
 
 
    template <typename T,
              typename = std::enable_if_t<!std::is_same_v<T, bool> &&
                                          std::is_trivially_copyable_v<T>>>
    inline void
    append_vector_of_trivially_copyable_to_buffer(
      const std::vector<T> &object,
      std::vector<char>    &dest_buffer)
    {
      const typename std::vector<T>::size_type vector_size = object.size();
 
      // Reserve for the buffer so that it can store the size of 'object' as
      // well as all of its elements.
      dest_buffer.reserve(dest_buffer.size() + sizeof(vector_size) +
                          vector_size * sizeof(T));
 
      // Copy the size into the vector
      dest_buffer.insert(dest_buffer.end(),
                         reinterpret_cast<const char *>(&vector_size),
                         reinterpret_cast<const char *>(&vector_size + 1));
 
      // Insert the elements at the end of the vector:
      if (vector_size > 0)
        dest_buffer.insert(dest_buffer.end(),
                           reinterpret_cast<const char *>(object.data()),
                           reinterpret_cast<const char *>(object.data() +
                                                          vector_size));
    }
 
 
 
    template <typename T,
              typename = std::enable_if_t<!std::is_same_v<T, bool> &&
                                          std::is_trivially_copyable_v<T>>>
    inline void
    append_vector_of_trivially_copyable_to_buffer(
      const std::vector<std::vector<T>> &object,
      std::vector<char>                 &dest_buffer)
    {
      using size_type             = typename std::vector<T>::size_type;
      const size_type vector_size = object.size();
 
      typename std::vector<T>::size_type aggregated_size = 0;
      std::vector<size_type>             sizes;
      sizes.reserve(vector_size);
      for (const auto &a : object)
        {
          aggregated_size += a.size();
          sizes.push_back(a.size());
        }
 
      // Reserve for the buffer so that it can store the size of 'object' as
      // well as all of its elements.
      dest_buffer.reserve(dest_buffer.size() +
                          sizeof(vector_size) * (1 + vector_size) +
                          aggregated_size * sizeof(T));
 
      // Copy the size into the vector
      dest_buffer.insert(dest_buffer.end(),
                         reinterpret_cast<const char *>(&vector_size),
                         reinterpret_cast<const char *>(&vector_size + 1));
 
      // Copy the sizes of the individual chunks into the vector
      if (vector_size > 0)
        dest_buffer.insert(dest_buffer.end(),
                           reinterpret_cast<const char *>(sizes.data()),
                           reinterpret_cast<const char *>(sizes.data() +
                                                          vector_size));
 
      // Insert the elements at the end of the vector:
      for (const auto &a : object)
        dest_buffer.insert(dest_buffer.end(),
                           reinterpret_cast<const char *>(a.data()),
                           reinterpret_cast<const char *>(a.data() + a.size()));
    }
 
 
 
    template <typename T>
    inline void
    create_vector_of_trivially_copyable_from_buffer(
      const std::vector<char>::const_iterator &,
      const std::vector<char>::const_iterator &,
      T &)
    {
      // We shouldn't get here:
      DEAL_II_ASSERT_UNREACHABLE();
    }
 
 
 
    template <typename T,
              typename = std::enable_if_t<!std::is_same_v<T, bool> &&
                                          std::is_trivially_copyable_v<T>>>
    inline void
    create_vector_of_trivially_copyable_from_buffer(
      const std::vector<char>::const_iterator &cbegin,
      const std::vector<char>::const_iterator &cend,
      std::vector<T>                          &object)
    {
      // The size of the object vector can be found in cbegin of the buffer.
      // The data starts at cbegin + sizeof(vector_size).
 
      // Get the size of the vector
      typename std::vector<T>::size_type vector_size;
      memcpy(&vector_size, &*cbegin, sizeof(vector_size));
 
      Assert(static_cast<std::ptrdiff_t>(cend - cbegin) ==
               static_cast<std::ptrdiff_t>(sizeof(vector_size) +
                                           vector_size * sizeof(T)),
             ExcMessage("The given buffer has the wrong size."));
      (void)cend;
 
      // Resize the output array and copy the elements into it. We need
      // to make sure that we don't access the buffer via a
      // reinterpret_cast<T*> because the T objects in the buffer may
      // not be aligned properly. Rather, use memcpy, which doesn't care
      // about alignment and is correct in this situation because we
      // are dealing with trivially copyable objects.
      //
      // (Strictly speaking, this writes into the output object twice, once
      // for the resize() operation and once during memcpy. This could be
      // avoided by (i) checking whether the point is aligned, using for
      // example boost::alignment::is_aligned(), and (ii) if the data
      // is aligned, re-create the output vector using
      //   object.clear();
      //   object.insert (object.end(),
      //                  (T*)(&*cbegin + sizeof(vector_size)),
      //                  (T*)(&*cbegin + sizeof(vector_size)) + vector_size);
      // In practice, the difference is likely rather small, assuming the
      // compiler does not already optimize away the first initialization.
      object.resize(vector_size);
      if (vector_size > 0)
        std::memcpy(object.data(),
                    &*cbegin + sizeof(vector_size),
                    vector_size * sizeof(T));
    }
 
 
 
    template <typename T,
              typename = std::enable_if_t<!std::is_same_v<T, bool> &&
                                          std::is_trivially_copyable_v<T>>>
    inline void
    create_vector_of_trivially_copyable_from_buffer(
      const std::vector<char>::const_iterator &cbegin,
      const std::vector<char>::const_iterator &cend,
      std::vector<std::vector<T>>             &object)
    {
      // First get the size of the vector, and resize the output object
      using size_type = typename std::vector<T>::size_type;
      std::vector<char>::const_iterator iterator = cbegin;
      size_type                         vector_size;
      memcpy(&vector_size, &*iterator, sizeof(vector_size));
      object.clear();
      object.resize(vector_size);
      std::vector<size_type> sizes(vector_size);
      if (vector_size > 0)
        std::memcpy(sizes.data(),
                    &*iterator + sizeof(vector_size),
                    vector_size * sizeof(size_type));
 
      iterator += sizeof(vector_size) * (1 + vector_size);
      size_type aggregated_size = 0;
      for (const auto a : sizes)
        aggregated_size += a;
 
      Assert(static_cast<std::ptrdiff_t>(cend - iterator) ==
               static_cast<std::ptrdiff_t>(aggregated_size * sizeof(T)),
             ExcMessage("The given buffer has the wrong size."));
      (void)cend;
 
      // Then copy the elements. As for the previous function, use memcpy
      // rather than accessing the data via reinterpret_cast<T*> to
      // avoid alignment issues.
      for (unsigned int i = 0; i < vector_size; ++i)
        if (sizes[i] > 0)
          {
            object[i].resize(sizes[i]);
            std::memcpy(object[i].data(), &*iterator, sizes[i] * sizeof(T));
            iterator += sizes[i] * sizeof(T);
          }
 
      Assert(iterator == cend,
             ExcMessage("The given buffer has the wrong size."));
    }
 
  } // namespace internal
 
 
 
  template <typename T>
  size_t
  pack(const T           &object,
       std::vector<char> &dest_buffer,
       const bool         allow_compression)
  {
    std::size_t size = 0;
 
 
    // see if the object is small and copyable via memcpy. if so, use
    // this fast path. otherwise, we have to go through the BOOST
    // serialization machinery
    if constexpr (std::is_trivially_copyable<T>() && sizeof(T) < 256)
      {
        // Determine the size. There are places where we would like to use a
        // truly empty type, for which we use std::tuple<> (i.e., a tuple
        // of zero elements). For this class, the compiler reports a nonzero
        // sizeof(...) because that is the minimum possible for objects --
        // objects need to have distinct addresses, so they need to have a size
        // of at least one. But we can special case this situation.
        size = (std::is_same_v<T, std::tuple<>> ? 0 : sizeof(T));
 
        (void)allow_compression;
        const std::size_t previous_size = dest_buffer.size();
        dest_buffer.resize(previous_size + size);
 
        if (size > 0)
          std::memcpy(dest_buffer.data() + previous_size, &object, size);
      }
    // Next try if we have a vector of trivially copyable objects.
    // If that is the case, we can shortcut the whole BOOST serialization
    // machinery and just copy the content of the vector bit for bit
    // into the output buffer, assuming that we are not asked to compress
    // the data.
    else if (internal::IsVectorOfTriviallyCopyable<T>::value &&
             (allow_compression == false))
      {
        const std::size_t previous_size = dest_buffer.size();
 
        // When we have DEAL_II_HAVE_CXX17 set by default, we can just
        // inline the code of the following function here and make the 'if'
        // above a 'if constexpr'. Without the 'constexpr', we need to keep
        // the general template of the function that throws an exception.
        internal::append_vector_of_trivially_copyable_to_buffer(object,
                                                                dest_buffer);
 
        size = dest_buffer.size() - previous_size;
      }
    else
      {
        // use buffer as the target of a compressing
        // stream into which we serialize the current object
        const std::size_t previous_size = dest_buffer.size();
        {
          boost::iostreams::filtering_ostreambuf fosb;
#ifdef DEAL_II_WITH_ZLIB
          if (allow_compression)
            fosb.push(boost::iostreams::gzip_compressor());
#else
          (void)allow_compression;
#endif
          fosb.push(boost::iostreams::back_inserter(dest_buffer));
 
          boost::archive::binary_oarchive boa(fosb);
          boa << object;
          // the stream object has to be destroyed before the return statement
          // to ensure that all data has been written in the buffer
        }
        size = dest_buffer.size() - previous_size;
      }
 
    return size;
  }
 
 
  template <typename T>
  std::vector<char>
  pack(const T &object, const bool allow_compression)
  {
    std::vector<char> buffer;
    pack<T>(object, buffer, allow_compression);
    return buffer;
  }
 
 
 
  template <typename T>
  T
  unpack(const std::vector<char>::const_iterator &cbegin,
         const std::vector<char>::const_iterator &cend,
         const bool                               allow_compression)
  {
    // see if the object is small and copyable via memcpy. if so, use
    // this fast path. otherwise, we have to go through the BOOST
    // serialization machinery
    if constexpr (std::is_trivially_copyable<T>() && sizeof(T) < 256)
      {
        // Determine the size. There are places where we would like to use a
        // truly empty type, for which we use std::tuple<> (i.e., a tuple
        // of zero elements). For this class, the compiler reports a nonzero
        // sizeof(...) because that is the minimum possible for objects --
        // objects need to have distinct addresses, so they need to have a size
        // of at least one. But we can special case this situation.
        const std::size_t size =
          (std::is_same_v<T, std::tuple<>> ? 0 : sizeof(T));
 
        T object;
 
        (void)allow_compression;
        Assert(std::distance(cbegin, cend) == size, ExcInternalError());
 
        if (size > 0)
          std::memcpy(&object, &*cbegin, size);
 
        return object;
      }
    // Next try if we have a vector of trivially copyable objects.
    // If that is the case, we can shortcut the whole BOOST serialization
    // machinery and just copy the content of the buffer bit for bit
    // into an appropriately sized output vector, assuming that we
    // are not asked to compress the data.
    else if (internal::IsVectorOfTriviallyCopyable<T>::value &&
             (allow_compression == false))
      {
        // When we have DEAL_II_HAVE_CXX17 set by default, we can just
        // inline the code of the following function here and make the 'if'
        // above a 'if constexpr'. Without the 'constexpr', we need to keep
        // the general template of the function that throws an exception.
        T object;
        internal::create_vector_of_trivially_copyable_from_buffer(cbegin,
                                                                  cend,
                                                                  object);
        return object;
      }
    else
      {
        // decompress the buffer section into the object
        boost::iostreams::filtering_istreambuf fisb;
#ifdef DEAL_II_WITH_ZLIB
        if (allow_compression)
          fisb.push(boost::iostreams::gzip_decompressor());
#else
        (void)allow_compression;
#endif
        fisb.push(boost::iostreams::array_source(&*cbegin, cend - cbegin));
 
        boost::archive::binary_iarchive bia(fisb);
 
        T object;
        bia >> object;
        return object;
      }
 
    return T();
  }
 
 
  template <typename T>
  T
  unpack(const std::vector<char> &buffer, const bool allow_compression)
  {
    return unpack<T>(buffer.cbegin(), buffer.cend(), allow_compression);
  }
 
 
  template <typename T, int N>
  void
  unpack(const std::vector<char>::const_iterator &cbegin,
         const std::vector<char>::const_iterator &cend,
         T (&unpacked_object)[N],
         const bool allow_compression)
  {
    // see if the object is small and copyable via memcpy. if so, use
    // this fast path. otherwise, we have to go through the BOOST
    // serialization machinery
    if constexpr (std::is_trivially_copyable<T>() && sizeof(T) * N < 256)
      {
        Assert(std::distance(cbegin, cend) == sizeof(T) * N,
               ExcInternalError());
        std::memcpy(unpacked_object, &*cbegin, sizeof(T) * N);
      }
    else
      {
        // decompress the buffer section into the object
        boost::iostreams::filtering_istreambuf fisb;
#ifdef DEAL_II_WITH_ZLIB
        if (allow_compression)
          fisb.push(boost::iostreams::gzip_decompressor());
#else
        (void)allow_compression;
#endif
        fisb.push(boost::iostreams::array_source(&*cbegin, cend - cbegin));
 
        boost::archive::binary_iarchive bia(fisb);
        bia >> unpacked_object;
      }
  }
 
 
  template <typename T, int N>
  void
  unpack(const std::vector<char> &buffer,
         T (&unpacked_object)[N],
         const bool allow_compression)
  {
    unpack<T, N>(buffer.cbegin(),
                 buffer.cend(),
                 unpacked_object,
                 allow_compression);
  }
 
 
 
  inline bool
  get_bit(const unsigned char number, const unsigned int n)
  {
    AssertIndexRange(n, 8);
 
    // source:
    // https://stackoverflow.com/questions/47981/how-do-you-set-clear-and-toggle-a-single-bit
    // "Checking a bit"
    return ((number >> n) & 1U) != 0u;
  }
 
 
 
  inline void
  set_bit(unsigned char &number, const unsigned int n, const bool x)
  {
    AssertIndexRange(n, 8);
 
    // source:
    // https://stackoverflow.com/questions/47981/how-do-you-set-clear-and-toggle-a-single-bit
    // "Changing the nth bit to x"
    number ^= (-static_cast<unsigned char>(x) ^ number) & (1U << n);
  }
 
 
 
  template <typename To, typename From>
  inline std::unique_ptr<To>
  dynamic_unique_cast(std::unique_ptr<From> &&p)
  {
    // Let's see if we can cast from 'From' to 'To'. If so, do the cast,
    // and then release the pointer from the old
    // owner
    if (To *cast = dynamic_cast<To *>(p.get()))
      {
        std::unique_ptr<To> result(cast);
        p.release();
        return result;
      }
    else
      throw std::bad_cast();
  }
 
 
 
  template <typename T>
  inline T &
  get_underlying_value(T &p)
  {
    return p;
  }
 
 
 
  template <typename T>
  inline T &
  get_underlying_value(std::shared_ptr<T> &p)
  {
    return *p;
  }
 
 
 
  template <typename T>
  inline T &
  get_underlying_value(const std::shared_ptr<T> &p)
  {
    return *p;
  }
 
 
 
  template <typename T>
  inline T &
  get_underlying_value(std::unique_ptr<T> &p)
  {
    return *p;
  }
 
 
 
  template <typename T>
  inline T &
  get_underlying_value(const std::unique_ptr<T> &p)
  {
    return *p;
  }
 
 
 
  template <typename Integer>
  std::vector<Integer>
  reverse_permutation(const std::vector<Integer> &permutation)
  {
    const std::size_t n = permutation.size();
 
    std::vector<Integer> out(n);
    for (std::size_t i = 0; i < n; ++i)
      out[i] = n - 1 - permutation[i];
 
    return out;
  }
 
 
 
  template <typename Integer>
  std::vector<Integer>
  invert_permutation(const std::vector<Integer> &permutation)
  {
    const std::size_t n = permutation.size();
 
    std::vector<Integer> out(n, numbers::invalid_unsigned_int);
 
    for (std::size_t i = 0; i < n; ++i)
      {
        AssertIndexRange(permutation[i], n);
        out[permutation[i]] = i;
      }
 
    // check that we have actually reached
    // all indices
    for (std::size_t i = 0; i < n; ++i)
      Assert(out[i] != numbers::invalid_unsigned_int,
             ExcMessage("The given input permutation had duplicate entries!"));
 
    return out;
  }
} // namespace Utilities
 
 
DEAL_II_NAMESPACE_CLOSE
 
#ifndef DOXYGEN
namespace boost
{
  namespace serialization
  {
    // Provides boost and c++11 with a way to serialize tuples and pairs
    // automatically.
    template <int N>
    struct Serialize
    {
      template <class Archive, typename... Args>
      static void
      serialize(Archive &ar, std::tuple<Args...> &t, const unsigned int version)
      {
        ar &std::get<N - 1>(t);
        Serialize<N - 1>::serialize(ar, t, version);
      }
    };
 
    template <>
    struct Serialize<0>
    {
      template <class Archive, typename... Args>
      static void
      serialize(Archive &ar, std::tuple<Args...> &t, const unsigned int version)
      {
        (void)ar;
        (void)t;
        (void)version;
      }
    };
 
    template <class Archive, typename... Args>
    void
    serialize(Archive &ar, std::tuple<Args...> &t, const unsigned int version)
    {
      Serialize<sizeof...(Args)>::serialize(ar, t, version);
    }
  } // namespace serialization
} // namespace boost
#endif
 
#endif