Random.hpp

Go to the documentation of this file.

/*******************************************************************************
 Causal Dynamical Triangulations in C++ using CGAL
 
 Copyright © 2026 Adam Getchell
 ******************************************************************************/

 
#ifndef CDT_PLUSPLUS_RANDOM_HPP
#define CDT_PLUSPLUS_RANDOM_HPP
 
#include <concepts>
#include <cstdint>
#include <istream>
#include <limits>
#include <locale>
#include <ostream>
#include <random>
#include <sstream>
#include <stdexcept>
#include <string>
#include <string_view>
 
#if !defined(__SIZEOF_INT128__) || (defined(PCG_FORCE_EMULATED_128BIT_MATH) && \
                                    PCG_FORCE_EMULATED_128BIT_MATH)
#include "pcg_uint128.hpp"

namespace pcg_extras
{
  // PCG's specific_stream::set_stream uses an int literal with its emulated
  // 128-bit value. Supply the heterogeneous overload that template deduction
  // cannot obtain through uint_x4's converting constructor.
  template <typename UInt, typename UIntX2>
  [[nodiscard]] auto operator|(uint_x4<UInt, UIntX2> const& value,
                               int const bits) -> uint_x4<UInt, UIntX2>
  { return value | uint_x4<UInt, UIntX2>{bits}; }
}  // namespace pcg_extras
#endif
 
#include "pcg_random.hpp"
 
namespace cdt
{
  class RandomSeed final
  {
    std::uint64_t m_value{};
 
   public:
    constexpr RandomSeed() noexcept = default;
    explicit constexpr RandomSeed(std::uint64_t const value) noexcept
        : m_value{value}
    {}

    [[nodiscard]] constexpr auto value() const noexcept -> std::uint64_t
    { return m_value; }

    [[nodiscard]] auto operator==(RandomSeed const& other) const noexcept
        -> bool = default;
  };

  class RandomStream final
  {
    std::uint64_t m_value{};
 
   public:
    constexpr RandomStream() noexcept = default;
    explicit constexpr RandomStream(std::uint64_t const value) noexcept
        : m_value{value}
    {}

    [[nodiscard]] constexpr auto value() const noexcept -> std::uint64_t
    { return m_value; }

    [[nodiscard]] auto operator==(RandomStream const& other) const noexcept
        -> bool = default;
  };

  [[nodiscard]] constexpr auto format_as(RandomSeed const seed) noexcept
      -> std::uint64_t
  { return seed.value(); }

  [[nodiscard]] constexpr auto format_as(RandomStream const stream) noexcept
      -> std::uint64_t
  { return stream.value(); }

  inline auto operator<<(std::ostream& output, RandomSeed const seed)
      -> std::ostream&
  { return output << seed.value(); }

  inline auto operator<<(std::ostream& output, RandomStream const stream)
      -> std::ostream&
  { return output << stream.value(); }
 
  namespace random_streams
  {
    inline constexpr RandomStream initialization{0};
    inline constexpr RandomStream transitions{1};
  }  // namespace random_streams

  class Random final
  {
   public:
    using result_type = pcg64::result_type;
 
   private:
    RandomSeed                m_seed{};
    RandomStream              m_stream{};
    pcg64                     m_engine;
 
    [[nodiscard]] static auto entropy_seed() -> RandomSeed
    {
      std::random_device                           entropy;
      std::uniform_int_distribution<std::uint64_t> distribution{
          std::numeric_limits<std::uint64_t>::min(),
          std::numeric_limits<std::uint64_t>::max()};
      return RandomSeed{distribution(entropy)};
    }
 
   public:
    Random() : Random{entropy_seed()} {}

    explicit Random(std::uint64_t const seed) : Random{RandomSeed{seed}} {}

    explicit Random(RandomSeed const   seed,
                    RandomStream const stream = RandomStream{})
        : m_seed{seed}, m_stream{stream}, m_engine{seed.value(), stream.value()}
    {}

    [[nodiscard]] static constexpr auto min() noexcept -> result_type
    { return pcg64::min(); }

    [[nodiscard]] static constexpr auto max() noexcept -> result_type
    { return pcg64::max(); }

    [[nodiscard]] auto operator()() -> result_type { return m_engine(); }

    [[nodiscard]] auto seed() const noexcept -> RandomSeed { return m_seed; }

    [[nodiscard]] auto stream() const noexcept -> RandomStream
    { return m_stream; }

    [[nodiscard]] auto split(RandomStream const stream) const -> Random
    { return Random{m_seed, stream}; }

    [[nodiscard]] auto serialized_state() const -> std::string
    {
      std::ostringstream output;
      output.imbue(std::locale::classic());
      output << m_engine;
      if (!output)
      {
        throw std::runtime_error("Could not serialize PCG state.");
      }
      return output.str();
    }

    [[nodiscard]] static auto from_serialized_state(
        RandomSeed const seed, RandomStream const stream,
        std::string_view const state) -> Random
    {
      auto               restored        = Random{seed, stream};
      auto const         expected_stream = restored.m_engine.stream();
      std::istringstream input{std::string{state}};
      input.imbue(std::locale::classic());
      input >> restored.m_engine;
      if (!input || restored.m_engine.stream() != expected_stream)
      {
        throw std::invalid_argument("Malformed or mismatched PCG state.");
      }
      input >> std::ws;
      if (!input.eof())
      {
        throw std::invalid_argument("PCG state contains trailing data.");
      }
      return restored;
    }
  };
 
  static_assert(std::uniform_random_bit_generator<Random>);
}  // namespace cdt
 
#endif  // CDT_PLUSPLUS_RANDOM_HPP