Class StdRandom

java.lang.Object
gaiasky.util.math.StdRandom

public final class StdRandom extends Object
The StdRandom class provides static methods for generating random number from various discrete and continuous distributions, including Bernoulli, uniform, Gaussian, exponential, pareto, Poisson, and Cauchy. It also provides method for shuffling an array or subarray.

For additional documentation, see Section 2.2 of Introduction to Programming in Java: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne.

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    Returns a random boolean from a Bernoulli distribution with success probability 1/2.
    static boolean
    bernoulli(double p)
    Returns a random boolean from a Bernoulli distribution with success probability p.
    static double
    beta(double alpha, double beta)
    Returns a random real number from a beta distribution with parameters α and β.
    static double
    Returns a random real number from the Cauchy distribution.
    static int
    discrete(double[] probabilities)
    Returns a random integer from the specified discrete distribution.
    static int
    discrete(int[] frequencies)
    Returns a random integer from the specified discrete distribution.
    static double
    exp(double lambda)
    Returns a random real number from an exponential distribution with rate λ.
    static double
    Returns a random real number from a standard Gaussian distribution.
    static double
    gaussian(double mu, double sigma)
    Returns a random real number from a Gaussian distribution with mean μ and standard deviation σ.
    static int
    geometric(double p)
    Returns a random integer from a geometric distribution with success probability p.
    static long
    Returns the seed of the pseudorandom number generator.
    static double
    Returns a random real number from the standard Pareto distribution.
    static double
    pareto(double alpha)
    Returns a random real number from a Pareto distribution with shape parameter α.
    static int
    poisson(double lambda)
    Returns a random integer from a Poisson distribution with mean λ.
    static double
    Deprecated.
    Replaced by uniform().
    static void
    setSeed(long s)
    Sets the seed of the pseudorandom number generator.
    static void
    shuffle(double[] a)
    Rearranges the elements of the specified array in uniformly random order.
    static void
    shuffle(double[] a, int lo, int hi)
    Rearranges the elements of the specified subarray in uniformly random order.
    static void
    shuffle(int[] a)
    Rearranges the elements of the specified array in uniformly random order.
    static void
    shuffle(int[] a, int lo, int hi)
    Rearranges the elements of the specified subarray in uniformly random order.
    static void
    Rearranges the elements of the specified array in uniformly random order.
    static void
    shuffle(Object[] a, int lo, int hi)
    Rearranges the elements of the specified subarray in uniformly random order.
    static double
    Returns a random real number uniformly in [0, 1).
    static double
    uniform(double a, double b)
    Returns a random real number uniformly in [a, b).
    static int
    uniform(int n)
    Returns a random integer uniformly in [0, n).
    static int
    uniform(int a, int b)
    Returns a random integer uniformly in [a, b).

    Methods inherited from class java.lang.Object

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

    • setSeed

      public static void setSeed(long s)
      Sets the seed of the pseudorandom number generator. This method enables you to produce the same sequence of "random" number for each execution of the program. Ordinarily, you should call this method at most once per program.
      Parameters:
      s - the seed
    • getSeed

      public static long getSeed()
      Returns the seed of the pseudorandom number generator.
      Returns:
      the seed
    • uniform

      public static double uniform()
      Returns a random real number uniformly in [0, 1).
      Returns:
      a random real number uniformly in [0, 1)
    • uniform

      public static int uniform(int n)
      Returns a random integer uniformly in [0, n).
      Parameters:
      n - number of possible integers
      Returns:
      a random integer uniformly between 0 (inclusive) and N (exclusive)
      Throws:
      IllegalArgumentException - if n invalid input: '<'= 0
    • random

      @Deprecated public static double random()
      Deprecated.
      Replaced by uniform().
      Returns a random real number uniformly in [0, 1).
      Returns:
      a random real number uniformly in [0, 1)
    • uniform

      public static int uniform(int a, int b)
      Returns a random integer uniformly in [a, b).
      Parameters:
      a - the left endpoint
      b - the right endpoint
      Returns:
      a random integer uniformly in [a, b)
      Throws:
      IllegalArgumentException - if b invalid input: '<'= a
      IllegalArgumentException - if b - a >= Integer.MAX_VALUE
    • uniform

      public static double uniform(double a, double b)
      Returns a random real number uniformly in [a, b).
      Parameters:
      a - the left endpoint
      b - the right endpoint
      Returns:
      a random real number uniformly in [a, b)
      Throws:
      IllegalArgumentException - unless a invalid input: '<' b
    • bernoulli

      public static boolean bernoulli(double p)
      Returns a random boolean from a Bernoulli distribution with success probability p.
      Parameters:
      p - the probability of returning true
      Returns:
      true with probability p and false with probability p
      Throws:
      IllegalArgumentException - unless p >= 0.0 and p invalid input: '<'= 1.0
    • bernoulli

      public static boolean bernoulli()
      Returns a random boolean from a Bernoulli distribution with success probability 1/2.
      Returns:
      true with probability 1/2 and false with probability 1/2
    • gaussian

      public static double gaussian()
      Returns a random real number from a standard Gaussian distribution.
      Returns:
      a random real number from a standard Gaussian distribution (mean 0 and standard deviation 1).
    • gaussian

      public static double gaussian(double mu, double sigma)
      Returns a random real number from a Gaussian distribution with mean μ and standard deviation σ.
      Parameters:
      mu - the mean
      sigma - the standard deviation
      Returns:
      a real number distributed according to the Gaussian distribution with mean mu and standard deviation sigma
    • geometric

      public static int geometric(double p)
      Returns a random integer from a geometric distribution with success probability p.
      Parameters:
      p - the parameter of the geometric distribution
      Returns:
      a random integer from a geometric distribution with success probability p; or Integer.MAX_VALUE if p is (nearly) equal to 1.0.
      Throws:
      IllegalArgumentException - unless p >= 0.0 and p invalid input: '<'= 1.0
    • poisson

      public static int poisson(double lambda)
      Returns a random integer from a Poisson distribution with mean λ.
      Parameters:
      lambda - the mean of the Poisson distribution
      Returns:
      a random integer from a Poisson distribution with mean lambda
      Throws:
      IllegalArgumentException - unless lambda > 0.0 and not infinite
    • pareto

      public static double pareto()
      Returns a random real number from the standard Pareto distribution.
      Returns:
      a random real number from the standard Pareto distribution
    • pareto

      public static double pareto(double alpha)
      Returns a random real number from a Pareto distribution with shape parameter α.
      Parameters:
      alpha - shape parameter
      Returns:
      a random real number from a Pareto distribution with shape parameter alpha
      Throws:
      IllegalArgumentException - unless alpha > 0.0
    • cauchy

      public static double cauchy()
      Returns a random real number from the Cauchy distribution.
      Returns:
      a random real number from the Cauchy distribution.
    • discrete

      public static int discrete(double[] probabilities)
      Returns a random integer from the specified discrete distribution.
      Parameters:
      probabilities - the probability of occurrence of each integer
      Returns:
      a random integer from a discrete distribution: i with probability probabilities[i]
      Throws:
      NullPointerException - if probabilities is null
      IllegalArgumentException - if sum of array entries is not (very nearly) equal to 1.0
      IllegalArgumentException - unless probabilities[i] >= 0.0 for each index i
    • discrete

      public static int discrete(int[] frequencies)
      Returns a random integer from the specified discrete distribution.
      Parameters:
      frequencies - the frequency of occurrence of each integer
      Returns:
      a random integer from a discrete distribution: i with probability proportional to frequencies[i]
      Throws:
      NullPointerException - if frequencies is null
      IllegalArgumentException - if all array entries are 0
      IllegalArgumentException - if frequencies[i] is negative for any index i
      IllegalArgumentException - if sum of frequencies exceeds Integer.MAX_VALUE (231 - 1)
    • exp

      public static double exp(double lambda)
      Returns a random real number from an exponential distribution with rate λ.
      Parameters:
      lambda - the rate of the exponential distribution
      Returns:
      a random real number from an exponential distribution with rate lambda
      Throws:
      IllegalArgumentException - unless lambda > 0.0
    • beta

      public static double beta(double alpha, double beta)
      Returns a random real number from a beta distribution with parameters α and β. The result is normalized in [-1,1]
      Parameters:
      alpha - the shape parameter α
      beta - the shape parameter β
      Returns:
      a random real number from a beta distribution normalized in [-1,1]
      Throws:
      IllegalArgumentException - unless alpha, beta > 0.0
    • shuffle

      public static void shuffle(Object[] a)
      Rearranges the elements of the specified array in uniformly random order.
      Parameters:
      a - the array to shuffle
      Throws:
      NullPointerException - if a is null
    • shuffle

      public static void shuffle(double[] a)
      Rearranges the elements of the specified array in uniformly random order.
      Parameters:
      a - the array to shuffle
      Throws:
      NullPointerException - if a is null
    • shuffle

      public static void shuffle(int[] a)
      Rearranges the elements of the specified array in uniformly random order.
      Parameters:
      a - the array to shuffle
      Throws:
      NullPointerException - if a is null
    • shuffle

      public static void shuffle(Object[] a, int lo, int hi)
      Rearranges the elements of the specified subarray in uniformly random order.
      Parameters:
      a - the array to shuffle
      lo - the left endpoint (inclusive)
      hi - the right endpoint (inclusive)
      Throws:
      NullPointerException - if a is null
      IndexOutOfBoundsException - unless (0 invalid input: '<'= lo) invalid input: '&'invalid input: '&' (lo invalid input: '<'= hi) invalid input: '&'invalid input: '&' (hi invalid input: '<' a.length)
    • shuffle

      public static void shuffle(double[] a, int lo, int hi)
      Rearranges the elements of the specified subarray in uniformly random order.
      Parameters:
      a - the array to shuffle
      lo - the left endpoint (inclusive)
      hi - the right endpoint (inclusive)
      Throws:
      NullPointerException - if a is null
      IndexOutOfBoundsException - unless (0 invalid input: '<'= lo) invalid input: '&'invalid input: '&' (lo invalid input: '<'= hi) invalid input: '&'invalid input: '&' (hi invalid input: '<' a.length)
    • shuffle

      public static void shuffle(int[] a, int lo, int hi)
      Rearranges the elements of the specified subarray in uniformly random order.
      Parameters:
      a - the array to shuffle
      lo - the left endpoint (inclusive)
      hi - the right endpoint (inclusive)
      Throws:
      NullPointerException - if a is null
      IndexOutOfBoundsException - unless (0 invalid input: '<'= lo) invalid input: '&'invalid input: '&' (lo invalid input: '<'= hi) invalid input: '&'invalid input: '&' (hi invalid input: '<' a.length)