org.randomness
Enum PRNG

java.lang.Object
  extended by java.lang.Enum<PRNG>
      extended by org.randomness.PRNG
All Implemented Interfaces:
Serializable, Comparable<PRNG>

public enum PRNG
extends Enum<PRNG>

List of implemented Pseudo Random Number Generators that produces a deterministic, periodic and predictable pseudorandom sequence of bits from a initial value called a seed. It contrast with a TRNG process.

PRNGs are not suitable for applications where it is important that the numbers are really unpredictable, such as data encryption and gambling. Note that none of these generators are suitable for cryptography. See Cryptographically Secure Pseudorandom Number Generators ( CSPRNG) for that purposes. Non-cryptographically secure methods are usually faster than cryptographic methods, but should not be used when security is needed, hence the classification.

PRNG Properties

Due to computational needs, memory requirements, security needs, and desired random number "quality", there are many different RNG algorithms. No one algorithm is suitable for all cases, in the same way that no sorting algorithm is best in all situations. In common, each PRNG can be described in following properties:

Table: Properties of implemented Pseudoranom Number Generators
Name Minlen Outlen Period Seedlen Statelen License Category Support Streams
Name of the PRNG. Minlen - size of pseudorandom bitstring in bytes, generated per iteration. Output lenght it is a size of PRNG generation cycle. Generation cycle - it is a number of bytes generated between two modifications of working state. The generation cycle value implements idea of block generation. Each block can be directly transferred into ByteBuffers Period is a variable N indicate period of PRNG in form of 2N. Seedlen is a size of PRNG seed in bytes. Statelen is a size of PRNG working state of in bytes. The full required memory is equal to sum of seedlen and statelen.

Name of the license under source code of PRNG is distributed. Field of usage. Features, comments, advantages and disadvantages. Indicate if supports streams concept proposed by Pierre L'Ecuyer.

PRNG usage:

PRNGs characteristics make it suitable for applications where many numbers are required and where it is useful that the same sequence can be replayed easily. Popular examples of such applications are:

Thanks to:

Author:
Anton Kabysh (randomness adaptation),
Daniel Dyer (uncommons-math versions of cellular automaton, CMWC4096, and XOR_SHIFT generators),
George Marsaglia (author and original C version of CMWC4096 and XOR shift generators),
Neil Coffey (java port of Numerical Recipes combined generator),
Frank Yellin (implementation of java.util.Random LCG from Java SDK),
Makoto Matsumoto and Takuji Nishimura (idea and authors: MT19937, MT19937 64-bit version, SFTM and dSFMT2 random generators),
Mutsuo Saito (coautor of SFMT and dSFMT2 generators),
Sean Luke (Fast Mersenne Twister java implementation),
Nick Galbreath (implementations of MT64, Bailey-Crandall and Rule30, 192 Cells CA PRNG from javarng),
Adrian King (java SFMT implementation),
François Panneton, Pierre L'Ecuyer and Makoto Matsumoto (authors of WELL generators family.),
Doug Lea (idea and implementation of java.util.concurrent.ThreadLocalRandom)
See Also:
True Random Number Generators, Cryptographically Secure Pseudorandom Number Generators

Enum Constant Summary
BAILEY_CRANDALL
          The Bailey-Crandall random number generator based on normal numbers; this algorithm natively computes random floating-point numbers instead of the usual random bitstrings.
CELLULAR_AUTOMATON
          Extra fast Cellular automaton pseudorandom number generator developed by Tony Pasqualoni.
CELLULAR_AUTOMATON_192_RULE_30
          A random number generator based on Cellular Automaton Rule 30.
CMWC4096
          A Java version of George Marsaglia's Complementary Multiply With Carry (CMWC) RNG.
COMBINED
          A 64-bit generator using two XOR Shift generators are combined with an LCG and a multiply with carry (MWC) generator provide a good compromise between quality and speed.
dSFMT2
          NOT IMPLEMENTED YET, WORK IN PROGRESS: An adaptation of Double precision SIMD-oriented Fast Mersenne Twister (dSFMT) version 2.1 by Mutsuo Saito (Hiroshima University) and Makoto Matsumoto (Hiroshima University).
LCG, NATIVE, UTIL_RANDOM
          This Linear Congruent Generator is wrapper over java.util.Random uses a 48-bit seed, which is modified using a Linear Congruential formula.
MT
           Exceptionally high-quality, fast pseudoranom number generator based on the Mersenne Twister algorithm with a good statistical properties developed by Makoto Matsumoto and Takuji Nishimura.
MT64
           This is a 64-bit version of Mersenne Twister pseudorandom number generator with the same statistical properties as original 32-bit version but is implemented use 64-bit registers (long) and produces different output; Mersenne Twister 64 is unique in that it natively generates 64-bit of randomness per cycle.
SFMT
          SFMT algorithm implements the SIMD-oriented Fast Mersenne Twister version 1.3 by Mutsuo Saito (Hiroshima University) and Makoto Matsumoto (Hiroshima University).
WELL512a, WELL1024a, WELL19937c, WELL44497b
          WELL is in a 32-bit Well Equidistributed Long-period Linear pseudorandom rumber generator suppotring different periods and better equidistribution than Mersenne Twister algorithm but a slight higher cost of time proposed by François Panneton, Pierre L'Ecuyer and Makoto Matsumoto.
