Random Numbers

Numerics.NET provides a comprehensive random number generation system for scientific computing, simulations, and machine learning. Whether you need quick convenience randomness, reproducible experiments, or high-performance parallel generation, the library offers modern APIs and state-of-the-art algorithms.

Numerics.NET goes beyond the standard System.Random to provide:

• Modern algorithms: PCG64, Xoshiro256**, Philox, ChaCha20, and other state-of-the-art generators used by NumPy, Julia, and .NET itself.

• Reproducibility: Seeded generators produce identical sequences across runs, essential for scientific experiments and debugging.

• High performance: Bulk generation APIs (span-first, vectors, matrices) offer considerable speedup over scalar loops.

• Parallel and distributed: Independent stream creation for parallel workloads without correlation or contention.

• Seamless interop: Adapters for converting to and from System.Random for compatibility with existing APIs.

Understanding a few key concepts will help you use the random number APIs effectively:

Random Source

A random source is the user-facing object you interact with to generate random numbers. It implements IRandomSource and provides methods like NextDouble(), Next(int), and Fill(Span<T>).

Behind the scenes, each random source wraps a generator algorithm (the fast computational engine), but you rarely need to think about that distinction—just create a source and use it.

Shared vs. Seeded

Numerics.NET provides two primary modes:

• Shared convenience randomness: Shared is a thread-safe global source for quick, incidental use. Not reproducible across runs.

• Seeded explicit randomness: Create(Int64) or direct construction (e.g., new Pcg64(42)) creates reproducible generators from seeds.

For experiments, simulations, and tests, always use seeded sources.

System.Random Interoperability

Numerics.NET random sources can be converted to and from System.Random via adapter extension methods (AsRandom(), AsRandomSource()). This allows seamless integration with existing .NET APIs while preserving the performance benefits of Numerics.NET generators when used directly.

Explore random number generation by scenario:

• Introduction to Random Sources

  Learn how to create and use random sources correctly, understand shared vs. seeded modes, and avoid common pitfalls.

• Generating Random Data

  Generate many values efficiently using span-first APIs, create random vectors and matrices, sample from probability distributions, and apply performance best practices.

• Parallel Randomness and Independent Streams

  Use randomness safely in parallel and concurrent code by creating independent streams for each worker.

• Compatibility and Interop

  Understand reproducibility guarantees, use seeding profiles for cross-platform compatibility, convert between Numerics.NET and System.Random, and apply best practices for strict reproducibility.

• Choosing a Random Number Generator

  Deep dive into the available generator algorithms, their properties, constructors, seed profiles, and advanced features like jumping and state persistence.

• Choosing a Random Number Generator

  Guidance on selecting the right generator for your use case: general-purpose, maximum performance, parallel computing, cryptographic, or platform compatibility.

• Quasi-Random Sequences

  Generate low-discrepancy sequences (Fauré, Halton, Sobol) for quasi-Monte Carlo integration and global optimization.