TRNG.Random {rTRNG}

TRNG random number generation.

Description

The functions below allow setting and manipulating the current TRNG random number engine (pseudo-random number generator), similar to base-R Random. The current engine is then used for generating random variates via any of the r<dist>_trng functions (e.g., runif_trng).

TRNGkind allows to query or set the kind of TRNG engine in use. See ‘Random number engines details’ for the available engines.

TRNGseed specifies the seed for the current engine.

If the current engine is of a parallel kind, TRNGjump advances its internal state without generating all intermediate steps.

If the current engine is of a parallel kind, TRNGsplit updates its internal state and parameters in order to generate directly a subsequence obtained by decimation, producing every sth element starting from the pth.

TRNG.Random.seed allows to get a full representation of the current state of the engine in use, and to restore the current engine from such representation.

Usage

TRNGkind(kind = NULL)

TRNGseed(seed)

TRNGjump(steps)

TRNGsplit(p, s)

TRNG.Random.seed(engspec)

Arguments

kind

Character string or NULL. If kind is not NULL, it defines the TRNG random number engine to be used. Use "default" for the rTRNG default kind ("yarn2").

seed

Scalar integer seed, determining the internal state of the current engine.

steps

Number of steps to jump ahead.

p

Number of subsequences to split the engine by.

s

Index of the desired subsequence between 1 and p.

engspec

Optional two-element character vector c(kind, state), where the second element is a character representation of the current engine's internal state and parameters.

Value

TRNGkind returns the TRNG kind selected before the call, invisibly if argument kind is not NULL.

TRNG.Random.seed() called with no arguments returns a two-element character vector c(kind, state) fully representing the current state of the engine in use. When argument engspec = c(kind, state) is provided, it is used to set an engine of the given kind with internal state and parameters restored from state.

Details

The TRNG C++ library provides a collection of random number engines (pseudo-random number generators). In particular, compared to conventional engines working in a purely sequential manner, parallel engines can be manipulated via jump and split operations. Jumping allows to advance the internal state by a number of steps without generating all intermediate states, whereas split operations allow to generate directly a subsequence obtained by decimating the original sequence. Please consult the TRNG C++ library documentation (see ‘References’) for an introduction to the concepts and details around (parallel) random number generation and engines, including details about the state size and period of the TRNG generators.

The current engine is an instance of one TRNG engine class provided by rTRNG, and is stored as "TRNGengine" global option. If not explicitly set via TRNGkind, an engine of default kind is implicitly created upon the first call to any TRNG* or r<dist>_trng function. Note that the current engine is not persistent across R sessions. Function TRNG.Random.seed can be used to extract and restore the current engine and its internal state.

Random number engines details

Parallel engines

lcg64

Linear congruential generator with modulus 2^{64}.

lcg64_shift

Linear congruential generator with modulus 2^{64} and bit-shift transformation.

mrg2, mrg3, mrg4, mrg5

Multiple recurrence generators based on a linear feedback shift register sequence with prime modulus 2^{31}-1.

mrg3s, mrg5s

Multiple recurrence generators based on a linear feedback shift register with Sophie-Germain prime modulus.

yarn2, yarn3, yarn4, yarn5

YARN generators based on the delinearization of a linear feedback shift register sequence with prime modulus 2^{31}-1.

yarn3s, yarn5s

YARN generators based on the delinearization of a linear feedback shift register sequence with Sophie-Germain prime modulus.

Conventional engines

lagfib2plus_19937_64, lagfib4plus_19937_64

Lagged Fibonacci generator with 2 or 4 feedback taps and addition.

lagfib2xor_19937_64, lagfib4xor_19937_64

Lagged Fibonacci generator with 2 or 4 feedback taps and exclusive-or operation.

mt19937

Mersenne-Twister generating 32 random bit.

mt19937_64

Mersenne-Twister generating 64 random bit.

References

Heiko Bauke, Tina's Random Number Generator Library, Version 4.23.1, https://github.com/rabauke/trng4/blob/v4.23.1/doc/trng.pdf.

See Also

TRNG distributions: rbinom_trng, rlnorm_trng, rnorm_trng, rpois_trng, runif_trng.

Examples

## TRNG kind of the current engine
TRNGkind()
## set a specific TRNG kind
TRNGkind("yarn5s")
TRNGkind()
## Not run: 
  ## error if kind is not valid
  TRNGkind("invalid")

## End(Not run)
## set the deafult TRNG kind
TRNGkind("default")
TRNGkind()

## seed the current random number engine
TRNGseed(117)

## full representation of the current state of the engine in use
s <- TRNG.Random.seed()
s

## draw 10 random variates using the current engine
runif_trng(10)

## restore the engine and its internal state
TRNG.Random.seed(s)

## jump and draw the last 3 variates out of the 10 above
TRNGjump(7) # jump 7 steps ahead
runif_trng(3)

## restore the internal state, split and draw every 5th element starting from
## the 2nd
TRNG.Random.seed(s)
TRNGsplit(5, 2)
runif_trng(2)

## TRNGseed, TRNGjump and TRNGsplit can be combined with r<dist>_trng in c(...)
## as they return NULL
c(TRNGseed(117),
  TRNGjump(2), runif_trng(2),
  TRNGsplit(3,2), runif_trng(2))