Package stdlib

Class StdRandom

java.lang.Object
stdlib.StdRandom
public final class StdRandom extends Object
This class provides static methods for generating random number from various discrete and continuous distributions, including uniform, Binomial, Bernoulli, geometric, Gaussian, exponential, Pareto, Poisson, and Cauchy. It also provides method for shuffling an array or subarray and generating random permutations.

By convention, all intervals are half open. For example, uniform(-1.0, 1.0) returns a random number between -1.0 (inclusive) and 1.0 (exclusive). Similarly, shuffle(a, lo, hi) shuffles the hi - lo elements in the array a[], starting at index lo (inclusive) and ending at index hi (exclusive).

For additional documentation, see Section 2.2 of Computer Science: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne.

Author:
Robert Sedgewick, Kevin Wayne

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    bernoulli()
    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 int
    binomial(int n, double p)
    Flips a coin with bias p a total of n times and returns the number of heads obtained.
    static double
    cauchy()
    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
    gaussian()
    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
    getSeed()
    Returns the seed of the pseudo-random number generator.
    static void
    main(String[] args)
    Unit tests the methods in this class.
    static double
    pareto()
    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[]
    permutation(int n)
    Returns a uniformly random permutation of n elements.
    static int[]
    permutation(int n, int k)
    Returns a uniformly random permutation of k of n elements.
    static int
    poisson(double lambda)
    Returns a random integer from a Poisson distribution with mean λ.
    static void
    setSeed(long s)
    Sets the seed of the pseudo-random 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
    shuffle(Object[] a)
    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
    uniform()
    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).
    static long
    uniform(long n)
    Returns a random long integer uniformly in [0, n).

    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 pseudo-random 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 pseudo-random 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 <= 0

    • uniform

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

    • 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 <= 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 < b

    • binomial

      public static int binomial(int n, double p)
      Flips a coin with bias p a total of n times and returns the number of heads obtained.
      Parameters:
      n - number of coin flips
      p - bias
      Returns:
      number of heads obtained

    • 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 1 - p
      Throws:
      IllegalArgumentException - unless 0 ≤ p ≤ 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. The integer represents the number of independent trials before the first success.
      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 <= 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:
      IllegalArgumentException - 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:
      IllegalArgumentException - 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

    • 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:
      IllegalArgumentException - 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:
      IllegalArgumentException - 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:
      IllegalArgumentException - 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 (exclusive)
      Throws:
      IllegalArgumentException - if a is null
      IllegalArgumentException - unless (0 <= lo) && (lo < hi) && (hi <= 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 (exclusive)
      Throws:
      IllegalArgumentException - if a is null
      IllegalArgumentException - unless (0 <= lo) && (lo < hi) && (hi <= 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 (exclusive)
      Throws:
      IllegalArgumentException - if a is null
      IllegalArgumentException - unless (0 <= lo) && (lo < hi) && (hi <= a.length)

    • permutation

      public static int[] permutation(int n)
      Returns a uniformly random permutation of n elements.
      Parameters:
      n - number of elements
      Returns:
      an array of length n that is a uniformly random permutation of 0, 1, ..., n-1
      Throws:
      IllegalArgumentException - if n is negative

    • permutation

      public static int[] permutation(int n, int k)
      Returns a uniformly random permutation of k of n elements.
      Parameters:
      n - number of elements
      k - number of elements to select
      Returns:
      an array of length k that is a uniformly random permutation of k of the elements from 0, 1, ..., n-1
      Throws:
      IllegalArgumentException - if n is negative
      IllegalArgumentException - unless 0 <= k <= n

    • main

      public static void main(String[] args)
      Unit tests the methods in this class.
      Parameters:
      args - the command-line arguments