pcg_random.hpp

Go to the documentation of this file.

#ifndef PCG_RANDOM_HPP
#define PCG_RANDOM_HPP
 
/**
 * \file pcg_random.hpp
 * \brief A minimal C++ implementation of the PCG32 random number generator.
 * \author M.E. O'Neill (original implementation)
 * \ingroup UtilsRandom
 *
 * This file provides a standalone implementation of pcg32, a 32-bit output
 * random number generator from the PCG family. It is designed to be a drop-in
 * replacement for standard C++ random number engines like std::mt19937.
 *
 * The PCG family of generators is known for its excellent statistical
 * properties, small code size, and high performance.
 *
 * This implementation is based on the C++ code provided on the official PCG
 * website: http://www.pcg-random.org/
 *
 * The original PCG library is distributed under the MIT or Apache 2.0
 * licenses. This minimal version is provided for convenience.
 */
 
#include <cstdint>
#include <limits>
 
namespace Rng {
 
    /**
     * \brief A 32-bit Permuted Congruential Generator (pcg32).
     * \ingroup UtilsRandom
     *
     * This class implements the `UniformRandomBitGenerator` concept from the
     * C++ standard library, making it compatible with distribution classes like
     * `std::uniform_int_distribution` and `std::uniform_real_distribution`.
     */
    class Pcg32 {
       public:
        /// \brief The result type of the generator, required by the
        /// UniformRandomBitGenerator concept.
        using result_type = uint32_t;
 
        /**
         * \brief Returns the minimum value the generator can produce.
         * \return The minimum value (0).
         */
        static constexpr result_type min() {
            return std::numeric_limits<result_type>::min();
        }
 
        /**
         * \brief Returns the maximum value the generator can produce.
         * \return The maximum value.
         */
        static constexpr result_type max() {
            return std::numeric_limits<result_type>::max();
        }
 
        /**
         * \brief Default constructor. Initializes the generator with a default
         *        seed.
         */
        Pcg32() : state_(0x853c49e6748fea9bULL), inc_(0xda3e39cb94b95bdbULL) {}
 
        /**
         * \brief Constructs the generator with a specific seed.
         * \param seed The initial seed value for the generator's state.
         */
        explicit Pcg32(uint64_t seed) { this->seed(seed); }
 
        /**
         * \brief Seeds the random number generator.
         *
         * \param init_seed The seed value. The stream is also initialised
         *                  based on this seed.
         */
        void seed(uint64_t init_seed) {
            state_ = 0;
            inc_ = (init_seed << 1) | 1;
            (*this)();  // Advance the generator once
            state_ += 0x853c49e6748fea9bULL;
            (*this)();  // Advance again
        }
 
        /**
         * \brief Generates the next random number in the sequence.
         * \return A 32-bit unsigned random integer.
         */
        result_type operator()() {
            const uint64_t old_state = state_;
            // Advance internal state
            state_ = old_state * 6364136223846793005ULL + (inc_ | 1);
            // Calculate output function (XSH-RR)
            const uint32_t xorshifted =
                static_cast<uint32_t>(((old_state >> 18u) ^ old_state) >> 27u);
            const uint32_t rot = static_cast<uint32_t>(old_state >> 59u);
            return (xorshifted >> rot) | (xorshifted << ((-rot) & 31));
        }
 
        /**
         * \brief Discards a specified number of values from the sequence.
         * \param z The number of values to discard.
         */
        void discard(unsigned long long z) {
            for (unsigned long long i = 0; i < z; ++i) {
                (*this)();
            }
        }
 
        // Equality and inequality operators
        /**
         * \brief Checks if two generators have the same internal state.
         * \return True if the state and stream are identical.
         */
        friend bool operator==(const Pcg32& lhs, const Pcg32& rhs) {
            return lhs.state_ == rhs.state_ && lhs.inc_ == rhs.inc_;
        }
        /**
         * \brief Checks if two generators have different internal states.
         * \return True if the state or stream are different.
         */
        friend bool operator!=(const Pcg32& lhs, const Pcg32& rhs) {
            return !(lhs == rhs);
        }
 
       private:
        /// \brief The internal state of the generator.
        uint64_t state_;
        /**
         * \brief The stream selector, which determines the sequence. Must be
         *        odd.
         */
        uint64_t inc_;
    };
 
}  // namespace Rng
 
#endif  // PCG_RANDOM_HPP