random.hpp

Go to the documentation of this file.

#pragma once
 
#include <helios/utils/common_traits.hpp>
 
#include <concepts>
#include <cstdint>
#include <functional>
#include <limits>
#include <random>
#include <type_traits>
 
namespace helios::utils {
 
/**
 * @brief Concept for random number engines compatible with std distributions.
 * @details Requires presence of `result_type`, `operator()`, and
 * `min()`/`max()` members.
 */
template <typename T>
concept RandomEngine = requires(T&& engine) {
  typename std::remove_cvref_t<T>::result_type;
  { engine() } -> std::convertible_to<typename T::result_type>;
  {
    std::remove_cvref_t<T>::min()
  } -> std::convertible_to<typename std::remove_cvref_t<T>::result_type>;
  {
    std::remove_cvref_t<T>::max()
  } -> std::convertible_to<typename std::remove_cvref_t<T>::result_type>;
};
 
/**
 * @brief Concept for standard-like distributions.
 * @details Requires presence of `result_type` and callable operator(engine).
 */
template <typename T, typename Engine>
concept Distribution = requires(T&& dist, Engine engine) {
  typename std::remove_cvref_t<T>::result_type;
  {
    dist(engine)
  } -> std::convertible_to<typename std::remove_cvref_t<T>::result_type>;
};
 
/**
 * @brief Default engine type used by random utilities.
 * @details Uses a 64-bit Mersenne Twister for quality pseudorandom numbers.
 */
using DefaultRandomEngine = std::mt19937_64;
 
/**
 * @brief Fast but lower-quality engine type used by random utilities.
 * @details Uses a 32-bit linear congruential engine suitable for
 * non-cryptographic, performance-critical scenarios.
 */
using FastRandomEngine = std::minstd_rand;
 
/**
 * @brief Internal helper to obtain seed from `std::random_device`.
 * @details This function is intentionally small and header-only to avoid static
 * initialization of engines in user code.
 * @return 64-bit seed value from `std::random_device`
 */
[[nodiscard]] inline uint64_t RandomDeviceSeed() {
  std::random_device rd{};
  using result_type = std::random_device::result_type;
  constexpr auto result_bits = sizeof(result_type) * 8U;
  constexpr auto target_bits = sizeof(uint64_t) * 8U;
 
  if constexpr (result_bits >= target_bits) {
    return static_cast<uint64_t>(rd());
  } else {
    uint64_t value = 0;
    auto shift = 0U;
    while (shift < target_bits) {
      value |= static_cast<uint64_t>(rd()) << shift;
      shift += result_bits;
    }
    return value;
  }
}
 
/**
 * @brief Creates a default-quality random engine seeded with
 * `std::random_device`.
 * @details Useful when the caller wants an engine instance but does not care
 * a specific engine type beyond the default choice.
 * @return `DefaultRandomEngine` instance seeded with `std::random_device`
 */
[[nodiscard]] inline DefaultRandomEngine MakeDefaultEngine() {
  return DefaultRandomEngine{RandomDeviceSeed()};
}
 
/**
 * @brief Creates a fast linear random engine seeded with `std::random_device`.
 * @details Intended for performance-critical code where statistical quality is
 * less important. Not suitable for cryptographic purposes.
 * @return `FastRandomEngine` instance seeded with `std::random_device`
 */
[[nodiscard]] inline FastRandomEngine MakeFastEngine() {
  return FastRandomEngine{
      static_cast<FastRandomEngine::result_type>(RandomDeviceSeed())};
}
 
/**
 * @brief Thread-local default-quality engine.
 * @details Uses Meyer's singleton pattern per thread to avoid global static
 * initialization order issues while providing a convenient default.
 * @return Reference to thread-local `DefaultRandomEngine` instance
 */
[[nodiscard]] inline DefaultRandomEngine& DefaultEngine() {
  thread_local auto engine = MakeDefaultEngine();
  return engine;
}
 
/**
 * @brief Thread-local fast engine.
 * @details Uses Meyer's singleton pattern per thread to avoid global static
 * initialization order issues while providing a fast default.
 * @return Reference to thread-local `FastRandomEngine` instance
 */
[[nodiscard]] inline FastRandomEngine& FastEngineInstance() {
  thread_local auto engine = MakeFastEngine();
  return engine;
}
 
/**
 * @brief Random number utilities with a user-provided engine.
 * @details This wrapper delegates all random generation to an underlying engine
 * instance supplied by the user. It never owns the engine and does not perform
 * any static initialization of engines itself.
 * @tparam Engine RandomEngine type used for generation
 */
template <RandomEngine Engine>
class RandomGenerator {
public:
  /**
   * @brief Constructs a `RandomGenerator` from an existing engine reference.
   * @details The engine is not owned and must outlive this object.
   * @param engine Reference to engine used for random generation
   */
  explicit RandomGenerator(Engine& engine) noexcept : engine_(engine) {}
  RandomGenerator(const RandomGenerator&) noexcept = default;
  RandomGenerator(RandomGenerator&&) noexcept = default;
  ~RandomGenerator() noexcept = default;
 
