PCGRandomLib¶
Usage
use Random.PCGRandomLib;
or
import Random.PCGRandomLib;
Lowlevel PCG RNG implementation.
This module includes a number of lowlevel PCG random functions. See http://www.pcgrandom.org/ and the paper, PCG: A Family of Simple Fast SpaceEfficient Statistically Good Algorithms for Random Number Generation by M.E. O’Neill.
This module provides the following lowlevel PCG RNGs:
pcg_setseq_64_xsh_rr_32_rng
(the default PCG RNG)pcg_setseq_64_rxs_m_xs_64_rng
pcg_setseq_32_rxs_m_xs_32_rng
pcg_setseq_16_rxs_m_xs_16_rng
pcg_setseq_8_rxs_m_xs_8_rng
pcg_setseq_N_rxs_m_xs_N_rng
which is a generalization of the above
These names come from the PCG paper and reference implementations. The first integer is the number of state bits, and the last integer is the number of output bits. The other parts describe the permutation function in the LCG.
Conceptually, a PCG RNG consists of three things:
 the algorithm variant (e.g. pcg_setseq_64_xsh_rr_32_rng)
 the current state
 the RNG sequence constant
Note that the sequence constant must be odd for this generator to
function correctly. The function pcg_getvalid_inc
is available
to construct an odd number based upon an arbitrary input.
When using these lowlevel interfaces, the sequence constant is not actually stored inside the RNG. Instead, users of this interface must pass the same sequence constant used in srandom to each of the other calls for that RNG object.
Besides storing the RNG state in the record, each of these PCG RNGs include at least the following methods:
 srandom to initialize the state from a seed
 random to produce the next random value
 advance to skip ahead some number of steps in RNG generation

record
pcg_setseq_64_xsh_rr_32_rng
¶ Lowlevel PCG random number generation interface (64bits of state, 32bits output).
This record implements the same RNG as pcg32_random_r does in PCGC0.94.
This RNG has 64bits of internal state and outputs 32bits at a time.
This RNG will iterate through all possible 64bit values of state. The sequence constant chooses between 2**63 random sequences that the RNG is iterating through.

var
state
: uint(64)¶ The RNG state

proc
srandom
(seed: uint(64), inc: uint(64))¶ Seed the random number generator. This function corresponds to pcg32_srandom_r.
Arguments:  seed – The initial internal state.
 inc – The sequence constant.

proc
random
(inc: uint(64)): uint(32)¶ Get the next 32bit random number. This function corresponds to pcg32_random_r.
Arguments: inc – The sequence constant (same as passed to srandom) Returns: 32 bits generated by the RNG.

proc
bounded_random
(inc: uint(64), bound: uint(32))¶ Generate a random number in [0,bound).
This function corresponds to pcg32_boundedrand_r and can call the randomnumber generator more than once.
Arguments:  inc – The sequence constant (same as passed to srandom)
 bound – The returned value will be < bound.
Returns: a random number in [0,bound).

proc
bounded_random_vary_inc
(inc: uint(64), bound: uint(32), seed: uint(64), skip: uint(64), next_inc: uint(64), inc_increment: uint(64))¶ Generate a random number in [0,bound).
This function corresponds to pcg32_boundedrand_r, but has one difference. Because parallel random number generation relies upon advancing to a known position, this function only advances the RNG state once per call. Where the pcg32_boundedrand_r would advance the RNG state multiple times, this function creates a new RNGs with the same initial seed but different sequence numbers and uses those when more random numbers are needed. In this way, this strategy is similar to the strategy for generating 64bit numbers by pairing 32bit PCG RNGs.
Note
The nextint and inc_increment values need to define a sequence of increments that is different from other increments used. Otherwise, these streams will not be independent.
Note
This a strategy for generating a value in a particular range that has not been subject to rigorous study and may have statistical problems. Additionally, its performance could be improved in the case that this function is called many times in a row by caching the temporary RNGs at their current position.
Arguments:  inc – The sequence constant (same as passed to srandom)
 bound – The returned value will be < bound.
 seed – The seed this RNG started with
 skip – How many numbers, before this one, has this RNG generated?
 nextinc – The first increment to pass to pcg_getvalid_inc and that should be unique for this RNG. Defaults to 100.
 inc_increment – Advance nextinc by inc_increment each time a new value is needed.
Returns: a random number in [0,bound).

proc
advance
(inc: uint(64), delta: uint(64))¶ Advance the RNG. Adjusts the state of the RNG to be the same as if delta calls were made to random.
This function corresponds to pcg32_advance_r.
Arguments:  inc – The sequence constant (same as passed to srandom)
 delta – The number of steps to jump ahead

var

record
pcg_setseq_64_rxs_m_xs_64_rng
¶ Lowlevel PCG random number generation interface (64bits of state, 64bits output).
This record implements the same RNG as pcg64i_random_r does in PCGC0.94.
This RNG has 64bits of internal state and outputs 64bits at a time.
This generator produces each 64bit value exactly once.
This generator should be considered insecure since it reveals its entire internal state with each output.

var
state
: uint(64)¶ The RNG state

proc
srandom
(seed: uint(64), inc: uint(64))¶ Seed the random number generator. This function corresponds to pcg64i_srandom_r.
Arguments:  seed – The initial internal state.
 inc – The sequence constant.

proc
random
(inc: uint(64)): uint(64)¶ Get the next 64bit random number. This function corresponds to pcg64i_random_r.
Arguments: inc – The sequence constant (same as passed to srandom) Returns: 64 bits generated by the RNG.

