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)

ClassnextIntnextDoublenextBool
Xrandom627640391
Random (dart:math)895929662
Qrandom / Drandom9331219398

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)

JSClassnextDoublenextFloat
Xorshift64569353
Xorshift128p635389
Xrandom640221
Splitmix64658398
Xorshift128815339
Mulberry32841301
Random (dart:math)929
Xoshiro256pp1182713
Qrandom / Drandom1219539

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.

JSMethodReturnsEquivalent of
nextRaw32()32-bit unsignednextInt(pow(2,32))
nextRaw53()53-bit unsignednextInt(pow(2,53))
nextRaw64()64-bit signednextInt(pow(2,64))
Speed comparison

Sorted by nextInt fastest to slowest
(numbers show execution time)

JSClassnextIntnextRaw32nextRaw64
Xrandom627280549
Xorshift128726341782
Xorshift64748346491
Mulberry32767307709
Xorshift128p772383529
Splitmix64838398500
Random (dart:math)895
XrandomHq9335371186
Xoshiro256pp11387031072

Since nextInt's return range is always limited to 32 bits, only comparison to nextRaw32 is "apples-to-apples".

Algorithms

NativeJSClassAlgorithmIntroducedAlias
Xorshift32xorshift322003Xrandom
Xorshift64xorshift642003
Xorshift128xorshift1282003
Splitmix64splitmix642015
Xorshift128pxorshift128+ v22015
Mulberry32mulberry322017
Xoshiro128ppxoshiro128++ 1.02019Qrandom, Drandom
Xoshiro256ppxoshiro256++ 1.02019

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)

JSClassnextIntnextDoublenextBool
Xrandom627640391
Xorshift128726815394
Xorshift64748569386
Mulberry32767841391
Xorshift128p772635394
Splitmix64838658392
Random (dart:math)895929662
Qrandom / Drandom9331219398
Xoshiro256pp11381182406

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 ints, 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 doubles 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.

Libraries

xrandom