IScalarEngine<T> Interface

Represents a scalar random number generator engine with 1:1 transition topology.

Definition

Namespace: Numerics.NET.Random.Engines
Assembly: Numerics.NET (in Numerics.NET.dll) Version: 10.3.0

public interface IScalarEngine<T> : IRandomEngine, 
	IStateful
where T : struct, new()

Visual Basic

Public Interface IScalarEngine(Of T As {Structure, New})
	Inherits IRandomEngine, IStateful

C++/CLI

generic<typename T>
where T : value class, gcnew()
public interface class IScalarEngine : IRandomEngine, 
	IStateful

type IScalarEngine<'T when 'T : struct, new()> = 
    interface
        interface IRandomEngine
        interface IStateful
    end

Implements: IRandomEngine, IStateful

Type Parameters

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

Remarks

Scalar engines have a 1:1 topology: each transition step advances the state by one output word. The engine separates state transition (Advance()) from output mapping (Next()), enabling explicit control over state evolution and flexible composition patterns.

Core Operations:

Transition: Advance() evolves the engine state by one step.
Output mapping: Next() returns the native word corresponding to the current state without mutating state.
Bulk generation: Fill(Span<T>) produces a sequence of output words by repeatedly invoking output mapping followed by state transition.

Normative Stream Convention:

The canonical stream order for scalar engines is defined as:


            for (int i = 0; i < destination.Length; i++)
            {
                destination[i] = Output();
                Advance();
            }

This convention ensures that Fill(Span<T>) produces the same sequence as repeated calls to Next() followed by Advance().

Purity Requirement:

Next()must not mutate engine state. It is a pure function mapping the current state to an output value. All state evolution occurs exclusively in Advance().

Examples of Scalar Engines:

PCG family (Pcg32, Pcg64, Pcg64Dxsm)
Xoshiro family (Xoshiro256**, Xoshiro256+, etc.)
SplitMix64
SFC64
WyRand

Example

// Create and seed a scalar engine
var engine = new Pcg64Engine();
engine.Seed(SeedSequences.SplitMix64(42));

// Generate single values using output-then-advance pattern
ulong value1 = engine.Output();
engine.Advance();

ulong value2 = engine.Output();
engine.Advance();

// Bulk generation using Fill
ulong[] values = new ulong[100];
engine.Fill(values);

Properties

BitsPerWord	Gets the native word size in bits. (Inherited from IRandomEngine)
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

Advance	Advances the engine state by one transition step.
Fill	Fills the destination span with successive native words from the engine's stream.
LoadState	Loads the engine's state from the source span in a stable little-endian format. (Inherited from IStateful)
Next	Advances the engine by one step and returns the native word produced for that step.
Output	Returns the native word produced by applying the output mapping function to the current engine state, without mutating that state.
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)