Random
edu.rit.util

Class Random

  • All Implemented Interfaces:
    Serializable
    Direct Known Subclasses:
    DefaultRandom, Mcg1Random


    public abstract class Randomextends Objectimplements 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.

    See Also:
    Serialized Form
    • Method Summary

      Methods 
      Modifier and TypeMethod and Description
      static RandomgetInstance(long seed)
      Construct a new PRNG with the given seed using the default algorithm.
      static RandomgetInstance(long seed, String algorithm)
      Construct a new PRNG with the given seed using the given algorithm.
      booleannextBoolean()
      Return the Boolean value from the next pseudorandom value in this PRNG's sequence.
      booleannextBoolean(long skip)
      Return the Boolean value from the pseudorandom value the given number of positions ahead in this PRNG's sequence.
      bytenextByte()
      Return the byte value from the next pseudorandom value in this PRNG's sequence.
      bytenextByte(long skip)
      Return the byte value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
      charnextCharacter()
      Return the character value from the next pseudorandom value in this PRNG's sequence.
      intnextCharacter(long skip)
      Return the character value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
      doublenextDouble()
      Return the double precision floating point value from the next pseudorandom value in this PRNG's sequence.
      doublenextDouble(long skip)
      Return the double precision floating point value from the pseudorandom value the given number of positions ahead in this PRNG's sequence.
      floatnextFloat()
      Return the single precision floating point value from the next pseudorandom value in this PRNG's sequence.
      floatnextFloat(long skip)
      Return the single precision floating point value from the pseudorandom value the given number of positions ahead in this PRNG's sequence.
      intnextInt(int n)
      Return the integer value in the given range from the next pseudorandom value in this PRNG's sequence.
      intnextInt(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.
      intnextInteger()
      Return the integer value from the next pseudorandom value in this PRNG's sequence.
      intnextInteger(long skip)
      Return the integer value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
      longnextLong()
      Return the long value from the next pseudorandom value in this PRNG's sequence.
      longnextLong(long skip)
      Return the long value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
      shortnextShort()
      Return the short value from the next pseudorandom value in this PRNG's sequence.
      shortnextShort(long skip)
      Return the short value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
      intnextUnsignedByte()
      Return the unsigned byte value from the next pseudorandom value in this PRNG's sequence.
      intnextUnsignedByte(long skip)
      Return the unsigned byte value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
      intnextUnsignedShort()
      Return the unsigned short value from the next pseudorandom value in this PRNG's sequence.
      intnextUnsignedShort(long skip)
      Return the unsigned short value from the next pseudorandom value the given number of positions ahead in this PRNG's sequence.
      abstract voidsetSeed(long seed)
      Set this PRNG's seed.
      voidskip()
      Skip one position ahead in this PRNG's sequence.
      voidskip(long skip)
      Skip the given number of positions ahead in this PRNG's sequence.
    • 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/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.

SCaVis 2.0 © jWork.ORG