PNRGByLeo/README.md at main

Name: MQL5 Algo Forge
Brand: MQL5

Watch

Nique_372 8eb893f874

2026-09-01 10:00:46 -05:00

5 KiB

Raw Permalink Blame History

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<TBackend> 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

#include "..\\Src\\Main.mqh"
#include "..\\Src\\Imp\\All.mqh"

void OnStart()
 {
  TSN::CRandom<TSN::CMersenneTwister64> 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 for the full list.

MetaTrader 5, build 5430+

Installation

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. It automatically downloads and installs all declared dependencies.

Quick Start

1. Include the library:

#include "..\\Src\\Main.mqh"
#include "..\\Src\\Imp\\All.mqh"

2. Use it:

TSN::CRandom<TSN::Xoshiro256> rng;
int n = rng.RandomInteger(1, 100);

License

Read Full 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 by Amr Ali. The original class was reduced to its PRNG core and the public API layer was generalized into the CRandom<TBackend> 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) — https://prng.di.unimi.it/.
Src/Imp/MT64/MT64.mqh (64-bit Mersenne Twister) is based on the reference implementation described in the MQL5 article: https://www.mql5.com/en/articles/14413.

Contact

Platform: MQL5 Community
Profile: https://www.mql5.com/es/users/nique_372
Articles: https://www.mql5.com/es/users/nique_372/publications

5 KiB Raw Permalink Blame History