IRandomStreamSource<TRandom> Interface

Defines a source for hierarchical streams of random number generators.

Definition

Namespace: Numerics.NET.Random
Assembly: Numerics.NET (in Numerics.NET.dll) Version: 10.3.0
C# 
public interface IRandomStreamSource<out TRandom>

Type Parameters

TRandom
The type of random number generator produced by this source.

Remarks

IRandomStreamSource<TRandom> provides a unified interface for managing hierarchical RNG stream generation. It supports two primary models:

  • Mixing-based streams (RandomStreamTree<TRandom>): Uses seed derivation to create deterministic hierarchical streams (NumPy-style).
  • Jump-based partitioning (RandomStreamPartition<TRandom>): Uses jump operations to partition a sequence into disjoint segments (RngStreams-style).

Path-Based Addressing:

Each stream source maintains a hierarchical path represented as a sequence of unsigned 64-bit indices. The path uniquely identifies the position within the stream hierarchy. For example, path [0, 3, 1] represents the second child of the fourth child of the first child of the root.

Index Management:

The NextIndex property tracks the next child index to be consumed at the current scope. Calling NextStream() returns the RNG at Path + [NextIndex] and then increments NextIndex.

Branching:

Stream sources support two branching patterns:

  • Branch(UInt64): Creates a child scope at a specific index without consuming the parent's next index.
  • BranchAndAdvance(): Creates a child scope at the current next index and advances the parent's counter.

Example

C# 
// Create a hierarchical stream tree
var options = new RandomOptions(42);
var tree = new RandomStreamTree<Pcg64>(in options);

// Get streams at the root level
var rng0 = tree.NextStream(); // Path: [0]
var rng1 = tree.NextStream(); // Path: [1]

// Create a child scope
var child = tree.Branch(5);   // Path: [5]
var rng5_0 = child.NextStream(); // Path: [5, 0]
var rng5_1 = child.NextStream(); // Path: [5, 1]

// Parent scope continues
var rng2 = tree.NextStream(); // Path: [2]

Properties

NextIndex Gets the index of the next stream to be consumed at this scope.
Path Gets the hierarchical path identifying the current scope.

Methods

Advance Advances the next index by the specified count without generating streams.
Branch Creates a child stream source at the specified index without advancing this source.
BranchAndAdvance Creates a child stream source at the current next index and advances this source.
NextStream Returns an RNG for the next child stream and advances the index.
NextStreams Returns an array of RNGs for the next N child streams and advances the index.
PrefixStream Returns an RNG corresponding to the current path prefix only.
Seek Sets the next stream index to the specified value.

See Also