Package com.github.kilianB.pcg.fast

Class PcgRSFast

  • All Implemented Interfaces:
    Pcg, java.io.Serializable
    public class PcgRSFast
extends java.util.Random
implements Pcg
    A 64 bit State PcgRNG with 32 bit output. PCG-XSH-RR

    The pcg family combines a linear congruential generators with a permutation output function resulting in high quality pseudo random numbers.

    The original concept was introduced by Melissa O’Neill please refer to pcg-random for more information.

    Opposed to RR this version performs a random shift rather than a random rotation. The RS instance permutates the output using the following function: 

     
 ((state >>> 22) ^ state) >>> ((state >>> 61) + 22)
    This implementation is Not thread safe, inlines most methods manually and performs other optimizations to maximize the throughput. While the basic methods to retrieve datatypes are implemented no guarantee is made regarding the stream and splitterator methods provided by the Random class. Additional tests have to be performed if they impact the internal state of this class in a harmful way.
    Author:
    Kilian
    See Also:
    www.pcg-random.org, Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected long inc
      Stream number of the rng.
      protected long state
      64 bit internal state

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        PcgRSFast()
      Create a PcgRSFast instance seeded with with 2 longs generated by xorshift*.
        PcgRSFast​(long seed, long streamNumber)
      Create a random number generator with the given seed and stream number.
      protected PcgRSFast​(long initialState, long increment, boolean dummy)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void advance​(long steps)
      Advance or set back the rngs state.
      long getInc()
      Returns the internal increment of the congurential generator used by this pcg
      long getMult()
      Returns the internal multiplication of the congurential generator used by this pcg
      protected static long getRandomSeed()  
      long getState()
      Returns the internal state of the congruential generator used by this pcg
      boolean isFast()
      Return true if this rng is a fast instance.
      int next​(int n)
      Returns an integer with the next n low bits randomly set and are used as a base to deviate smaller data types.
      boolean nextBoolean()
      Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence.
      boolean nextBoolean​(double probability)
      Returns the next pseudorandom boolean value from this random number generator's sequence with the given probability of being true.
      byte nextByte()
      Returns the next pseudorandom, uniformly distributed byte value from this random number generator's sequence.
      void nextBytes​(byte[] b)
      Generates random bytes and places them into a user-supplied byte array.
      char nextChar()
      Returns the next pseudorandom, uniformly distributed char value from this random number generator's sequence.
      double nextDouble()
      Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.
      double nextDouble​(boolean includeZero, boolean includeOne)
      Returns the next pseudorandom, uniformly distributed double value in the range from 0.0 to 1.0, possibly inclusive of 0.0 and 1.0 themselves.
      float nextFloat()
      Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence.
      float nextFloat​(boolean includeZero, boolean includeOne)
      Returns the next pseudorandom, uniformly distributed float valuet in the range from 0.0f to 1.0f, possibly inclusive of 0.0f and 1.0f themselves.
      double nextGaussian()  
      int nextInt()
      Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence.
      int nextInt​(int n)
      Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.
      long nextLong()
      Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence.
      long nextLong​(long n)
      Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence.
      short nextShort()
      Returns the next pseudorandom, uniformly distributed short value from this random number generator's sequence.
      protected void setInc​(long increment)  
      void setSeed​(long seed, long streamNumber)
      Sets the seed of this random number generator using .
      protected void setState​(long state)  
      <T> T split()
      Splits the generator in a copy with the exact same state and stream number.
      <T> T splitDistinct()
      Splits the generator in a copy with distinct state and stream number.

      • Methods inherited from class java.util.Random

        doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, setSeed

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • state

        protected long state
        64 bit internal state

      • inc

        protected long inc
        Stream number of the rng.

    • Constructor Detail

      • PcgRSFast

        public PcgRSFast()
        Create a PcgRSFast instance seeded with with 2 longs generated by xorshift*. The values chosen are very likely not used as seeds in any other non argument constructor of any of the classes provided in this library.

      • PcgRSFast

        public PcgRSFast​(long seed,
                 long streamNumber)
        Create a random number generator with the given seed and stream number. The seed defines the current state in which the rng is in and corresponds to seeds usually found in other RNG instances. RNGs with different seeds are able to catch up after they exhaust their period and produce the same numbers. (2^63).

        Different stream numbers alter the increment of the rng and ensure distinct state sequences

        Only generators with the same seed AND stream numbers will produce identical values

        Parameters:
        seed - used to compute the starting state of the RNG
        streamNumber - used to compute the increment for the lcg.

      • PcgRSFast

        protected PcgRSFast​(long initialState,
                    long increment,
                    boolean dummy)

    • Method Detail

      • setSeed

        public void setSeed​(long seed,
                    long streamNumber)
        Sets the seed of this random number generator using . The general contract of setSeed is that it alters the state of this random number generator object so as to be in exactly the same state as if it had just been created with the argument seed as a seed. Only generators with the same seed AND stream numbers will produce identical values

        Parameters:
        seed - used to compute the starting state of the RNG
        streamNumber - used to compute the increment for the lcg.

      • advance

        public void advance​(long steps)
        Advance or set back the rngs state. In other words fast skip the next n generated random numbers or set the PNG back so it will create the last n numbers in the same sequence again. 
                int x = nextInt();
        nextInt(); nextInt();
        step(-3);
        int y = nextInt(); 
        x == y TRUE
        Be aware that this relationship is only true for deterministic generation calls. nextGaussian() or any bound limited number generations might loop and consume more than one step to generate a number.

        To advance n steps the function performs Math.ceil( log2(n) ) iterations. So you may go ahead and skip as many steps as you like without any performance implications.

        Negative indices can be used to jump backwards in time going the long way around

        Specified by:
        advance in interface Pcg
        Parameters:
        steps - the amount of steps to advance or in case of a negative number go back in history

      • nextByte

        public byte nextByte()
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed byte value from this random number generator's sequence. The general contract of nextByte is that one byte value is pseudorandomly generated and returned. All possible byte values are produced with (approximately) equal probability.
        Specified by:
        nextByte in interface Pcg
        Returns:
        the next pseudorandom, uniformly distributed byte value from this random number generator's sequence

      • nextBytes

        public void nextBytes​(byte[] b)
        Description copied from interface: Pcg
        Generates random bytes and places them into a user-supplied byte array. The number of random bytes produced is equal to the length of the byte array.
        Specified by:
        nextBytes in interface Pcg
        Overrides:
        nextBytes in class java.util.Random
        Parameters:
        b - the byte array to fill with random bytes
        See Also:
        Pcg.nextByte()

      • nextChar

        public char nextChar()
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed char value from this random number generator's sequence. The general contract of nextChar is that one char value is pseudorandomly generated and returned. All possible char values are produced with (approximately) equal probability.
        Specified by:
        nextChar in interface Pcg
        Returns:
        the next pseudorandom, uniformly distributed char value from this random number generator's sequence

      • nextShort

        public short nextShort()
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed short value from this random number generator's sequence. The general contract of nextShort is that one short value is pseudorandomly generated and returned. All possible short values are produced with (approximately) equal probability.
        Specified by:
        nextShort in interface Pcg
        Returns:
        the next pseudorandom, uniformly distributed short value from this random number generator's sequence

      • nextInt

        public int nextInt()
        Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general contract of nextInt is that one int value is pseudorandomly generated and returned. All 232 possible int values are produced with (approximately) equal probability.
        Specified by:
        nextInt in interface Pcg
        Overrides:
        nextInt in class java.util.Random
        Returns:
        the next pseudorandom, uniformly distributed int value from this random number generator's sequence

      • nextInt

        public int nextInt​(int n)
        Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.
        Specified by:
        nextInt in interface Pcg
        Overrides:
        nextInt in class java.util.Random
        Parameters:
        n - the upper bound (exclusive). Must be positive.
        Returns:
        the next pseudorandom, uniformly distributed int value between zero (inclusive) and bound (exclusive) from this random number generator's sequence
        See Also:
        Pcg.nextInt()

      • nextBoolean

        public boolean nextBoolean()
        Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence. The general contract of nextBoolean is that one boolean value is pseudorandomly generated and returned. The values true and false are produced with (approximately) equal probability.
        Specified by:
        nextBoolean in interface Pcg
        Overrides:
        nextBoolean in class java.util.Random
        Returns:
        the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence

      • nextBoolean

        public boolean nextBoolean​(double probability)
        Description copied from interface: Pcg
        Returns the next pseudorandom boolean value from this random number generator's sequence with the given probability of being true.

        A probability value of 0 will always return false and a value of 1 will always return true.

        Specified by:
        nextBoolean in interface Pcg
        Parameters:
        probability - the probability of the returned boolean to be true in range of [0-1]
        Returns:
        the next pseudorandom boolean with given probability to tbe true

      • nextLong

        public long nextLong()
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned.
        Specified by:
        nextLong in interface Pcg
        Overrides:
        nextLong in class java.util.Random
        Returns:
        the next pseudorandom, uniformly distributed long value from this random number generator's sequence

      • nextLong

        public long nextLong​(long n)
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned.
        Specified by:
        nextLong in interface Pcg
        Parameters:
        n - the upper bound (exclusive). Must be positive.
        Returns:
        the next pseudorandom, uniformly distributed long value from this random number generator's sequence

      • nextDouble

        public double nextDouble()
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.

        The general contract of nextDouble is that one double value, chosen (approximately) uniformly from the range 0.0d (inclusive) to 1.0d (exclusive), is pseudorandomly generated and returned.

        Specified by:
        nextDouble in interface Pcg
        Overrides:
        nextDouble in class java.util.Random
        Returns:
        the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence

      • nextDouble

        public double nextDouble​(boolean includeZero,
                         boolean includeOne)
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed double value in the range from 0.0 to 1.0, possibly inclusive of 0.0 and 1.0 themselves. Thus:
        ExpressionInterval
        nextDouble(false, false)(0.0, 1.0)
        nextDouble(true, false)[0.0, 1.0)
        nextDouble(false, true)(0.0, 1.0]
        nextDouble(true, true)[0.0, 1.0]
        Table of intervals

        This version preserves all possible random values in the double range.

        Specified by:
        nextDouble in interface Pcg
        Parameters:
        includeZero - if true may return 0d
        includeOne - if true may return 1d
        Returns:
        the next pseudorandom, uniformly distributed double value from this random number generator's sequence
        See Also:
        Pcg.nextDouble()

      • nextFloat

        public float nextFloat()
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence.

        The general contract of nextFloat is that one float value, chosen (approximately) uniformly from the range 0.0f (inclusive) to 1.0f (exclusive), is pseudorandomly generated and returned. All 224 possible float values of the form m x 2-24, where m is a positive integer less than 224, are produced with (approximately) equal probability.

        Specified by:
        nextFloat in interface Pcg
        Overrides:
        nextFloat in class java.util.Random
        Returns:
        the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence

      • nextFloat

        public float nextFloat​(boolean includeZero,
                       boolean includeOne)
        Description copied from interface: Pcg
        Returns the next pseudorandom, uniformly distributed float valuet in the range from 0.0f to 1.0f, possibly inclusive of 0.0f and 1.0f themselves. Thus:
        ExpressionInterval
        nextFloat(false, false)(0.0f, 1.0f)
        nextFloat(true, false)[0.0f, 1.0f)
        nextFloat(false, true)(0.0f, 1.0f]
        nextFloat(true, true)[0.0f, 1.0f]
        Table of intervals

        This version preserves all possible random values in the float range.

        Specified by:
        nextFloat in interface Pcg
        Parameters:
        includeZero - if true may return 0f
        includeOne - if true may return 1f
        Returns:
        the next pseudorandom, uniformly distributed float value from this random number generator's sequence
        See Also:
        Pcg.nextFloat()

      • nextGaussian

        public double nextGaussian()
        Specified by:
        nextGaussian in interface Pcg
        Overrides:
        nextGaussian in class java.util.Random

      • getInc

        public long getInc()
        Description copied from interface: Pcg
        Returns the internal increment of the congurential generator used by this pcg
        Specified by:
        getInc in interface Pcg
        Returns:
        the increment

      • getState

        public long getState()
        Description copied from interface: Pcg
        Returns the internal state of the congruential generator used by this pcg
        Specified by:
        getState in interface Pcg
        Returns:
        the internal state

      • setInc

        protected void setInc​(long increment)

      • setState

        protected void setState​(long state)

      • split

        public <T> T split()
            throws java.lang.ReflectiveOperationException
        Description copied from interface: Pcg
        Splits the generator in a copy with the exact same state and stream number. The produced generators don't share any state variables enabling to generate random numbers without impacting the other generator. While the states are independent they are exact copies resulting in the generated numbers to follow the same sequence.

        On the other hand Pcg.splitDistinct() will return a generator who has a different state and stream number ensuring that the generated sequence is NOT the same as this generator.

        Specified by:
        split in interface Pcg
        Type Parameters:
        T - Class of the constructed generator which is equals the class this method was invoked on.
        Returns:
        an identical generator with no shared references
        Throws:
        java.lang.ReflectiveOperationException - if the extending class does not implement the required constructor

      • splitDistinct

        public <T> T splitDistinct()
                    throws java.lang.ReflectiveOperationException
        Description copied from interface: Pcg
        Splits the generator in a copy with distinct state and stream number. The produced generators don't share any state variables enabling to generate random numbers without impacting the other generator. The generators are guaranteed to produce different sequences of numbers and can't be used independently of each other.

        On the other hand Pcg.split() will return a generator who has an identical state and stream number ensuring that the generated sequence is the same as this generator.

        Specified by:
        splitDistinct in interface Pcg
        Type Parameters:
        T - Class of the constructed generator which is equals the class this method was invoked on.
        Returns:
        a distinct generator with no shared references
        Throws:
        java.lang.ReflectiveOperationException - if the extending class does not implement the required constructor

      • next

        public int next​(int n)
        Description copied from interface: Pcg
        Returns an integer with the next n low bits randomly set and are used as a base to deviate smaller data types. The used bits are the high bits used from the underlying integer. An n of more 31 bits will result in no bits being set, thus returning 0.
        Specified by:
        next in interface Pcg
        Overrides:
        next in class java.util.Random
        Parameters:
        n - the number of randomly set bits. Must be positive and does not produce reasonable results for > 31
        Returns:
        an integer

      • getMult

        public long getMult()
        Description copied from interface: Pcg
        Returns the internal multiplication of the congurential generator used by this pcg
        Specified by:
        getMult in interface Pcg
        Returns:
        the multiplication factor

      • isFast

        public boolean isFast()
        Description copied from interface: Pcg
        Return true if this rng is a fast instance. This check is mostly used int he distance calculation due to the fact that the state of fast RNGs is shifted by one. They first calculate a new value and directly use it instead of using the old state and calculating a new one
        Specified by:
        isFast in interface Pcg
        Returns:
        true if the subclass uses the newly generated state directly

      • getRandomSeed

        protected static long getRandomSeed()