Repository files navigation

TRNG (Tina’s Random NumberGenerator) is a state-of-the-art C++ pseudo-random number generatorlibrary for sequential and parallel Monte Carlo simulations. It providesa variety of random number engines (pseudo-random number generators) anddistributions. In particular,parallel random number engines providedby TRNG can be manipulated byjump andsplit operations. These allowtojump ahead by an arbitrary number of steps and tosplit asequence into any desired sub-sequence(s), thus enabling techniques suchasblock-splitting andleapfrogging suitable to parallel algorithms.

PackagerTRNG provides the R user with access to the functionalityof the underlying TRNG C++ library, both in R directly or more typicallyas part of other projects combining R with C++.

Anintroduction torTRNG[pdf]was given at the useR!2017 conference, and is also available as packagevignette:

vignette("rTRNG.useR2017","rTRNG")

Thesub-matrix simulation vignette showsrTRNG in action for aflexibleand consistent (parallel) simulation of a matrix of MonteCarlo variates:

vignette("mcMat","rTRNG")

A full applied example of usingrTRNG for the simulation of creditdefaults was presented at theR/Finance 2017conference[pdf].The underlying code and data are hosted onGitHub, as is thecorrespondingR Markdownoutput.

For more information and references, you can consult the packagedocumentation page viahelp("rTRNG-package").

You can install the package from CRAN:

install.packages("rTRNG")

The development version ofrTRNG can be installed from ourGitHubrepository with:

# install.packages("remotes")remotes::install_github("miraisolutions/rTRNG")# in order to also build the vignettes, you'll have to run below insteadremotes::install_github("miraisolutions/rTRNG",build_vignettes=TRUE)

Build note

If you try to build the package yourself from source and runRcpp::compileAttributes() during the process, you need to use aversion ofRcpp >= 0.12.11.2. Earlier versions like 0.12.11 willnot generate the desired_rcpp_module_boot_trng symbol inRcppExports.cpp.

Similar to base-R (?Random),rTRNG allows to select and manipulateacurrent TRNG engine of a givenkind (e.g. yarn2), and to draw fromit using any of the providedr<dist>_trng functions:

library(rTRNG)TRNGkind("yarn2") TRNGseed(12358)runif_trng(15)#>  [1] 0.58025981 0.33943403 0.22139368 0.36940239 0.54267877#>  [6] 0.00285146 0.12399649 0.34681378 0.12179942 0.94712445#> [11] 0.33651657 0.12892618 0.38037989 0.55069238 0.43600265

The specialjump andsplit operations can be applied to the currentengine in a similar way:

TRNGseed(12358)TRNGjump(6)# advance by 6 the internal stateTRNGsplit(5,3)# subsequence: one element every 5 starting from the 3rdrunif_trng(2)#> [1] 0.121799 0.550692#   => compare to the full sequence above

TRNG engines can also be created and manipulated directly asReferenceClass objects, and passed asengine argument tor<dist>_trng:

rng<-yarn2$new()rng$seed(12358)rng$jump(6)rng$split(5,3)runif_trng(2,engine=rng)#> [1] 0.121799 0.550692

In addition, parallel generation of random variates can be enabled inr<dist>_trng viaRcppParallel using argumentparallelGrain > 0:

TRNGseed(12358)RcppParallel::setThreadOptions(numThreads=2)x_parallel<- rnorm_trng(1e5L,parallelGrain=100L)TRNGseed(12358)x_serial<- rnorm_trng(1e5L)identical(x_serial,x_parallel)#> [1] TRUE

The TRNG C++ library is made available byrTRNG to standalone C++code compiled withRcpp::sourceCpp thanks to theRcpp::dependsattribute:

// [[Rcpp::depends(rTRNG)]]#include<Rcpp.h>#include<trng/yarn2.hpp>#include<trng/uniform_dist.hpp>// [[Rcpp::export]]Rcpp::NumericVectorexampleCpp() {  trng::yarn2rng(12358);  rng.jump(6);  rng.split(5,2);// 0-based index  Rcpp::NumericVectorx(2);  trng::uniform_dist<>unif(0,1);for (unsignedint i =0; i <2; i++) {    x[i] =unif(rng);  }return x;}

exampleCpp()#> [1] 0.121799 0.550692

Creating an R package with C++ code using the TRNG library and headersthroughrTRNG is achieved by

• addingImports: rTRNG andLinkingTo: rTRNG to the DESCRIPTION file
• importing one symbol in the NAMESPACE:importFrom(rTRNG, TRNG.Version)
• setting the relevant linker flags in Makevars[.win] viarTRNG::LdFlags()
  • Makevars:PKG_LIBS += $(shell ${R_HOME}/bin/Rscript -e "rTRNG::LdFlags()")
  • Makevars.win:PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "rTRNG::LdFlags()")

C++ code using the TRNG library (sourced viaRcpp::sourceCpp or partof an R package) might fail on certain systems due to issues withbuilding and linking againstrTRNG. This is typically the case formacOS, and can generally be checked by running

rTRNG::check_rTRNG_linking()