Table of Contents

Class PCG64DXSM

Namespace
NumSharp
Assembly
NumSharp.dll

PCG64DXSM — the 128-bit PCG with the cheap 64-bit multiplier and the stronger "double xorshift multiply" output (NumPy's numpy.random.PCG64DXSM), recommended by NumPy for massively parallel use.

public class PCG64DXSM : BitGenerator
Inheritance
PCG64DXSM
Inherited Members

Remarks

Port of NumPy 2.4.2's _pcg64.pyx PCG64DXSM + pcg64.h pcg_cm_random_r. It is seeded exactly like PCG64 (the same pcg64_set_seed, so the two share a state for the same seed) but outputs DXSM of the PRE-iterated state and then steps with state * 0xda942042e4dd58b5 + inc; its advance(BigInteger) composes that cheap-multiplier step. The raw stream is byte-identical to NumPy's.

Constructors

PCG64DXSM()

Constructs a PCG64DXSM seeded from fresh, unpredictable OS entropy (NumPy's PCG64DXSM()).

public PCG64DXSM()

PCG64DXSM(ISeedSequence)

Constructs and seeds a PCG64DXSM from the given seed sequence (generate_state(4, uint64)).

public PCG64DXSM(ISeedSequence seed)

Parameters

seed ISeedSequence

The seed sequence — null is NumPy's seed=None: a fresh OS-entropy SeedSequence (the parameter name is NumPy's, so seed: sequence ports verbatim).

Remarks

The overload a bare null literal binds (new PCG64DXSM(null), NumPy's PCG64DXSM(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

seed is a SeedlessSeedSequence.

PCG64DXSM(int[])

Constructs a PCG64DXSM seeded from a sequence of non-negative integers through SeedSequence.

public PCG64DXSM(int[] seed)

Parameters

seed int[]

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.

PCG64DXSM(long)

Constructs a PCG64DXSM seeded from a non-negative integer through SeedSequence.

public PCG64DXSM(long seed)

Parameters

seed long

The seed (must be non-negative).

Exceptions

ValueError

seed is negative.

PCG64DXSM(long[])

Constructs a PCG64DXSM seeded from a sequence of non-negative integers through SeedSequence.

public PCG64DXSM(long[] seed)

Parameters

seed long[]

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.

PCG64DXSM(BigInteger)

Constructs a PCG64DXSM seeded from an arbitrary-size non-negative integer through SeedSequence.

public PCG64DXSM(BigInteger seed)

Parameters

seed BigInteger

The seed (must be non-negative).

Exceptions

ValueError

seed is negative.

PCG64DXSM(uint[])

Constructs a PCG64DXSM seeded from uint32 words through SeedSequence.

public PCG64DXSM(uint[] seed)

Parameters

seed uint[]

The seed words. Null is NumPy's None — fresh OS entropy (it used to seed the fixed empty-list stream).

PCG64DXSM(ulong)

Constructs a PCG64DXSM seeded from a non-negative integer through SeedSequence.

public PCG64DXSM(ulong seed)

Parameters

seed ulong

The 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

string

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), typed.

public PCG64DXSM.State state { get; set; }

Property Value

PCG64DXSM.State

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

seed ISeedSequence

The 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

dst double*

The destination (at least n doubles).

n long

The 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

dst float*

The destination (at least n floats).

n long

The number of draws (non-positive: nothing).

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

dst ulong*

The destination (at least n words).

n long

The number of words (non-positive: nothing).

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

dst uint*

The destination (at least n words).

n long

The number of words (non-positive: nothing).

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

dst ulong*

The destination (at least n words; may be unaligned).

n long

The 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

value BitGeneratorState

The 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 PCG64DXSM.advance → pcg64_cm_advance), in O(log delta).

public PCG64DXSM advance(BigInteger delta)

Parameters

delta BigInteger

The number of 64-bit draws to skip — any integer, reduced mod 2**128 (negative steps back).

Returns

PCG64DXSM

This bit generator (advanced in place).

Remarks

Composes the CHEAP-multiplier step; resets the buffered 32-bit half. 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 PCG64DXSM.jumped).

public PCG64DXSM jumped(long jumps = 1)

Parameters

jumps long

The number of jumps (any integer; 0 is a plain copy of the state).

Returns

PCG64DXSM

A new PCG64DXSM carrying a fresh OS-entropy seed sequence (NumPy's self.class()).

jumped(BigInteger)

Arbitrary-size jumped(long).

public PCG64DXSM jumped(BigInteger jumps)

Parameters

jumps BigInteger

The number of jumps (any integer).

Returns

PCG64DXSM

A new, jumped PCG64DXSM.