Package org.evoludo.math

Class RNGDistribution

Object
RNGDistribution
Direct Known Subclasses:
RNGDistribution.Binomial, RNGDistribution.Exponential, RNGDistribution.Geometric, RNGDistribution.Gillespie, RNGDistribution.Normal, RNGDistribution.Uniform
public abstract class RNGDistribution extends Object
Collection of distributions of random numbers based on the Mersenne Twister.

Currently available random number distributions:

Uniform:
Uniformly distributed random numbers with support [min, max).
Exponential:
Exponentially distributed random numbers with support [0.0, Double.MAX_VALUE)
Normal:
Normally (or Gaussian) distributed random numbers with support (-Double.MAX_VALUE, Double.MAX_VALUE).
Geometric:
Geometrically distributed random numbers with support {1,2,3,...}.
Binomial:
Binomially distributed random numbers with support {0,1,2,3,...}.

Note: in order to permit 100% reproducible results it is essential that all models must share a single instance of the random number generator (RNG). By the same token, GUI methods that require random numbers (e.g. for laying out networks) must use a different instance of the RNG. If an initial seed was set for the models' RNG then it is recommended that a reproducible seed (the same seed) is also set for the RNG used by the GUI. This ensures that e.g. identical layouts can be re-generated while not interfering with the model calculations.

