Class StaticRandom

java.lang.Object
org.bzdev.math.StaticRandom

public class StaticRandom extends Object
Random-number generator class. Provides a single random number generator for applications as all the methods are static. The methods include ones with the same name and behavior as the public methods of the class java.util.Random and the setSeed methods for java.security.SecureRandom. Additional methods are The two-argument methods that generate Poisson distributions use tables created by the class PoissonTable. The use of these tables, applicable when the parameter λ≤745, will minimize computation time but at the expense of using additional memory. The algorithms used for computing Poisson distributed values are:
  • Table lookup: used for λ≤745 and when a table is available. A table, if not currently cached, is created when λ≤745 and the second argument of a two-argument Poisson method has the value true. The table may be removed by the garbage collector, although the method PoissonTable.add(double) can be used to create a persistent table. This algorithm is basically inverse transform sampling with pre-computed values and a binary search to find the inverse. The limit on λ is set by numerical-accuracy constraints.
  • Inverse transform sampling: used for λ≤18. The inverse is found by computing the CDF for increasing values of k until the value for the CDF is larger than a uniformly distributed random number (computed once).
  • The PTRD algorithm (Wolfgang Hörmann, "The Transformed Rejection Method for Generating Poisson Random Variables," page 6, Virtschaftsuniversität Wien, April 1992, http://epub.wu.ac.at/352/1/document.pdf): used for 18<λ<225.
  • Approximation via a normal distribution: used for λ≥225.
See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    Determine if the current random number generator is a high quality one.
    static void
    Maximize the quality of the random number generator.
    static void
    Minimize the quality of the random number generator.
    static <T> T
    newRandomVariable(Class<T> clasz, Object... args)
    Create a new random variable.
    static boolean
    Generate a boolean with equal odds of returning true or false.
    static void
    nextBytes(byte[] bytes)
    Generates a sequence of random bytes and puts them into an array.
    static double
    Generate a double-precision floating point random number in the range [0.0, 1.0].
    static double
    nextDoubleExpDistr(double mean)
    Generate random numbers with an exponential distribution.
    static double
    nextDoubleExpDistr(double mean, int n)
    Generate a random numbers that are the sum of n exponentially distributed random numbers, each of which has the same mean value.
    static float
    Generate a single-precision floating point random number in the range [0.0, 1.0].
    static double
    Generate a random number with a Gaussian distribution with a mean of 0.0 and a standard deviation of 1.0.
    static int
    Generate uniformly distributed random integer.
    static int
    nextInt(int n)
    Generate uniformly distributed random integer in the range [0,n).
    static long
    Generate uniformly distributed random long integer.
    static long
    nextPoissonIATime(double mean)
    Generate random numbers for interarrival times for Poisson distributed events.
    static long
    nextPoissonIATime(double mean, int n)
    Generate a random numbers that are the sum of n random variables that represent interarrival times for a Poisson process with the same mean interarrival time.
    static long
    poissonCDF(double lambda)
    Generate a long integer with a Poisson distribution
    static double
    poissonDouble(double lambda)
    Generate a random number with a Poisson distribution.
    static double
    poissonDouble(double lambda, boolean mode)
    Generate a random number with a Poisson distribution and optionally using a table for efficiency.
    static int
    poissonInt(double lambda)
    Generate a random integer with a Poisson distribution.
    static int
    poissonInt(double lambda, boolean mode)
    Generate a random integer with a Poisson distribution and optionally using a table for efficiency.
    static long
    poissonLong(double lambda)
    Generate a random long integer with a Poisson distribution.
    static long
    poissonLong(double lambda, boolean mode)
    Generate a random long integer with a Poisson distribution and optionally using a table for efficiency.
    static void
    setSeed(byte[] seed)
    Set the seed using a seed of arbitrary length.
    static void
    setSeed(long seed)
    Set the seed for the random number generator.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • isHighQuality

      public static boolean isHighQuality()
      Determine if the current random number generator is a high quality one.
      Returns:
      true if it is high quality; false otherwise
    • maximizeQuality

      public static void maximizeQuality()
      Maximize the quality of the random number generator. This should normally be called before the random number generator first is used. It will increase the quality of the sequence of random numbers created by using a cryptographically secure random number generator, but will be computationally more expensive.
    • minimizeQuality

      public static void minimizeQuality()
      Minimize the quality of the random number generator. This should normally be called before the random number generator first is used. It will decrease the quality of the sequence of random numbers created by using the default random number generator.
    • nextBytes

      public static void nextBytes(byte[] bytes)
      Generates a sequence of random bytes and puts them into an array.
      Parameters:
      bytes - the array to store the bytes generated
    • nextBoolean

      public static boolean nextBoolean()
      Generate a boolean with equal odds of returning true or false.
      Returns:
      true or false
    • nextDouble

      public static double nextDouble()
      Generate a double-precision floating point random number in the range [0.0, 1.0]. All values in the range have an equal probability of occurring.
      Returns:
      a number in [0.0, 1.0]
    • nextFloat

      public static float nextFloat()
      Generate a single-precision floating point random number in the range [0.0, 1.0]. All values in the range have an equal probability of occurring.
      Returns:
      a number in [0.0, 1.0]
    • nextGaussian

      public static double nextGaussian()
      Generate a random number with a Gaussian distribution with a mean of 0.0 and a standard deviation of 1.0.
      Returns:
      a random number with a Gaussian distribution.
    • nextInt

      public static int nextInt()
      Generate uniformly distributed random integer.
      Returns:
      a random integer
    • nextInt

      public static int nextInt(int n)
      Generate uniformly distributed random integer in the range [0,n).
      Parameters:
      n - the upper bound on the number generated with all generated values below this value
      Returns:
      a random integer in the range [0,n).
    • nextLong

      public static long nextLong()
      Generate uniformly distributed random long integer.
      Returns:
      a random long integer
    • setSeed

      public static void setSeed(long seed)
      Set the seed for the random number generator. Only a subset of possible initial random-number generator states may be possible due to the limited number of bits in a long integer, although that is generally an issue only for cryptographic applications.

      The seed is set for the current random number generator, which may be changed between two implementations when maximizeQuality() or minimizeQuality() is called.

      Parameters:
      seed - the seed
    • setSeed

      public static void setSeed(byte[] seed)
      Set the seed using a seed of arbitrary length. For a for a high-quality random number generator, the seed is used directly by an instance of java.security.SecureRandom. If a low quality random number generator is used, a SHA-1 digest of the seed is computed and the first 8 bytes of the digest are used.

      The seed is set for the current random number generator, which may be changed between two implementations when maximizeQuality() or minimizeQuality() is called.

      Parameters:
      seed - the seed
    • nextPoissonIATime

      public static long nextPoissonIATime(double mean)
      Generate random numbers for interarrival times for Poisson distributed events. Note: the mean is the reciprocal of the rate for the interarrival times for a Poisson distribution, where the probability density for the interarrival times is given by f(x) = λe-λx where &lamba; is the rate.
      Parameters:
      mean - the mean value of the distribution
      Returns:
      a random number that gives the interarrival times for Poisson distributed events
    • nextPoissonIATime

      public static long nextPoissonIATime(double mean, int n)
      Generate a random numbers that are the sum of n random variables that represent interarrival times for a Poisson process with the same mean interarrival time. Note: the mean is the reciprocal of the rate for the interarrival times for a Poisson distribution, where the probability density for the interarrival times is given by f(x) = λe-λx where &lamba; is the rate. This method is provided because it is faster than simply calling nextPoissonIATime() n times and adding up those values.
      Parameters:
      mean - the mean value for the distribution
      n - the number of random variables to sum
      Returns:
      a random number that is the sum of n random variables that have an exponential distribution with the same mean value
    • nextDoubleExpDistr

      public static double nextDoubleExpDistr(double mean)
      Generate random numbers with an exponential distribution. Note: the mean is the reciprocal of the rate for an exponential distribution, where the probability density is given by f(x) = λe-λx where &lamba; is the rate.
      Parameters:
      mean - the mean value for the distribution
      Returns:
      a random number that has an exponential distribution
    • nextDoubleExpDistr

      public static double nextDoubleExpDistr(double mean, int n)
      Generate a random numbers that are the sum of n exponentially distributed random numbers, each of which has the same mean value. This method is provided because it is faster than simply calling nextDoubleExpDistr() n times and adding up those values.
      Parameters:
      mean - the mean value for the distribution
      n - the number of random variables to sum
      Returns:
      a random number that is the sum of n random variables that have an exponential distribution with the same mean value
    • poissonCDF

      public static long poissonCDF(double lambda)
      Generate a long integer with a Poisson distribution
      Parameters:
      lambda - the mean for the distribution
      Returns:
      a random long integer using a Poission distribution
    • poissonInt

      public static int poissonInt(double lambda)
      Generate a random integer with a Poisson distribution.
      Parameters:
      lambda - the mean value of the distribution
      Returns:
      a random number with a Poission distribution
      Throws:
      IllegalArgumentException - an argument was out of range
    • poissonInt

      public static int poissonInt(double lambda, boolean mode)
      Generate a random integer with a Poisson distribution and optionally using a table for efficiency.

      When mode is true, a precomputed table of the cummulative distribution function is used in conjunction with binary search. Due to numerical accuracy issues, this is allowed only when the parameter lambda is less than 644. If lambda is larger than 644, the parameter mode is set to false. A temporary cache of tables for values of the argument lambda is maintained transparently, with entries that are not currently in use removed at the discretion of the Java garbage collector. If a table for a given value of lambda should be persistent, the method PoissonTable.add(double) can be used.

      Parameters:
      lambda - the mean value of the distribution
      mode - true if table should be used to speed up the computation; false otherwise
      Returns:
      a random number with a Poission distribution
      Throws:
      IllegalArgumentException - an argument was out of range
      See Also:
    • poissonLong

      public static long poissonLong(double lambda)
      Generate a random long integer with a Poisson distribution.
      Parameters:
      lambda - the mean value of the distribution
      Returns:
      a random number with a Poission distribution
      Throws:
      IllegalArgumentException - an argument was out of range
    • poissonLong

      public static long poissonLong(double lambda, boolean mode)
      Generate a random long integer with a Poisson distribution and optionally using a table for efficiency.

      When mode is true, a precomputed table of the cummulative distribution function is used in conjunction with binary search. Due to numerical accuracy issues, this is allowed only when the parameter lambda is less than 644. If lambda is larger than 644, the parameter mode is set to false. A temporary cache of tables for values of the argument lambda is maintained transparently, with entries that are not currently in use removed at the discretion of the Java garbage collector. If a table for a given value of lambda should be persistent, the method PoissonTable.add(double) can be used.

      Parameters:
      lambda - the mean value of the distribution
      mode - true if table should be used to speed up the computation; false otherwise
      Returns:
      a random number with a Poission distribution
      Throws:
      IllegalArgumentException - an argument was out of range
      See Also:
    • poissonDouble

      public static double poissonDouble(double lambda)
      Generate a random number with a Poisson distribution. The number returned is a double that (when possible) will be rounded to the nearest long integer and then type casted so that the value returned is a double.
      Parameters:
      lambda - the mean value of the distribution
      Returns:
      a random number with a Poission distribution
      Throws:
      IllegalArgumentException - an argument was out of range
    • poissonDouble

      public static double poissonDouble(double lambda, boolean mode)
      Generate a random number with a Poisson distribution and optionally using a table for efficiency. The number returned is a double that (when possible) will be rounded to the nearest long integer and then type casted so that the value returned is a double.

      When mode is true, a precomputed table of the cummulative distribution function is used in conjunction with binary search. Due to numerical accuracy issues, this is allowed only when the parameter lambda is less than 644. If lambda is larger than 644, the parameter mode is set to false. A temporary cache of tables for values of the argument lambda is maintained transparently, with entries that are not currently in use removed at the discretion of the Java garbage collector. If a table for a given value of lambda should be persistent, the method PoissonTable.add(double) can be used.

      Parameters:
      lambda - the mean value of the distribution
      mode - true if table should be used to speed up the computation; false otherwise
      Returns:
      a random number with a Poission distribution
      Throws:
      IllegalArgumentException - an argument was out of range
      See Also:
    • newRandomVariable

      public static <T> T newRandomVariable(Class<T> clasz, Object... args) throws InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetException
      Create a new random variable.
      Type Parameters:
      T - the type specified by the first argument
      Parameters:
      clasz - the class implementing the random variable (must be a class that implements org.cmdl.math.rv.RandomVariable)
      args - arguments that match a constructor for the class clasz
      Returns:
      a new random variable
      Throws:
      InstantiationException - if a constructor failed
      IllegalAccessException - if this method does not have access to a method or constructor
      IllegalArgumentException - if an argument is not appropriate
      InvocationTargetException - if an exception was wrapped as this exception