TRNG.Engine {rTRNG}

TRNG random number engines.

Description

Reference Classes exposing random number engines (pseudo-random number generators) in the TRNG C++ library. Engine objects of a class engineClass are created as r <- engineClass$new(...), and a method m is invoked as x$m(...). The engine object r can be then used for generating random variates via any of the r<dist>_trng functions (e.g., runif_trng), specifying the optional argument engine = r.

Classes

Parallel random number engines

lcg64, lcg64_shift, mrg2, mrg3, mrg3s, mrg4, mrg5, mrg5s, yarn2, yarn3, yarn3s, yarn4, yarn5, yarn5s.

Conventional random number engines

lagfib2plus_19937_64, lagfib2xor_19937_64, lagfib4plus_19937_64, lagfib4xor_19937_64, mt19937_64, mt19937.

Constructors

$new()

Construct a random engine object using default seed and internal parameters.

$new(seed)

Construct a random engine object with default internal parameters using the provided seed.

$new(string)

Construct a random engine object restoring its internal state and parameters from a character string, falling back to $new() for empty strings. See method $toString().

Methods

$seed(seed)

Use the scalar integer seed to set the engine's internal state.

$jump(steps)

Advance by steps the internal state of the engine. Applies to parallel engines only.

$split(p, s)

Update the internal state and parameters of the engine for generating directly the sth of p subsequences, with s in [1, p], producing one element every s starting from the pth. Applies to parallel engines only.

$name(), $kind()

Return the name of the random number engine (e.g., "yarn2"), also referred to as kind in rTRNG similarly to base R.

$toString()

Return a character representation of the engine's internal state and parameters.

$copy()

Specialization of the generic method for Reference Classes, ensuring the underlying C++ engine object is properly copied.

$show()

Specialization of the generic show, displaying $toString() (truncated to 80 characters).

$.Random.seed()

Return a two-element character vector with elements $kind() and $toString(), suitable for use in TRNG.Random.seed (and by a possible function returning an engine object given a TRNG.Random.seed).

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.

Random number engines from the C++ TRNG library are exposed to R using Rcpp Modules. As a consequence, the arguments to all Constructors and Methods above are not passed by name but by order. Moreover, arguments and return values are both defined in terms of C++ data types. Details can be displayed via the standard Reference Class documentation method $help (e.g., yarn2$help(split)).

Most of the Methods above are simple wrappers of analogous methods in the corresponding C++ class provided by the TRNG library. A few differences/details are worth being mentioned.

• Argument s of the split method is exposed to R according to R's 1-based indexing, thus in the [1, p] interval, whereas the TRNG C++ implementation follows C++ 0-based indexing, thus allowing values in [0, p-1].

• Constructor new(string) and method toString() rely on streaming operators >> and << available for all C++ TRNG classes.

• TRNG C++ random number engine objects are copy-constructible and assignable, whereas their R counterparts in rTRNG are purely reference-based. In particular, as for any R Reference Object, engines are not copied upon assignment but via the $copy() method.

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

ReferenceClasses, TRNG.Random.

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

Examples

## Class yarn2 used in the examples below can be replaced by any other TRNG
## engine class (only of a parallel kind for jump and split examples).

## basic constructor with default internal state (and parameters)
r <- yarn2$new()
## show the internal parameters and state
r
## return internal parameters and state as character string
r$toString()

## seed the random number engine
r$seed(117)
r
## construct with given initial seed
s <- yarn2$new(117)
identical(s$toString(), r$toString())

## construct from string representation
s <- yarn2$new(r$toString()) # implicitly creates a copy
identical(s$toString(), r$toString())
s <- yarn2$new("") # same as yarn2$new()
identical(s$toString(), yarn2$new()$toString())
## Not run: 
  ## error if the string is not a valid representation
  s <- yarn2$new("invalid")

## End(Not run)

## copy vs. reference
r_ref <- r # reference to the same engine object
r_cpy <- r$copy() # copy an engine
identical(r_cpy$toString(), r$toString())
rbind(c(runif_trng(4, engine = r), runif_trng(6, engine = r_ref)),
      runif_trng(10, engine = r_cpy))

## jump (and draw from reference)
runif_trng(10, engine = r_cpy)
r_ref$jump(7) # jump 7 steps ahead
runif_trng(3, engine = r) # jump has effect on the original r

## split
r_cpy <- r$copy()
runif_trng(10, engine = r)
r_cpy$split(5, 2) # every 5th element starting from the 2nd
runif_trng(2, engine = r_cpy)

## seed, jump and split can be used in c(...) as they return NULL
r <- yarn2$new()
r_cpy <- r$copy()
r$seed(117)
runif_trng(10, engine = r)
c(r_cpy$seed(117),
  r_cpy$jump(2), runif_trng(2, engine = r_cpy),
  r_cpy$split(3,2), runif_trng(2, engine = r_cpy))

## TRNG engine name/kind
r$kind()
r$name()

## use $.Random.seed() to set the current engine (as a copy)
r$.Random.seed()
TRNG.Random.seed(r$.Random.seed())