Hawkynt.RandomNumberGenerators 1.0.0.44

Hawkynt.RandomNumberGenerators

A comprehensive C# library of random number generators — algorithms across pseudo-random, cryptographically secure, quasi-random and non-uniform distributions, all behind a single IRandomNumberGenerator interface plus an ArbitraryNumberGenerator helper that exposes ergonomic methods on top of any generator.

The long-form article that motivates and explains every algorithm in this package lives at Randomizer.

Install

dotnet add package Hawkynt.RandomNumberGenerators

Target framework: net8.0. The package is AOT-compatible and trimmable.

Namespaces

The core interface

Every PRNG, CSPRNG and quasi-random sequence in the package implements:

public interface IRandomNumberGenerator {
  void Seed(ulong seed);
  ulong Next();
}

Seed sets the initial state; calling Seed again is allowed and will restart the sequence. Next returns a uniformly distributed 64-bit value (for PRNG/CSPRNG) or the next element of the sequence (for quasi-random).

Quick examples

1. Pick a generator, produce raw 64-bit values

using Hawkynt.RandomNumberGenerators.Deterministic;

var rng = new Xoshiro256SS();
rng.Seed(42);
ulong a = rng.Next();
ulong b = rng.Next();

2. Use the high-level helpers

using Hawkynt.RandomNumberGenerators.Composites;
using Hawkynt.RandomNumberGenerators.Deterministic;

var rng = new ArbitraryNumberGenerator(new Xoshiro256SS());
rng.Seed(42);

double d    = rng.NextDouble();            // uniform [0, 1)
ulong  r    = rng.NextRange(1, 100);       // uniform [1, 100)
bool   flip = rng.NextBoolean(0.7);        // true with probability 0.7
int    sign = rng.NextSign();              // -1 or +1
float  f    = rng.NextSingle();            // uniform [0, 1f)

byte[] buffer = new byte[32];
rng.NextBytes(buffer);                     // fill the span
Guid g = rng.NextGuid();                   // RFC 4122 v4

var deck = Enumerable.Range(1, 52).ToArray();
rng.Shuffle(deck);                         // Fisher-Yates, in place
int card  = rng.Choice(deck);              // one random element
int[] hand = rng.Sample(deck, 5);          // 5 distinct elements (reservoir)

3. Sample from non-uniform distributions

using Hawkynt.RandomNumberGenerators.NonUniform;

var u = new ArbitraryNumberGenerator(new Xoshiro256SS());
u.Seed(42);

var normal = new MarsagliaPolar(u);
var (z0, z1) = normal.Next();              // two independent N(0, 1)

var requests = new Poisson(u, lambda: 4.2);
int arrivals = requests.Next();            // discrete count

var price = new Lognormal(u, mu: 0, sigma: 0.3);
double next = price.Next();                // strictly positive

// Weighted choice from a list
var loot = new Categorical<string>(u, new[] {
  ("Common", 70.0), ("Rare", 25.0), ("Legendary", 5.0)
});
string drop = loot.Next();

4. Cryptographic use

For anything security-sensitive (session IDs, password salts, key generation) use a CSPRNG from the Cryptographic namespace, not a PRNG. They are slower but designed to resist state recovery.

using Hawkynt.RandomNumberGenerators.Cryptographic;

using var csprng = new AesCtrDrbg();        // implements IDisposable
csprng.Seed(GetEntropyFromOsOrHsm());
ulong sessionId = csprng.Next();

Choosing an algorithm

The full comparison table with state sizes, periods, speed and quality classes is in the main article.

License

LGPL-3.0-or-later. See the LICENSE file.

Contributing

Issues and pull requests welcome at Randomizer.