RandomStreamTree<TRandom> Class

public sealed class RandomStreamTree<TRandom> : RandomStreamSource<TRandom>
where TRandom : Object, IRandomSourceFactory<TRandom>

Public NotInheritable Class RandomStreamTree(Of TRandom As {Object, IRandomSourceFactory(Of TRandom)})
	Inherits RandomStreamSource(Of TRandom)

generic<typename TRandom>
where TRandom : Object, IRandomSourceFactory<TRandom>
public ref class RandomStreamTree sealed : public RandomStreamSource<TRandom>

[<SealedAttribute>]
type RandomStreamTree<'TRandom when 'TRandom : Object and IRandomSourceFactory<'TRandom>> = 
    class
        inherit RandomStreamSource<'TRandom>
    end

Inheritance

Object  →  RandomStreamSource<TRandom>  →  RandomStreamTree<TRandom>

Type Parameters

TRandom

The type of random number generator to produce.

RandomStreamTree<TRandom> provides NumPy-style hierarchical stream generation where each stream is derived from base seed material combined with its hierarchical path. This approach ensures:

• Determinism: Same seed + same path always produces identical streams
• Independence: Different paths produce uncorrelated streams
• Unlimited depth: Hierarchy can be arbitrarily deep
• O(1) advancement: Advance(UInt64) is constant-time

NumPy Compatibility:

When using Numpy, single-level streams (paths with one element, e.g., [0], [1], [5]) produce bit-identical output to NumPy's SeedSequence.spawn() for compatible RNGs (PCG64, Philox, etc.). The path element corresponds directly to NumPy's spawn key.

For multi-level hierarchies (nested spawning), the current implementation uses a deterministic hash-based combination of path elements. This ensures reproducible behavior within Numerics.NET but may not produce bit-identical results to NumPy's nested spawn() calls. For bit-exact NumPy compatibility in nested scenarios, use single-level spawning and manually create RandomOptions with explicit stream IDs that match NumPy's spawn keys.

Hierarchical Addressing:

Each position in the hierarchy is addressed by a path of 64-bit indices. For single-level NumPy-compatible spawning: // Matches: np.random.SeedSequence(42).spawn(10)[3] var tree = new RandomStreamTree<Pcg64>( new RandomOptions(42, null, SeedProfile.Numpy)); var rng = tree.Branch(3).PrefixStream(); For nested hierarchies (deterministic but not bit-exact with NumPy): var tree = new RandomStreamTree<Pcg64>( new RandomOptions(42, null, SeedProfile.Numpy)); var child = tree.Branch(3); var grandchild = child.Branch(2); var rng = grandchild.PrefixStream();

Performance:

Stream creation cost is O(1) in the number of streams at the same level, but O(depth) in the hierarchy depth due to path-based derivation. For very deep hierarchies (depth > 10), consider caching commonly-used child scopes.

Reference