https://github.com/coatless-rpkg/sitmo
Sitmo parallel random number engine headers in an R package
https://github.com/coatless-rpkg/sitmo
parallel r random-generation rcpp
Last synced: 6 months ago
JSON representation
Sitmo parallel random number engine headers in an R package
- Host: GitHub
- URL: https://github.com/coatless-rpkg/sitmo
- Owner: coatless-rpkg
- License: other
- Created: 2016-03-03T20:23:08.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2023-11-14T08:22:06.000Z (over 1 year ago)
- Last Synced: 2024-11-24T19:48:29.880Z (6 months ago)
- Topics: parallel, r, random-generation, rcpp
- Language: C++
- Homepage: http://r-pkg.thecoatlessprofessor.com/sitmo/
- Size: 540 KB
- Stars: 7
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
README
---
output:
md_document:
variant: gfm
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
[](https://github.com/coatless-rpkg/sitmo/actions/workflows/R-CMD-check.yaml)
[](https://www.r-pkg.org/pkg/sitmo)
[](https://cran.r-project.org/package=sitmo)
# `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:
```r
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:
- [macOS](https://thecoatlessprofessor.com/programming/r-compiler-tools-for-rcpp-on-os-x/)
- [Windows](https://thecoatlessprofessor.com/programming/rcpp/install-rtools-for-rcpp/)
With a compiler in hand, one can then install the package from GitHub by:
```{r, echo = T, eval = F}
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`.
```cpp
#include
#include
// [[Rcpp::depends(sitmo)]]
```
To use the two other engines, `threefry` and `vandercorput`, they must be
loaded like:
```cpp
#include
#include // or use #include
// [[Rcpp::depends(sitmo)]]
// [[Rcpp::plugins(cpp11)]]
```
#### `sitmo` Engine Example
Below is a hello world example meant to show a basic implementation of `sitmo`.
```cpp
#include
#include // C++11 RNG library
#include // 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.
```cpp
#include
#include
// 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.
```cpp
#include
#include
// 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:
```{Rcpp, eval = FALSE}
#include
#include // SITMO for C++98 & C++11 PPRNG
#include // THREEFRY C++11-only PPRNG
#include // 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.