https://github.com/rtmigo/xrandom_dart
Dart library with random number generators focused on the consistency, performance and reproducibility
https://github.com/rtmigo/xrandom_dart
algorithms benchmarks dart dart-library dart-package deterministic flutter javascript prng pubdev random random-generation random-number-generators rng splitmix xorshift xorshift-generator xoshiro xrandom
Last synced: 2 months ago
JSON representation
Dart library with random number generators focused on the consistency, performance and reproducibility
- Host: GitHub
- URL: https://github.com/rtmigo/xrandom_dart
- Owner: rtmigo
- License: mit
- Created: 2021-03-12T02:36:26.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-03-15T01:12:57.000Z (over 3 years ago)
- Last Synced: 2025-04-05T12:04:43.836Z (6 months ago)
- Topics: algorithms, benchmarks, dart, dart-library, dart-package, deterministic, flutter, javascript, prng, pubdev, random, random-generation, random-number-generators, rng, splitmix, xorshift, xorshift-generator, xoshiro, xrandom
- Language: Dart
- Homepage: https://pub.dev/packages/xrandom
- Size: 10.5 MB
- Stars: 10
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pub.dev/packages/xrandom)
[](https://pub.dev/packages/xrandom/score)
# [xrandom](https://github.com/rtmigo/xrandom)
Classes implementing all-purpose, rock-solid **random number generators**.
Library priorities:
- generation of identical bit-accurate numbers regardless of the platform
- reproducibility of the random results in the future
- high-quality randomness
- performance
----------
It has the same API as the standard
[`Random`](https://api.dart.dev/stable/2.12.1/dart-math/Random-class.html)
``` dart
import 'package:xrandom/xrandom.dart';
final random = Xrandom();
var a = random.nextBool();
var b = random.nextDouble();
var c = random.nextInt(n);
var unordered = [1, 2, 3, 4, 5]..shuffle(random);
```
# Creating the object
The library provides classes that differ in the first letter: `Xrandom`,
`Qrandom`, `Drandom`.
If you just want a random number:
``` dart
final random = Xrandom();
quoteOfTheDay = quotes[ random.nextInt(quotes.length) ];
```
If you want the same numbers each time:
``` dart
final random = Drandom(); // D is for Dumb Determinism
test("no surprises ever", () {
expect(random.nextInt(100), 42);
expect(random.nextInt(100), 17);
expect(random.nextInt(100), 96);
});
```
If you are solving a computational problem:
``` dart
final random = Qrandom(); // Q is for Quantifiable Quality
feedMonteCarloSimulation(random);
```
If you prefer a specific algorithm:
``` dart
final random = Splitmix64(); // see list of algorithms below
feedMonteCarloSimulation(random);
```
# Speed
Generating random numbers with AOT-compiled binary.
Sorted by `nextInt` **fastest to slowest**
(numbers show execution time)
| Class | nextInt | nextDouble | nextBool |
|------------------------|--------:|-----------:|---------:|
| Xrandom | 627 | 640 | 391 |
| **Random (dart:math)** | 895 | 929 | 662 |
| Qrandom / Drandom | 933 | 1219 | 398 |
# Additions to Random
## nextFloat
`nextFloat()` generates a floating-point value in the range 0.0 ≤ x <1.0.
Unlike the `nextDouble`, `nextFloat` prefers speed to precision.
It's still a `double`, but it has four billion shades instead of eight
quadrillions.
Speed comparison
Sorted by `nextDouble` **fastest to slowest**
(numbers show execution time)
| JS | Class | nextDouble | nextFloat |
|----|------------------------|-----------:|----------:|
| | Xorshift64 | 569 | 353 |
| | Xorshift128p | 635 | 389 |
| ✓ | Xrandom | 640 | 221 |
| | Splitmix64 | 658 | 398 |
| ✓ | Xorshift128 | 815 | 339 |
| | Mulberry32 | 841 | 301 |
| ✓ | **Random (dart:math)** | 929 | |
| | Xoshiro256pp | 1182 | 713 |
| ✓ | Qrandom / Drandom | 1219 | 539 |
## nextRaw
These methods return the raw output of the generator uncompromisingly fast.
Depending on the algorithm, the output is a number consisting of either 32
random bits or 64 random bits.
Xrandom combines small integers or splits large ones. The methods work with any
of the generators.
| JS | Method | Returns | Equivalent of |
|-------|--------|-----------------|---------------------------------|
| ✓ | `nextRaw32()` | 32-bit unsigned | `nextInt(pow(2,32))` |
| ✓ | `nextRaw53()` | 53-bit unsigned | `nextInt(pow(2,53))` |
| | `nextRaw64()` | 64-bit signed | `nextInt(pow(2,64))` |
Speed comparison
Sorted by `nextInt` **fastest to slowest**
(numbers show execution time)
| JS | Class | nextInt | nextRaw32 | nextRaw64 |
|----|------------------------|--------:|----------:|----------:|
| ✓ | Xrandom | 627 | 280 | 549 |
| ✓ | Xorshift128 | 726 | 341 | 782 |
| | Xorshift64 | 748 | 346 | 491 |
| | Mulberry32 | 767 | 307 | 709 |
| | Xorshift128p | 772 | 383 | 529 |
| | Splitmix64 | 838 | 398 | 500 |
| ✓ | **Random (dart:math)** | 895 | | |
| ✓ | XrandomHq | 933 | 537 | 1186 |
| | Xoshiro256pp | 1138 | 703 | 1072 |
Since `nextInt`'s return range is always limited to 32 bits,
only comparison to `nextRaw32` is "apples-to-apples".
# Algorithms
| Native | JS | Class | Algorithm | Introduced | Alias |
|:------:|:--:|----------------|-------------------------------------------------------------------|:-----------------:|------|
| ✓ | ✓ | `Xorshift32` | [xorshift32](https://www.jstatsoft.org/article/view/v008i14) | 2003 | `Xrandom` |
| ✓ | | `Xorshift64` | [xorshift64](https://www.jstatsoft.org/article/view/v008i14) | 2003 |
| ✓ | ✓ | `Xorshift128` | [xorshift128](https://www.jstatsoft.org/article/view/v008i14) | 2003 |
| ✓ | | `Splitmix64` | [splitmix64](https://prng.di.unimi.it/splitmix64.c) | 2015 |
| ✓ | | `Xorshift128p` | [xorshift128+ v2](https://arxiv.org/abs/1404.0390) | 2015 |
| ✓ | | `Mulberry32` | [mulberry32](https://git.io/JmoUq) | 2017 |
| ✓ | | `Xoshiro256ss` | [xoshiro256** 1.0](https://xoshiro.di.unimi.it/xoshiro256starstar.c) | 2018 | |
| ✓ | ✓ | `Xoshiro128pp` | [xoshiro128++ 1.0](https://prng.di.unimi.it/xoshiro128plusplus.c) | 2019 | `Qrandom`, `Drandom` |
| ✓ | | `Xoshiro256pp` | [xoshiro256++ 1.0](https://prng.di.unimi.it/xoshiro256plusplus.c) | 2019 | |
You can use any generator from the library in the same way as in the examples with the `Xrandom` class.
``` dart
final random = Mulberry32();
quoteOfTheDay = quotes[ random.nextInt(quotes.length) ];
```
# Compatibility
TL;DR `Xrandom`, `Qrandom`, `Drandom` work on all platforms. Others may not work
on JS.
The library is written in pure Dart. Therefore, it works wherever Dart works.
But some of the classes need full support for 64-bit integers. *JavaScript**
actually only supports **53 bits**. If your target platform is JavaScript, then
the selection will have to be narrowed down to the options marked with **[✓]
checkmark in the JS column**. Trying to create a incompatible object in
JavaScript-transpiled code will lead to `UnsupportedError`.
If your code compiles to native (like in **Flutter** apps for **Android** and
*iOS**), *64-bit** generators will work best for you. For example, `Xorshift64`
for speed or `Xoshiro256pp` for quality.
# More benchmarks
`nextInt` **fastest to slowest**
(numbers show execution time)
| JS | Class | nextInt | nextDouble | nextBool |
|----|------------------------|--------:|-----------:|---------:|
| ✓ | Xrandom | 627 | 640 | 391 |
| ✓ | Xorshift128 | 726 | 815 | 394 |
| | Xorshift64 | 748 | 569 | 386 |
| | Mulberry32 | 767 | 841 | 391 |
| | Xorshift128p | 772 | 635 | 394 |
| | Splitmix64 | 838 | 658 | 392 |
| ✓ | **Random (dart:math)** | 895 | 929 | 662 |
| ✓ | Qrandom / Drandom | 933 | 1219 | 398 |
| | Xoshiro256pp | 1138 | 1182 | 406 |
All the benchmarks on this page are from AOT-compiled binaries running on AMD
A9-9420e with Ubuntu 20.04. Time is measured in milliseconds.
The tables are created using the [tabular](https://pub.dev/packages/tabular)
library.
# Consistency
The library has been thoroughly **tested to match [reference
numbers](https://github.com/rtmigo/randomref)** generated by the same algorithms
implemented in C++. Not only `int`s, but also numbers converted to `double`
including all decimal places that the compiler takes into account.
The sources in C are taken directly from scientific publications or the
reference implementations by the authors of the algorithms. The Xorshift128+
results are also matched to reference values from [JavaScript xorshift
library](https://github.com/AndreasMadsen/xorshift), which tested the 128+
similarly.
Therefore, the sequence generated for example by the `Xoshiro128pp.nextRaw32()`
with the seed `(1, 2, 3, 4)` is the same as the [C99
code](https://prng.di.unimi.it/xoshiro128plusplus.c) will produce with the same
seed.
The `double` values will also be the same as if the upper bits of `uint64_t`
type were converted to `double_t` in C99 by unsafe pointer casting. No matter
how exotic pointer casting sounds for Dart, and even more so for JavaScript.
JavaScript doesn't even have any upper bits of `uint64_t`. But `double`s are the
same type everywhere, and their random values will be the same.
Testing is done in the GitHub Actions cloud on **Windows**, **Ubuntu**, and
**macOS** in **VM** and **Node.js** modes.