TRNG.Engine | R Documentation |
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
.
lcg64
, lcg64_shift
, mrg2
, mrg3
, mrg3s
,
mrg4
, mrg5
, mrg5s
, yarn2
, yarn3
,
yarn3s
, yarn4
, yarn5
, yarn5s
.
lagfib2plus_19937_64
, lagfib2xor_19937_64
,
lagfib4plus_19937_64
, lagfib4xor_19937_64
, mt19937_64
,
mt19937
.
$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()
.
$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 s
th of p
subsequences, with s
in
[1
, p
], producing one element every s
starting from
the p
th. 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
).
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 Module
s. 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.
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.
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.
Heiko Bauke, Tina's Random Number Generator Library, Version 4.23.1, https://github.com/rabauke/trng4/blob/v4.23.1/doc/trng.pdf.
ReferenceClasses
, TRNG.Random
.
TRNG distributions:
rbinom_trng
, rlnorm_trng
, rnorm_trng
, rpois_trng
, runif_trng
.
## 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())
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.