IBlockEngine<T> Interface

Represents a block-based random number generator engine with 1:N transition topology.

Definition

Namespace: Numerics.NET.Random.Engines
Assembly: Numerics.NET (in Numerics.NET.dll) Version: 10.3.0
C# 
public interface IBlockEngine<T> : IRandomEngine, 
	IStateful
where T : struct, new()
Implements
IRandomEngine, IStateful

Type Parameters

T
The native word type produced by this engine (typically UInt32 or UInt64).

Remarks

Block engines have a 1:N topology: each block transition selects a new "entropy window" containing multiple output values, while output is accessed by index within the current block. This design is efficient for generators that naturally produce output in fixed-size batches.

Core Operations:

  • Block transition: AdvanceBlock() advances the engine to the next block (the next entropy window).
  • Indexed output mapping: Output(Int32) returns the native word at the specified index within the current block without mutating state.
  • Bulk output within block: Fill(Int32, Span<T>) fills a span with values from a contiguous range of indices within the current block.

Block Size:

The BlockLength property returns the number of addressable words in each block. This value is algorithm-specific and constant for a given engine type. For example:

  • Mersenne Twister: 624 words
  • Philox-4x32: 4 words
  • ChaCha: 16 words

Purity Requirement:

Output(Int32) and Fill(Int32, Span<T>)must not mutate engine state. They are pure functions mapping the current block and an index (or index range) to output values. All state evolution occurs exclusively in AdvanceBlock().

Index Range:

Output methods are only defined for indices in the range [0, BlockLength). Accessing indices outside this range results in undefined behavior.

Examples of Block Engines:

  • Mersenne Twister (MT19937, MT19937-64)
  • Counter-based engines (Philox, Threefry, ChaCha) via ICounterBased<T>

Example

C# 
// Create and seed a block engine
var engine = new MersenneTwisterEngine();
engine.Seed(SeedSequences.SplitMix64(42));

// Access values within the current block
uint value0 = engine.Output(0);
uint value1 = engine.Output(1);

// Fill from a range of indices within the current block
uint[] slice = new uint[10];
engine.Fill(5, slice); // Fill from indices [5, 15)

// Advance to the next block
engine.AdvanceBlock();

Properties

BitsPerWord Gets the native word size in bits.
(Inherited from IRandomEngine)
BlockLength Gets the number of native words addressable in each block.
Name Gets a human-readable name for this engine.
(Inherited from IRandomEngine)
StateSize Gets the number of bytes required to save/load this engine's state.
(Inherited from IStateful)

Methods

AdvanceBlock Advances the engine state to the next block (next entropy window).
Fill Fills the destination span with values from a contiguous range of indices within the current block.
LoadState Loads the engine's state from the source span in a stable little-endian format.
(Inherited from IStateful)
Output Returns the native word at the specified index within the current block.
SaveState Saves the engine's state to the destination span in a stable little-endian format.
(Inherited from IStateful)
Seed Initializes the engine state from a seed sequence.
(Inherited from IRandomEngine)

See Also