proc
advance
(inc: uint(64), delta: uint(64))¶ Advance the RNG. Adjusts the state of the RNG to be the same as if delta calls were made to random.
This function corresponds to pcg64i_advance_r.
Arguments:  inc – The sequence constant (same as passed to srandom)
 delta – The number of steps to jump ahead

var

record
pcg_setseq_32_rxs_m_xs_32_rng
¶ Lowlevel PCG random number generation interface (32bits of state, 32bits output).
This record implements the same RNG as pcg32i_random_r does in PCGC0.94.
This RNG has 32bits of internal state and outputs 32bits at a time.
This generator produces each 32bit value exactly once.
This generator should be considered insecure since it reveals its entire internal state with each output.

var
state
: uint(32)¶ The RNG state

proc
srandom
(seed: uint(32), inc: uint(32))¶ Seed the random number generator. This function corresponds to pcg32i_srandom_r.
Arguments:  seed – The initial internal state.
 inc – The sequence constant

proc
random
(inc: uint(32)): uint(32)¶ Get the next 32bit random number. This function corresponds to pcg32i_random_r.
Arguments: inc – The sequence constant (same as passed to srandom) Returns: 32 bits generated by the RNG.

proc
advance
(inc: uint(32), delta: uint(32))¶ Advance the RNG. Adjusts the state of the RNG to be the same as if delta calls were made to random.
This function corresponds to pcg32i_advance_r.
Arguments:  inc – The sequence constant (same as passed to srandom)
 delta – The number of steps to jump ahead

var

record
pcg_setseq_16_rxs_m_xs_16_rng
¶ Lowlevel PCG random number generation interface (16bits of state, 16bits output).
This record implements the same RNG as pcg16i_random_r does in PCGC0.94.
This RNG has 16bits of internal state and outputs 16bits at a time.
This generator produces each 16bit value exactly once.
This generator should be considered insecure since it reveals its entire internal state with each output.

var
state
: uint(16)¶ The RNG state

proc
srandom
(seed: uint(16), inc: uint(16))¶ Seed the random number generator. This function corresponds to pcg16i_srandom_r.
Arguments:  seed – The initial internal state.
 inc – The sequence constant

proc
random
(inc: uint(16)): uint(16)¶ Get the next 16bit random number. This function corresponds to pcg16i_random_r.
Arguments: inc – The sequence constant (same as passed to srandom) Returns: 16 bits generated by the RNG.

proc
advance
(inc: uint(16), delta: uint(16))¶ Advance the RNG. Adjusts the state of the RNG to be the same as if delta calls were made to random.
This function corresponds to pcg16i_advance_r.
Arguments:  inc – The sequence constant (same as passed to srandom)
 delta – The number of steps to jump ahead

var

record
pcg_setseq_8_rxs_m_xs_8_rng
¶ Lowlevel PCG random number generation interface (8bits of state, 8bits output).
This record implements the same RNG as pcg8i_random_r does in PCGC0.94.
This RNG has 8bits of internal state and outputs 8bits at a time.
This generator produces each 8bit value exactly once.
This generator should be considered insecure since it reveals its entire internal state with each output.

var
state
: uint(8)¶ The RNG state

proc
srandom
(seed: uint(8), inc: uint(8))¶ Seed the random number generator. This function corresponds to pcg16i_srandom_r.
Arguments:  seed – The initial internal state.
 inc – The sequence constant

proc
random
(inc: uint(8)): uint(8)¶ Get the next 16bit random number. This function corresponds to pcg16i_random_r.
Arguments: inc – The sequence constant (same as passed to srandom) Returns: 16 bits generated by the RNG.

proc
advance
(inc: uint(8), delta: uint(8))¶ Advance the RNG. Adjusts the state of the RNG to be the same as if delta calls were made to random.
This function corresponds to pcg16i_advance_r.
Arguments:  inc – The sequence constant (same as passed to srandom)
 delta – The number of steps to jump ahead

var

record
pcg_setseq_N_rxs_m_xs_N_rng
¶ Lowlevel PCG random number generation interface for N bits of state, N bits output. This generator can be useful for generating a permutation since it produces each Nbit output exactly once and N is variable.
This record implements an Nbit random number generator based upon
pcg_setseq_64_rxs_m_xs_64_rng
,pcg_setseq_32_rxs_m_xs_32_rng
,pcg_setseq_16_rxs_m_xs_16_rng
,pcg_setseq_8_rxs_m_xs_8_rng
, and a custom generalization of these generators. This generator always truncates its internal state to N bits.This generator should be considered insecure since it reveals its entire internal state with each output. It produces each Nbit value exactly once.

const
N
¶ the number of bits in state and in each output random number

var
state
: uint¶ The RNG state

proc
srandom
(seed: uint, inc: uint)¶ Seed the random number generator.
Arguments:  seed – The initial internal state.
 inc – The sequence constant

proc
random
(inc: uint): uint¶ Get the next Nbit random number.
Arguments: inc – The sequence constant (same as passed to srandom) Returns: N bits generated by the RNG.

proc
advance
(inc: uint, delta: uint)¶ Advance the RNG. Adjusts the state of the RNG to be the same as if delta calls were made to random.
Arguments:  inc – The sequence constant (same as passed to srandom)
 delta – The number of steps to jump ahead

const

proc
pcg_getvalid_inc
(initseq: uint(64)): uint(64)¶ The inc field in the PCG RNG must be odd. This function arranges for that to be the case given any input.