Package edu.rit.util

Class Random

java.lang.Object
edu.rit.util.Random
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
DefaultRandom, Mcg1Random
public abstract class Random extends Object implements Serializable
Class Random is the abstract base class for a pseudorandom number generator (PRNG) designed for use in parallel scientific programming. It differs from class java.util.Random in the following ways:
  • Instances can be created by calling a static factory method. The factory method can take the name of a subclass as an argument and return an instance of that subclass of class Random. This makes it easier to write a program that can substitute a different PRNG algorithm at run time. Class DefaultRandom provides a default PRNG algorithm.
     
  • Whereas class java.util.Random generates 48-bit numbers under the hood, class Random generates 64-bit numbers. This makes class Random faster than class java.util.Random for some operations, notably the nextDouble() method.
     
  • Whereas the PRNG algorithm in class java.util.Random has a period of about 248, the default PRNG algorithm in class DefaultRandom has a period of about 264. This lets a parallel program scale up to larger problem sizes without exhausting the PRNG's period.
     
  • To support the leapfrogging and sequence splitting techniques for generating pseudorandom numbers in multiple parallel threads or processes, class Random includes methods for skipping ahead in the sequence of generated numbers, without having to generate all the intermediate numbers.
     
  • To avoid unnecessary thread synchronization overhead, class Random is not multiple thread safe. It assumes that the surrounding program ensures that only one thread at a time calls methods on an instance.

Each method for generating a number comes in two versions; for example: 

     public double nextDouble();
     public double nextDouble (long skip);
Calling the second version with an argument skip is equivalent to calling the first version skip times: 
     Random prng1 = Random.getInstance (1234L);
     double x = prng1.nextDouble (1000);
     Random prng2 = Random.getInstance (1234L);
     double y;
     for (int i = 0; i < 1000; ++ i)
         y = prng2.nextDouble();
At the end of the above code fragment, x and y will have the same value. However, calling nextDouble(1000) will typically be much faster than calling nextDouble() 1000 times. Conversely, nextDouble(1) is equivalent to nextDouble(), but the former will typically be slower than the latter.

An instance of class Random can be serialized; for example, to checkpoint the state of the PRNG into a file and restore its state later.

The design of class Random is inspired in part by Coddington's JAPARA library. For further information, see P. Coddington and A. Newell, JAPARA -- A Java random number generator library for high-performance computing, in Proceedings of the 18th IEEE International Parallel and Distributed Processing Symposium (IPDPS'04), April 26-30, 2004, page 156.

