Numerics.NET.Random.Engines Namespace

The Numerics.NET.Random.Engines namespace contains the core engine layer of the Numerics.NET random number generation infrastructure. Engines are the lowest-level RNG components that own algorithm state and produce native words (UInt32 or UInt64) and bytes deterministically with a stable, portable state format.

Architecture Overview:

The RNG architecture is layered:

1. Layer 1 — Engines (this namespace): Core algorithms with state ownership, native output generation, and portable persistence.
2. Layer 2 — Generators: Minimal adapters that provide uniform primitive interfaces (uint/ulong generation, byte filling) with caching and block indexing.
3. Layer 3 — Algorithm Classes: User-facing types with modern Random API, distribution methods, and policy support.

Core Interfaces:

• IStateful: State persistence with little-endian format
• IRandomEngine: Base engine contract with seeding, generation, and byte filling
• ICounterBased<T>: Extended contract for counter-based engines (Philox, Threefry, ChaCha)

Engine Families:

The namespace includes implementations of several modern RNG families:

• PCG family: Permuted Congruential Generators with advancement and jumping (Pcg32, Pcg64, Pcg64Dxsm)
• Xoshiro/Xoroshiro family: Fast, high-quality generators with jump support (Xoshiro256**, Xoshiro256++, Xoshiro256+, Xoroshiro128++, Xoshiro128**, Xoshiro128+)
• Counter-based family: Cryptographic-style generators with O(1) skip-ahead (Philox-4x32, Philox-4x64, Threefry-4x64, ChaCha)
• Utility generators: Specialized algorithms (SplitMix64, Sfc64, WyRand)
• Legacy algorithms: Classic generators for compatibility (MersenneTwister, MersenneTwister64, GFSR)

Portability Guarantees:

All engines guarantee:

• Identical output sequences across all platforms (x86, x64, ARM, ARM64)
• Stable state serialization format (little-endian byte order)
• Deterministic seeding from SeedSequence instances
• Little-endian byte generation regardless of host endianness

Usage Note:

Most applications should use the Layer 3 algorithm classes (e.g., Pcg64, Xoshiro256StarStar) from the Numerics.NET.Random namespace rather than working directly with engines. Engines are primarily for advanced scenarios requiring direct state manipulation or custom generator composition.