XOR_SHIFT
          Very fast PRNG using XOR Shift purposed by George Marsaglia.
 
Field Summary
static AtomicReference<Randomness> DEFAULT_ENTROPY_INPUT
          Default seed generator for PRNG entropy input function that uses Java's bundled SecureRandom (as instance of TRNG.NATIVE) source to generate random seed data with sufficient entropy.
 
Synonym Summary
static PRNG MERSENNE_TWISTER
          Synonym of Mersenne Twister algorithm.
static PRNG MERSENNE_TWISTER_64
          Synonym of 64-bit version of Mersenne Twister algorithm.
static PRNG NATIVE
          Represents native pseudorandom number generator nativelly suppotred by Java Platform - java.util.Random (also here as LCG).
static PRNG UTIL_RANDOM
          Synonym of Linear Congruental algorithm which java.util.Random is used.
 
Factories Summary
 Pseudorandomness shared()
          Returns a new PRNG object shared across multiply threads allowing thread safe acess to generation methods.
 Pseudorandomness current()
          Returns a unique PRNG generator isolated to the current thread (thread local random).
 
Properties Summary
 int minlen()
          Determine PRNG minlen - size of minimum pseudorandom bitstring generated per iteration.
 int outlen()
          Determine PRNG generation cycle - Generation cycle - it is a number of bytes generated between two modifications of working state.
 int period()
          Determine current PRNG period value n, such as actual period is 2n.
 int seedlen()
          Determine default initial seed length used by underlying DRBG algorithm in bytes (not configurable).
 
Method Summary
 boolean nextBoolean()
          Return's next generated pseudorandom 1-bit boolean value checking most significant bit.
 byte nextByte()
          Return's next generated pseudorandom 8-bit byte value.
 char nextChar()
          Return's next generated pseudorandom unsigned 16-bit char value.
 double nextDouble()
          Return's next generated pseudorandom 64-bit double value between 0.0 (inclusive) and 1.0 (exclusive).
 double nextDouble(double from, double to)
          Return's next generated pseudorandom 64-bit floating point double value chosen pseudorandomly with (approximately) uniform distribution from open interval [from,to] (excluding from and to).
 float nextFloat()
          Return's next generated pseudorandom 32-bit float value between 0.0 (inclusive) and 1.0 (exclusive).
 float nextFloat(float from, float to)
          Return's next generated pseudorandom 32-bit floating-point float value chosen pseudorandomly with (approximately) uniform distribution from open interval [from,to] (excluding from and to).
 int nextInt()
          Return's next generated pseudorandom 32-bit int value.
 int nextInt(int n)
          Return's next generated pseudorandom 32-bit int value chosen pseudorandomly with (approximately) uniform distribution from range 0 (inclusive) to n (exclusive).
 int nextInt(int from, int to)
          Returns a uniformly distributed random number in the closed interval [from,to] (including from and to).
 long nextLong()
          Return's next generated pseudorandom 64-bit long value.
 long nextLong(long n)
          Return's next generated pseudorandom 64-bit long value chosen pseudorandomly with (approximately) uniform distribution from range 0 (inclusive) to n (exclusive).
 long nextLong(long from, long to)
          Return's next generated pseudorandom 64-bit long value chosen pseudorandomly with (approximately) uniform distribution from closed interval [from,to] (including from and to).
 boolean nextProbability(float probability)
          Return's next generated boolean with a specified probability of returning true, else returning false.
 short nextShort()
          Return's next generated pseudorandom 16-bit short value.
 double random()
          Returns a double value with a positive sign, greater than or equal to 0.0 and less than 1.0 (as in java.lang.Math).
 void read(byte[] bytes)
          Generates random block of pseudorandom bytes and places them into a user-supplied byte array.
 int read(ByteBuffer buffer)
          Reads a sequence of pseudorandom bytes from this PRNG into the given buffer.
 int read(DoubleBuffer doubleBuffer)
          Transfers a sequence of generated double's from this PRNG into the given buffer.
 int read(FloatBuffer floatBuffer)
          Transfers a sequence of generated pseudorandom float's from this PRNG into the given buffer.
 int read(IntBuffer intBuffer)
          Transfers a sequence of generated pseudorandom int's from this PRNG into the given buffer.
 int read(LongBuffer longBuffer)
          Transfers a sequence of generated long's from this PRNG into the given buffer.
 PRNG reseed()
          Reseed internal instance of this PRNG to new initial internal state using default entropy input.
 PRNG reseed(ByteBuffer seed)
          Reseed internal instance of this PRNG to new initial internal state using specifed seed bytes.
 PRNG reset()
          Resets internal instance of this PRNG to its initial internal state.
 void shuffle(List<?> list)
          Randomly permute the specified list using this PRNG.
static PRNG valueOf(String name)
          Returns the enum constant of this type with the specified name.
static PRNG[] values()
          Returns an array containing the constants of this enum type, in the order they are declared.
 
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Enum Constant Detail

CELLULAR_AUTOMATON

public static final PRNG CELLULAR_AUTOMATON
Extra fast Cellular automaton pseudorandom number generator developed by Tony Pasqualoni.

Table: Properties of Cellular automaton pseudorandom number generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
Cellular Automaton RNG
32-bit string
4 (int)
4
?
4
8228
Apache License 2.0
Experimental

