RcppParallel

https://rcppcore.github.io/RcppParallel/
Admin
RcppParallel provides a complete toolkit for creating portable, high-performance parallel algorithms...
Tokens:5,113
Snippets:36
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Use proportion of cores with defaultNumThreads

Source: https://rcppcore.github.io/RcppParallel/index.html

Use defaultNumThreads to set threads as a proportion of available cores. This example uses half of the available cores.

```r
library(RcppParallel)
setThreadOptions(numThreads = defaultNumThreads() / 2)
```

--------------------------------

### Install RcppParallel from CRAN

Source: https://rcppcore.github.io/RcppParallel/index.html

Run in R to install the RcppParallel package from CRAN.

```r
install.packages("RcppParallel")
```

--------------------------------

### R package setup - edit DESCRIPTION, NAMESPACE, Makevars, Makevars.win

Source: https://rcppcore.github.io/RcppParallel/index.html

Required file edits to use RcppParallel from within an R package. DESCRIPTION adds imports and linking; NAMESPACE imports a helper function; Makevars and Makevars.win add compiler/linker flags, with the Windows variant requiring an extra TBB enable flag.

```text
Imports: RcppParallel
LinkingTo: RcppParallel
SystemRequirements: GNU make
```

```r
importFrom(RcppParallel, RcppParallelLibs)
```

```makefile
PKG_LIBS += $(shell ${R_HOME}/bin/Rscript -e "RcppParallel::RcppParallelLibs()")
```

```makefile
PKG_CXXFLAGS += -DRCPP_PARALLEL_USE_TBB=1

PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" \
              -e "RcppParallel::RcppParallelLibs()")
```

--------------------------------

### Benchmark parallel vs serial matrix sqrt

Source: https://rcppcore.github.io/RcppParallel/index.html

Benchmark the parallel matrix square root against the serial version using the rbenchmark package. The example allocates a matrix, verifies identical results, and runs a benchmark comparison.

```r
# allocate a matrix
m <- matrix(as.numeric(c(1:1000000)), nrow = 1000, ncol = 1000)

# ensure that serial and parallel versions give the same result
stopifnot(identical(matrixSqrt(m), parallelMatrixSqrt(m)))

# compare performance of serial and parallel
library(rbenchmark)
res <- benchmark(matrixSqrt(m),
                 parallelMatrixSqrt(m),
                 order="relative")
res[,1:4]
```

```output
                   test replications elapsed relative
2 parallelMatrixSqrt(m)          100   0.294    1.000
1         matrixSqrt(m)          100   0.755    2.568
```

--------------------------------

### Set maximum threads with setThreadOptions

Source: https://rcppcore.github.io/RcppParallel/index.html

Use RcppParallel::setThreadOptions to allocate a fixed number of threads. This example sets a maximum of 4 threads.

```r
RcppParallel::setThreadOptions(numThreads = 4)
```

--------------------------------

### Set grain size in parallelReduce

Source: https://rcppcore.github.io/RcppParallel/index.html

Pass an additional parameter to parallelReduce to set the minimum chunk size for parallelization. The default grain size is 1; this example prevents threads from processing fewer than 100 items.

```cpp
parallelReduce(0, x.length(), sum, 100);
```

--------------------------------

### Create thread-safe accessors for input and output vectors

Source: https://rcppcore.github.io/RcppParallel/index.html

Wrap both the input vector and an allocated output vector with RVector<int> so parallel code can safely read and write. The output vector is created with Rcpp before wrapping.

```cpp
// [[Rcpp::export]]
IntegerVector transformVector(IntegerVector x) {
  RVector<int> input(x);        // create threadsafe wrapper to input
  IntegerVector y(x.size());    // allocate output vector
  RVector<int> output(y);       // create threadsafe wrapper to output
  
  // ...transform vector in parallel ...
  
  return y;
}
```

--------------------------------

### parallelReduce with Sum Worker

Source: https://rcppcore.github.io/RcppParallel/index.html

Defines a Worker that sums a vector using parallelReduce. The Worker must provide a standard constructor, a splitting constructor (taking a Split argument), an operator() that accumulates values, and a join method to combine results. The second block shows the exported Rcpp function that initializes the Sum instance and calls parallelReduce.

