Class PCG64
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
PCG64 (XSL-RR 128/64) bit generator — the default BitGenerator behind
np.random.default_rng.
public class PCG64 : BitGenerator
- Inheritance
-
PCG64
- Inherited Members
Remarks
Port of NumPy 2.4.2's PCG64 (numpy/random/src/pcg64/pcg64.h, _pcg64.pyx), a 128-bit LCG
with the XSL-RR 128→64 output permutation. The 128-bit state arithmetic is expressed with .NET's native
UInt128, so the raw stream is byte-for-byte identical to NumPy's (verified against
random_raw). Seeding goes through SeedSequence exactly as NumPy does
(generate_state(4, uint64) → initial state and increment). advance(BigInteger) and
jumped(long) move the stream in O(log n).
Constructors
PCG64()
Constructs a PCG64 seeded from fresh, unpredictable OS entropy (NumPy's PCG64() / seed=None).
public PCG64()
PCG64(ISeedSequence)
Constructs and seeds a PCG64 from the given seed sequence.
public PCG64(ISeedSequence seed)
Parameters
seedISeedSequenceThe seed sequence;
generate_state(4, uint64)supplies the state and the stream — null is NumPy'sseed=None: a fresh OS-entropy SeedSequence (the parameter name is NumPy's, soseed: sequenceports verbatim).
Remarks
The overload a bare null literal binds (new PCG64(null), NumPy's PCG64(None)): the
int[]/long[]/uint[] overloads are equally good targets for it under plain C# rules, so
this one carries the higher OverloadResolutionPriority — harmless for every non-null argument, since
only a seed sequence converts to ISeedSequence.
Exceptions
- NotImplementedError
seedis a SeedlessSeedSequence.
PCG64(int[])
Constructs a PCG64 seeded from a sequence of non-negative integers through SeedSequence.
public PCG64(int[] seed)
Parameters
seedint[]The seed words (each must be non-negative). Null is NumPy's
None— fresh OS entropy (it used to seed the fixed empty-list stream).
Exceptions
- ValueError
An element is negative.
PCG64(long)
Constructs a PCG64 seeded from a non-negative integer through SeedSequence.
public PCG64(long seed)
Parameters
seedlongThe seed (must be non-negative).
Exceptions
- ValueError
seedis negative (expected non-negative integer).
PCG64(long[])
Constructs a PCG64 seeded from a sequence of non-negative integers through SeedSequence.
public PCG64(long[] seed)
Parameters
seedlong[]The seed words (each must be non-negative; values of 2**32 and above span several words). Null is NumPy's
None— fresh OS entropy (it used to seed the fixed empty-list stream).
Exceptions
- ValueError
An element is negative.
PCG64(BigInteger)
Constructs a PCG64 seeded from an arbitrary-size non-negative integer through SeedSequence.
public PCG64(BigInteger seed)
Parameters
seedBigIntegerThe seed (must be non-negative).
Exceptions
- ValueError
seedis negative.
PCG64(uint[])
Constructs a PCG64 seeded from uint32 words through SeedSequence (NumPy's uint32-array pass-through).
public PCG64(uint[] seed)
Parameters
seeduint[]The seed words. Null is NumPy's
None— fresh OS entropy (it used to seed the fixed empty-list stream).
PCG64(ulong)
Constructs a PCG64 seeded from a non-negative integer through SeedSequence.
public PCG64(ulong seed)
Parameters
seedulongThe seed.
Properties
Name
The bit generator's class name, e.g. "PCG64". Drives Generator's repr and the state checks.
public override string Name { get; }
Property Value
Remarks
A subclass returns its own NumPy-style class name: Generator prints it as
Generator(NAME). Its own state refusal (in SetStateCore(BitGeneratorState)) should name the same class, as the
built-in generators' NumPy texts do.
state
Gets or sets the current internal state (NumPy's bit_generator.state property), typed.
public PCG64.State state { get; set; }
Property Value
Remarks
The getter returns a fresh snapshot; the setter copies the values in. Both hold the lock.
Exceptions
- TypeError
Setting null.
Methods
CreateFromSeed(ISeedSequence)
Constructs a new instance of this bit generator's concrete type seeded from seed (NumPy's type(self)(seed=seed)).
public override BitGenerator CreateFromSeed(ISeedSequence seed)
Parameters
seedISeedSequenceThe seed sequence.
Returns
- BitGenerator
The new, independently seeded generator.
Remarks
spawn(int) builds every child through it, so a subclass returns its OWN type here - a subclass of a built-in generator that does not override it spawns instances of the built-in class.
FillDouble(double*, long)
Fills n next_double draws in [0, 1) (the stream NextDouble() yields).
public override void FillDouble(double* dst, long n)
Parameters
dstdouble*The destination (at least
ndoubles).nlongThe number of draws (non-positive: nothing).
Remarks
The caller holds lock.
FillFloat(float*, long)
Fills n next_float draws in [0, 1) (the stream NextFloat() yields).
public override void FillFloat(float* dst, long n)
Parameters
Remarks
The caller holds lock.
FillRaw(ulong*, long)
Fills n raw words (next_raw, widened to 64 bits) — the stream NextRaw() yields.
public override void FillRaw(ulong* dst, long n)
Parameters
Remarks
The caller holds lock.
FillUInt32(uint*, long)
Fills n words of next_uint32, buffered halves included (the stream NextUInt32() yields).
public override void FillUInt32(uint* dst, long n)
Parameters
Remarks
The caller holds lock.
FillUInt64(ulong*, long)
Fills n words of next_uint64 (the stream NextUInt64() yields).
public override void FillUInt64(ulong* dst, long n)
Parameters
dstulong*The destination (at least
nwords; may be unaligned).nlongThe number of words (non-positive: nothing).
Remarks
The caller holds lock.
GetStateCore()
Snapshots the engine state.
public override BitGeneratorState GetStateCore()
Returns
- BitGeneratorState
A fresh state object of the concrete generator's state type.
Remarks
The unlocked half of state's getter, which a subclass implements. Callers read state instead: called directly this skips lock, so a concurrent draw can tear the snapshot.
NextUInt32()
The next uniform 32-bit word (NumPy's next_uint32).
public override uint NextUInt32()
Returns
- uint
A uniformly distributed 32-bit value; advances (or consumes a buffered half of) the engine state.
Remarks
Not synchronized, as NextUInt64(). A 64-bit engine returns the low half of a word and
buffers the high half for the next call (NumPy's has_uint32 / uinteger), which its state must
carry.
NextUInt64()
The next uniform 64-bit word (NumPy's next_uint64).
public override ulong NextUInt64()
Returns
- ulong
A uniformly distributed 64-bit value; advances the engine state.
Remarks
Not synchronized: a caller outside Generator holds lock around its draws, or two threads tear the state and emit values of no seed's stream.
SetStateCore(BitGeneratorState)
Restores the engine state from a snapshot (validated against this generator's type).
public override void SetStateCore(BitGeneratorState value)
Parameters
valueBitGeneratorStateThe non-null snapshot.
Remarks
The unlocked half of state's setter, which a subclass implements (and which must refuse a snapshot of another type). Callers assign state instead: called directly this skips the null check and lock.
Exceptions
- ValueError
The snapshot belongs to another bit generator type.
advance(BigInteger)
Advance the underlying RNG as if delta draws had occurred (NumPy's PCG64.advance),
in O(log delta).
public PCG64 advance(BigInteger delta)
Parameters
deltaBigIntegerThe number of 64-bit draws to skip — any integer, reduced mod 2**128 as NumPy's
wrap_intdoes, so a negative delta steps backwards (advance(-1)undoes one draw).
Returns
- PCG64
This bit generator (advanced in place).
Remarks
Resets the buffered 32-bit half, as NumPy does "to ensure exact reproducibility" — a distribution's draw count is not a count of raw words (rejection sampling, 32-bit halves), so only raw words are skipped. Holds the lock.
jumped(long)
Returns a new bit generator with this one's state jumped as if jumps * 210306068529402873165736369884012333109
draws had been made (NumPy's PCG64.jumped; the step is (phi - 1) * 2**128).
public PCG64 jumped(long jumps = 1)
Parameters
jumpslongThe number of jumps (any integer; 0 is a plain copy of the state).
Returns
Remarks
Built like NumPy's self.class() — the copy carries a FRESH OS-entropy seed sequence, not this
one's — then state = self.state and advance(step * jumps) (which also clears the buffered half).
jumped(BigInteger)
Arbitrary-size jumped(long).
public PCG64 jumped(BigInteger jumps)
Parameters
jumpsBigIntegerThe number of jumps (any integer).