utilities.h

// ---------------------------------------------------------------------
//
// Copyright (C) 2005 - 2018 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii_utilities_h
#define dealii_utilities_h

#include <deal.II/base/config.h>
#include <deal.II/base/exceptions.h>

#include <vector>
#include <utility>
#include <functional>
#include <string>
#include <tuple>
#include <type_traits>

#ifdef DEAL_II_WITH_TRILINOS
#  include <Epetra_Comm.h>
#  include <Epetra_Map.h>
#  ifdef DEAL_II_WITH_MPI
#    include <Epetra_MpiComm.h>
#  else
#    include <Epetra_SerialComm.h>
#  endif
#endif

#include <boost/archive/binary_oarchive.hpp>
#include <boost/archive/binary_iarchive.hpp>
#include <boost/serialization/vector.hpp>
#include <boost/serialization/array.hpp>

#ifdef DEAL_II_WITH_ZLIB
#  include <boost/iostreams/stream.hpp>
#  include <boost/iostreams/filtering_stream.hpp>
#  include <boost/iostreams/device/back_inserter.hpp>
#  include <boost/iostreams/filter/gzip.hpp>
#endif

DEAL_II_NAMESPACE_OPEN


namespace Utilities
{
  std::string dealii_version_string ();

  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);

  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 <int N, typename T>
  T
  fixed_power (const T t);

  template <int a, int N>
  struct DEAL_II_DEPRECATED fixed_int_power
  {
    static const int value = a *fixed_int_power<a,N-1>::value;
  };

  template <int a>
  struct DEAL_II_DEPRECATED fixed_int_power<a,0>
  {
    static const int value = 1;
  };

  constexpr
  unsigned int
  pow(const unsigned int base, const unsigned int iexp)
  {
    return iexp == 0 ? 1 : base*::Utilities::pow(base, iexp - 1);
  }

  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);

  std::vector<unsigned int>
  reverse_permutation (const std::vector<unsigned int> &permutation);

  std::vector<unsigned int>
  invert_permutation (const std::vector<unsigned int> &permutation);

  std::vector<unsigned long long int>
  reverse_permutation (const std::vector<unsigned long long int> &permutation);

  std::vector<unsigned long long int>
  invert_permutation (const std::vector<unsigned long long int> &permutation);

  template <typename T>
  size_t pack (const T &object, std::vector<char> &dest_buffer);

  template <typename T>
  std::vector<char> pack (const T &object);

  template <typename T>
  T unpack (const std::vector<char> &buffer);

  template <typename T>
  T unpack (const std::vector<char>::iterator &begin,
            const std::vector<char>::iterator &end);

  template <typename T, int N>
  void unpack (const std::vector<char> &buffer,
               T (&unpacked_object)[N]);

  template <typename T, int N>
  void unpack (const std::vector<char>::iterator &begin,
               const std::vector<char>::iterator &end,
               T (&unpacked_object)[N]);

  template <typename To, typename From>
  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();
  }

  namespace System
  {

    double get_cpu_load ();

    const 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, size_t alignment, size_t size);
  }


#ifdef DEAL_II_WITH_TRILINOS

  namespace Trilinos
  {
    const Epetra_Comm &comm_world();

    const Epetra_Comm &comm_self();

    Epetra_Comm *
    duplicate_communicator (const Epetra_Comm &communicator);

    void
    destroy_communicator (Epetra_Comm &communicator);

    unsigned int get_n_mpi_processes (const Epetra_Comm &mpi_communicator);

    unsigned int get_this_mpi_process (const Epetra_Comm &mpi_communicator);

    Epetra_Map
    duplicate_map (const Epetra_BlockMap  &map,
                   const Epetra_Comm &comm);
  }

#endif


}


// --------------------- inline functions

