SeedSequence Class

Represents a stateful deterministic entropy stream derived from a primary seed.

Definition

Namespace: Numerics.NET.Random
Assembly: Numerics.NET (in Numerics.NET.dll) Version: 10.3.0
C# 
public abstract class SeedSequence
Inheritance
Object  →  SeedSequence
Derived

Remarks

SeedSequence provides a uniform interface for expanding a simple seed value into the full state required by any pseudo-random number generator. Different PRNGs require different amounts of entropy for initialization, and SeedSequence abstracts this complexity.

Key Properties:

  • Stateful: Successive calls to NextUInt32() advance an internal stream position
  • Deterministic: Identical seed produces identical output stream across all platforms
  • Length-agnostic: Supports PRNGs with arbitrary state sizes (e.g., 128-bit, 256-bit, or larger)
  • Pure entropy provider: Does not validate or fix PRNG state (e.g., does not detect all-zero states)
  • 32-bit basis: The fundamental entropy unit is 32-bit words (NextUInt32()). 64-bit values are derived via little-endian packing of consecutive 32-bit values.

32-bit Basis Rationale:

The 32-bit design aligns with established reference implementations including C++11 std::seed_seq and NumPy's SeedSequence. This ensures cross-platform reproducibility when using compatible algorithms. 64-bit values from NextUInt64() are formed by packing two consecutive 32-bit values in little-endian order.

PRNG Responsibility:

SeedSequence generates entropy values but does not enforce PRNG-specific constraints. For example, if a PRNG like Xoshiro256** requires non-zero state, the PRNG constructor must validate and handle this case. The typical pattern is: retry with additional entropy if an all-zero state is detected.

Construction Flow:

The typical initialization flow is: Seeds → SeedSequence → PRNG state. Use factory methods in SeedSequences to create instances with well-defined, cross-platform reproducible behavior (e.g., SplitMix64, NumPy factory methods).

  Important

Do not instantiate SeedSequence directly. Use the factory methods in SeedSequences to ensure consistent, documented behavior across the library.

Example

C# 
// Use factory methods from SeedSequences
var seedSequence = SeedSequences.SplitMix64(12345);
var rng = new Xoshiro256StarStar(seedSequence);

// Or use RandomOptions which automatically creates the
// SeedSequence
var options = new RandomOptions(12345, null, 
    SeedProfile.Default);
var rng2 = new Xoshiro256StarStar(options);

// For custom initialization, manually fill state
var customSeq = SeedSequences.SplitMix64(42);
ulong[] state = new ulong[4];
customSeq.Fill(state);

Constructors

SeedSequenceInitializes a new instance of the SeedSequence class

Methods

EqualsDetermines whether the specified object is equal to the current object.
(Inherited from Object)
Fill(Span<UInt32>) Fills a span of 32-bit unsigned integers with entropy values.
Fill(Span<UInt64>) Fills a span of 64-bit unsigned integers with entropy values.
Fill(UInt64[]) Fills an array of 64-bit unsigned integers with entropy values.
FillBytes Fills a span of bytes with entropy values.
FinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object)
GetHashCodeServes as the default hash function.
(Inherited from Object)
GetTypeGets the Type of the current instance.
(Inherited from Object)
MemberwiseCloneCreates a shallow copy of the current Object.
(Inherited from Object)
NextUInt32 Generates the next 32-bit unsigned integer from the entropy stream.
NextUInt64 Generates the next 64-bit unsigned integer from the entropy stream.
Reset Resets the internal state of the entropy stream to the initial state.
ToStringReturns a string that represents the current object.
(Inherited from Object)

See Also