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 2⁴⁸, the default PRNG algorithm in class DefaultRandom has a period of about 2⁶⁴. 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.

See Also:

Serialized Form

Constructor Summary

protected

Random() Construct a new PRNG.

Method Summary

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 Detail

Random

protected Random()

Construct a new PRNG.

Method Detail

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.

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.

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/2⁸.

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/2⁸.

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/2⁸.

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/2⁸.

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/2¹⁶.

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/2¹⁶.

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/2¹⁶.

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/2¹⁶.

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/2¹⁶.

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/2¹⁶.

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/2³².

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/2³².

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/2⁶⁴.

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/2⁶⁴.

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.