namespace Utilities
{
  template <int N, typename T>
  inline
  T fixed_power (const T n)
  {
    Assert (N>=0, ExcNotImplemented());
    switch (N)
      {
      case 0:
        return ::internal::NumberType<T>::value(1);
      case 1:
        return n;
      case 2:
        return n*n;
      case 3:
        return n*n*n;
      case 4:
        return n*n*n*n;
      default:
        T result = n;
        for (int d=1; d<N; ++d)
          result *= n;
        return result;
      }
  }



  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
                Assert (false, ExcInternalError());
              }
          }



        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

  template <typename T>
  size_t pack (const T &object, std::vector<char> &dest_buffer)
  {
    // 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
    //
    // we have to work around the fact that GCC 4.8.x claims to be C++
    // conforming, but is not actually as it does not implement
    // std::is_trivially_copyable.
#if __GNUG__ && __GNUC__ < 5
    if (  __has_trivial_copy(T) && sizeof(T)<256)
#else
#  ifdef DEAL_II_WITH_CXX17
    if constexpr (std::is_trivially_copyable<T>() && sizeof(T)<256)
#  else
    if (std::is_trivially_copyable<T>() && sizeof(T)<256)
#  endif
#endif
      {
        const size_t previous_size = dest_buffer.size();
        dest_buffer.resize (previous_size + sizeof(T));

        std::memcpy (dest_buffer.data() + previous_size, &object, sizeof(T));

        return sizeof(T);
      }
    else
      {
        // use buffer as the target of a compressing
        // stream into which we serialize the current object
        const size_t previous_size = dest_buffer.size();
        {
#ifdef DEAL_II_WITH_ZLIB
          boost::iostreams::filtering_ostream out;
          out.push(boost::iostreams::gzip_compressor
                   (boost::iostreams::gzip_params
                    (boost::iostreams::gzip::best_compression)));
          out.push(boost::iostreams::back_inserter(dest_buffer));

          boost::archive::binary_oarchive archive(out);
          archive << object;
          out.flush();
#else
          std::ostringstream out;
          boost::archive::binary_oarchive archive(out);
          archive << object;

          const std::string &s = out.str();
          dest_buffer.reserve (dest_buffer.size() + s.size());
          std::move (s.begin(), s.end(), std::back_inserter(dest_buffer));
#endif
        }
        return (dest_buffer.size() - previous_size);
      }
  }


  template <typename T>
  std::vector<char> pack (const T &object)
  {
    std::vector<char> buffer;
    pack<T> (object, buffer);
    return buffer;
  }


  template <typename T>
  T unpack (const std::vector<char>::const_iterator &cbegin,
            const std::vector<char>::const_iterator &cend)
  {
    // 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
    //
    // we have to work around the fact that GCC 4.8.x claims to be C++
    // conforming, but is not actually as it does not implement
    // std::is_trivially_copyable.
#if __GNUG__ && __GNUC__ < 5
    if (  __has_trivial_copy(T) && sizeof(T)<256)
#else
#  ifdef DEAL_II_WITH_CXX17
    if constexpr (std::is_trivially_copyable<T>() && sizeof(T)<256)
#  else
    if (std::is_trivially_copyable<T>() && sizeof(T)<256)
#  endif
#endif
      {
        Assert (std::distance(cbegin, cend) == sizeof(T), ExcInternalError());
        T object;
        std::memcpy (&object, &*cbegin, sizeof(T));
        return object;
      }
    else
      {
        std::string decompressed_buffer;
        T object;

        // first decompress the buffer
        {
#ifdef DEAL_II_WITH_ZLIB
          boost::iostreams::filtering_ostream decompressing_stream;
          decompressing_stream.push(boost::iostreams::gzip_decompressor());
          decompressing_stream.push(boost::iostreams::back_inserter(decompressed_buffer));
          decompressing_stream.write (&*cbegin, std::distance(cbegin, cend));
#else
          decompressed_buffer.assign (cbegin, cend);
#endif
        }

        // then restore the object from the buffer
        std::istringstream in(decompressed_buffer);
        boost::archive::binary_iarchive archive(in);

        archive >> object;
        return object;
      }
  }


  template <typename T>
  T unpack(const std::vector<char> &buffer)
  {
    return unpack<T> (buffer.cbegin(), buffer.cend());
  }


  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])
  {
    // 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
    //
    // we have to work around the fact that GCC 4.8.x claims to be C++
    // conforming, but is not actually as it does not implement
    // std::is_trivially_copyable.
    if (
#if __GNUG__ && __GNUC__ < 5
      __has_trivial_copy(T)
#else
      std::is_trivially_copyable<T>()
#endif
      &&
      sizeof(T)*N<256)
      {
        Assert (std::distance(cbegin, cend) == sizeof(T)*N, ExcInternalError());
        std::memcpy (unpacked_object, &*cbegin, sizeof(T)*N);
      }
    else
      {
        std::string decompressed_buffer;

        // first decompress the buffer
        {
#ifdef DEAL_II_WITH_ZLIB
          boost::iostreams::filtering_ostream decompressing_stream;
          decompressing_stream.push(boost::iostreams::gzip_decompressor());
          decompressing_stream.push(boost::iostreams::back_inserter(decompressed_buffer));
          decompressing_stream.write (&*cbegin, std::distance(cbegin, cend));
#else
          decompressed_buffer.assign (cbegin, cend);
#endif
        }

        // then restore the object from the buffer
        std::istringstream in(decompressed_buffer);
        boost::archive::binary_iarchive archive(in);

        archive >> unpacked_object;
      }
  }


  template <typename T, int N>
  void unpack (const std::vector<char> &buffer,
               T (&unpacked_object)[N])
  {
    unpack<T,N> (buffer.cbegin(), buffer.cend(), unpacked_object);
  }

}


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);
    }
  }
}
#endif

#endif