```cpp
// [[Rcpp::depends(RcppParallel)]]
#include <RcppParallel.h>
using namespace RcppParallel;

struct Sum : public Worker
{   
   // source vector
   const RVector<double> input;
   
   // accumulated value
   double value;
   
   // constructors
   Sum(const NumericVector input) : input(input), value(0) {}
   Sum(const Sum& sum, Split) : input(sum.input), value(0) {}
   
   // accumulate just the element of the range I've been asked to
   void operator()(std::size_t begin, std::size_t end) {
      value += std::accumulate(input.begin() + begin, input.begin() + end, 0.0);
   }
     
   // join my value with that of another Sum
   void join(const Sum& rhs) { 
      value += rhs.value; 
   }
};
```

```cpp
// [[Rcpp::export]]
double parallelVectorSum(NumericVector x) {
   
   // declare the Sum instance 
   Sum sum(x);
   
   // call parallel_reduce to start the work
   parallelReduce(0, x.length(), sum);
   
   // return the computed sum
   return sum.value;
}
```

--------------------------------

### parallelFor with SquareRoot Worker

Source: https://rcppcore.github.io/RcppParallel/index.html

Defines a Worker that computes the square root of each element in a matrix using parallelFor. The Worker must derive from RcppParallel::Worker and implement operator() with a [begin,end) range. The second block shows the exported Rcpp function that creates the worker and calls parallelFor.

```cpp
// [[Rcpp::depends(RcppParallel)]]
#include <RcppParallel.h>
using namespace RcppParallel;

struct SquareRoot : public Worker
{
   // source matrix
   const RMatrix<double> input;
   
   // destination matrix
   RMatrix<double> output;
   
   // initialize with source and destination
   SquareRoot(const NumericMatrix input, NumericMatrix output) 
      : input(input), output(output) {}
   
   // take the square root of the range of elements requested
   void operator()(std::size_t begin, std::size_t end) {
      std::transform(input.begin() + begin, 
                     input.begin() + end, 
                     output.begin() + begin, 
                     ::sqrt);
   }
};
```

```cpp
// [[Rcpp::export]]
NumericMatrix parallelMatrixSqrt(NumericMatrix x) {
  
  // allocate the output matrix
  NumericMatrix output(x.nrow(), x.ncol());
  
  // SquareRoot functor (pass input and output matrixes)
  SquareRoot squareRoot(x, output);
  
  // call parallelFor to do the work
  parallelFor(0, x.length(), squareRoot);
  
  // return the output matrix
  return output;
}
```

--------------------------------

### Include RcppParallel in standalone C++ file

Source: https://rcppcore.github.io/RcppParallel/index.html

Place at the top of a C++ source file to declare the dependency and include the main header. When compiled with Rcpp::sourceCpp, the required compiler and linker settings are added automatically.

```cpp
// [[Rcpp::depends(RcppParallel)]]
#include <RcppParallel.h>
```

--------------------------------

### Conditional TBB implementation with serial fallback using RCPP_PARALLEL_USE_TBB

Source: https://rcppcore.github.io/RcppParallel/tbb.html

Use this pattern in a CRAN package to provide a TBB-accelerated implementation with a serial fallback. The RCPP_PARALLEL_USE_TBB macro is defined in RcppParallel.h, which also includes <tbb/tbb.h> on supported platforms. Both branches define the same function name; only one is compiled based on the macro.

```cpp
#include <RcppParallel.h>

#if RCPP_PARALLEL_USE_TBB

IntegerVector transformDataImpl(IntegerVector x) {

  // Implement by calling TBB APIs directly 

}

#else

IntegerVector transformDataImpl(IntegerVector x) {

  // Implement serially

}

#endif

// [[Rcpp::export]]
IntegerVector transformData(IntegerVector x) {
  return transformDataImpl(x);
}
```

--------------------------------

### Include RcppParallel header in package source files

Source: https://rcppcore.github.io/RcppParallel/index.html

Add this include directive in any C++ file within the package that needs RcppParallel functionality.

```cpp
#include <RcppParallel.h>
```

--------------------------------

### Create a thread-safe accessor for an Rcpp vector

Source: https://rcppcore.github.io/RcppParallel/index.html

Construct an RVector<int> wrapper around an IntegerVector to safely access the underlying array from multiple threads. The R API must not be called inside parallel workers.

```cpp
// [[Rcpp::export]]
IntegerVector transformVector(IntegerVector x) {
  RVector<int> input(x);
  // etc...
}
```
Tokens:
Raw