Since:
2006
See Also:
Wikipedia - Cellular automaton

CELLULAR_AUTOMATON_192_RULE_30

public static final PRNG CELLULAR_AUTOMATON_192_RULE_30
A random number generator based on Cellular Automaton Rule 30.

This implementation uses an circular array of 192 cells. Each cell is updated, in parallel, based on the three values, the left neighbor, itself, and the right neighbor. according to "rule 30" defined by:

111 110 101 100 011 010 001 000
0 0 0 1 1 1 1 0

The central or middle cell contains the "random" value.

Using a seed of 1L << 32 and subsequent calls to next(1) will produce a sequence of bits equivalent to (in Mathematica):

 CellularAutomaton[30,
   ReplacePart[Table[0, {192}], 1, 192/2],
   n,
   {All, {192/2 - 1}}]
 

The three 64-bit long value define the initial starting conditions and the bit values are layed out as a bit-string from left to right

 w0-0 w0-1 .... w0-63 w1-0 w1-1 .... w1-63 w2-0 w2-1 ... w2-63
 
To get the classical Rule 30 with "black dot" in the middle Use (0L, 1L << 32, 0L)

WARNING: Rule 30 has some obvious practical problems. Some initial conditions will result in loops or terminate (e.g. all 0s). These problems are not corrected here. This is a "pure" implementation designed for research (especially since this is quite slow in java)

