CounterBasedRandomSource<TGenerator, TWord> Class

public abstract class CounterBasedRandomSource<TGenerator, TWord> : RandomSource<TGenerator>, 
	ICounterBased<TWord>
where TGenerator : struct, new(), IBlockRandomGenerator, ICounterBased<TWord>
where TWord : struct, new(), Object

Public MustInherit Class CounterBasedRandomSource(Of TGenerator As {Structure, New, IBlockRandomGenerator, ICounterBased(Of TWord)}, TWord As {Structure, New, Object})
	Inherits RandomSource(Of TGenerator)
	Implements ICounterBased(Of TWord)

generic<typename TGenerator, typename TWord>
where TGenerator : value class, gcnew(), IBlockRandomGenerator, ICounterBased<TWord>
where TWord : value class, gcnew(), Object
public ref class CounterBasedRandomSource abstract : public RandomSource<TGenerator>, 
	ICounterBased<TWord>

[<AbstractClassAttribute>]
type CounterBasedRandomSource<'TGenerator, 'TWord when 'TGenerator : struct, new() and IBlockRandomGenerator and ICounterBased<'TWord> when 'TWord : struct, new() and Object> = 
    class
        inherit RandomSource<'TGenerator>
        interface ICounterBased<'TWord>
    end

Inheritance

Object  →  RandomSource<TGenerator>  →  CounterBasedRandomSource<TGenerator, TWord>

Derived

Numerics.NET.Random.ChaCha

Numerics.NET.Random.Philox4x32

Numerics.NET.Random.Philox4x64

Numerics.NET.Random.Threefry4x64

Implements

ICounterBased<TWord>

Type Parameters

TGenerator

The underlying generator type of the random source, used to enable optimizations like inlining. Must be a struct implementing IRandomGenerator and ICounterBased<T>.

TWord

The native word type (typically UInt32 or UInt64).

CounterBasedRandomSource<TGenerator, TWord> extends RandomSource<TGenerator> to add counter-based RNG (CBRNG) functionality. It implements ICounterBased<T> by delegating all counter operations to the underlying Layer 2 generator.

Counter-Based Architecture:

Counter-based RNGs use a cryptographic-like structure where output is computed from a counter and key using a deterministic function. This design enables:

• Efficient parallel generation: Multiple threads can generate independent subsequences by using different counter ranges.
• Fast skip-ahead: Jumping to arbitrary positions in the sequence is O(1) by setting the counter directly.
• Block generation: Output is computed in fixed-size blocks, where each block corresponds to one counter value.
• Reproducibility: Setting the key and counter to specific values always produces the same output block.

Key Counter-Based Methods:

This class exposes counter-based operations through the ICounterBased<T> interface:

• GetKey(Span<TWord>) / SetKey(ReadOnlySpan<TWord>): Access and modify the generator key
• GetCounter(Span<TWord>) / SetCounter(ReadOnlySpan<TWord>): Access and modify the counter
• ResetCounter(): Reset the counter to all zeros
• GenerateBlock(): Recompute the current output block
• AdvanceBlock(UInt64): Skip ahead by multiple blocks

Consistency Protocol:

After calling SetKey(ReadOnlySpan<TWord>), SetCounter(ReadOnlySpan<TWord>), or ResetCounter(), the generator enters an inconsistent state. Callers must invoke GenerateBlock() before using output methods to bring the generator back to a consistent state.

Example Derived Class:

public sealed class Philox4x64 
    : CounterBasedRandomSource&lt;BlockGenerator64<Philox4x64Engine>, ulong>
{
    public Philox4x64() : base() { }

    public Philox4x64(ulong seed, StreamAddress streamAddress = default, SeedProfile seedProfile = SeedProfile.Default)
        : base(seed, streamAddress, seedProfile) { }

    protected override void Initialize(in RandomOptions options, ref CounterBasedGenerator64<Philox4x64Engine> generator)
    {
        SeedSequence seedSequence = options.CreateSeedSequence();
        // Initialize generator using seed sequence
    }

    public override string Name => "Philox4x64";
    public override int BitsPerWord => 64;
}

Common Counter-Based Generators:

• Philox (4x32, 4x64)
• Threefry (4x64)
• ChaCha (configurable rounds)

Reference