add-rcpp-integration

Files (1)

• SKILL.md

SKILL.md (first lines)

# Add Rcpp Integration

Integrate C++ code into an R package using Rcpp for performance-critical operations.

## When to Use

- R function is too slow and profiling confirms a bottleneck
- Need to interface with existing C/C++ libraries
- Implementing algorithms that benefit from compiled code (loops, recursion)
- Adding RcppArmadillo for linear algebra operations

## Inputs

- **Required**: Existing R package
- **Required**: R function to replace or augment with C++
- **Optional**: External C++ library to interface with
- **Optional**: Whether to use RcppArmadillo (default: plain Rcpp)

## Procedure

### Step 1: Set Up Rcpp Infrastructure

```r
usethis::use_rcpp()
```

This:
- Creates `src/` directory
- Adds `Rcpp` to LinkingTo and Imports in DESCRIPTION
- Creates `R/packagename-package.R` with `@useDynLib` and `@importFrom Rcpp sourceCpp`
- Updates `.gitignore` for compiled files

For RcppArmadillo:

```r
usethis::use_rcpp_armadillo()
```

**Got:** `src/` directory created, DESCRIPTION updated with `Rcpp` in LinkingTo and Imports, and `R/packagename-package.R` contains `@useDynLib` directive.

**If fail:** If `usethis::use_rcpp()` fails, manually create `src/`, add `LinkingTo: Rcpp` and `Imports: Rcpp` to DESCRIPTION, and add `#' @useDynLib packagename, .registration = TRUE` and `#' @importFrom Rcpp sourceCpp` to the package-level documentation file.

### Step 2: Write C++ Function

Create `src/my_function.cpp`:

```cpp
#include <Rcpp.h>
using namespace Rcpp;

//' Compute cumulative sum efficiently
//'
//' @param x A numeric vector
//' @return A numeric vector of cumulative sums
//' @export
// [[Rcpp::export]]
NumericVector cumsum_cpp(NumericVector x) {
  int n = x.size();
  NumericVector out(n);
  out[0] = x[0];
  for (int i = 1; i < n; i++) {
    out[i] = out[i - 1] + x[i];
  }
  return out;
}
```

For RcppArmadillo:

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

//' Matrix multiplication using Armadillo
//'
//' @param A A numeric matrix
//' @param B A numeric matrix
//' @return The matrix product A * B
//' @export
// [[Rcpp::export]]
arma::mat mat_mult(const arma::mat& A, const arma::mat& B) {
  return A * B;
}
```

**Got:** C++ source file exists at `src/my_function.cpp` with valid `// [[Rcpp::export]]` annotation and roxygen-style `//'` documentation comments.

**If fail:** Verify the file uses `#include <Rcpp.h>` (or `<RcppArmadillo.h>` for Armadillo), that the export annotation is on its own line directly above the function signature, and that return types map to valid Rcpp types.

### Step 3: Generate RcppExports

```r
Rcpp::compileAttributes()
devtools::document()
```

**Got:** `R/RcppExports.R` and `src/RcppExports.cpp` generated automatically.

**If fail:** Check C++ syntax errors. Ensure `// [[Rcpp::export]]` tag is present above each exported function.

### Step 4: Verify Compilation

```r
devtools::load_all()
```

**Got:** Package compiles and loads without errors.

**If fail:** Check compiler output for errors. Common issues:
- Missing system headers: Install development libraries
- Syntax errors: C++ compiler messages point to the line
- Missing `Rcpp::depends` attribute for RcppArmadillo

### Step 5: Write Tests for Compiled Code

```r
test_that("cumsum_cpp matches base R", {
  x <- c(1, 2, 3, 4, 5)
  expect_equal(cumsum_cpp(x), cumsum(x))

From pjt222/agent-almanac, MIT.

More from pjt222/agent-almanac