RcppNT2

RcppNT2 is an R package that provides bindings to the Numerical Template Toolbox (NT2). It provides a framework for implementing highly optimizable algorithms, taking advantage of SIMD instructions when possible, and falling back to scalar operations when not.

Overview

NT2 is an open source C++ library aimed at simplifying the development, debugging and optimization of high-performance computing applications by providing a Matlab-like syntax that eases the transition between prototype and actual application.

NT2 provides with a large toolbox of algorithms, facilitating scientific computing for many tasks. By including <RcppNT2.h>, these functions are all made available as part of the nt2 namespace, and so are immediately ready to use. A quick glance at the types of functions available:

  • Arithmetic: Most of the arithmetic operations you are familiar with will be provided by NT2: as a sampling, we have sum(), prod(), abs(), floor(), ceil(), sqrt(), sqr() exp(), pow() and log().

  • Bitwise: Bitwise operators are provided in the nt2 namespace, prefixed with bitwise_. For example, nt2::bitwise_and() can be used to perform the logical equivalent of the & operator. These functions also work with floating point types.

  • Trigonometric: All of sin(), cos() and tan() are provided within the nt2 namespace, alongside their inverses asin(), acos(), and atan(). The trigonometric inverses (sec(), csc(), cot()) are provided as well.

The full collection can be browsed within the NT2 User Manual – it’s worth taking a quick look at an overview for each toolset, to get an idea of what functions are provided.

Articles

The Rcpp Gallery hosts a number of stand-alone articles describing how Rcpp and its various extensions can be used. A number of articles introducing RcppNT2 are provided as well:

Examples

RcppNT2 also comes with a number of standalone examples, which we hope will help demonstrate how the package can be used. Try running the examples yourself with Rcpp::sourceCpp(), and then iterate to get a better feel for how RcppNT2 can be used.

  • Using simdTransform() — demonstrates how simdTransform() can be used to compute the vectorized addition of two vectors.

  • Using simdFor() — demonstrates how simdFor() can be used, alongside a stateful functor, to compute the product of a set of numbers.

  • Variadic simdFor() — demonstrates how the variadic flavor of simdFor() can be used to handle arbitrary number of vector inputs.

  • Handling Missing Values — demonstrates how missing values can be handled. The variance of a vector of numbers is computed, with missing values omitted.

After you’ve browsed through a couple examples, take a look at the Quick Reference to learn more.

Getting Started

You can install the RcppNT2 package from GitHub using devtools:

devtools::install_github("RcppCore/RcppNT2")

If you’re using RStudio, consider downloading the RStudio Preview first: the NT2 library makes extensive use of C++ template metaprogramming; unfortunately, this causes huge slowdowns in the libclang diagnostics engine, which powers the diagnostics behind C++ files open in RStudio. The preview version adds some provisions to ensure this does not happen.

sourceCpp

Add the following to a standalone C++ source file to import RcppNT2:

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

When you compile a file using Rcpp::sourceCpp(), the required compiler and linker settings for RcppNT2 will be automatically included in the compilation.

Many of the optimizations underlying NT2 are made possible through the use of C++ template metaprogramming techniques. As a consequence, it can often take a very long time to compile translation units that include <RcppNT2.h>.

You can use RcppNT2::precompileRcppNT2() to generate a pre-compiled header, which Rcpp::sourceCpp() will automatically include and use as appropriate. This can improve compile times by up to ~5x in translation units including the <RcppNT2.h> header.

R Packages

Because RcppNT2 is a header-only library, using it in client R packages is easy. Just ensure you have the following in your DESCRIPTION file:

LinkingTo: RcppNT2, BH (>= 1.60.0)
SystemRequirements: C++11

After you’ve added the above to the package you can simply include the main RcppNT2 package header in source files that need to use it:

#include <RcppNT2.h>