Pcg64 Class

Represents a pseudo-random number generator based on the PCG64 XSL-RR algorithm with full 128-bit multiplier.

Definition

Namespace: Numerics.NET.Random
Assembly: Numerics.NET (in Numerics.NET.dll) Version: 10.3.0
C#
public sealed class Pcg64 : RandomSource<ScalarGenerator64<Pcg64Engine>>, 
	IRandomSourceFactory<Pcg64>, IAdvanceable, IJumpable
Inheritance
Object  →  RandomSource<ScalarGenerator64<Pcg64Engine>>  →  Pcg64
Implements
IAdvanceable, IJumpable, IRandomSourceFactory<Pcg64>

Remarks

Use the Pcg64 class to represent a pseudo-random number generator that uses the PCG64 XSL-RR (Xorshift-Low, Random-Rotate) algorithm by Melissa O'Neill.

This generator features a 128-bit state with a period of 2128. It passes the strictest statistical tests including BigCrush and PractRand, and provides excellent statistical properties and performance.

Algorithm details:

  • LCG: 128-bit state
  • Multiplier: 0x2360ED051FC65DA44385DF649FCCF645 (full 128-bit multiplier)
  • Output function: XSL-RR 128/64 (Xorshift-Low, Random-Rotate)
  • Output ordering: output-then-advance (outputs from state before advancing)

Use case: This is the reference PCG64 implementation matching the canonical specification with full 128-bit multiplication. It is compatible with NumPy 1.17+ PCG64 (which also uses the full multiplier) and serves as the academic/reference implementation.

Compatibility note: This generator will produce different sequences than Pcg64Dxsm even with the same seed, due to the different multiplier and/or output function.

PCG generators are notable for their mathematical soundness, predictability, and ease of implementing multiple independent streams.

Reference: Melissa E. O'Neill. "PCG: A Family of Simple Fast Space-Efficient Statistically Good Algorithms for Random Number Generation." Harvey Mudd College, 2014.

See also: https://www.pcg-random.org/ and https://numpy.org/doc/stable/reference/random/bit_generators/pcg64.html

Example

C#
var rng = new Pcg64(42);
double x = rng.NextDouble();
ulong bits = rng.NextUInt64();

Constructors

Pcg64() Initializes a new instance of the Pcg64 class using OS entropy.
Pcg64(RandomOptions) Initializes a new instance of the Pcg64 class with the specified options.
Pcg64(ReadOnlySpan<Byte>) Initializes a new instance of the Pcg64 class from saved state.
Pcg64(UInt64) Initializes a new instance of the Pcg64 class with direct state initialization.
Pcg64(Int64, SeedProfile) Initializes a new instance of the Pcg64 class with the specified seed.
Pcg64(ReadOnlySpan<UInt64>, SeedProfile) Initializes a new instance of the Pcg64 class with the specified seed array.
Pcg64(UInt128, UInt128) Initializes a new instance of the Pcg64 class with direct state and stream initialization.
Pcg64(UInt64, UInt64) Initializes a new instance of the Pcg64 class with direct state and stream initialization.
Pcg64(Int64, StreamAddress, SeedProfile) Initializes a new instance of the Pcg64 class with the specified seed.
Pcg64(ReadOnlySpan<UInt64>, StreamAddress, SeedProfile) Initializes a new instance of the Pcg64 class with the specified seed array.
Pcg64(UInt64, UInt64, UInt64, UInt64) Initializes a new instance of the Pcg64 class with direct state and stream initialization.

Properties

BitsPerWord Gets the number of bits per word in the generator's native output.
(Overrides RandomSource<TGenerator>.BitsPerWord)
JumpSize Gets the size category of the primary jump operation.
LongJumpSize Gets the size category of the long jump operation.
Name Gets a human-readable name for this random number generator.
(Overrides RandomSource<TGenerator>.Name)
StateSize Gets the number of bytes required to save/load this generator's state.
(Inherited from RandomSource<TGenerator>)
Uncached Gets an uncached facade for this random number generator.
(Inherited from RandomSource<TGenerator>)

