| ~~ |
| ~~ Licensed to the Apache Software Foundation (ASF) under one or more |
| ~~ contributor license agreements. See the NOTICE file distributed with |
| ~~ this work for additional information regarding copyright ownership. |
| ~~ The ASF licenses this file to You under the Apache License, Version 2.0 |
| ~~ (the "License"); you may not use this file except in compliance with |
| ~~ the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, software |
| ~~ distributed under the License is distributed on an "AS IS" BASIS, |
| ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| ~~ See the License for the specific language governing permissions and |
| ~~ limitations under the License. |
| ~~ |
| |
| ----------------------------- |
| The Apache Commons RNG User Guide |
| ----------------------------- |
| |
| 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 {{{./why_not_java_random.html}severing ties}} to <<<java.util.Random>>>. |
| |
| The library is divided into modules: |
| |
| * {{{../commons-rng-client-api/apidocs/org/apache/commons/rng/package-summary.html}Client API}} (requires Java 6) |
| |
| This module provides the |
| {{{../commons-rng-client-api/apidocs/org/apache/commons/rng/RestorableUniformRandomProvider.html}interface}} |
| to be passed as argument to a procedure that needs to access to a sequence of random numbers. |
| |
| * {{{../commons-rng-core/apidocs/org/apache/commons/rng/core/package-summary.html}Core}} (requires Java 6) |
| |
| 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 {{{http://openjdk.java.net/projects/jigsaw/}Java modularization}}, it is possible |
| that future releases of the library will enforce access through the |
| {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/RandomSource.html}RandomSource}} |
| factory. |
| |
| * {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/package-summary.html}Simple}} (requires Java 6) |
| |
| This module provides factory methods for creating instances of all the generators implemented |
| in the <<<commons-rng-core>>> module. |
| |
| * {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/package-summary.html}Sampling}} (requires Java 6) |
| |
| This module provides implementations that generate a sequence of numbers according to some |
| specified probability distribution, and utilities to sample from a generic collection of items. |
| 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". |
| |
| As of version 1.1, the following modules are provided: |
| |
| ** <<<examples-jmh>>>: JMH benchmarking (requires Java 8) |
| |
| This module uses the {{{http://openjdk.java.net/projects/code-tools/jmh/}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 {{{./dist_density_approx.html}this userguide}}. |
| |
| ** <<<examples-jpms>>>: JPMS integration (requires Java 9) |
| |
| This module implements a dummy application that shows how to use the artefacts (produced |
| from the maven modules described above) as Java modules ({{{https://en.wikipedia.org/wiki/Java_Platform_Module_System}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 |
| {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/RandomSource.html#enum.constant.detail}all the available implementations}}. |
| |
| +--------------------------+ |
| import org.apache.commons.rng.UniformRandomProvider; |
| import org.apache.commons.rng.simple.RandomSource; |
| |
| UniformRandomProvider rng = RandomSource.create(RandomSource.MT); |
| +--------------------------+ |
| |
| |
| * A generator will 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. |
| +--------------------------+ |
| +--------------------------+ |
| long n = rng.nextLong(); // Long.MIN_VALUE <= n <= Long.MAX_VALUE. |
| long m = rng.nextLong(max); // 0 <= m < max. |
| +--------------------------+ |
| +--------------------------+ |
| float x = rng.nextFloat(); // 0 <= x < 1. |
| +--------------------------+ |
| +--------------------------+ |
| double x = rng.nextDouble(); // 0 <= x < 1. |
| +--------------------------+ |
| |
| |
| * A generator will 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); |
| +--------------------------+ |
| |
| |
| * In order to generate reproducible sequences, generators must be instantiated with a user-defined seed. |
| |
| +--------------------------+ |
| UniformRandomProvider rng = RandomSource.create(RandomSource.SPLIT_MIX_64, 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.create(RandomSource.ISAAC, 5776); |
| +--------------------------+ |
| +--------------------------+ |
| UniformRandomProvider rng = RandomSource.create(RandomSource.ISAAC, new int[] { 6, 7, 7, 5, 6, 1, 0, 2 }); |
| +--------------------------+ |
| +--------------------------+ |
| UniformRandomProvider rng = RandomSource.create(RandomSource.ISAAC, 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 behaviour 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 |
| {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/RandomSource.html#enum.constant.detail}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.create(RandomSource.TWO_CMRES_SELECT, seed, first, second); |
| +--------------------------+ |
| |
| In the above example, valid "subcycle identifiers" are in the interval [0, 13]. |
| |
| |
| * The current state of a generator can be |
| {{{../commons-rng-client-api/apidocs/org/apache/commons/rng/RestorableUniformRandomProvider.html#saveState--}saved}} |
| and |
| {{{../commons-rng-client-api/apidocs/org/apache/commons/rng/RestorableUniformRandomProvider.html#restoreState-org.apache.commons.rng.RandomProviderState-}restored}} |
| later on. |
| |
| +--------------------------+ |
| import org.apache.commons.rng.RestorableUniformRandomProvider; |
| import org.apache.commons.rng.RandomProviderState; |
| |
| RestorableUniformRandomProvider rng = RandomSource.create(RandomSource.WELL_512_A); |
| 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.MT_64; // Known source identifier. |
| |
| RestorableUniformRandomProvider rngOrig = RandomSource.create(source); // 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 = RandomSource.create(source); // New RNG instance from the same "source". |
| |
| // Restore original state on the new instance. |
| rngNew.restoreState(stateNew); |
| +--------------------------+ |
| |
| |
| * Generation of {{{./dist_density_approx.html}random deviates}} for various |
| {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/package-summary.html}distributions}}. |
| |
| +--------------------------+ |
| import org.apache.commons.rng.sampling.distribution.ContinuousSampler; |
| import org.apache.commons.rng.sampling.distribution.GaussianSampler; |
| import org.apache.commons.rng.sampling.distribution.MarsagliaNormalizedGaussianSampler; |
| |
| ContinuousSampler sampler = new GaussianSampler(new MarsagliaNormalizedGaussianSampler(RandomSource.create(RandomSource.MT_64)), |
| 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 = new RejectionInversionZipfSampler(RandomSource.create(RandomSource.ISAAC), |
| 5, 1.2); |
| int random = sampler.sample(); |
| +--------------------------+ |
| |
| * {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/PermutationSampler.html}Permutation}}, |
| {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/CollectionSampler.html}sampling from a <<<Collection>>>}} |
| and shuffling utilities. |
| |
| +--------------------------+ |
| import org.apache.commons.rng.sampling.PermutationSampler; |
| |
| PermutationSampler sampler = new PermutationSampler(RandomSource.create(RandomSource.KISS), |
| 6, 3); |
| |
| // 3 elements from a shuffling of the (0, 1, 2, 3, 4, 5) tuplet. |
| int[] random = sampler.sample(); |
| +--------------------------+ |
| |
| +--------------------------+ |
| import java.util.ArrayList; |
| import org.apache.commons.rng.sampling.CollectionSampler; |
| |
| ArrayList<String> list = new ArrayList<String>(); |
| list.add("Apache"); |
| list.add("Commons"); |
| list.add("RNG"); |
| |
| CollectionSampler<String> sampler = new CollectionSampler<String>(RandomSource.create(RandomSource.MWC_256), |
| list, 1); |
| String word = sampler.sample().get(0); |
| +--------------------------+ |
| |
| [] |
| |
| |
| 3. Library layout |
| |
| The API for client code consists of classes and interfaces defined in package |
| {{{../commons-rng-client-api/apidocs/org/apache/commons/rng/package-summary.html}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. |
| |
| [] |
| |
| |
| The API for instantiating generators is defined in package |
| {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/package-summary.html}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 {{{../commons-rng-core/apidocs/org/apache/commons/rng/core/package-summary.html}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>>>. |
| |
| [] |
| |
| * <<<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 |
| {{{../commons-rng-examples/examples-jmh/apidocs/org/apache/commons/rng/jmh/package-summary.html}performance benchmarks}} of the RNG implementations. |
| |
| All runs were performed on a platform with the following characteristics: |
| |
| * CPU: Intel(R) Core(TM) i7-3770 CPU @ 3.40GHz |
| |
| * Java version: 1.8.0_121 (build 1.8.0_121-8u121-b13-3-b13) |
| |
| * JVM: OpenJDK 64-Bit Server VM (build 25.121-b13, mixed mode) |
| |
| [] |
| |
| The following tables indicate the performance (as measured by |
| {{{http://openjdk.java.net/projects/code-tools/jmh/}JMH}}) for generating |
| |
| * a sequence of 32-bits integers (a.k.a. Java type <<<int>>>) |
| |
| * a sequence of 64-bits integers (a.k.a. Java type <<<long>>>) |
| |
| * a sequence of 64-bits floating point numbers (a.k.a. Java type <<<double>>>) |
| |
| [] |
| |
| |
| The first column is the RNG identifier (see {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/RandomSource.html}RandomSource}}). |
| |
| In these tables, <lower> is <better>. |
| |
| |
| ** Generating <<<int>>> values |
| |
| *--------------------------*----------------+ |
| || RNG identifier || Score (normalized to the score of <<<RandomSource.JDK>>>) | |
| *--------------------------*----------------+ |
| | MWC_256 | 0.43405 | |
| *--------------------------*----------------+ |
| | SPLIT_MIX_64 | 0.46945 | |
| *--------------------------*----------------+ |
| | TWO_CMRES | 0.53129 | |
| *--------------------------*----------------+ |
| | XOR_SHIFT_1024_S | 0.57792 | |
| *--------------------------*----------------+ |
| | KISS | 0.61673 | |
| *--------------------------*----------------+ |
| | ISAAC | 0.61966 | |
| *--------------------------*----------------+ |
| | MT | 0.67974 | |
| *--------------------------*----------------+ |
| | MT_64 | 0.68905 | |
| *--------------------------*----------------+ |
| | WELL_512_A | 0.83342 | |
| *--------------------------*----------------+ |
| | WELL_1024_A | 0.89916 | |
| *--------------------------*----------------+ |
| | JDK | 1.00000 | |
| *--------------------------*----------------+ |
| | WELL_19937_C | 1.10156 | |
| *--------------------------*----------------+ |
| | WELL_19937_A | 1.10758 | |
| *--------------------------*----------------+ |
| | WELL_44497_A | 1.18293 | |
| *--------------------------*----------------+ |
| | WELL_44497_B | 1.23908 | |
| *--------------------------*----------------+ |
| |
| |
| ** Generating <<<long>>> values |
| |
| *--------------------------*----------------+ |
| || RNG identifier || Score (normalized to the score of <<<RandomSource.JDK>>>) | |
| *--------------------------*----------------+ |
| | SPLIT_MIX_64 | 0.20866 | |
| *--------------------------*----------------+ |
| | TWO_CMRES | 0.24560 | |
| *--------------------------*----------------+ |
| | XOR_SHIFT_1024_S | 0.26774 | |
| *--------------------------*----------------+ |
| | MWC_256 | 0.31939 | |
| *--------------------------*----------------+ |
| | MT_64 | 0.32588 | |
| *--------------------------*----------------+ |
| | KISS | 0.49883 | |
| *--------------------------*----------------+ |
| | MT | 0.53191 | |
| *--------------------------*----------------+ |
| | ISAAC | 0.54878 | |
| *--------------------------*----------------+ |
| | WELL_1024_A | 0.64829 | |
| *--------------------------*----------------+ |
| | WELL_512_A | 0.66269 | |
| *--------------------------*----------------+ |
| | WELL_19937_A | 0.94553 | |
| *--------------------------*----------------+ |
| | WELL_19937_C | 0.99949 | |
| *--------------------------*----------------+ |
| | JDK | 1.00000 | |
| *--------------------------*----------------+ |
| | WELL_44497_A | 1.03821 | |
| *--------------------------*----------------+ |
| | WELL_44497_B | 1.09792 | |
| *--------------------------*----------------+ |
| |
| |
| ** Generating <<<double>>> values |
| |
| *--------------------------*----------------+ |
| || RNG identifier || Score (normalized to the score of <<<RandomSource.JDK>>>) | |
| *--------------------------*----------------+ |
| | SPLIT_MIX_64 | 0.27214 | |
| *--------------------------*----------------+ |
| | XOR_SHIFT_1024_S | 0.30975 | |
| *--------------------------*----------------+ |
| | TWO_CMRES | 0.31785 | |
| *--------------------------*----------------+ |
| | MWC_256 | 0.37810 | |
| *--------------------------*----------------+ |
| | MT_64 | 0.38516 | |
| *--------------------------*----------------+ |
| | KISS | 0.51777 | |
| *--------------------------*----------------+ |
| | ISAAC | 0.62528 | |
| *--------------------------*----------------+ |
| | MT | 0.63868 | |
| *--------------------------*----------------+ |
| | WELL_512_A | 0.66895 | |
| *--------------------------*----------------+ |
| | WELL_1024_A | 0.70950 | |
| *--------------------------*----------------+ |
| | JDK | 1.00000 | |
| *--------------------------*----------------+ |
| | WELL_19937_A | 1.06693 | |
| *--------------------------*----------------+ |
| | WELL_44497_A | 1.15398 | |
| *--------------------------*----------------+ |
| | WELL_19937_C | 1.15598 | |
| *--------------------------*----------------+ |
| | WELL_44497_B | 1.19013 | |
| *--------------------------*----------------+ |
| |
| |
| ** Sampling from a <N(0,1)> Gaussian distribution ({{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.html}MarsagliaNormalizedGaussianSampler}} implementation) |
| |
| *--------------------------*----------------+ |
| || RNG identifier || Score (normalized to the score of <<<RandomSource.JDK>>>) | |
| *--------------------------*----------------+ |
| | SPLIT_MIX_64 | 0.46750 | |
| *--------------------------*----------------+ |
| | XOR_SHIFT_1024_S | 0.48672 | |
| *--------------------------*----------------+ |
| | TWO_CMRES | 0.54703 | |
| *--------------------------*----------------+ |
| | MWC_256 | 0.55824 | |
| *--------------------------*----------------+ |
| | MT_64 | 0.58233 | |
| *--------------------------*----------------+ |
| | ISAAC | 0.64820 | |
| *--------------------------*----------------+ |
| | KISS | 0.66279 | |
| *--------------------------*----------------+ |
| | MT | 0.68759 | |
| *--------------------------*----------------+ |
| | WELL_512_A | 0.77854 | |
| *--------------------------*----------------+ |
| | WELL_1024_A | 0.82204 | |
| *--------------------------*----------------+ |
| | WELL_19937_A | 0.93504 | |
| *--------------------------*----------------+ |
| | WELL_19937_C | 0.98401 | |
| *--------------------------*----------------+ |
| | WELL_44497_A | 0.99620 | |
| *--------------------------*----------------+ |
| | JDK | 1.00000 | |
| *--------------------------*----------------+ |
| | WELL_44497_B | 1.03380 | |
| *--------------------------*----------------+ |
| |
| ** Comparing {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/BoxMullerNormalizedGaussianSampler.html}BoxMullerNormalizedGaussianSampler}}, {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.html}MarsagliaNormalizedGaussianSampler}}, {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/ZigguratNormalizedGaussianSampler.html}ZigguratNormalizedGaussianSampler}}. |
| Each score is normalized to the score of {{{https://docs.oracle.com/javase/8/docs/api/java/util/Random.html#nextGaussian--}nextGaussian()}} method of <<<java.util.Random>>>. |
| |
| *--------------------------*----------------+----------------+----------------+ |
| || RNG identifier || <<<BoxMullerNormalizedGaussianSampler>>> || <<<MarsagliaNormalizedGaussianSampler>>> || <<<ZigguratNormalizedGaussianSampler>>> | |
| *--------------------------*----------------+----------------+----------------+ |
| | ISAAC | 0.96494 | 0.41090 | 0.26529 | |
| *--------------------------*----------------+----------------+----------------+ |
| | JDK | 1.04037 | 0.65917 | 0.35473 | |
| *--------------------------*----------------+----------------+----------------+ |
| | KISS | 0.93580 | 0.41354 | 0.24676 | |
| *--------------------------*----------------+----------------+----------------+ |
| | MT | 0.95563 | 0.43966 | 0.25891 | |
| *--------------------------*----------------+----------------+----------------+ |
| | MT_64 | 0.85963 | 0.37269 | 0.22864 | |
| *--------------------------*----------------+----------------+----------------+ |
| | MWC_256 | 0.90648 | 0.34902 | 0.21321 | |
| *--------------------------*----------------+----------------+----------------+ |
| | SPLIT_MIX_64 | 0.82831 | 0.29894 | 0.18664 | |
| *--------------------------*----------------+----------------+----------------+ |
| | TWO_CMRES | 0.84886 | 0.35546 | 0.18992 | |
| *--------------------------*----------------+----------------+----------------+ |
| | WELL_1024_A | 1.00718 | 0.52266 | 0.29707 | |
| *--------------------------*----------------+----------------+----------------+ |
| | WELL_19937_A | 1.06638 | 0.61714 | 0.32631 | |
| *--------------------------*----------------+----------------+----------------+ |
| | WELL_19937_C | 1.09771 | 0.61585 | 0.37650 | |
| *--------------------------*----------------+----------------+----------------+ |
| | WELL_44497_A | 1.10244 | 0.62584 | 0.36866 | |
| *--------------------------*----------------+----------------+----------------+ |
| | WELL_44497_B | 1.10634 | 0.65012 | 0.38879 | |
| *--------------------------*----------------+----------------+----------------+ |
| | WELL_512_A | 0.99513 | 0.50448 | 0.31737 | |
| *--------------------------*----------------+----------------+----------------+ |
| | XOR_SHIFT_1024_S | 0.84066 | 0.30669 | 0.19735 | |
| *--------------------------*----------------+----------------+----------------+ |
| |
| |
| 5. Quality |
| |
| This section reports results of |
| {{{../commons-rng-examples/apidocs/org/apache/commons/rng/examples/stress/package-summary.html}performing "stress tests"}} |
| that aim at detecting failures of an implementation to produce sequences of numbers |
| that follow a uniform distribution. |
| |
| Two different test suites were used: |
| |
| * {{{http://www.phy.duke.edu/~rgb/General/dieharder.php}Dieharder}} |
| |
| * {{{http://simul.iro.umontreal.ca/testu01/tu01.html}TestU01}} |
| |
| [] |
| |
| The first column is the RNG identifier (see {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/RandomSource.html}RandomSource}}). |
| The second and third columns contain the number of tests which <Dieharder> and <TestU01> |
| respectively reported as below the accepted threshold for considering the sequence as |
| uniformly random; hence, in this table, <lower> is <better>. |
| |
| For each the two test suites, three runs were performed (using random seeds): Click on one |
| of the numbers of the comma-separated list in order to see the text report of the |
| corresponding run. |
| Note: For <Dieharder>, a failure on the "Diehard Sums Test" can be {{{http://www.phy.duke.edu/~rgb/General/dieharder.php}ignored}}. |
| |
| |
| *---------------------------------*----------------*---------------------* |
| || RNG identifier || Dieharder || TestU01 (BigCrush) | |
| *----------------*----------------*----------------*---------------------* |
| | JDK | {{{../txt/userguide/stress/dh/run_1/dh_1}14}}, {{{../txt/userguide/stress/dh/run_2/dh_1}16}}, {{{../txt/userguide/stress/dh/run_3/dh_1}15}} | {{{../txt/userguide/stress/tu/run_1/tu_1}78}}, {{{../txt/userguide/stress/tu/run_2/tu_1}75}}, {{{../txt/userguide/stress/tu/run_3/tu_1}76}} | |
| *---------------------------------*----------------*----------------* |
| | MT | {{{../txt/userguide/stress/dh/run_1/dh_2}0}}, {{{../txt/userguide/stress/dh/run_2/dh_2}0}}, {{{../txt/userguide/stress/dh/run_3/dh_2}0}} | {{{../txt/userguide/stress/tu/run_1/tu_2}2}}, {{{../txt/userguide/stress/tu/run_2/tu_2}2}}, {{{../txt/userguide/stress/tu/run_3/tu_2}2}} | |
| *---------------------------------*----------------*----------------* |
| | WELL_512_A | {{{../txt/userguide/stress/dh/run_1/dh_3}0}}, {{{../txt/userguide/stress/dh/run_2/dh_3}0}}, {{{../txt/userguide/stress/dh/run_3/dh_3}0}} | {{{../txt/userguide/stress/tu/run_1/tu_3}6}}, {{{../txt/userguide/stress/tu/run_2/tu_3}6}}, {{{../txt/userguide/stress/tu/run_3/tu_3}6}} | |
| *---------------------------------*----------------*----------------* |
| | WELL_1024_A | {{{../txt/userguide/stress/dh/run_1/dh_4}0}}, {{{../txt/userguide/stress/dh/run_2/dh_4}0}}, {{{../txt/userguide/stress/dh/run_3/dh_4}1}}| {{{../txt/userguide/stress/tu/run_1/tu_4}4}}, {{{../txt/userguide/stress/tu/run_2/tu_4}6}}, {{{../txt/userguide/stress/tu/run_3/tu_4}5}} | |
| *---------------------------------*----------------*----------------* |
| | WELL_19937_A | {{{../txt/userguide/stress/dh/run_1/dh_5}0}}, {{{../txt/userguide/stress/dh/run_2/dh_5}0}}, {{{../txt/userguide/stress/dh/run_3/dh_5}0}} | {{{../txt/userguide/stress/tu/run_1/tu_5}2}}, {{{../txt/userguide/stress/tu/run_2/tu_5}3}}, {{{../txt/userguide/stress/tu/run_3/tu_5}4}} | |
| *---------------------------------*----------------*----------------* |
| | WELL_19937_C | {{{../txt/userguide/stress/dh/run_1/dh_6}0}}, {{{../txt/userguide/stress/dh/run_2/dh_6}0}}, {{{../txt/userguide/stress/dh/run_3/dh_6}0}} | {{{../txt/userguide/stress/tu/run_1/tu_6}2}}, {{{../txt/userguide/stress/tu/run_2/tu_6}2}}, {{{../txt/userguide/stress/tu/run_3/tu_6}2}} | |
| *---------------------------------*----------------*----------------* |
| | WELL_44497_A | {{{../txt/userguide/stress/dh/run_1/dh_7}0}}, {{{../txt/userguide/stress/dh/run_2/dh_7}0}}, {{{../txt/userguide/stress/dh/run_3/dh_7}0}} | {{{../txt/userguide/stress/tu/run_1/tu_7}3}}, {{{../txt/userguide/stress/tu/run_2/tu_7}3}}, {{{../txt/userguide/stress/tu/run_3/tu_7}2}} | |
| *---------------------------------*----------------*----------------* |
| | WELL_44497_B | {{{../txt/userguide/stress/dh/run_1/dh_8}0}}, {{{../txt/userguide/stress/dh/run_2/dh_8}1}}, {{{../txt/userguide/stress/dh/run_3/dh_8}0}} | {{{../txt/userguide/stress/tu/run_1/tu_8}2}}, {{{../txt/userguide/stress/tu/run_2/tu_8}2}}, {{{../txt/userguide/stress/tu/run_3/tu_8}3}} | |
| *---------------------------------*----------------*----------------* |
| | ISAAC | {{{../txt/userguide/stress/dh/run_1/dh_9}0}}, {{{../txt/userguide/stress/dh/run_2/dh_9}0}}, {{{../txt/userguide/stress/dh/run_3/dh_9}0}} | {{{../txt/userguide/stress/tu/run_1/tu_9}1}}, {{{../txt/userguide/stress/tu/run_2/tu_9}0}}, {{{../txt/userguide/stress/tu/run_3/tu_9}0}} | |
| *---------------------------------*----------------*----------------* |
| | MT_64 | {{{../txt/userguide/stress/dh/run_1/dh_10}0}}, {{{../txt/userguide/stress/dh/run_2/dh_10}0}}, {{{../txt/userguide/stress/dh/run_3/dh_10}0}} | {{{../txt/userguide/stress/tu/run_1/tu_10}2}}, {{{../txt/userguide/stress/tu/run_2/tu_10}2}}, {{{../txt/userguide/stress/tu/run_3/tu_10}3}} | |
| *---------------------------------*----------------*----------------* |
| | SPLIT_MIX_64 | {{{../txt/userguide/stress/dh/run_1/dh_11}0}}, {{{../txt/userguide/stress/dh/run_2/dh_11}0}}, {{{../txt/userguide/stress/dh/run_3/dh_11}0}} | {{{../txt/userguide/stress/tu/run_1/tu_11}0}}, {{{../txt/userguide/stress/tu/run_2/tu_11}0}}, {{{../txt/userguide/stress/tu/run_3/tu_11}0}} | |
| *---------------------------------*----------------*----------------* |
| | XOR_SHIFT_1024_S | {{{../txt/userguide/stress/dh/run_1/dh_12}0}}, {{{../txt/userguide/stress/dh/run_2/dh_12}0}}, {{{../txt/userguide/stress/dh/run_3/dh_12}0}} | {{{../txt/userguide/stress/tu/run_1/tu_12}0}}, {{{../txt/userguide/stress/tu/run_2/tu_12}0}}, {{{../txt/userguide/stress/tu/run_3/tu_12}0}} | |
| *---------------------------------*----------------*----------------* |
| | TWO_CMRES | {{{../txt/userguide/stress/dh/run_1/dh_13}0}}, {{{../txt/userguide/stress/dh/run_2/dh_13}1}}, {{{../txt/userguide/stress/dh/run_3/dh_13}0}} | {{{../txt/userguide/stress/tu/run_1/tu_13}0}}, {{{../txt/userguide/stress/tu/run_2/tu_13}0}}, {{{../txt/userguide/stress/tu/run_3/tu_13}0}} | |
| *---------------------------------*----------------*----------------* |
| | MWC_256 | {{{../txt/userguide/stress/dh/run_1/dh_14}0}}, {{{../txt/userguide/stress/dh/run_2/dh_14}0}}, {{{../txt/userguide/stress/dh/run_3/dh_14}0}} | {{{../txt/userguide/stress/tu/run_1/tu_14}0}}, {{{../txt/userguide/stress/tu/run_2/tu_14}0}}, {{{../txt/userguide/stress/tu/run_3/tu_14}0}} | |
| *---------------------------------*----------------*----------------* |
| | KISS | {{{../txt/userguide/stress/dh/run_1/dh_15}0}}, {{{../txt/userguide/stress/dh/run_2/dh_15}0}}, {{{../txt/userguide/stress/dh/run_3/dh_15}0}} | {{{../txt/userguide/stress/tu/run_1/tu_15}0}}, {{{../txt/userguide/stress/tu/run_2/tu_15}1}}, {{{../txt/userguide/stress/tu/run_3/tu_15}0}} | |
| *---------------------------------*----------------*----------------* |
| |
| |
| 6. Dependencies |
| |
| Apache Commons RNG requires JDK 1.6+ and has no runtime dependencies. |