Table: Properties of Cellular automaton 190 Rule 30 pseudorandom number generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
Celluar Automaton Rule 30
32-bit sting
4 (int)
4
?
24 (3 x long's)
24
New BSD License
Experimental

BAILEY_CRANDALL

public static final PRNG BAILEY_CRANDALL
The Bailey-Crandall random number generator based on normal numbers; this algorithm natively computes random floating-point numbers instead of the usual random bitstrings.

This generator is based on properties of the a2,3, a "2-normal" number. Normal numbers have the interesting property that the binary expansion (infinite) contains every binary string in exactly same frequency as a "truly random sequence."

Table: Properties of Bailey-Crandall Pseudoranom Number Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
Bailey-Crandall 51-bit floating point double [0,1) 4 bytes
8
?
8
56
New BSD License
Experimental, Floating-point output

Algorithm:

  1. Select seed s in the range [ 333, 253]
  2. Compute x = 2s - (3^33) * Floor(333/2) mod 333
  3. Compute a "random" 64-bit IEEE double value with
    1. Compute x = 253x mod 333
    2. Return x3-33

In order to do these computations, "double double" (128-bit) arithmetic is used. The performance could be improved if Java allowed "fused multiply-add" available on PowerPC and some other microprocessors.

For any non-floating point values used 32-bit precision random blocks from the mantissa.

References:

Since:
2004
See Also:
Mathworld - Normal Number

CMWC4096

public static final PRNG CMWC4096
A Java version of George Marsaglia's Complementary Multiply With Carry (CMWC) RNG.

This is a very fast PRNG with an extremely long period 2131104. It should be used in preference to the other generators when a very long period is required.

Table: Properties of Complementary Multiply With Carry (CMWC) RNG
Name Precision Minlen Outlen Period Seedlen Statelen License Category
CMWC4096
32-bit string
4 (int)
4
131104
16388
16392
Apache License 2.0
Modern, Extra long period

One potential drawback of this PRNG is that it requires significantly more seed data than the other PRNGs. It requires just over 16 kilobytes, which may be a problem if your are obtaining seed data from a slow or limited entropy source.

Since:
2003
See Also:
Multiply-with-carry,
George Marsaglia

COMBINED

public static final PRNG COMBINED
A 64-bit generator using two XOR Shift generators are combined with an LCG and a multiply with carry (MWC) generator provide a good compromise between quality and speed.

Without going into all the details here, notice the two blocks of three shifts each, which are the XORShifts; the first line which is the LCG, similar to the standard Random, and the line between the two XORShifts, which is a Multiply-With-Carry generator. Purposed by authors of Numerical Recipes: The Art of Scientific Computing and provide a good compromise between quality and speed.

This generator is useful in cases where you need fast, good-quality randomness but don't need cryptographic randomness, as provided by the Java SecureRandom class. It is not much slower than java.util.Random and provides much better quality randomness and a much larger period. It is about 20 times faster than SecureRandom. Typical candidates for using this generator would be games and simulations.

Table: Properties of Combined PRNG
Name Precision Minlen Outlen Period Seedlen Statelen License Category
Combined RNG
64-bit string
8 (long)
8
?
8
24
Written by Neil Coffey.
Javamex UK 2010.
64-bit precision generation, Games, Simulation

Since:
unknown
See Also:
A Java implementation of the Numerical Recipes random number generator

LCG

public static final PRNG LCG
This Linear Congruent Generator is wrapper over java.util.Random uses a 48-bit seed, which is modified using a Linear Congruential formula. (See Donald Knuth, The Art of Computer Programming, Volume 3, Section 3.2.1.).

LCGs should not be used for applications where high-quality randomness is critical. For example, it is not suitable for a Monte Carlo simulation because of the serial correlation. A further problem of LCGs is that the lower-order bits of the generated sequence have a far shorter period than the sequence as a whole if m is set to a power of 2.

Table: Properties of Linear Congruent Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
Linear Congruent Generator,
java.util.Random,
NATIVE (system default)
48-bit string
4 (int)
4
48
8
8
GPL
Classic

Since:
1996
See Also:
Wikipedia - Linear congruential generator ,
Using java.util.Random

MT

public static final PRNG MT

Exceptionally high-quality, fast pseudoranom number generator based on the Mersenne Twister algorithm with a good statistical properties developed by Makoto Matsumoto and Takuji Nishimura.

In 1997 Makoto Matsumoto and Takuji Nishimura published the Mersenne Twister algorithm, which avoided many of the problems with earlier generators. They presented two versions, MT11213 and MT19937, with periods of 2^11213-1 and 2^19937-1 (approximately 10^6001), which represents far more computation than is likely possible in the lifetime of the entire universe. MT19937 uses an internal state of 624 ints, or 19968 bits, which is about expected for the huge period.

It is faster than the LCG, is equidistributed in up to 623 dimensions, and has become the main RNG used in statistical simulations. The speed comes from only updating a small part of the state for each random number generated, and moving through the state over multiple calls. Mersenne Twister is a Twisted Generalized Feedback Shift register (TGFSR). It is not cryptographically secure: observing 624 sequential outputs allows one to determine the internal state, and then predict the remaining sequence (link1, link2). Mersenne Twister has some flaws, covered in the WELL19937c and SFMT algorithms below.

This is the best PRNG for most experiments. It passes the full DIEHARD suite. The MersenneTwister generator uses a 624 elements integer array, so it consumes less than 2.5 kilobytes.

Table: Properties of Mersenne Twister Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
Mersenne Twister
19937-bit array
4 (int)
2496
(uses a 624 elements integer array)
19937
16
2500
Apache License 2.0.
Professional, Simulation, Fast Generator, Block Output.

Reference.

Since:
1997
See Also:
Mersenne Twister Home Page,
Wikipedia - Mersenne twister

MT64

public static final PRNG MT64

This is a 64-bit version of Mersenne Twister pseudorandom number generator with the same statistical properties as original 32-bit version but is implemented use 64-bit registers (long) and produces different output; Mersenne Twister 64 is unique in that it natively generates 64-bit of randomness per cycle.

This is a very fast random number generator with good statistical properties (it passes the full DIEHARD suite). This is the best PRNG for most experiments if needed 64-bit values. The output has 64 bits of precision. The output of this version of Mersenne Twister is differs from default 32-bit version of Mersenne twister generator.

Table: Properties of Mersenne Twisted 64-bit version
Name Precision Minlen Outlen Period Seedlen Statelen License Category
Mersenne Twister 64 bit
19937-bit array
8 (long)
2496
(uses a 312 elements long's array)
19937
32
2500
Apache License 2.0.
64-bit precision output, Professional, Simulation, Fast Generator, Block Output.

References:

Since:
2000
See Also:
Combined 64-bit output PRNG,
Mersenne Twister 64-bit version ,
This is mostly a straight port of the C-code (mt19937-64.c),
Wikipedia - Mersenne Twister

SFMT

public static final PRNG SFMT
SFMT algorithm implements the SIMD-oriented Fast Mersenne Twister version 1.3 by Mutsuo Saito (Hiroshima University) and Makoto Matsumoto (Hiroshima University).

SFMT is a new variant of Mersenne Twister (MT) introduced in 2006. SFMT is a Linear Feedbacked Shift Register (LFSR) generator that generates a 128-bit pseudorandom integer at one step. SFMT is designed with recent parallelism of modern CPUs, such as multi-stage pipelining and SIMD (e.g. 128-bit integer) instructions. It supports 32-bit and 64-bit integers, as well as double precision floating point as output. SFMT is much faster than Mersenne Twister, in most platforms. Not only the speed, but also the dimensions of equidistributions at v-bit precision are improved. In addition, recovery from 0-excess initial state is much faster.

This adaptation supports only the period 219937 − 1; the original supports some longer and shorter periods: 2607 −1, 21279−1, ..., 2132049−1, 2216091−1.

Table: Properties of SIMD-oriented Fast Mersenne Twister Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
SIMD-oriented Fast Mersenne Twister
19937-bit array
4 (int)
2496
(uses a 624 elements integer array)
19937
32
2500
modified BSD License
Simulation, Best equidistribution properties, Extra-Fast Generator, Block Output

Since:
2007
See Also:
Master's Thesis of Mutsuo Saito for detail,
SIMD-oriented Fast Mersenne Twister (SFMT) web page,
Wikipedia - SFMT,
Wikipedia SSE2:CPUs supporting SSE2

dSFMT2

public static final PRNG dSFMT2
NOT IMPLEMENTED YET, WORK IN PROGRESS: An adaptation of Double precision SIMD-oriented Fast Mersenne Twister (dSFMT) version 2.1 by Mutsuo Saito (Hiroshima University) and Makoto Matsumoto (Hiroshima University).

The purpose of dSFMT is to speed up the generation by avoiding the expensive conversion of integer to double (floating point). dSFMT directly generates double precision floating point pseudorandom numbers which have the IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985) format. dSFMT is only available on the CPUs which use IEEE 754 format double precision floating point numbers. (Java use it).

Table: Properties of Double precision SIMD-oriented Fast Mersenne Twister
Name Precision Minlen Outlen Period Seedlen Statelen License Category
dSFMT2
64-bit floating point
8 (int)
4
2496
16
2500
Apache License Version 2.0
floating-point output

dSFMT doesn't support integer outputs. dSFMT supports the output of double precision floating point pseudorandom numbers which distribute in the range of [1, 2), [0, 1), (0, 1] and (0, 1). And it also supports the various periods form 2607-1 to 2132049-1. (dSFMT ver. 2.1 supports the periods from 2521-1 to 2216091-1.)

Since:
2009
See Also:
Slides was used for the talk at MCQMC 2008

WELL512a

public static final PRNG WELL512a
Well Equidistributed Long-period Linear (WELL) is in a 32-bit pseudorandom rumber generator with period 2512 proposed by François Panneton, Pierre L'Ecuyer and Makoto Matsumoto.

Matsumoto (co-creator of the Mersenne Twister), L’Ecuyer (a major RNG researcher), and Panneton introduced another class of TGFSR PRNGs in 2006. These algorithms produce numbers with better equidistribution than Mersenne Twister and improve upon “bit-mixing” properties. They are fast, come in many sizes, and produce higher quality random numbers. The only downside is that WELL are slightly slower than MT19937, but not much. The upside is the numbers are considered to be higher quality, and the code is significantly simpler. The WELL generators are better to escape zeroland as explained by the WELL generators creators.

WELL period sizes are presented for period 2^n for n = 512, 521, 607, 800, 1024 ,19937 , 21701, 23209, and 44497, with corresponding state sizes. This allows a user to trade period length for state size. All run at similar speed. 2^512 is about 10^154, and it is unlikely any video game will ever need that many random numbers, since it is far larger then the number of particles in the universe.

Table: Properties of WELL512a Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
WELL512a
32-bit string
4 (int)
4
512
64
24
Apache License Version 2.0
Professional, Simulation, Fast Generator, Best equidistribution properties

Reference:

Since:
2006
See Also:
Wikipedia - WELL,
WELL Random number generator,
Apache commons-math WELL implementation,
SSJ: Stochastic Simulation in Java (Contains several WELL implementations)

WELL1024a

public static final PRNG WELL1024a
WELL1024a is in a 32-bit Well Equidistributed Long-period Linear pseudorandom rumber generator with period 21024 and better equidistribution than Mersenne Twister algorithm but a slight higher cost of time proposed by François Panneton, Pierre L'Ecuyer and Makoto Matsumoto.

WELL algorithms produce numbers with better equidistribution than Mersenne Twister and improve upon “bit-mixing” properties. They are fast, come in many sizes, and produce higher quality random numbers. The only downside is that WELL are slightly slower than MT19937, but not much. The upside is the numbers are considered to be higher quality, and the code is significantly simpler. If initialization array contains many zero bits, MersenneTwister may take a very long time (several hundreds of thousands of iterations to reach a steady state with a balanced number of zero and one in its bits pool). So the WELL generators are better to escape zeroland as explained by the WELL generators creators.

WELL period sizes are presented for period 2^n for n = 512, 521, 607, 800, 1024 ,19937 , 21701, 23209, and 44497, with corresponding state sizes. The larger periods ones aren’t really needed except for computation like weather modeling or earth simulations.

WELL1024a , WELL19937c and WELL44497b are maximally equidistributed for blocks size up to 32 bits (they should behave correctly also for double based on more than 32 bits blocks, but equidistribution is not proven at these blocks sizes).

Table: Properties of WELL1024a Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
WELL1024a
32-bit string
4 (int)
4
1024
128
768
Apache License Version 2.0
Professional, Simulation, Fast Generator, Best equidistribution properties

Reference:

Since:
2006
See Also:
Wikipedia - WELL,
WELL Random number generator,
Apache commons-math WELL implementation,
SSJ: Stochastic Simulation in Java (Contains several WELL implementations)

WELL19937c

public static final PRNG WELL19937c
WELL19937c is in a 32-bit Well Equidistributed Long-period Linear pseudorandom rumber generator with period 219937 and better equidistribution than Mersenne Twister algorithm but a slight higher cost of time proposed by François Panneton, Pierre L'Ecuyer and Makoto Matsumoto.

WELL algorithms produce numbers with better equidistribution than Mersenne Twister and improve upon “bit-mixing” properties. They are fast, come in many sizes, and produce higher quality random numbers. The only downside is that WELL are slightly slower than MT19937, but not much. The upside is the numbers are considered to be higher quality, and the code is significantly simpler. If initialization array contains many zero bits, MersenneTwister may take a very long time (several hundreds of thousands of iterations to reach a steady state with a balanced number of zero and one in its bits pool). So the WELL generators are better to escape zeroland as explained by the WELL generators creators.

WELL period sizes are presented for period 2^n for n = 512, 521, 607, 800, 1024 ,19937 , 21701, 23209, and 44497, with corresponding state sizes. The larger periods ones aren’t really needed except for computation like weather modeling or earth simulations.

Note: The WELL generators use 6 integer arrays with a size equal to the pool size, so the WELL19937 generator uses about 15 kilobytes. This may be important if a very large number of generator instances were used at the same time.

WELL19937c and are maximally equidistributed for blocks size up to 32 bits (they should behave correctly also for double based on more than 32 bits blocks, but equidistribution is not proven at these blocks sizes).

Table: Properties of WELL19937c Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
WELL19937c
32-bit string
4 (int)
4
19937
2496
15k
Apache License Version 2.0
Professional, Simulation, Modeling, Fast Generator, Best equidistribution properties

Reference:

Since:
2006
See Also:
Wikipedia - WELL,
WELL Random number generator,
Apache commons-math WELL implementation,
SSJ: Stochastic Simulation in Java

WELL44497b

public static final PRNG WELL44497b
WELL44497b is in a 32-bit Well Equidistributed Long-period Linear pseudorandom rumber generator with period 244497 and better equidistribution than Mersenne Twister algorithm but a slight higher cost of time proposed by François Panneton, Pierre L'Ecuyer and Makoto Matsumoto.

WELL algorithms produce numbers with better equidistribution than Mersenne Twister and improve upon “bit-mixing” properties. They are fast, come in many sizes, and produce higher quality random numbers. The only downside is that WELL are slightly slower than MT19937, but not much. The upside is the numbers are considered to be higher quality, and the code is significantly simpler. If initialization array contains many zero bits, MersenneTwister may take a very long time (several hundreds of thousands of iterations to reach a steady state with a balanced number of zero and one in its bits pool). So the WELL generators are better to escape zeroland as explained by the WELL generators creators.

WELL period sizes are presented for period 2^n for n = 512, 521, 607, 800, 1024 ,19937 , 21701, 23209, and 44497, with corresponding state sizes.

Note that WELL generators use 6 integer arrays with a size equal to the pool size, so the the WELL44497b generator uses about 33 kilobytes. This may be important if a very large number of generator instances were used at the same time.

WELL44497b are maximally equidistributed for blocks size up to 32 bits (they should behave correctly also for double based on more than 32 bits blocks, but equidistribution is not proven at these blocks sizes).

Table: Properties of WELL44497b Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
WELL44497b
32-bit string
4 (int)
4
44497
5564
33k
Apache License Version 2.0
Professional, Simulation, Modeing, Fast Generator, Best equidistribution properties

Reference:

Since:
2006
See Also:
Wikipedia - WELL,
WELL Random number generator,
Apache commons-math WELL implementation,
SSJ: Stochastic Simulation in Java

XOR_SHIFT

public static final PRNG XOR_SHIFT
Very fast PRNG using XOR Shift purposed by George Marsaglia.

This PRNG has a period of about 2160, which is not as long as the but it is faster.

Table: Properties of SIMD-oriented Fast Mersenne Twister Generator
Name Precision Minlen Outlen Period Seedlen Statelen License Category
XOR Shift
32-bit string
4 (int)
4
160
20
20
Apache License Version 2.0
Modern, Fast

Since:
2003
See Also:
Good random number generator from George Marsaglia, XORShift random number generators, Wikipedia - XOR Shift, George Marsaglia
Field Detail

UTIL_RANDOM

public static final PRNG UTIL_RANDOM
Synonym of Linear Congruental algorithm which java.util.Random is used.


NATIVE

public static final PRNG NATIVE
Represents native pseudorandom number generator nativelly suppotred by Java Platform - java.util.Random (also here as LCG).

See Also:
Native truerandomness, Native cryptoranomdness

MERSENNE_TWISTER

public static final PRNG MERSENNE_TWISTER
Synonym of Mersenne Twister algorithm.


MERSENNE_TWISTER_64

public static final PRNG MERSENNE_TWISTER_64
Synonym of 64-bit version of Mersenne Twister algorithm.


DEFAULT_ENTROPY_INPUT

public static final AtomicReference<Randomness> DEFAULT_ENTROPY_INPUT
Default seed generator for PRNG entropy input function that uses Java's bundled SecureRandom (as instance of TRNG.NATIVE) source to generate random seed data with sufficient entropy. This is the only seeding strategy that is guaranteed to work on all platforms.

Method Detail

values

public static PRNG[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (PRNG c : PRNG.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static PRNG valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null

shared

public Pseudorandomness shared()
Returns a new PRNG object shared across multiply threads allowing thread safe acess to generation methods.

Returns:
a new Pseugorandomness generator.

current

public final Pseudorandomness current()
Returns a unique PRNG generator isolated to the current thread (thread local random). Any attempt to use this instance from another thread will throw ConcurrentModificationException.

Usages of this class should typically be of the form: PRNG.XXX.current().nextX(...) (where XXX - one of implemented PRNG generators, and X is Int, Long, etc). When all usages are of this form, it is never possible to accidently share a thread local random across multiple threads.

The thread local random instance is unique for parent thread, so locality can be cheked as:

 public boolean isThreadLocal(Randomness rnd) {
        return PRNG.XXX.current() == rnd;
 }
 
where XXX - one of implemented PRNG generators

Returns:
the thread local instance of PRNG for current thread.
See Also:
ThreadLocal,
TRNG#current() Thread local for Truerandomness,,
CSPRNG#current() Thread-local for Cryptorandomness.

reset

public final PRNG reset()
Resets internal instance of this PRNG to its initial internal state.

This method behaves exactly as specified in the instantiate function.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.


reseed

public final PRNG reseed()
Reseed internal instance of this PRNG to new initial internal state using default entropy input.

This method behaves exactly as specified in the reseed function.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Returns:
this

reseed

public final PRNG reseed(ByteBuffer seed)
Reseed internal instance of this PRNG to new initial internal state using specifed seed bytes.

This method behaves exactly as specified in the reseed function.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Returns:
this

nextProbability

public final boolean nextProbability(float probability)
Return's next generated boolean with a specified probability of returning true, else returning false.

Uses 32-bit precision.

Parameters:
probability - probability must be between 0.0 and 1.0, inclusive.
Returns:
the next generated

nextInt

public final int nextInt()
Return's next generated pseudorandom 32-bit int value. Returned values are chosen pseudorandomly with (approximately) uniform distribution from range Integer.MIN_VALUE to Integer.MAX_VALUE.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

There are several pseudorandom generators, essentially producing int values:

  1. CELLULAR_AUTOMATON,
  2. CELLULAR_AUTOMATON_192_RULE_30
  3. CMWC4096,
  4. LCG,
  5. MT,
  6. SFMT,
  7. WELL512a,WELL1024a,WELL19937c, WELL44497b
  8. XOR_SHIFT

Returns:
a pseudorandom int value.

nextBoolean

public final boolean nextBoolean()
Return's next generated pseudorandom 1-bit boolean value checking most significant bit. Returned values are chosen pseudorandomly with (approximately) uniform distribution from true or false with equal probability.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Returns:
a pseudorandom boolean value.
See Also:
Wikipedia - Bit, JLS - 4.2.5 The boolean Type and boolean Values

nextByte

public final byte nextByte()
Return's next generated pseudorandom 8-bit byte value. Returned values are chosen pseudorandomly with (approximately) uniform distribution from range Byte.MIN_VALUE to Byte.MAX_VALUE.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Returns:
a pseudorandom byte value.
See Also:
Wikipedia - Byte, JLS - 4.2.1 Integral Types and Values

nextChar

public final char nextChar()
Return's next generated pseudorandom unsigned 16-bit char value. Returned values are chosen pseudorandomly with (approximately) uniform distribution from range Character.MIN_VALUE to Character.MAX_VALUE.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Returns:
a random double greater than or equal to 0.0 and less than 1.0.
See Also:
JLS - 4.2.1 Integral Types and Values

nextDouble

public final double nextDouble()
Return's next generated pseudorandom 64-bit double value between 0.0 (inclusive) and 1.0 (exclusive). Returned values are chosen pseudorandomly with (approximately) uniform distribution greater than or equal to 0.0 and less than 1.0.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

There are several PRNGs, essentially producing double values:

  1. dSFMT2,
  2. BAILEY_CRANDALL,

Returns:
newly generated pseudorandom double value.
See Also:
JLS - 4.2.3 Floating-Point Types, Formats, and Values, Wikipedia - IEEE 754

nextFloat

public final float nextFloat()
Return's next generated pseudorandom 32-bit float value between 0.0 (inclusive) and 1.0 (exclusive). Returned values are chosen pseudorandomly with (approximately) uniform distribution greater than or equal to 0.0 and less than 1.0.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Returns:
newly generated pseudorandom float value.
See Also:
JLS - 4.2.3 Floating-Point Types, Formats, and Values, Wikipedia - IEEE 754

nextLong

public final long nextLong()
Return's next generated pseudorandom 64-bit long value. Returned values are chosen pseudorandomly with (approximately) uniform distribution from range Long.MIN_VALUE to Long.MAX_VALUE.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

There are several pseudorandom generators, essentially producing long values:

  1. COMBINED,
  2. MT64

Returns:
a pseudorandom long value.

nextShort

public final short nextShort()
Return's next generated pseudorandom 16-bit short value. Returned values are chosen pseudorandomly with (approximately) uniform distribution from range Short.MIN_VALUE to Short.MAX_VALUE.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Returns:
a pseudorandom short value.
See Also:
Wikipedia - Byte, JLS - 4.2.1 Integral Types and Values

read

public final void read(byte[] bytes)
Generates random block of pseudorandom bytes and places them into a user-supplied byte array.

Parameters:
bytes - - the byte array to fill with pseudorandom bytes

read

public final int read(ByteBuffer buffer)
Reads a sequence of pseudorandom bytes from this PRNG into the given buffer.

Transfers a sequence generated bytes from this PRNG into the given buffer. An attempt is made to read up to r bytes from PRNG, where r is the number of bytes remaining in the buffer, that is, buffer.remaining(), at the moment this method is invoked.

Suppose that a byte sequence of length n is read, where 0  <= n <= r. This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment this method is invoked. Upon return the buffer's position will be equal to p + n; its limit will not have changed. As many bytes as possible are transferred into each buffer, hence the final position is guaranteed to be equal to that buffer's limit.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.XXX.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own thread-local pseudorandom-number generator.

Parameters:
buffer - The buffer into which random bytes are to be transferred.
Returns:
The number of bytes read from PRNG.
Throws:
NullPointerException - if buffer is null.

read

public final int read(IntBuffer intBuffer)
Transfers a sequence of generated pseudorandom int's from this PRNG into the given buffer.

Otherwise this method behaves exactly as specified in the read(ByteBuffer) method.

Parameters:
intBuffer - The buffer into which random integers are to be transferred
Returns:
The number of int's read, possibly zero.

read

public final int read(FloatBuffer floatBuffer)
Transfers a sequence of generated pseudorandom float's from this PRNG into the given buffer.

This method behaves exactly as specified in the read(ByteBuffer) method.

Parameters:
floatBuffer - The buffer into which random floating point values are to be transferred
Returns:
The number of float's read, possibly zero.

read

public final int read(LongBuffer longBuffer)
Transfers a sequence of generated long's from this PRNG into the given buffer.

This method behaves exactly as specified in the read(ByteBuffer) method.

Parameters:
longBuffer - The buffer into which random long values are to be transferred.
Returns:
The number of long's read.

read

public final int read(DoubleBuffer doubleBuffer)
Transfers a sequence of generated double's from this PRNG into the given buffer.

This method behaves exactly as specified in the read(ByteBuffer) method.

Parameters:
doubleBuffer - The buffer into which random double's are to be transferred
Returns:
The number of double's read.

random

public final double random()
Returns a double value with a positive sign, greater than or equal to 0.0 and less than 1.0 (as in java.lang.Math). Returned values are chosen randomly with (approximately) uniform distribution from that range.

When this method is first called, it creates a single new PRNG, exactly as if by the expression new PRNG.shared() This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

The underlying PRNG is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own pseudorandom-number generator.

Returns:
a random double greater than or equal to 0.0 and less than 1.0.

nextInt

public final int nextInt(int from,
                         int to)
Returns a uniformly distributed random number in the closed interval [from,to] (including from and to).

Parameters:
from - low border of interval (included)
to - hight border of interval (included)
Returns:
next generated uniformly distributed random number in interval [from,to].
Throws:
IllegalArgumentException - if from >= to.

nextInt

public final int nextInt(int n)
Return's next generated pseudorandom 32-bit int value chosen pseudorandomly with (approximately) uniform distribution from range 0 (inclusive) to n (exclusive).

Suffice it to say, n must be > 0, or an IllegalArgumentException is raised.

Returns:
a pseudorandom int value in range [0...n-1].
Throws:
IllegalArgumentException - if n < 0

nextDouble

public final double nextDouble(double from,
                               double to)
Return's next generated pseudorandom 64-bit floating point double value chosen pseudorandomly with (approximately) uniform distribution from open interval [from,to] (excluding from and to).

Parameters:
from - low border of interval (excluded)
to - hight border of interval (excluded)
Returns:
a pseudorandom long value in range [0...n-1].
Throws:
IllegalArgumentException - if from >= to.

nextFloat

public final float nextFloat(float from,
                             float to)
Return's next generated pseudorandom 32-bit floating-point float value chosen pseudorandomly with (approximately) uniform distribution from open interval [from,to] (excluding from and to).

Parameters:
from - low border of interval (excluded)
to - hight border of interval (excluded)
Returns:
next generated uniformly distributed random floating point in interval [from,to].
Throws:
IllegalArgumentException - if from >= to.

nextLong

public final long nextLong(long n)
Return's next generated pseudorandom 64-bit long value chosen pseudorandomly with (approximately) uniform distribution from range 0 (inclusive) to n (exclusive).

Suffice it to say, n must be > 0, or an IllegalArgumentException is raised.

Returns:
a pseudorandom long value in range [0...n-1].
Throws:
IllegalArgumentException - if n < 0

nextLong

public final long nextLong(long from,
                           long to)
Return's next generated pseudorandom 64-bit long value chosen pseudorandomly with (approximately) uniform distribution from closed interval [from,to] (including from and to).

Parameters:
from - low border of interval (included)
to - hight border of interval (included)
Returns:
a pseudorandom long value in range [0...n-1].
Throws:
IllegalArgumentException - if from >= to.

shuffle

public final void shuffle(List<?> list)
Randomly permute the specified list using this PRNG. All permutations occur with equal likelihood assuming that the source of randomness is fair.
 Pseudorandomness rand = ...
 rand.shuffle(Arrays.asList(200,300,212,111,6,2332));
 
This implementation traverses the list backwards, from the last element up to the second, repeatedly swapping a randomly selected element into the "current position". Elements are randomly selected from the portion of the list that runs from the first element to the current position, inclusive.

This method runs in linear time. If the specified list does not implement the RandomAccess interface and is large, this implementation dumps the specified list into an array before shuffling it, and dumps the shuffled array back into the list. This avoids the quadratic behavior that would result from shuffling a "sequential access" list in place.

Parameters:
list - the list to be shuffled.
Throws:
UnsupportedOperationException - if the specified list or its list-iterator does not support the set operation.
See Also:
Collections#shuffle(List);

seedlen

public final int seedlen()
Determine default initial seed length used by underlying DRBG algorithm in bytes (not configurable).

Note that seed length value is essential part of PRNG itself depending on its nature.

Returns:
seed length in bytes

outlen

public final int outlen()
Determine PRNG generation cycle - Generation cycle - it is a number of bytes generated between two modifications of working state.

If PRNG is closed in arbitrary moment, the returned number of generated bytes G not less than G >= N * outlen, where N - it is a number of generation cycles done by generate function.

Returns:
PRNG output block value

minlen

public final int minlen()
Determine PRNG minlen - size of minimum pseudorandom bitstring generated per iteration.

Note that minlen value is essential part of PRNG itself depending on its nature.

Returns:
minlen in bytes

period

public final int period()
Determine current PRNG period value n, such as actual period is 2n.

Returns:
period value of specified PRNG