Author:
Christoph Hauert
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    RNGDistribution.Binomial
    Binomially distributed random numbers with support {0,1,2,3,..., n}.
    static class 
    RNGDistribution.Exponential
    Exponentially distributed random numbers with support [0.0, Double.MAX_VALUE).
    static class 
    RNGDistribution.Geometric
    Geometrically distributed random numbers with support {1,2,3,...}.
    static class 
    RNGDistribution.Gillespie
    Gillespie algorithm for selecting integers with support {0,1,2,3,..., n} but with different weights.
    static class 
    RNGDistribution.Normal
    Normally (or Gaussian) distributed random numbers with support (-Double.MAX_VALUE, Double.MAX_VALUE).
    static interface 
    RNGDistribution.TestCommand
    The interface to execute commands in a manner that is agnostic to the implementation details regarding GWT or JRE environments.
    static class 
    RNGDistribution.Uniform
    Uniformly distributed random numbers with support [min, max).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected MersenneTwister
    rng
    Reference to the MersenneTwister that supplies the random numbers for the different distributions.
    protected long
    seed
    Seed for random number generator.
    protected boolean
    seedSet
    true if seed was set.
    protected int
    testSamples
    number of samples for tests.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    RNGDistribution(MersenneTwister rng)
    Create new random number distribution using rng as the random number generator.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clearRNGSeed()
    Clear seed for random number generator.
    abstract RNGDistribution
    clone()
    Clone this RNGDistribution to ensure both objects return identical sequences of random numbers.
    protected void
    clone(RNGDistribution clone)
    Copy settings of this to clone.
    MersenneTwister
    getRNG()
    Get random number generator of this distribution.
    long
    getRNGSeed()
    Retrieve seed of random number generator in [0, 233-1].
    boolean
    isRNGSeedSet()
    Check if seed of random number generator has been set.
    boolean
    nextBoolean()
    Uniformly distributed random boolean.
    byte
    nextByte()
    Uniformly distributed random byte in [0, Byte.MAX_VALUE).
    void
    nextBytes(byte[] bytes)
    Fill byte array bytes with uniformly distributed random bytes in [0, Byte.MAX_VALUE).
    double
    nextDouble()
    Uniformly distributed random number from interval [0, 1) with regular precision (based on 31bit random integer).
    double
    nextGaussian()
    Gaussian distributed random number with mean 0 and variance 1 (standard Normal distribution).
    int
    nextInt()
    Uniformly distributed random integer in [0, Integer.MAX_VALUE).
    int
    nextInt(int n)
    Uniformly distributed random integer in [0, n).
    double
    random01()
    Uniformly distributed random number from interval [0, 1) with regular precision (based on 31bit random integer).
    double
    random01d()
    Uniformly distributed random number from interval [0, 1) with high precision (based on 53bit random integer).
    int
    random0n(int n)
    Uniformly distributed integer random number from interval [0, n).
    int
    random0N(int n)
    Uniformly distributed integer random number from interval [0, n].
    void
    setRNG(MersenneTwister rng)
    Set custom random number generator rng of this distribution.
    void
    setRNGSeed()
    Pass seed to random number generator.
    void
    setRNGSeed(long seed)
    Set seed of random number generator to seed.

    Methods inherited from class Object

    equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • rng

      protected MersenneTwister rng
      Reference to the MersenneTwister that supplies the random numbers for the different distributions.

    • seed

      protected long seed
      Seed for random number generator.

    • seedSet

      protected boolean seedSet
      true if seed was set.

    • testSamples

      protected int testSamples
      number of samples for tests.

  • Constructor Details

    • RNGDistribution

      protected RNGDistribution(MersenneTwister rng)
      Create new random number distribution using rng as the random number generator. If rng==null a new instance of the MersenneTwister random number generator is assigned to distribution.

      Protected default constructor to ensure non-instantiability.

      Parameters:
      rng - random number generator

  • Method Details

    • setRNG

      public void setRNG(MersenneTwister rng)
      Set custom random number generator rng of this distribution.
      Parameters:
      rng - random number generator

    • getRNG

      public MersenneTwister getRNG()
      Get random number generator of this distribution.
      Returns:
      random number generator of distribution

    • random01

      public double random01()
      Uniformly distributed random number from interval [0, 1) with regular precision (based on 31bit random integer).
      Returns:
      random number in [0, 1)
      See Also:

    • random01d

      public double random01d()
      Uniformly distributed random number from interval [0, 1) with high precision (based on 53bit random integer).
      Returns:
      high precision random number in [0, 1)
      See Also:

    • random0N

      public int random0N(int n)
      Uniformly distributed integer random number from interval [0, n].
      Parameters:
      n - upper bound (inclusive)
      Returns:
      random integer in [0, n]
      See Also:

    • random0n

      public int random0n(int n)
      Uniformly distributed integer random number from interval [0, n).
      Parameters:
      n - integer upper bound (exclusive)
      Returns:
      random integer in [0, n)
      See Also:

    • nextInt

      public int nextInt()
      Uniformly distributed random integer in [0, Integer.MAX_VALUE).

      Note: compatibility method with Random.

      Returns:
      random integer in [0, Integer.MAX_VALUE)
      See Also:

    • nextInt

      public int nextInt(int n)
      Uniformly distributed random integer in [0, n).

      Note: compatibility method with Random.

      Parameters:
      n - integer upper bound (exclusive)
      Returns:
      random integer in [0, n)
      See Also:

    • nextByte

      public byte nextByte()
      Uniformly distributed random byte in [0, Byte.MAX_VALUE).

      Note: compatibility method with Random.

      Returns:
      random byte in [0, 127]
      See Also:

    • nextBytes

      public void nextBytes(byte[] bytes)
      Fill byte array bytes with uniformly distributed random bytes in [0, Byte.MAX_VALUE).

      Note: compatibility method with Random.

      Parameters:
      bytes - array to fill with uniformly distributed random bytes in [0, 127]
      See Also:

    • nextBoolean

      public boolean nextBoolean()
      Uniformly distributed random boolean.

      Note: compatibility method with Random.

      Returns:
      true with probability 0.5
      See Also:

    • nextDouble

      public double nextDouble()
      Uniformly distributed random number from interval [0, 1) with regular precision (based on 31bit random integer).
      Returns:
      random number in [0, 1)
      See Also:

    • nextGaussian

      public double nextGaussian()
      Gaussian distributed random number with mean 0 and variance 1 (standard Normal distribution). with regular precision (based on 31bit random integer).
      Returns:
      random number in [0, 1)
      See Also:

    • setRNGSeed

      public void setRNGSeed(long seed)
      Set seed of random number generator to seed. Since MersenneTwister only uses lower 32bits of long, seed is truncated accordingly to fall in interval [0, 233-1].
      Parameters:
      seed - for random number generator
      See Also:

    • setRNGSeed

      public void setRNGSeed()
      Pass seed to random number generator.
      See Also:

    • getRNGSeed

      public long getRNGSeed()
      Retrieve seed of random number generator in [0, 233-1]. If no seed has been set, return -1L.
      Returns:
      seed of random number generator or -1L if seed has not been set

    • clearRNGSeed

      public void clearRNGSeed()
      Clear seed for random number generator.

    • isRNGSeedSet

      public boolean isRNGSeedSet()
      Check if seed of random number generator has been set.
      Returns:
      true if seed set

    • clone

      public abstract RNGDistribution clone()
      Clone this RNGDistribution to ensure both objects return identical sequences of random numbers.

      IMPORTANT:

      1. overrides clone() in Object but conflicts with GWT's aversion to clone()ing...
      2. remove @SuppressWarnings("all") to ensure that no other issues crept in when modifying method.
      Overrides:
      clone in class Object
      Returns:
      clone of RNGDistribution

    • clone

      protected void clone(RNGDistribution clone)
      Copy settings of this to clone.
      Parameters:
      clone - cloned RNGDistribution