Package com.github.kilianB.pcg.cas

Class RandomBaseCAS

  • All Implemented Interfaces:
    Pcg, java.io.Serializable
    Direct Known Subclasses:
    PcgRRCas, PcgRSCas
    public abstract class RandomBaseCAS
extends RandomBase64
implements Pcg
    Base class for 64 bit state pcg random number generators. The PCG family uses a linear congruential generator as the state-transition function—the “CG” of PCG stands for “congruential generator”. Linear congruential generators are known to be statistically weak.

    PCG uses a new technique called permutation functions on tuples to produce output that is much more random than the RNG's internal state. The output function is defined by the extending classes. A paper highlighting the individual properties can be found here. http://www.pcg-random.org/paper.html. This class is an adaption to the original c source code provided by M.E. O'Neill. Contract: every extending class must implement the (long,long,boolean) constructor and pass it's argument to the superclass. This constructor functions as copy constructor and blindly passes the arguments on. As it does not perform proper initialization of the seed this method should not be exposed.

    Author:
    Kilian
    See Also:
    www.pcg-random.org, Serialized Form

    • Field Detail

      • mult64

        protected long mult64
        linear congruential constant. Same as MMIX by Donald Knuth and Newlib, Musl

      • state

        protected java.util.concurrent.atomic.AtomicLong state
        64 bit internal state

      • inc

        protected long inc
        Stream number of the rng.

    • Constructor Detail

      • RandomBaseCAS

        public RandomBaseCAS()
        Seeds the generator with 2 longs generated by xorshift*. The values choosen are very likely not used in any other invocation of this constructor.

      • RandomBaseCAS

        public RandomBaseCAS​(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 implementations. RNGs with different seeds are able to catch up after they exhaust their period and produce the same numbers.

        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.

      • RandomBaseCAS

        @Deprecated
protected RandomBaseCAS​(long initialState,
                        long increment,
                        boolean dummy)
        Deprecated.
        Copy constructor. Has to be implemented in all inheriting instances. This will be invoked through reflection!. If no special behavior is desired simply pass though the values.
        Parameters:
        initialState - of the lcg
        increment - used in the lcg. has to be odd
        dummy - used to resolve signature disambiguate

    • Method Detail

      • stepRight

        protected long stepRight()
        Update the state of the lcg and move a step forward. The old state should be used to extract bits used to construct a number.
        Specified by:
        stepRight in class RandomBase64
        Returns:
        the old value of the state variable before updating.

      • 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. Random.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

      • getInt

        protected abstract int getInt​(long state)
        Construct a 32bit int from the given 64bit state using a permutation function. The produced int will be used to construct all other datatypes returned by this RNG.
        Specified by:
        getInt in class RandomBase64
        Parameters:
        state - random int as produced by the internal lcg
        Returns:
        a random int

      • isFast

        public boolean isFast()
        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

      • 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

      • 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

      • setInc

        protected void setInc​(long increment)
        Description copied from class: RandomBase64
        Set the increment of the pcg. This method is used during the seeding process of this class and therefore, it is most likely is never correct to alter the variable passed to this function.

        "Although there are rules for the choice of constants [17], if we pick a power-of-two modulus and a good multiplicative constant, the only constraint on c for a full period generator is that c is odd and > 0"

        Chapter 4.2.1 (http://www.pcg-random.org/pdf/hmc-cs-2014-0905.pdf)

        Allowed operations are synchronization on those methods-

        Specified by:
        setInc in class RandomBase64
        Parameters:
        increment - of the pcg

      • setState

        protected void setState​(long initialState)
        Description copied from class: RandomBase64
        Set the internal state of the pcg. This method is used during the seeding process of this class and therefore, it is most likely is never correct to alter the variable passed to this function.

        Allowed operations are synchronization on those methods-

        Specified by:
        setState in class RandomBase64
        Parameters:
        initialState - of the pcg