Class Philox
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
The Philox 4x64-10 counter-based bit generator (NumPy's numpy.random.Philox): a 256-bit counter
encrypted under a 128-bit key by ten Feistel-like rounds, so any stream position — and any of 2**128 keyed
streams — is directly addressable.
public class Philox : BitGenerator
- Inheritance
-
Philox
- Inherited Members
Remarks
Port of NumPy 2.4.2's _philox.pyx + src/philox/philox.{c,h} (Salmon et al., "Parallel Random
Numbers: As Easy as 1, 2, 3", SC11); the raw stream is byte-identical to NumPy's. Each block increments the
counter (with carry) BEFORE encrypting it and yields four 64-bit words, served from a buffer; 32-bit draws
split a 64-bit word and cache its high half. Seeding follows NumPy exactly: a seed goes through
SeedSequence (generate_state(2, uint64) becomes the key, the counter starts at zero),
while an explicit key bypasses seeding altogether — then seed_seq is null
and spawn(int) is unavailable, as in NumPy. advance(BigInteger) adds to the counter
(mod 2256); jumped(long) advances by 2128 per jump.
Constructors
Philox()
Constructs a Philox seeded from fresh, unpredictable OS entropy (NumPy's Philox()).
public Philox()
Philox(ISeedSequence)
Constructs a Philox keyed from the given seed sequence (generate_state(2, uint64)), counter zero.
public Philox(ISeedSequence seed)
Parameters
seedISeedSequenceThe seed sequence — normally a SeedSequence; any ISeedSequence works; null is NumPy's
seed=None: a fresh OS-entropy SeedSequence (the parameter name is NumPy's, soseed: sequenceports verbatim).
Remarks
The overload a bare null literal binds (new Philox(null), NumPy's Philox(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.
Philox(int[])
Constructs a Philox keyed from a sequence of non-negative integers through SeedSequence.
public Philox(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.
Philox(long)
Constructs a Philox keyed from a non-negative integer seed through SeedSequence.
public Philox(long seed)
Parameters
seedlongThe seed (must be non-negative).
Exceptions
- ValueError
seedis negative.
Philox(long[])
Constructs a Philox keyed from a sequence of non-negative integers through SeedSequence.
public Philox(long[] seed)
Parameters
seedlong[]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.
Philox(BigInteger)
Constructs a Philox keyed from an arbitrary-size non-negative integer seed through SeedSequence.
public Philox(BigInteger seed)
Parameters
seedBigIntegerThe seed (must be non-negative).
Exceptions
- ValueError
seedis negative.
Philox(object, object, object)
Constructs a Philox with NumPy's full signature, Philox(seed=None, counter=None, key=None).
public Philox(object seed = null, object counter = null, object key = null)
Parameters
seedobjectnull (with no
key: fresh OS entropy), an ISeedSequence, or anything SeedSequence accepts as entropy; itsgenerate_state(2, uint64)becomes the key.counterobjectThe initial 256-bit counter (null = 0): an integer in
[0, 2**256)(a real float truncates toward zero, a string parses as a Python int), or a four-element array of words, lowest first, cast to uint64 as NumPy'sastypecasts (a negative word wraps, a float word truncates).keyobjectAn explicit 128-bit key — an integer in
[0, 2**128)or a two-element word array, same forms ascounter. Mutually exclusive withseed; the resulting generator has no seed sequence (so it cannot spawn(int)).
Remarks
Validation follows NumPy's order — the seed/key conflict, then the seed (inside SeedSequence), then the key, then the counter — so the first bad argument reported matches NumPy's.
Exceptions
- ValueError
Both
seedandkeygiven (seed and key cannot be both used); a key/counter integer out of range (key must be positive and less than 2**128.); an array form of the wrong size (counter must have 4 elements when using array form); a NaN or unparsable string; an invalid seed.- OverflowError
An infinite float key/counter; an integer element too large for uint64.
- TypeError
An invalid seed type, or a complex/non-numeric key or counter.
Philox(uint[])
Constructs a Philox keyed from uint32 words through SeedSequence.
public Philox(uint[] seed)
Parameters
seeduint[]The seed words. Null is NumPy's
None— fresh OS entropy (it used to seed the fixed empty-list stream).
Philox(ulong)
Constructs a Philox keyed from a non-negative integer seed through SeedSequence.
public Philox(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), typed.
public Philox.State state { get; set; }
Property Value
Exceptions
- TypeError
Setting null, or a state with an unset (null) word array — NumPy's subscript of
None,'NoneType' object is not subscriptable, raised at the first read of that array.- IndexError
A word array shorter than NumPy's loop reads (counter 4, key 2, buffer 4).
- ValueError
A negative
buffer_pos.
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 Philox.advance)
— strictly, as if delta BLOCKS had been encrypted: the value is added to the 256-bit
counter, and each block holds four 64-bit draws.
public Philox advance(BigInteger delta)
Parameters
deltaBigIntegerThe counter increment — any integer, reduced mod 2**256 as NumPy's
wrap_intdoes (a negative delta steps back).
Returns
- Philox
This bit generator (advanced in place).
Remarks
Resets the block buffer and the buffered 32-bit half (NumPy "to ensure exact reproducibility"), so a partially consumed block is discarded. Holds the lock.
jumped(long)
Returns a new bit generator with this one's state jumped as if 2**128 * jumps draws had been made
(NumPy's Philox.jumped): the counter's upper half advances by jumps.
public Philox jumped(long jumps = 1)
Parameters
jumpslongThe number of jumps (any integer; 0 is a copy of the counter and key).
Returns
- Philox
A new Philox — built like NumPy's
self.class(), so it carries a FRESH OS-entropy seed sequence — with this one's state, then advanced (which discards the copied block buffer).
jumped(BigInteger)
Arbitrary-size jumped(long).
public Philox jumped(BigInteger jumps)
Parameters
jumpsBigIntegerThe number of jumps (any integer).