Fast pseudo-random number generation library for MQL5, with a generic backend template
supporting Xoshiro256**, 64-bit Mersenne Twister, and MQL5's native generator.
---
## Main Features
- **Backend-agnostic API**: `CRandom` exposes the same rich API (integers, longs, doubles, normal distribution, sampling) regardless of the underlying PRNG
- **Three interchangeable backends**: Xoshiro256** (SHA-256 seeded), 64-bit Mersenne Twister, and a thin wrapper over MQL5's native `MathRand()`
- **Unbiased bounded generation**: uses Lemire's fastrange method for `RandomInteger(min, max)` / `RandomLong(min, max)` without modulo bias
- **Sampling utilities**: `Shuffle`, `Sample` (without replacement), `SampleWithReplacement`, all Fisher-Yates based
### Usage examples
```mql5
#include "..\\Src\\Main.mqh"
#include "..\\Src\\Imp\\All.mqh"
void OnStart()
{
TSN::CRandom rng;
rng.Seed(5489);
for(int i = 0; i < 10; i++)
Print(rng.RandomInteger());
}
```
Swap the backend by changing the template parameter — `TSN::Xoshiro256`, `TSN::CMersenneTwister64`, or `TSN::CMathRandNative`.
---
## Benchmark
`nextUInt32()`, 500,000,000 iterations per backend, single-threaded.
| Backend | Time (500M iters) | ns/op | Ops/sec |
|---|---|---|---|
| **Xoshiro256\*\*** | 0.371 s | 0.741 ns | ~1,349 M/s |
| Mersenne Twister 64 | 0.903 s | 1.806 ns | ~554 M/s |
| Native (`MathRand`) | 1.195 s | 2.389 ns | ~419 M/s |
### Machine
- OS Name: Microsoft Windows 10 Pro
- Version: 10.0.19045 Build 19045
- OS Manufacturer: Microsoft Corporation
- System Manufacturer: LENOVO
- System Model: 81DE
- System Type: x64-based PC
- System SKU: LENOVO_MT_81DE_BU_idea_FM_ideapad 330-15IKB
- Processor: Intel(R) Core(TM) i5-8250U CPU @ 1.60GHz, 1800 MHz, 4 Cores, 8 Logical Processors
- RAM Type (Form Factor): SODIMM
- RAM Speed: 2133 MHz
- Installed Physical Memory (RAM): 8.00 GB
- Total Physical Memory: 7.91 GB
- Available Physical Memory: 2.87 GB
- Total Virtual Memory: 15.2 GB
- Available Virtual Memory: 9.13 GB
- Page File Space: 7.25 GB
- Storage: 13 GB Intel MEMPEI1J016GAL SSD, 224 GB HP SSD S650 240GB SSD
- Graphics Card: AMD Radeon(TM) 530 (2 GB), Intel(R) UHD Graphics 620 (128 MB)
---
## Repository Structure
```
PNRGByLeo/
├── Src/ # Full code (Main.mqh generic API + Imp/ backends)
├── Test/ # Tests and benchmarks
```
---
## Requirements
See [dependencies.json](./dependencies.json) for the full list.
- MetaTrader 5, build 5430+
---
## Installation
```bash
cd "C:\Users\YOUR_USER\AppData\Roaming\MetaQuotes\Terminal\YOUR_ID\MQL5\Shared Projects"
tsndep install "https://forge.mql5.io/nique_372/PNRGByLeo.git"
```
Requires the `tsndep` package, available on [PyPI](https://pypi.org/project/tsndep). It automatically downloads and installs all declared dependencies.
---
## Quick Start
**1. Include the library:**
```mql5
#include "..\\Src\\Main.mqh"
#include "..\\Src\\Imp\\All.mqh"
```
**2. Use it:**
```mql5
TSN::CRandom rng;
int n = rng.RandomInteger(1, 100);
```
---
## License
**[Read Full License](./LICENSE)**
By downloading or using this repository, you accept the license terms.
---
## Third-Party Code & References
This repository builds on external work. The full obligations of each source license apply independently of this project's own [NL-NC] license.
- **`Src/Imp/Xho/Xho.mqh`** (Xoshiro256** core: `Seed`, `nextUInt64`, `nextUInt32`, `rotl`) and the bulk of the public API in **`Src/Main.mqh`** (`RandomInteger`, `RandomDouble`, `RandomDoubleHighRes`, `RandomNormal`, `Shuffle`, `Sample`, `SampleWithReplacement`, `boundedUInt32`, `boundedUInt64`, `mulhi`) are adapted from [Xoshiro256](https://forge.mql5.io/amrali/Xoshiro256) by **Amr Ali**. The original class was reduced to its PRNG core and the public API layer was generalized into the `CRandom` template so it could be reused across multiple backends. The native `CryptEncode(CRYPT_HASH_SHA256, ...)` seeding call was replaced with `TSN::CCryptoHash::SHA256` from the TSN ecosystem's CryptoByLeo library.
- The underlying **xoshiro256\*\*** algorithm itself was created by David Blackman and Sebastiano Vigna, released into the public domain (CC0) — .
- **`Src/Imp/MT64/MT64.mqh`** (64-bit Mersenne Twister) is based on the reference implementation described in the MQL5 article: .
---
## Contact
- **Platform:** [MQL5 Community](https://www.mql5.com/es/users/nique_372)
- **Profile:** https://www.mql5.com/es/users/nique_372
- **Articles:** https://www.mql5.com/es/users/nique_372/publications
---
Copyright © 2026 Niquel & Leo — TSN Ecosystem