Version:
17-Aug-2009
Author:
Alan Kaminsky
See Also:

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Random()
    Construct a new PRNG.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Random
    getInstance(long seed)
    Construct a new PRNG with the given seed using the default algorithm.
    static Random
    getInstance(long seed, String algorithm)
    Construct a new PRNG with the given seed using the given algorithm.
    protected abstract long
    next()
    Return the next 64-bit pseudorandom value in this PRNG's sequence.
    protected abstract long
    next(long skip)
    Return the 64-bit pseudorandom value the given number of positions ahead in this PRNG's sequence.
    boolean
    nextBoolean()
    Return the Boolean value from the next pseudorandom value in this PRNG's sequence.
    boolean
    nextBoolean(long skip)
    Return the Boolean value from the pseudorandom value the given number of positions ahead in this PRNG's sequence.
    byte
    nextByte()
    Return the byte value from the next pseudorandom value in this PRNG's sequence.
    byte
    nextByte(long skip)
    Return the byte value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
    char
    nextCharacter()
    Return the character value from the next pseudorandom value in this PRNG's sequence.
    int
    nextCharacter(long skip)
    Return the character value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
    double
    nextDouble()
    Return the double precision floating point value from the next pseudorandom value in this PRNG's sequence.
    double
    nextDouble(long skip)
    Return the double precision floating point value from the pseudorandom value the given number of positions ahead in this PRNG's sequence.
    float
    nextFloat()
    Return the single precision floating point value from the next pseudorandom value in this PRNG's sequence.
    float
    nextFloat(long skip)
    Return the single precision floating point value from the pseudorandom value the given number of positions ahead in this PRNG's sequence.
    int
    nextInt(int n)
    Return the integer value in the given range from the next pseudorandom value in this PRNG's sequence.
    int
    nextInt(int n, long skip)
    Return the integer value in the given range from the pseudorandom value the given number of positions ahead in this PRNG's sequence.
    int
    nextInteger()
    Return the integer value from the next pseudorandom value in this PRNG's sequence.
    int
    nextInteger(long skip)
    Return the integer value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
    long
    nextLong()
    Return the long value from the next pseudorandom value in this PRNG's sequence.
    long
    nextLong(long skip)
    Return the long value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
    short
    nextShort()
    Return the short value from the next pseudorandom value in this PRNG's sequence.
    short
    nextShort(long skip)
    Return the short value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
    int
    nextUnsignedByte()
    Return the unsigned byte value from the next pseudorandom value in this PRNG's sequence.
    int
    nextUnsignedByte(long skip)
    Return the unsigned byte value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
    int
    nextUnsignedShort()
    Return the unsigned short value from the next pseudorandom value in this PRNG's sequence.
    int
    nextUnsignedShort(long skip)
    Return the unsigned short value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
    abstract void
    setSeed(long seed)
    Set this PRNG's seed.
    void
    skip()
    Skip one position ahead in this PRNG's sequence.
    void
    skip(long skip)
    Skip the given number of positions ahead in this PRNG's sequence.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Random

      protected Random()
      Construct a new PRNG.

  • Method Details

    • getInstance

      public static Random getInstance(long seed)
      Construct a new PRNG with the given seed using the default algorithm.

      If the "pj.prng" Java system property is specified, it gives the fully-qualified class name of the default PRNG class that the getInstance() method will construct. Specifying the "pj.prng" property will substitute a different PRNG algorithm into a program without needing to recompile.

      If the "pj.prng" Java system property is not specified, the getInstance() method will return an instance of class DefaultRandom.

      You can specify the "pj.prng" property on the Java command line like this:     java -Dpj.prng=MyOwnPrngClass . . .

      Note: Depending on the PRNG algorithm, certain seed values may not be allowed. See the PRNG algorithm subclass for further information.

      Parameters:
      seed - Seed.
      Returns:
      a Random object.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if the PRNG algorithm does not allow the given seed value.
      TypeNotPresentException - (unchecked exception) Thrown if a PRNG instance could not be constructed. The chained exception gives further information about the problem.

    • getInstance

      public static Random getInstance(long seed, String algorithm)
      Construct a new PRNG with the given seed using the given algorithm.

      Note: Depending on the PRNG algorithm, certain seed values may not be allowed. See the PRNG algorithm subclass for further information.

      Parameters:
      seed - Seed.
      algorithm - Fully-qualified name of the class to construct. This must be a subclass of class Random.
      Returns:
      a Random object.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if the PRNG algorithm does not allow the given seed value.
      TypeNotPresentException - (unchecked exception) Thrown if a PRNG instance could not be constructed. The chained exception gives further information about the problem.

    • setSeed

      public abstract void setSeed(long seed)
      Set this PRNG's seed.

      Note: Depending on the PRNG algorithm, certain seed values may not be allowed. See the PRNG algorithm subclass for further information.

      Parameters:
      seed - Seed.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if the PRNG algorithm does not allow the given seed value.

    • skip

      public void skip()
      Skip one position ahead in this PRNG's sequence.

    • skip

      public void skip(long skip)
      Skip the given number of positions ahead in this PRNG's sequence. If skip <= 0, the skip() method does nothing.
      Parameters:
      skip - Number of positions to skip.

    • nextBoolean

      public boolean nextBoolean()
      Return the Boolean value from the next pseudorandom value in this PRNG's sequence. With a probability of 0.5 true is returned, with a probability of 0.5 false is returned.
      Returns:
      Boolean value.

    • nextBoolean

      public boolean nextBoolean(long skip)
      Return the Boolean value from the pseudorandom value the given number of positions ahead in this PRNG's sequence. With a probability of 0.5 true is returned, with a probability of 0.5 false is returned.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Boolean value.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextByte

      public byte nextByte()
      Return the byte value from the next pseudorandom value in this PRNG's sequence. Each value in the range −128 through 127 is returned with a probability of 1/28.
      Returns:
      Byte value in the range −128 through 127 inclusive.

    • nextByte

      public byte nextByte(long skip)
      Return the byte value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range −128 through 127 is returned with a probability of 1/28.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Byte value in the range −128 through 127 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextUnsignedByte

      public int nextUnsignedByte()
      Return the unsigned byte value from the next pseudorandom value in this PRNG's sequence. Each value in the range 0 through 255 is returned with a probability of 1/28.
      Returns:
      Unsigned byte value (as an int) in the range 0 through 255 inclusive.

    • nextUnsignedByte

      public int nextUnsignedByte(long skip)
      Return the unsigned byte value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range 0 through 255 is returned with a probability of 1/28.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Unsigned byte value (as an int) in the range 0 through 255 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextCharacter

      public char nextCharacter()
      Return the character value from the next pseudorandom value in this PRNG's sequence. Each value in the range '\u0000' through '\uFFFF' is returned with a probability of 1/216.
      Returns:
      Character value in the range '\u0000' through '\uFFFF' inclusive.

    • nextCharacter

      public int nextCharacter(long skip)
      Return the character value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range '\u0000' through '\uFFFF' is returned with a probability of 1/216.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Character value in the range '\u0000' through '\uFFFF' inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextShort

      public short nextShort()
      Return the short value from the next pseudorandom value in this PRNG's sequence. Each value in the range −32768 through 32767 is returned with a probability of 1/216.
      Returns:
      Short value in the range −32768 through 32767 inclusive.

    • nextShort

      public short nextShort(long skip)
      Return the short value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range −32768 through 32767 is returned with a probability of 1/216.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Short value in the range −32768 through 32767 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextUnsignedShort

      public int nextUnsignedShort()
      Return the unsigned short value from the next pseudorandom value in this PRNG's sequence. Each value in the range 0 through 65535 is returned with a probability of 1/216.
      Returns:
      Unsigned short value (as an int) in the range 0 through 65535 inclusive.

    • nextUnsignedShort

      public int nextUnsignedShort(long skip)
      Return the unsigned short value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range 0 through 65535 is returned with a probability of 1/216.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Unsigned short value (as an int) in the range 0 through 65535 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextInteger

      public int nextInteger()
      Return the integer value from the next pseudorandom value in this PRNG's sequence. Each value in the range −2147483648 through 2147483647 is returned with a probability of 1/232.
      Returns:
      Integer value in the range −2147483648 through 2147483647 inclusive.

    • nextInteger

      public int nextInteger(long skip)
      Return the integer value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range −2147483648 through 2147483647 is returned with a probability of 1/232.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Integer value in the range −2147483648 through 2147483647 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextInt

      public int nextInt(int n)
      Return the integer value in the given range from the next pseudorandom value in this PRNG's sequence. Each value in the range 0 through N−1 is returned with a probability of 1/N.
      Parameters:
      n - Range of values to return.
      Returns:
      Integer value in the range 0 through N−1 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if N <= 0.

    • nextInt

      public int nextInt(int n, long skip)
      Return the integer value in the given range from the pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range 0 through N−1 is returned with a probability of 1/N.
      Parameters:
      n - Range of values to return.
      skip - Number of positions to skip.
      Returns:
      Integer value in the range 0 through N−1 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if N <= 0. Thrown if skip <= 0.

    • nextLong

      public long nextLong()
      Return the long value from the next pseudorandom value in this PRNG's sequence. Each value in the range −9223372036854775808 through 9223372036854775807 is returned with a probability of 1/264.
      Returns:
      Long value in the range −9223372036854775808 through 9223372036854775807 inclusive.

    • nextLong

      public long nextLong(long skip)
      Return the long value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence. Each value in the range −9223372036854775808 through 9223372036854775807 is returned with a probability of 1/264.
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Long value in the range −9223372036854775808 through 9223372036854775807 inclusive.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextFloat

      public float nextFloat()
      Return the single precision floating point value from the next pseudorandom value in this PRNG's sequence. The returned numbers have a uniform distribution in the range 0.0 (inclusive) to 1.0 (exclusive).
      Returns:
      Float value.

    • nextFloat

      public float nextFloat(long skip)
      Return the single precision floating point value from the pseudorandom value the given number of positions ahead in this PRNG's sequence. The returned numbers have a uniform distribution in the range 0.0 (inclusive) to 1.0 (exclusive).
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Float value.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • nextDouble

      public double nextDouble()
      Return the double precision floating point value from the next pseudorandom value in this PRNG's sequence. The returned numbers have a uniform distribution in the range 0.0 (inclusive) to 1.0 (exclusive).
      Returns:
      Double value.

    • nextDouble

      public double nextDouble(long skip)
      Return the double precision floating point value from the pseudorandom value the given number of positions ahead in this PRNG's sequence. The returned numbers have a uniform distribution in the range 0.0 (inclusive) to 1.0 (exclusive).
      Parameters:
      skip - Number of positions to skip.
      Returns:
      Double value.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if skip <= 0.

    • next

      protected abstract long next()
      Return the next 64-bit pseudorandom value in this PRNG's sequence.
      Returns:
      Pseudorandom value.

    • next

      protected abstract long next(long skip)
      Return the 64-bit pseudorandom value the given number of positions ahead in this PRNG's sequence.
      Parameters:
      skip - Number of positions to skip, assumed to be > 0.
      Returns:
      Pseudorandom value.