# 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`

```
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:

```
final random = Xrandom();
quoteOfTheDay = quotes[ random.nextInt(quotes.length) ];
```

If you want the same numbers each time:

```
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:

```
final random = Qrandom(); // Q is for Quantifiable Quality
feedMonteCarloSimulation(random);
```

If you prefer a specific algorithm:

```
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 | 2003 | `Xrandom` |

✓ | `Xorshift64` | xorshift64 | 2003 | ||

✓ | ✓ | `Xorshift128` | xorshift128 | 2003 | |

✓ | `Splitmix64` | splitmix64 | 2015 | ||

✓ | `Xorshift128p` | xorshift128+ v2 | 2015 | ||

✓ | `Mulberry32` | mulberry32 | 2017 | ||

✓ | ✓ | `Xoshiro128pp` | xoshiro128++ 1.0 | 2019 | `Qrandom` , `Drandom` |

✓ | `Xoshiro256pp` | xoshiro256++ 1.0 | 2019 |

You can use any generator from the library in the same way as in the examples with the `Xrandom`

class.

```
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 library.

# Consistency

The library has been thoroughly **tested to match reference numbers** generated
by the same algorithms implemented in C99. 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, 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 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.