Methods

Advance Advances the RNG state by the specified number of outputs.
Copy Returns a deep copy of this RNG.
Create Creates a new Pcg64 instance from the specified options.
CreateStreamPartition Creates a jump-based stream partition for generating independent RNG streams.
CreateStreamTree Creates a hierarchical stream tree for generating independent RNG streams.
EqualsDetermines whether the specified object is equal to the current object.
(Inherited from Object)
Fill(Span<UInt32>) Fills a span with random 32-bit unsigned integer values.
(Inherited from RandomSource<TGenerator>)
Fill(Span<Int32>, Int32) Fills a span with random 32-bit signed integers less than the specified maximum.
(Inherited from RandomSource<TGenerator>)
Fill(Span<Int64>, Int64) Fills a span with random 64-bit signed integers less than the specified maximum.
(Inherited from RandomSource<TGenerator>)
Fill(Span<Int32>, Int32, Int32) Fills a span with random 32-bit signed integers within a specified range.
(Inherited from RandomSource<TGenerator>)
Fill(Span<Int64>, Int64, Int64) Fills a span with random 64-bit signed integers within a specified range.
(Inherited from RandomSource<TGenerator>)
GetHashCodeServes as the default hash function.
(Inherited from Object)
GetState Returns the current state of the generator as a byte array.
(Inherited from RandomSource<TGenerator>)
GetTypeGets the Type of the current instance.
(Inherited from Object)
Jumped Returns a new instance of the random number generator that is advanced by a specified number of jumps in the sequence.
LoadState Loads the generator's state from the source span in a stable little-endian format.
(Inherited from RandomSource<TGenerator>)
LongJumped Returns a new instance of the random number generator that is advanced by a specified number of long jumps in the sequence.
Next() Returns a non-negative random integer.
(Inherited from RandomSource<TGenerator>)
Next(Int32) Returns a non-negative random integer less than the specified maximum.
(Inherited from RandomSource<TGenerator>)
Next(Int32, Int32) Returns a random integer within a specified range.
(Inherited from RandomSource<TGenerator>)
NextBytes(Byte[]) Fills the elements of a specified array of bytes with random numbers.
(Inherited from RandomSource<TGenerator>)
NextBytes(Span<Byte>) Fills the elements of a specified span of bytes with random numbers.
(Inherited from RandomSource<TGenerator>)
NextBytes(Byte[], Boolean) Fills the elements of a specified span of bytes with random numbers.
(Inherited from RandomSource<TGenerator>)
NextBytes(Span<Byte>, Boolean) Fills the elements of a specified span of bytes with random numbers.
(Inherited from RandomSource<TGenerator>)
NextDouble Returns a random floating-point number in the range [0.0, 1.0).
(Inherited from RandomSource<TGenerator>)
NextInt64() Returns a non-negative random 64-bit integer.
(Inherited from RandomSource<TGenerator>)
NextInt64(Int64) Returns a non-negative random 64-bit integer less than the specified maximum.
(Inherited from RandomSource<TGenerator>)
NextInt64(Int64, Int64) Returns a random 64-bit integer within a specified range.
(Inherited from RandomSource<TGenerator>)
NextSingle Returns a random single-precision floating-point number in the range [0.0, 1.0).
(Inherited from RandomSource<TGenerator>)
NextUInt32 Returns a random 32-bit unsigned integer.
(Inherited from RandomSource<TGenerator>)
NextUInt64 Returns a random 64-bit unsigned integer.
(Inherited from RandomSource<TGenerator>)
NumpyJump Advances this generator by the equivalent of count NumPy PCG64 jumps.
Reinitialize Reinitializes this random number generator using the specified initialization options.
(Inherited from RandomSource<TGenerator>)
SaveState Saves the generator's state to the destination span in a stable little-endian format.
(Inherited from RandomSource<TGenerator>)
ToStringReturns a string that represents the current object.
(Inherited from Object)

See Also