sitmo v2.0.1

0

Monthly downloads

0th

Percentile

Parallel Pseudo Random Number Generator (PPRNG) 'sitmo' Header Files

Provided within are two high quality and fast PPRNGs that may be used in an 'OpenMP' parallel environment. In addition, there is a generator for one dimensional low-discrepancy sequence. The objective of this library to consolidate the distribution of the 'sitmo' (C++98 & C++11), 'threefry' and 'vandercorput' (C++11-only) engines on CRAN by enabling others to link to the header files inside of 'sitmo' instead of including a copy of each engine within their individual package. Lastly, the package contains example implementations using the 'sitmo' package and three accompanying vignette that provide additional information.

Readme

Travis-CI Build
StatusCRAN
RStudio mirror
downloads CRAN\_Status\_Badge

sitmo: A header-only package for R containing SITMO PPRNGs

The repository houses the sitmo R package for Parallel Psuedo Random Number Generation (PPRNG). The package provides a way to obtain the SITMO Consulting’s PPRNG header files via LinkTo.

Installing sitmo

sitmo is available on both CRAN (Stable) and GitHub (Development). Using CRAN to download and install sitmo is the preferred option as it is significantly more stable vs. the GitHub version.

Stable (CRAN) Install Instructions

To install the package from CRAN, you can simply type:

install.packages("sitmo")

The package will be installed and available in a similar fashion to other R packages. The main exception to this note is that to use sitmo to create a package you will need to acquire a compiler. This is detailed under the development install instructions.

Development Install Instructions

To install the package, you must first have a compiler on your system that is compatible with R.

For help on obtaining a compiler consult:

With a compiler in hand, one can then install the package from GitHub by:

install.packages("devtools")

devtools::install_github("coatless/sitmo")

Using sitmo

There are two ways to use sitmo. The first is to use sitmo in a standalone script. The script is typically built using sourceCpp(). The second approach allows for sitmo to be used within an R package.

Standalone file usage

Within the C++ file, the sitmo package provides an Rcpp plugins’ depends statement that must be included after sitmo.h header. This plugin statement indicates that a dependency is sitmo.

#include <Rcpp.h>
#include <sitmo.h> 
// [[Rcpp::depends(sitmo)]]

To use the two other engines, threefry and vandercorput, they must be loaded like:

#include <Rcpp.h>
#include <threefry.h>      // or use #include <vandercorput.h>
// [[Rcpp::depends(sitmo)]]
// [[Rcpp::plugins(cpp11)]]

sitmo Engine Example

Below is a hello world example meant to show a basic implementation of sitmo.

#include <Rcpp.h>
#include <random>  // C++11 RNG library
#include <sitmo.h> // SITMO PPRNG

// Rcpp depends attribute is required for standalone use. 
// It is not needed if in package linking to the sitmo package (detailed next).
// [[Rcpp::depends(sitmo)]]

// [[Rcpp::export]]
Rcpp::NumericVector sitmo_draws_ex(unsigned int n) {

  Rcpp::NumericVector o(n);

  // Create a prng engine
  sitmo::prng eng;

  // Draw from base engine
  for (unsigned int i=0; i< n ; ++i){
    o(i) = eng();  
  }

  return o;
}

/*** R
sitmo_draws_ex(5)
*/

threefry Engine Example

Below is a hello world example meant to show a basic implementation of threefry. This engine requires C++11.

#include <Rcpp.h>
#include <threefry.h>

// Rcpp depends attribute is required for standalone use. 
// It is not needed if in package linking to the sitmo package (detailed next).
// [[Rcpp::depends(sitmo)]]

// threefry requires access to a C++11 compatible compiler
// [[Rcpp::plugins(cpp11)]]

// [[Rcpp::export]]
void threefry_draws_streaming(unsigned int n) {
    sitmo::threefry eng1, eng2; 

    eng1.seed(0);  // reset the first engine (not really necessary)
    eng2.seed(1);  // 2nd engine gets a different seed

    Rcpp::Rcout << "\nTwo independent streams.\n";
    for (unsigned int i = 0; i < n; ++i)
        Rcpp::Rcout << eng1() << " " << eng2() << "\n";
}

vandercorput Engine Example

Below is a hello world example meant to show a basic implementation of vandercorput. This engine requires C++11.

#include <Rcpp.h>
#include <vandercorput.h>

// Rcpp depends attribute is required for standalone use. 
// It is not needed if in package linking to the sitmo package (detailed next).
// [[Rcpp::depends(sitmo)]]

// vandercorput requires access to a C++11 compatible compiler
// [[Rcpp::plugins(cpp11)]]

// [[Rcpp::export]]
void vandercorput_draws_streaming(unsigned int n) {
    sitmo::vandercorput eng;
    for (unsigned int i = 0; i < n; ++i)
        Rcpp::Rcout << eng() << "\n"; 
}

Package usage

To use sitmo in your R package, modify the DESCRIPTION file by adding:

LinkingTo: Rcpp, sitmo
Imports:
    Rcpp (>= 0.12.11)

To use C++11’s statistical distributions, you may want to add the following to your src/Makevars and src/Makevars.win file:

CXX_STD = CXX11

Within a C++ file in src/, then add:

#include <Rcpp.h>
#include <sitmo.h>      // SITMO for C++98 & C++11 PPRNG
#include <threefry.h>   // THREEFRY C++11-only PPRNG
#include <vandercorput> // VANDERCORPUT C++11-only Low-discrepancy sequence

You do not need to add each header file. Pick and choose the appropriate engine for your needs.

Functions in sitmo

Name Description
sitmo_engine_reset Example Seed Set and RNG Draws with sitmo
sitmo_engine_seed Example Seed Set and RNG Draws with sitmo
sitmo-package sitmo: Parallel Pseudo Random Number Generator (PPRNG) 'sitmo' Header Files
sitmo_draws Example RNG Draws with sitmo
sitmo_parallel Test Generation using sitmo and C++11
sitmo_two_seeds Two RNG engines running side-by-side
runif_r Random Uniform Number Generator using base R
runif_sitmo Random Uniform Number Generator with sitmo
No Results!

Vignettes of sitmo

Name
big_crush_test.Rmd
sitmo_internals.Rmd
uniform_rng_with_sitmo.Rmd
No Results!

Last month downloads

Details

URL https://github.com/coatless/sitmo, http://thecoatlessprofessor.com/projects/sitmo/, https://github.com/stdfin/random/
BugReports https://github.com/coatless/sitmo/issues
License MIT + file LICENSE
LazyData true
LinkingTo Rcpp
RoxygenNote 6.1.1
VignetteBuilder knitr
Encoding UTF-8
NeedsCompilation yes
Packaged 2019-01-04 18:21:27 UTC; ronin
Repository CRAN
Date/Publication 2019-01-07 21:40:07 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/sitmo)](http://www.rdocumentation.org/packages/sitmo)