  RandomGenerator& operator=(const RandomGenerator&) noexcept = default;
  RandomGenerator& operator=(RandomGenerator&&) noexcept = default;
 
  /**
   * @brief Generates a value using the provided distribution.
   * @details This is a low-level interface that accepts an arbitrary
   * distribution object. Intended for cases where caller needs full control
   * over distribution parameters.
   * @tparam Dist Distribution type compatible with `Engine`
   * @param dist Distribution instance used for generation
   * @return Generated random value of type `Dist::result_type`
   */
  template <typename Dist>
    requires Distribution<Dist, Engine>
  [[nodiscard]] auto Next(Dist& dist) noexcept(
      std::is_nothrow_invocable_v<Dist, Engine&>) ->
      typename Dist::result_type {
    return dist(engine_.get());
  }
 
  /**
   * @brief Generates a random arithmetic value using a reasonable default
   * distribution.
   * @details For integral types, uses `std::uniform_int_distribution` over the
   * full representable range, except for `bool` which uses a uniform {false,
   * true}. For floating point types, uses `std::uniform_real_distribution` in
   * the [0, 1) range to avoid dependence on `std::numeric_limits<>::min()`.
   * @tparam T Arithmetic type to generate
   * @return Randomly generated value of type `T`
   */
  template <utils::ArithmeticTrait T>
  [[nodiscard]] T Value();
 
  /**
   * @brief Generates a random arithmetic value within the specified range.
   * @details For integral types, uses `std::uniform_int_distribution` with
   * closed interval [min, max]. For floating point types, uses
   * std::uniform_real_distribution with interval [min, max).
   * @tparam T Arithmetic type
   * @tparam U Arithmetic type
   * @param min Lower bound of the range
   * @param max Upper bound of the range
   * @return Random value of `std::common_type_t<T, U>` within [min, max] or
   * [min, max)
   */
  template <utils::ArithmeticTrait T, utils::ArithmeticTrait U>
  [[nodiscard]] auto ValueFromRange(T min, U max) -> std::common_type_t<T, U>;
 
