Apache Commons logo Apache Commons RNG

The Apache Commons RNG User Guide

Table of contents

1. Purpose

Commons RNG provides generators of "pseudo-randomness", i.e. the generators produce deterministic sequences of bytes, currently in chunks of 32 (a.k.a. int) or 64 bits (a.k.a. long), depending on the implementation.

The goal was to provide an API that is simple and unencumbered with old design decisions.

The design is clean and its rationale is explained in the code and Javadoc (as well as in the extensive discussions on the "Apache Commons" project's mailing list).

The code evolved during several months in order to accommodate the requirements gathered from the design issues identified in the org.apache.commons.math3.random package and the explicit design goal of severing ties to java.util.Random.

The library is divided into modules:

  • Client API (requires Java 8)

    This module provides the interface to be passed as argument to a procedure that needs to access to a sequence of random numbers.

  • Core (requires Java 8)

    This module contains the implementations of several generators of pseudo-random sequences of numbers. Code in this module is intended to be internal to this library and no user code should access it directly. With the advent of Java modularization, it is possible that future releases of the library will enforce access through the RandomSource factory.

  • Simple (requires Java 8)

    This module provides factory methods for creating instances of all the generators implemented in the commons-rng-core module.

  • Sampling (requires Java 8)

    This module provides implementations that: generate a sequence of numbers according to some specified probability distribution; sample coordinates from geometric shapes; sample from generic collections of items; and other sampling utilities. It is an example of usage of the API provided in the commons-rng-client-api module.

  • Examples

    This module provides miscellaneous complete applications that illustrate usage of the library. Please note that this module is not part of the library's API; no compatibility should be expected in successive releases of "Commons RNG". The examples can be download in the source distribution.

    As of version 1.1, the following modules are provided:

    • examples-jmh: JMH benchmarking (requires Java 8)

      This module uses the JMH micro-benchmark framework in order to assess the relative performance of the generators (see tables below).

    • examples-stress: Stress testing (requires Java 8)

      This module implements a wrapper that calls external tools that can assess the quality of the generators by submitting their output to a battery of "stress tests" (see tables below).

    • examples-sampling: Probability density (requires Java 8)

      This module contains the code that generates the data used to produce the probability density plots shown in this userguide.

    • examples-jpms: JPMS integration (requires Java 11)

      This module implements a dummy application that shows how to use the artefacts (produced from the maven modules described above) as Java modules (JPMS).

    • examples-quadrature: Quadrature (requires Java 8)

      This module contains an application that estimates the number 𝞹 using quasi-Montecarlo integration.

2. Usage overview

Please refer to the generated documentation (of the appropriate module) for details on the API illustrated by the following examples.

  • Random number generator objects are instantiated through factory methods defined in RandomSource, an enum that declares all the available implementations.
    import org.apache.commons.rng.UniformRandomProvider;
    import org.apache.commons.rng.simple.RandomSource;
    
    UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
  • A generator can return a randomly selected element from a range of possible values of some Java (primitive) type.
    boolean isOn = rng.nextBoolean(); // "true" or "false".
    int n = rng.nextInt();         // Integer.MIN_VALUE <= n <= Integer.MAX_VALUE.
    int m = rng.nextInt(max);      // 0 <= m < max.
    int l = rng.nextInt(min, max); // min <= l < max.
    long n = rng.nextLong();         // Long.MIN_VALUE <= n <= Long.MAX_VALUE.
    long m = rng.nextLong(max);      // 0 <= m < max.
    long l = rng.nextLong(min, max); // min <= l < max.
    float x = rng.nextFloat();         // 0 <= x < 1.
    float y = rng.nextFloat(max);      // 0 <= y < max.
    float z = rng.nextFloat(min, max); // min <= z < max.
    double x = rng.nextDouble();         // 0 <= x < 1.
    double y = rng.nextDouble(max);      // 0 <= y < max.
    double z = rng.nextDouble(min, max); // min <= z < max.
  • A generator can fill a given byte array with random values.
    byte[] a = new byte[47];
    // The elements of "a" are replaced with random values from the interval [-128, 127].
    rng.nextBytes(a);
    byte[] a = new byte[47];
    // Replace 3 elements of the array (at indices 15, 16 and 17) with random values.
    rng.nextBytes(a, 15, 3);
  • A generator can return a stream of primitive values.
    IntStream s1 = rng.ints();         // [Integer.MIN_VALUE, Integer.MAX_VALUE]
    IntStream s2 = rng.ints(max);      // [0, max)
    IntStream s3 = rng.ints(min, max); // [min, max)
    LongStream s1 = rng.longs();         // [Long.MIN_VALUE, Long.MAX_VALUE]
    LongStream s2 = rng.longs(max);      // [0, max)
    LongStream s3 = rng.longs(min, max); // [min, max)
    DoubleStream s1 = rng.doubles();         // [0, 1)
    DoubleStream s2 = rng.doubles(max);      // [0, max)
    DoubleStream s3 = rng.doubles(min, max); // [min, max)

    Streams can be limited by a stream size argument.

    // Roll a die 1000 times
    int[] rolls = rng.ints(1000, 1, 7).toArray();

    It should be noted that streams returned by the interface default implementation perform repeat calls to the relevant next generation method and may have a performance overhead. Efficient streams can be created using an instance of a sampler which can precompute coefficients on construction (see the sampling module).

  • The UniformRandomProvider interface provides default implementations for all generation methods except nextLong. Implementation of a new generator must only provide a 64-bit source of randomness.
    UniformRandomProvider rng = new SecureRandom()::nextLong;

    Abstract classes for a 32-bit or 64-bit source of randomness, with additional functionality not present in the interface, are provided in the core module.

  • In order to generate reproducible sequences, generators must be instantiated with a user-defined seed.
    UniformRandomProvider rng = RandomSource.SPLIT_MIX_64.create(5776);

    If no seed is passed, a random seed is generated implicitly.

    Convenience methods are provided for explicitly generating random seeds of the various types.

    int seed = RandomSource.createInt();
    long seed = RandomSource.createLong();
    int[] seed = RandomSource.createIntArray(128); // Length of returned array is 128.
    long[] seed = RandomSource.createLongArray(128); // Length of returned array is 128.
  • Any of the following types can be passed to the create method as the "seed" argument:
    • int or Integer
    • long or Long
    • int[]
    • long[]
    • byte[]
    UniformRandomProvider rng = RandomSource.ISAAC.create(5776);
    UniformRandomProvider rng = RandomSource.ISAAC.create(new int[] { 6, 7, 7, 5, 6, 1, 0, 2 });
    UniformRandomProvider rng = RandomSource.ISAAC.create(new long[] { 0x638a3fd83bc0e851L, 0x9730fd12c75ae247L });

    Note however that, upon initialization, the underlying generation algorithm

    • may not use all the information contents of the seed,
    • may use a procedure (using the given seed as input) for further filling its internal state (in order to avoid a too uniform initial state).

    In both cases, the behavior is not standard but should not change between releases of the library (bugs notwithstanding).

    Each RNG implementation has a single "native" seed; when the seed argument passed to the create method is not of the native type, it is automatically converted. The conversion preserves the information contents but is otherwise not specified (i.e. different releases of the library may use different conversion procedures).

    Hence, if reproducibility of the generated sequences across successive releases of the library is necessary, users should ensure that they use native seeds.

    long seed = 9246234616L;
    if (!RandomSource.TWO_CMRES.isNativeSeed(seed)) {
        throw new IllegalArgumentException("Seed is not native");
    }

    For each available implementation, the native seed type is specified in the Javadoc.

  • Whenever a random source implementation is parameterized, the custom arguments are passed after the seed.
    int seed = 96912062;
    int first = 7; // Subcycle identifier.
    int second = 4; // Subcycle identifier.
    UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create(seed, first, second);

    In the above example, valid "subcycle identifiers" are in the interval [0, 13].

  • The current state of a generator can be saved and restored later on.
    import org.apache.commons.rng.RestorableUniformRandomProvider;
    import org.apache.commons.rng.RandomProviderState;
    
    RestorableUniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
    RandomProviderState state = rng.saveState();
    double x = rng.nextDouble();
    rng.restoreState(state);
    double y = rng.nextDouble(); // x == y.
  • The UniformRandomProvider objects returned from the create methods do not implement the java.io.Serializable interface.

    However, users can easily set up a custom serialization scheme if the random source is known at both ends of the communication channel. This would be useful namely to save the state to persistent storage, and restore it such that the sequence will continue from where it left off.

    import org.apache.commons.rng.RestorableUniformRandomProvider;
    import org.apache.commons.rng.simple.RandomSource;
    import org.apache.commons.rng.core.RandomProviderDefaultState;
    
    RandomSource source = RandomSource.KISS; // Known source identifier.
    
    RestorableUniformRandomProvider rngOrig = source.create(); // Original RNG instance.
    
    // Save and serialize state.
    RandomProviderState stateOrig = rngOrig.saveState(rngOrig);
    ByteArrayOutputStream bos = new ByteArrayOutputStream();
    ObjectOutputStream oos = new ObjectOutputStream(bos);
    oos.writeObject(((RandomProviderDefaultState) stateOrig).getState());
    
    // Deserialize state.
    ByteArrayInputStream bis = new ByteArrayInputStream(bos.toByteArray());
    ObjectInputStream ois = new ObjectInputStream(bis);
    RandomProviderState stateNew = new RandomProviderDefaultState((byte[]) ois.readObject());
    
    RestorableUniformRandomProvider rngNew = source.create(); // New RNG instance from the same "source".
    
    // Restore original state on the new instance.
    rngNew.restoreState(stateNew);
  • The JumpableUniformRandomProvider interface allows creation of a copy of the generator and advances the state of the current generator a large number of steps in a single jump. This can be used to create a set of generators that will not overlap in their output sequence for the length of the jump for use in parallel computations.
    import org.apache.commons.rng.UniformRandomProvider;
    import org.apache.commons.rng.JumpableUniformRandomProvider;
    import org.apache.commons.rng.simple.RandomSource;
    import java.util.concurrent.ForkJoinPool;
    
    RandomSource source = RandomSource.XO_RO_SHI_RO_128_SS; // Known to be jumpable.
    
    JumpableUniformRandomProvider jumpable = (JumpableUniformRandomProvider) source.create();
    
    // For use in parallel
    int streamSize = 10;
    jumpable.jumps(streamSize).forEach(rng -> {
        ForkJoinPool.commonPool().execute(() -> {
            // Task using the rng
        });
    });

    Note that here the stream of RNGs is sequential; each RNG is used within a potentially long-running task that can run concurrently with other tasks using an executor service.

    In the above example, the source is known to implement the JumpableUniformRandomProvider interface. Not all generators support this functionality. You can determine if a RandomSource is jumpable without creating one using the instance methods isJumpable() and isLongJumpable().

    import org.apache.commons.rng.simple.RandomSource;
    
    public void initialise(RandomSource source) {
        if (!source.isJumpable()) {
            throw new IllegalArgumentException("Require a jumpable random source");
        }
        // ...
    }
  • The SplittableUniformRandomProvider interface allows splitting a generator into two objects (the original and a new instance) each of which implements the same interface (and can be recursively split indefinitely). This can be used for parallel computations where the number of forks is unknown. These generators provide support for parallel streams. It should be noted that in general creation of a new generator instance may result in correlation of the output sequence with an existing generator. The generators that support this interface have algorithms designed to minimise correlation between instances. In particular the stream of generators provided by recursive splitting of a parallel stream are robust to collision of their sequence output.
    import org.apache.commons.rng.UniformRandomProvider;
    import org.apache.commons.rng.SplittableUniformRandomProvider;
    import org.apache.commons.rng.simple.RandomSource;
    
    RandomSource source = RandomSource.L64_X128_MIX; // Known to be splittable.
    
    SplittableUniformRandomProvider splittable = (SplittableUniformRandomProvider) source.create();
    
    // For use in parallel
    int streamSize = 10;
    jumpable.splits(streamSize).parallel().forEach(rng -> {
        // Task using the rng
    });

    Note that here the stream of RNGs is parallel; each RNG is used within a potentially long-running task that can run concurrently with other tasks if the enclosing stream parallel support utilises multiple threads.

    In the above example, the source is known to implement the SplittableUniformRandomProvider interface. Not all generators support this functionality. You can determine if a RandomSource is splittable without creating one using the instance method isSplittable().

    import org.apache.commons.rng.simple.RandomSource;
    
    public void initialise(RandomSource source) {
        if (!source.isSplittable()) {
            throw new IllegalArgumentException("Require a splittable random source");
        }
        // ...
    }
  • Generation of random deviates for various distributions.
    import org.apache.commons.rng.sampling.distribution.ContinuousSampler;
    import org.apache.commons.rng.sampling.distribution.GaussianSampler;
    import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
    
    ContinuousSampler sampler = GaussianSampler.of(ZigguratSampler.NormalizedGaussian.of(RandomSource.ISAAC.create()),
                                                   45.6, 2.3);
    double random = sampler.sample();
    import org.apache.commons.rng.sampling.distribution.DiscreteSampler;
    import org.apache.commons.rng.sampling.distribution.RejectionInversionZipfSampler;
    
    DiscreteSampler sampler = RejectionInversionZipfSampler.of(RandomSource.ISAAC.create(),
                                                               5, 1.2);
    int random = sampler.sample();
  • Sampler interfaces are provided for generation of the primitive types int, long, and double and objects of type T. The samples method creates a stream of sample values using the Java 8 streaming API:
    import org.apache.commons.rng.sampling.distribution.PoissonSampler;
    import org.apache.commons.rng.simple.RandomSource;
    
    double mean = 15.5;
    int streamSize = 100;
    int[] counts = PoissonSampler.of(RandomSource.L64_X128_MIX.create(), mean)
                                 .samples(streamSize)
                                 .toArray();
    import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
    import org.apache.commons.rng.simple.RandomSource;
    
    // Lower-truncated Normal distribution samples
    double low = -1.23;
    double[] samples = ZigguratSampler.NormalizedGaussian.of(RandomSource.L64_X128_MIX.create())
                                                         .samples()
                                                         .filter(x -> x > low)
                                                         .limit(100)
                                                         .toArray();
  • The SharedStateSampler interface allows creation of a copy of the sampler using a new generator. The samplers share only their immutable state and can be used in parallel computations.
    import org.apache.commons.rng.UniformRandomProvider;
    import org.apache.commons.rng.sampling.distribution.MarsagliaTsangWangDiscreteSampler;
    import org.apache.commons.rng.sampling.distribution.SharedStateDiscreteSampler;
    import org.apache.commons.rng.simple.RandomSource;
    
    RandomSource source = RandomSource.XO_RO_SHI_RO_128_PP;
    
    double[] probabilities = {0.1, 0.2, 0.3, 0.4};
    SharedStateDiscreteSampler sampler1 = MarsagliaTsangWangDiscreteSampler.Enumerated.of(source.create(),
                                                                                          probabilities);
    
    // For use in parallel
    SharedStateDiscreteSampler sampler2 = sampler1.withUniformRandomProvider(source.create());

    All samplers support the SharedStateSampler interface.

  • Permutation, Combination, sampling from a Collection and shuffling utilities.
    import org.apache.commons.rng.sampling.PermutationSampler;
    import org.apache.commons.rng.sampling.CombinationSampler;
    
    // 3 elements from the (0, 1, 2, 3, 4, 5) tuplet.
    int n = 6;
    int k = 3;
    
    // If the order of the elements matters.
    PermutationSampler permutationSampler = new PermutationSampler(RandomSource.KISS.create(),
                                                                   n, k);
    // n! / (n - k)! = 120 permutations.
    int[] permutation = permutationSampler.sample();
    
    // If the order of the elements does not matter.
    CombinationSampler combinationSampler = new CombinationSampler(RandomSource.KISS.create(),
                                                                   n, k);
    // n! / (k! (n - k)!) = 20 combinations.
    int[] combination = combinationSampler.sample();
    import java.util.HashSet;
    import org.apache.commons.rng.sampling.CollectionSampler;
    
    HashSet<String> elements = new HashSet<>();
    elements.add("Apache");
    elements.add("Commons");
    elements.add("RNG");
    
    CollectionSampler<String> sampler = new CollectionSampler<>(RandomSource.MWC_256.create(),
                                                                elements);
    String word = sampler.sample();
    import java.util.Arrays;
    import java.util.List;
    import org.apache.commons.rng.UniformRandomProvider;
    import org.apache.commons.rng.sampling.ListSampler;
    
    List<String> list = Arrays.asList("Apache", "Commons", "RNG");
    
    UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
    
    // Get 2 random items
    int k = 2;
    List<String> sample = ListSampler.sample(rng, list, k);
    
    // Shuffle the list
    ListSampler.shuffle(rng, list)
  • Sampling from geometric shapes: Box, Ball, Line, Triangle, and Tetrahedron.
    import org.apache.commons.rng.sampling.shape.BoxSampler;
    
    double[] lower = {1, 2, 3};
    double[] upper = {15, 16, 17};
    BoxSampler sampler = BoxSampler.of(RandomSource.KISS.create(),
                                       lower, upper);
    double[] coordinate = sampler.sample();
    double[][] coordinates = sampler.samples(100).toArray(double[][]::new);
  • The CompositeSamplers utility class can create a composite sampler that is a weighted combination of samplers that return the same type.

    The following example will create a sampler to uniformly sample the border of a triangle using the line segment lengths as weights:

    import org.apache.commons.rng.sampling.shape.LineSampler;
    
    UniformRandomProvider rng = RandomSource.JSF_64.create();
    
    // Triangle vertices
    double[] a = {1.23, 4.56};
    double[] b = {6.78, 9.01};
    double[] c = {3.45, 2.34};
    // Line lengths
    double ab = Math.hypot(a[0] - b[0], a[1] - b[1]);
    double bc = Math.hypot(b[0] - c[0], b[1] - c[1]);
    double ca = Math.hypot(c[0] - a[0], c[1] - a[1]);
    
    ObjectSampler<double[]> sampler =
        CompositeSamplers.<double[]>newObjectSamplerBuilder()
            .add(LineSampler.of(rng, a, b), ab)
            .add(LineSampler.of(rng, b, c), bc)
            .add(LineSampler.of(rng, c, a), ca)
            .build(rng);
    
    double[] coordinate = sampler.sample();

3. Library layout

The API for client code consists of classes and interfaces defined in package org.apache.commons.rng.

  • Interface UniformRandomProvider provides access to a sequence of random values uniformly distributed within some range.
  • Interfaces RestorableUniformRandomProvider and RandomProviderState provide the "save/restore" API.
  • Interfaces JumpableUniformRandomProvider and LongJumpableUniformRandomProvider provide the "copy and jump" API for parallel computations. These are suitable for tasks where the number of instances to use in parallel is known.
  • Interface SplittableUniformRandomProvider provides the "split" API for parallel computations. This is suitable for tasks where the number of instances to use in parallel is unknown, for example execution of tasks within a stream using the JDK parallelism support.

The API for instantiating generators is defined in package org.apache.commons.rng.simple.

  • Enum RandomSource determines which algorithm to use for generating the sequence of random values.

The org.apache.commons.rng.simple.internal package contains classes for supporting initialization (a.k.a. "seeding") of the generators. They must not be used directly in applications, as all the necessary utilities are accessible through methods defined in RandomSource.

  • ProviderBuilder: contains methods for instantiating the concrete RNG implementations based on the source identifier; it also takes care of calling the appropriate classes for seed type conversion.
  • SeedFactory: contains factory methods for generating random seeds.
  • SeedConverter: interface for classes that transform between supported seed types.
  • Various classes that implement SeedConverter in order to transform from caller's seed to "native" seed.

The org.apache.commons.rng.core package contains the implementation of the algorithms for the generation of pseudo-random sequences. Applications should not directly import or use classes defined in this package: all generators can be instantiated through the RandomSource factory.

  • Class RandomProviderDefaultState implements the RandomProviderState interface to enable "save/restore" for all RestorableUniformRandomProvider instances created through the RandomSource factory methods.
  • BaseProvider: base class for all concrete RNG implementations; it contains higher-level algorithms nextInt(int n) and nextLong(long n) common to all implementations.
  • org.apache.commons.rng.core.util
    • NumberFactory: contains utilities for interpreting and combining the output (int or long) of the underlying source of randomness into the requested output, i.e. one of the Java primitive types supported by UniformRandomProvider.
    • RandomStreams: contains utilities for generating a stream of objects created using a random seed and source of randomness.
  • org.apache.commons.rng.core.source32
    • RandomIntSource: describes an algorithm that generates randomness in 32-bits chunks (a.k.a Java int).
    • IntProvider: base class for concrete classes that implement RandomIntSource.
    • Concrete RNG algorithms that are subclasses of IntProvider.
  • org.apache.commons.rng.core.source64
    • RandomLongSource: describes an algorithm that generates randomness in 64-bits chunks (a.k.a Java long).
    • LongProvider: base class for concrete classes that implement RandomLongSource.
    • Concrete RNG algorithms that are subclasses of LongProvider.

4. Performance

This section reports performance benchmarks of the RNG implementations.

All runs were performed on a platform with the following characteristics:

  • CPU: Intel(R) Xeon(R) CPU E5-1680 v3 @ 3.20GHz
  • Java version: 11.0.16 (build 11.0.16+8-post-Ubuntu-0ubuntu118.04)
  • JVM: OpenJDK 64-Bit Server VM (build 11.0.16+8-post-Ubuntu-0ubuntu118.04, mixed mode, sharing)

Performance was measured using the Java Micro-benchmark Harness (JMH).

Timings are representative of performance; the relative ranking of results may change depending on the JVM, operating system and hardware.

In these tables:

  • The first column is the RNG identifier (see RandomSource)
  • Lower is better.

4.1 Generating primitive values

The following table indicates the performance for generating:

  • a sequence of true/false values (a.k.a. Java type boolean)
  • a sequence of 64-bit floating point numbers (a.k.a. Java type double)
  • a sequence of 64-bit integers (a.k.a. Java type long)
  • a sequence of 32-bit floating point numbers (a.k.a. Java type float)
  • a sequence of 32-bit integers (a.k.a. Java type int)

Scores are normalized to the score of RandomSource.JDK.

Note that the core implementations use all the bits from the random source. For example a native generator of 32-bit int values requires 1 generation call per 32 boolean values; a native generator of 64-bit long values requires 1 generation call per 2 int values. This implementation is fast for all generators but requires a high quality random source. See the Quality section.

RNG identifier boolean double long float int
JDK 1.00000 1.00000 1.00000 1.00000 1.00000
WELL_512_A 1.11461 0.59987 0.58102 0.87589 0.75203
WELL_1024_A 1.36841 0.60740 0.59623 0.89262 0.74222
WELL_19937_A 1.08024 0.76173 0.74484 1.08742 1.02213
WELL_19937_C 1.32791 1.02451 0.79133 1.17066 1.09529
WELL_44497_A 1.32461 1.02395 0.78924 1.12883 1.09717
WELL_44497_B 1.33975 1.09410 0.86264 1.22877 1.17148
MT 1.08968 0.50325 0.44883 0.59148 0.48715
ISAAC 1.04350 0.59010 0.53097 0.90597 0.56016
SPLIT_MIX_64 1.40526 0.13745 0.09556 0.32604 0.21787
XOR_SHIFT_1024_S 1.33565 0.19589 0.15776 0.37325 0.26841
TWO_CMRES 1.27146 0.19437 0.17278 0.37910 0.30381
MT_64 1.41411 0.28240 0.24923 0.47918 0.37518
MWC_256 0.92836 0.29161 0.22826 0.41015 0.29642
KISS 0.97299 0.41728 0.40927 0.60185 0.45477
XOR_SHIFT_1024_S_PHI 1.32728 0.19677 0.15789 0.36337 0.26868
XO_RO_SHI_RO_64_S 0.89088 0.19783 0.13549 0.26151 0.20178
XO_RO_SHI_RO_64_SS 0.89907 0.25505 0.17562 0.30908 0.25002
XO_SHI_RO_128_PLUS 0.92138 0.26290 0.17695 0.35388 0.30901
XO_SHI_RO_128_SS 0.94245 0.33710 0.25896 0.43273 0.32846
XO_RO_SHI_RO_128_PLUS 1.34781 0.10860 0.08962 0.25963 0.17839
XO_RO_SHI_RO_128_SS 1.34709 0.13777 0.11315 0.29280 0.20425
XO_SHI_RO_256_PLUS 1.36885 0.15035 0.13031 0.31551 0.22234
XO_SHI_RO_256_SS 1.36178 0.18242 0.14083 0.33548 0.25444
XO_SHI_RO_512_PLUS 1.35392 0.24760 0.19849 0.40975 0.35794
XO_SHI_RO_512_SS 1.36391 0.28976 0.23257 0.42100 0.37262
PCG_XSH_RR_32 0.97803 0.32336 0.26250 0.40892 0.21951
PCG_XSH_RS_32 0.98559 0.25332 0.19727 0.29730 0.22179
PCG_RXS_M_XS_64 1.38272 0.13825 0.11401 0.32616 0.22109
PCG_MCG_XSH_RR_32 0.98173 0.31553 0.27401 0.38673 0.19127
PCG_MCG_XSH_RS_32 0.97713 0.22620 0.18129 0.27693 0.19128
MSWS 1.14544 0.18920 0.15237 0.26609 0.17483
SFC_32 0.90771 0.27679 0.19194 0.36690 0.30937
SFC_64 1.24542 0.15066 0.13172 0.30157 0.22107
JSF_32 1.14519 0.24544 0.16966 0.32851 0.28360
JSF_64 1.24219 0.14705 0.12808 0.30411 0.21567
XO_SHI_RO_128_PP 0.91119 0.30224 0.22359 0.39342 0.32205
XO_RO_SHI_RO_128_PP 1.23874 0.12269 0.10495 0.27554 0.19165
XO_SHI_RO_256_PP 1.38254 0.18221 0.13768 0.32843 0.24371
XO_SHI_RO_512_PP 1.37576 0.27996 0.21466 0.39719 0.37026
XO_RO_SHI_RO_1024_PP 1.38428 0.20780 0.16899 0.38017 0.28539
XO_RO_SHI_RO_1024_S 1.36140 0.20379 0.16047 0.38798 0.29636
XO_RO_SHI_RO_1024_SS 1.37634 0.21938 0.18260 0.39993 0.29927
PCG_XSH_RR_32_OS 0.97903 0.32323 0.26342 0.40666 0.22412
PCG_XSH_RS_32_OS 0.97764 0.25234 0.19507 0.29867 0.22140
PCG_RXS_M_XS_64_OS 1.38334 0.13917 0.11581 0.32657 0.22231
L64_X128_SS 1.37881 0.20132 0.15051 0.37165 0.28290
L64_X128_MIX 1.41965 0.24710 0.18779 0.40333 0.31450
L64_X256_MIX 1.40043 0.28843 0.22641 0.43458 0.36224
L64_X1024_MIX 1.31032 0.31798 0.25004 0.49949 0.42021
L128_X128_MIX 1.46235 0.41459 0.39984 0.60225 0.60025
L128_X256_MIX 1.45053 0.42359 0.40235 0.62181 0.62422
L128_X1024_MIX 1.46674 0.43250 0.41553 0.62237 0.62227
L32_X64_MIX 0.95378 0.42086 0.37200 0.57229 0.38774

Notes:

The RandomSource.JDK generator uses thread-safe (synchronized) int generation which has a performance overhead (see the int generation results). Note that the output will be low quality and this generator should not be used. See the Quality section for details. Multi-threaded applications should use a generator for each thread.

The speed of boolean generation is related to the base implementation that caches the 32-bit or 64-bit output from the generator. In these results the 32-bit generators have the better performance. These timings are relative and all implements are very fast. A RNG to compute boolean samples should be chosen based on the quality of the output.

4.2 Generating Gaussian samples

The following table compares the BoxMullerNormalizedGaussianSampler, MarsagliaNormalizedGaussianSampler, ZigguratNormalizedGaussianSampler, and ZigguratSampler.NormalizedGaussian.

Each score is normalized to the score of nextGaussian() method of java.util.Random which internally uses the Box-Muller algorithm.

RNG identifier BoxMullerNormalizedGaussianSampler MarsagliaNormalizedGaussianSampler ZigguratNormalizedGaussianSampler ZigguratSampler.NormalizedGaussian
JDK 0.72864 0.82035 0.36026 0.37240
WELL_512_A 0.57513 0.60603 0.27574 0.26031
WELL_1024_A 0.60669 0.64716 0.25733 0.26244
WELL_19937_A 0.70086 0.75437 0.39599 0.34672
WELL_19937_C 0.71438 0.81312 0.35042 0.33974
WELL_44497_A 0.70695 0.78274 0.34627 0.35930
WELL_44497_B 0.73477 0.81227 0.37086 0.35371
MT 0.53583 0.51641 0.21284 0.19978
ISAAC 0.55638 0.53112 0.22969 0.24661
SPLIT_MIX_64 0.45178 0.30374 0.09349 0.09665
XOR_SHIFT_1024_S 0.44582 0.31782 0.11948 0.11923
TWO_CMRES 0.44569 0.40012 0.15777 0.12335
MT_64 0.49332 0.39600 0.17076 0.14266
MWC_256 0.45679 0.34753 0.14330 0.14594
KISS 0.47298 0.48791 0.18812 0.19092
XOR_SHIFT_1024_S_PHI 0.44456 0.31603 0.11946 0.12211
XO_RO_SHI_RO_64_S 0.63187 0.32096 0.11796 0.11563
XO_RO_SHI_RO_64_SS 0.62738 0.34528 0.14085 0.13715
XO_SHI_RO_128_PLUS 0.45069 0.33461 0.13998 0.13917
XO_SHI_RO_128_SS 0.46666 0.42353 0.15621 0.15369
XO_RO_SHI_RO_128_PLUS 0.41110 0.28271 0.08406 0.08578
XO_RO_SHI_RO_128_SS 0.43201 0.29328 0.09216 0.09695
XO_SHI_RO_256_PLUS 0.42893 0.28613 0.09728 0.10625
XO_SHI_RO_256_SS 0.55701 0.29316 0.11777 0.11569
XO_SHI_RO_512_PLUS 0.41901 0.30672 0.13528 0.13637
XO_SHI_RO_512_SS 0.44332 0.32406 0.13255 0.14975
PCG_XSH_RR_32 0.63853 0.46199 0.16100 0.14618
PCG_XSH_RS_32 0.62500 0.35912 0.13526 0.12871
PCG_RXS_M_XS_64 0.45670 0.30098 0.09328 0.09883
PCG_MCG_XSH_RR_32 0.63831 0.43842 0.15828 0.15012
PCG_MCG_XSH_RS_32 0.62252 0.34500 0.12497 0.12172
MSWS 0.58977 0.32080 0.10982 0.10874
SFC_32 0.43940 0.34021 0.14306 0.12439
SFC_64 0.41754 0.28430 0.09697 0.08781
JSF_32 0.44026 0.32928 0.12811 0.13261
JSF_64 0.42437 0.28102 0.09989 0.10300
XO_SHI_RO_128_PP 0.59633 0.34603 0.14808 0.14888
XO_RO_SHI_RO_128_PP 0.41775 0.27995 0.08859 0.09678
XO_SHI_RO_256_PP 0.43340 0.29711 0.10289 0.11488
XO_SHI_RO_512_PP 0.42602 0.32023 0.12673 0.14101
XO_RO_SHI_RO_1024_PP 0.43407 0.31549 0.11515 0.11791
XO_RO_SHI_RO_1024_S 0.43494 0.30470 0.11188 0.11259
XO_RO_SHI_RO_1024_SS 0.44134 0.32623 0.12696 0.12791
PCG_XSH_RR_32_OS 0.63818 0.46323 0.15676 0.17173
PCG_XSH_RS_32_OS 0.62963 0.34848 0.13540 0.12839
PCG_RXS_M_XS_64_OS 0.44982 0.30106 0.09104 0.09866
L64_X128_SS 0.45983 0.31177 0.11647 0.11647
L64_X128_MIX 0.45649 0.33868 0.13662 0.13702
L64_X256_MIX 0.46925 0.34798 0.14384 0.14019
L64_X1024_MIX 0.47994 0.37118 0.16070 0.15674
L128_X128_MIX 0.52488 0.51651 0.18264 0.19039
L128_X256_MIX 0.52286 0.54631 0.20215 0.19860
L128_X1024_MIX 0.51316 0.48730 0.23322 0.20935
L32_X64_MIX 0.48315 0.47286 0.17991 0.18868

Notes:

The reference java.util.Random nextGaussian() method uses synchronized method calls per sample. The RandomSource.JDK RNG will use synchronized method calls when generating numbers for the BoxMullerNormalizedGaussianSampler but the calls to obtain the samples are not synchronized, hence the observed difference. All the other RNGs are not synchronized.

5. Quality

This section reports results of performing "stress tests" that aim at detecting failures of an implementation to produce sequences of numbers that follow a uniform distribution.

Three different test suites were used:

Note that the Dieharder and TestU01 test suites accept 32-bit integer values. Any generator of 64-bit long values has the upper and lower 32-bits passed to the test suite. PractRand supports 64-bit generators.

The first column is the RNG identifier (see RandomSource). The remaining columns contain the results of separate runs of the test suite using different random seeds. Click on one of the entries of the comma-separated list in order to see the text report of the corresponding run.

The Dieharder and TestU01 test suites contain many tests each requiring an approximately fixed size of random output; in the case of multiple tests different output is used for each test. Dieharder was run using the full set of tests. TestU01 was run using BigCrush. The number in the table indicates the number of failed tests, i.e. tests reported as below the accepted threshold for considering the sequence as uniformly random; hence lower is better. Note: For Dieharder the flawed "Diehard Sums Test" is ignored from the failure counts.

PractRand tests a length of the RNG output with all the selected tests; this is repeated with doubling lengths until a failure is detected or the maximum size is reached. PractRand was run using the core tests and smart folding. This is the default mode and comprises tests with little overlap in their characteristics and additional targeting testing of the lower bits of the output sequence. The limit for these results was 4 terabytes (4 TiB). A number in the table indicates the size in bytes of output where a failure occurred expressed as an exponent of 2; hence higher is better. A dash (-) indicates no failure and is best.

Spurious failures are a failure in a single run of the test suite. These are to be expected as the tests use probability thresholds to determine if the output is non-random. Systematic failures where the RNG fails the same test in every run indicate a problem with the RNG output. The count of systematic failures for Dieharder and TestU01 are shown in parentheses. The maximum output at which a failure always occurs for PractRand is shown in parentheses.

Any RNG with no systematic failures is highlighted in bold. Note that some RNGs fail PractRand on tests which target the lower bits. These are not suitable as all purpose generators but have utility in floating-point number generation where the lower bits are not used.

RNG identifier Dieharder TestU01 (BigCrush) PractRand
JDK 4, 4, 4, 4, 4 (4) 50, 51, 52, 49, 51 (48) 20, 20, 20 (1 MiB)
WELL_512_A 0, 0, 0, 0, 0 6, 7, 8, 6, 6 (6) 24, 24, 24 (16 MiB)
WELL_1024_A 0, 0, 0, 0, 0 5, 4, 5, 5, 4 (4) 27, 27, 27 (128 MiB)
WELL_19937_A 0, 1, 0, 0, 0 2, 2, 3, 3, 3 (2) 39, 39, 39 (512 GiB)
WELL_19937_C 0, 0, 0, 0, 0 4, 2, 2, 2, 2 (2) 39, 39, 39 (512 GiB)
WELL_44497_A 0, 0, 0, 0, 0 3, 2, 2, 2, 3 (2) 42, 42, 42 (4 TiB)
WELL_44497_B 0, 0, 0, 0, 0 2, 2, 2, 2, 2 (2) 42, 42, 42 (4 TiB)
MT 0, 0, 0, 0, 0 2, 3, 2, 2, 3 (2) 38, 38, 38 (256 GiB)
ISAAC 0, 0, 0, 0, 0 1, 1, 0, 0, 1 -, -, -
SPLIT_MIX_64 0, 0, 0, 0, 0 0, 0, 0, 1, 0 -, -, -
XOR_SHIFT_1024_S 0, 0, 0, 0, 0 1, 0, 0, 0, 2 31, 31, 31 (2 GiB)
TWO_CMRES 2, 2, 2, 2, 2 (2) 0, 1, 0, 0, 0 32, 32, 32 (4 GiB)
MT_64 0, 0, 0, 0, 0 2, 2, 2, 2, 2 (2) 39, 39, 39 (512 GiB)
MWC_256 0, 0, 0, 0, 0 0, 1, 1, 1, 0 -, -, -
KISS 0, 0, 0, 0, 0 1, 1, 0, 0, 0 -, -, -
XOR_SHIFT_1024_S_PHI 0, 0, 0, 0, 0 0, 2, 0, 0, 1 33, 33, 33 (8 GiB)
XO_RO_SHI_RO_64_S 0, 0, 0, 0, 0 1, 2, 3, 1, 1 (1) 21, 21, 21 (2 MiB)
XO_RO_SHI_RO_64_SS 0, 0, 0, 0, 0 0, 1, 0, 0, 0 -, -, -
XO_SHI_RO_128_PLUS 0, 0, 0, 0, 0 0, 0, 1, 0, 0 24, 24, 24 (16 MiB)
XO_SHI_RO_128_SS 0, 0, 0, 0, 0 1, 0, 1, 0, 0 -, -, -
XO_RO_SHI_RO_128_PLUS 0, 0, 0, 0, 0 1, 0, 0, 0, 0 25, 25, 25 (32 MiB)
XO_RO_SHI_RO_128_SS 0, 0, 0, 0, 0 1, 1, 1, 0, 0 -, -, -
XO_SHI_RO_256_PLUS 0, 0, 0, 0, 0 1, 0, 0, 0, 0 27, 27, 27 (128 MiB)
XO_SHI_RO_256_SS 0, 0, 0, 0, 0 0, 0, 0, 0, 1 -, -, -
XO_SHI_RO_512_PLUS 0, 0, 0, 0, 0 0, 2, 0, 0, 0 30, 30, 30 (1 GiB)
XO_SHI_RO_512_SS 0, 0, 0, 0, 0 0, 0, 0, 0, 0 -, -, -
PCG_XSH_RR_32 0, 0, 0, 0, 0 0, 0, 0, 0, 0 -, -, -
PCG_XSH_RS_32 0, 0, 0, 0, 0 0, 1, 2, 1, 0 41, -, -
PCG_RXS_M_XS_64 0, 0, 0, 0, 0 0, 1, 0, 0, 0 -, -, -
PCG_MCG_XSH_RR_32 0, 0, 0, 0, 0 0, 0, 0, 0, 0 -, -, -
PCG_MCG_XSH_RS_32 0, 0, 0, 0, 0 2, 1, 0, 1, 0 40, 41, 41 (2 TiB)
MSWS 0, 0, 0, 0, 0 0, 0, 0, 1, 2 -, -, -
SFC_32 0, 0, 0, 0, 0 0, 0, 0, 1, 1 -, -, -
SFC_64 0, 0, 0, 0, 0 0, 0, 0, 1, 2 -, -, -
JSF_32 0, 0, 0, 0, 0 0, 0, 0, 1, 2 -, -, -
JSF_64 0, 0, 0, 0, 0 0, 0, 2, 0, 0 -, -, -
XO_SHI_RO_128_PP 0, 0, 0, 0, 0 0, 0, 0, 1, 1 -, -, -
XO_RO_SHI_RO_128_PP 0, 0, 0, 0, 0 0, 0, 0, 0, 0 -, -, -
XO_SHI_RO_256_PP 0, 0, 0, 0, 0 0, 1, 1, 0, 1 -, -, -
XO_SHI_RO_512_PP 0, 0, 0, 0, 0 0, 0, 1, 0, 0 -, -, -
XO_RO_SHI_RO_1024_PP 0, 0, 0, 0, 0 0, 0, 3, 0, 1 -, -, -
XO_RO_SHI_RO_1024_S 0, 0, 0, 1, 0 0, 1, 0, 0, 0 33, 33, 33 (8 GiB)
XO_RO_SHI_RO_1024_SS 0, 0, 0, 0, 0 0, 1, 0, 0, 0 -, -, -
PCG_XSH_RR_32_OS 0, 0, 0, 0, 0 0, 0, 1, 0, 0 -, -, -
PCG_XSH_RS_32_OS 0, 0, 0, 0, 0 0, 0, 1, 0, 0 -, -, -
PCG_RXS_M_XS_64_OS 0, 0, 0, 0, 0 0, 0, 0, 1, 2 -, -, -
L64_X128_SS 0, 0, 0, 0, 0 0, 0, 0, 0, 0 -, -, -
L64_X128_MIX 0, 0, 0, 0, 0 0, 0, 1, 1, 0 -, -, -
L64_X256_MIX 0, 0, 0, 0, 0 0, 0, 0, 0, 0 -, -, -
L64_X1024_MIX 0, 0, 0, 0, 0 0, 1, 1, 1, 0 -, -, -
L128_X128_MIX 0, 0, 0, 0, 0 1, 0, 0, 0, 0 -, -, -
L128_X256_MIX 1, 0, 0, 0, 0 1, 0, 0, 0, 0 -, -, -
L128_X1024_MIX 0, 0, 0, 0, 0 0, 0, 0, 1, 0 -, -, -
L32_X64_MIX 0, 0, 0, 0, 0 0, 0, 0, 0, 0 -, -, -

6. Examples

The source distribution for Apache Commons RNG contains example applications to demonstrate functionality of the library. These are contained in the following modules:

Example Module Description
Stress Application for calling external tools that perform stringent uniformity tests. This application is used to generate results in the Quality section.
Sampling Application producing output from distribution samplers to create an approximate probability density function (PDF) as shown here.
Quadrature Application for computing numerical quadrature by Monte-Carlo (random) integration.
JMH Benchmarks that assess the performance of the generators using the Java Microbenchmark Harness. This application is used to generate results in the Performance section.
JPMS Example JPMS application using all the JPMS modules of Commons RNG (requires Java 11+).

The examples require Java 8+ unless specifed as requiring a higher version.

The examples can be built using profiles in the relevant module. For example to build the JMH benchmarks application and show the help information:

cd commons-rng-examples/examples-jmh
mvn package -P examples-jmh
java -jar target/examples-jmh.jar -h

Details of each example module is contained in a HOWTO.md document in the module directory.

7. Release compatibility

Apache Commons RNG will maintain binary compatibility within a major release number. However the output from a random generator may differ between releases. This is a functional compatibility change. The result is that when upgrading the library any code based on a random generator may produce different results. For example any unit test code written with a fixed seed to generate pseudo-random test data may fail after update as the test data has changed.

The library generators are algorithms that produce a stream of random bits using 32-bit or 64-bit integer output. The output from the primary type will maintain functional compatibility for the lifetime of the library. This output is tested to match a reference implementation of the algorithm and should be invariant. The only exception is to address bug fixes identified in the upstream implementation.

The primary output of the generator is used to produced derived types, for example floating point values, byte arrays and integers within a range. The output for derived types is not subject to functional compatibility constraints. Put simply the output from a generator may be different even when using the same starting seed due to updates to generation algorithms that use the underlying stream of random bits. Any library changes that result in a functional compatibility should be recorded in the release notes.

The library is provided as modules. It is recommended to explicitly include all required RNG modules in a project using the same version number. This will avoid version mismatch occurring between modules due to transitive dependencies; specifically this avoids using an alternative version number explicitly specified in the dependency tree. A Bill of Materials (BOM) is provided to ease dependency management.

8. Dependencies

Apache Commons RNG requires JDK 1.8+ and has no runtime dependencies.