  /**
   * @brief Provides access to the underlying engine.
   * @return Reference to the engine used by this generator
   */
  [[nodiscard]] Engine& EngineRef() const noexcept { return engine_.get(); }
 
private:
  std::reference_wrapper<Engine> engine_;
};
 
template <RandomEngine Engine>
template <utils::ArithmeticTrait T>
inline T RandomGenerator<Engine>::Value() {
  Engine& engine = engine_.get();
  if constexpr (std::integral<T>) {
    if constexpr (std::same_as<T, bool>) {
      std::uniform_int_distribution<int> dist(0, 1);
      return dist(engine) == 1;
    } else {
      std::uniform_int_distribution<T> dist(std::numeric_limits<T>::min(),
                                            std::numeric_limits<T>::max());
      return dist(engine);
    }
  } else {
    std::uniform_real_distribution<T> dist(static_cast<T>(0),
                                           static_cast<T>(1));
    return dist(engine);
  }
}
 
template <RandomEngine Engine>
template <utils::ArithmeticTrait T, utils::ArithmeticTrait U>
inline auto RandomGenerator<Engine>::ValueFromRange(T min, U max)
    -> std::common_type_t<T, U> {
  using Common = std::common_type_t<T, U>;
  const auto cmin = static_cast<Common>(min);
  const auto cmax = static_cast<Common>(max);
 
  Engine& engine = engine_.get();
  if constexpr (std::integral<Common>) {
    using DistType =
        std::conditional_t<std::signed_integral<Common>, int64_t, uint64_t>;
    std::uniform_int_distribution<DistType> dist(static_cast<DistType>(cmin),
                                                 static_cast<DistType>(cmax));
    return static_cast<Common>(dist(engine));
  } else {
    std::uniform_real_distribution<Common> dist(cmin, cmax);
    return dist(engine);
  }
}
 
/**
 * @brief Convenience alias for a generator using the default-quality engine.
 * @details Uses thread-local `DefaultEngine()` as the underlying engine.
 */
using DefaultRandomGenerator = RandomGenerator<DefaultRandomEngine>;
 
/**
 * @brief Convenience alias for a generator using the fast engine.
 * @details Uses thread-local `FastEngineInstance()` as the underlying engine.
 */
using FastRandomGeneratorType = RandomGenerator<FastRandomEngine>;
 
/**
 * @brief Provides access to a thread-local default-quality random generator.
 * @details Uses Meyer's singleton pattern per thread and avoids any static
 * engine objects other than thread-local instances that are lazily initialized
 * on first use.
 * @return Reference to `DefaultRandomGenerator` bound to `DefaultEngine()`
 */
[[nodiscard]] inline DefaultRandomGenerator& RandomDefault() {
  thread_local DefaultRandomGenerator generator{DefaultEngine()};
  return generator;
}
 
/**
 * @brief Provides access to a thread-local fast random generator.
 * @details Uses Meyer's singleton pattern per thread and avoids any static
 * engine objects other than thread-local instances that are lazily initialized
 * on first use.
 * @return Reference to `FastRandomGeneratorType` bound to
 * `FastEngineInstance()`
 */
[[nodiscard]] inline FastRandomGeneratorType& RandomFast() {
  thread_local FastRandomGeneratorType generator{FastEngineInstance()};
  return generator;
}
 
/**
 * @brief Convenience function to generate a default-distribution value using
 * the default engine.
 * @details Equivalent to `RandomDefault().Value<T>()`, but shorter to call.
 * @tparam T Arithmetic type to generate
 * @return Randomly generated value of type T
 */
template <utils::ArithmeticTrait T>
[[nodiscard]] inline T RandomValue() {
  return RandomDefault().Value<T>();
}
 
/**
 * @brief Convenience function to generate a value in range using the default
 * engine.
 * @details Equivalent to `RandomDefault().ValueFromRange(min, max)`.
 * @tparam T Arithmetic type
 * @tparam U Arithmetic type
 * @param min Lower bound of the range
 * @param max Upper bound of the range
 * @return Random value of `std::common_type_t<T, U>` in [min, max] or [min,
 * max)
 */
template <utils::ArithmeticTrait T, utils::ArithmeticTrait U>
[[nodiscard]] inline auto RandomValueFromRange(T min, U max)
    -> std::common_type_t<T, U> {
  return RandomDefault().ValueFromRange(min, max);
}
 
/**
 * @brief Convenience function to generate a default-distribution value using
 * the fast engine.
 * @details Equivalent to `RandomFast().Value<T>()`, but shorter to call.
 * @tparam T Arithmetic type to generate
 * @return Randomly generated value of type `T` using the fast engine
 */
template <utils::ArithmeticTrait T>
[[nodiscard]] inline T RandomFastValue() {
  return RandomFast().Value<T>();
}
 
/**
 * @brief Convenience function to generate a value in range using the fast
 * engine.
 * @details Equivalent to `RandomFast().ValueFromRange(min, max)`.
 * @tparam T Arithmetic type
 * @tparam U Arithmetic type
 * @param min Lower bound of the range
 * @param max Upper bound of the range
 * @return Random value of `std::common_type_t<T, U>` in [min, max] or [min,
 * max)
 */
template <utils::ArithmeticTrait T, utils::ArithmeticTrait U>
[[nodiscard]] inline auto RandomFastValueFromRange(T min, U max)
    -> std::common_type_t<T, U> {
  return RandomFast().ValueFromRange(min, max);
}
 
}  // namespace helios::utils