Various refinements to Boost.SIMD implementation

jjallaire · jjallaire · commit db3517dd590f · 2016-01-15T08:35:05.000-05:00
- Opt-in via preprocessor variable (RCPP_PARALLEL_USE_SIMD) rather then dedicated include. This is more clear and enables dynamic use of SIMD where available with a fallback where it's not.

- Introduce LdFlags and CxxFlags functions for dynamic configuration from Makevars (more consistent with other packages in the Rcpp family)

- Remove explicit -mtune= (I found no difference between mtune=native and mtune=core2 on OS X). In any case this is really the business of the particular installation of R rather than an individual package.

- Add option to disable RStudio clang indexing to .Rprofile (expression templates are too much for the indexing engine).
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -1,5 +1,6 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^\.Rprofile$
 ^src/tbb/build/lib_.*$
 ^tests/testthat/pkg/RcppParallelTest/src/.*\.s?o$
 ^tests/testthat/pkg/RcppParallelTest/src/.*\.dll$
@@ -8,4 +9,4 @@
 ^README.md
 ^doc$
 ^src/.*\.o$
-^examples/
+^examples/
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -18,6 +18,7 @@ Description: High level functions for doing parallel programming with 'Rcpp'.
   For example, the parallelFor() function can be used to convert the work of 
   a standard serial "for" loop into a parallel one and the parallelReduce() 
   function can be used for accumulating aggregate or other values.
+Depends: R (>= 3.0.2)
 Suggests:
     Rcpp,
     RUnit,
diff --git a/R/build.R b/R/build.R
@@ -1,23 +1,36 @@
 
 
+# Output the CXX flags. These flags are propagated to sourceCpp via the 
+# inlineCxxPlugin (defined below) and to packages via a line in Makevars[.win]
+# like this:
+#
+#  PKG_CXXFLAGS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "RcppParallel::CxxFlags()")
+#
+CxxFlags <- function(simd = FALSE) {
+   cat(tbbCxxFlags(simd = simd))
+}
+
+
 # Output the LD flags for building against TBB. These flags are propagated
 # to sourceCpp via the inlineCxxPlugin (defined below) and to packages 
-# via a line in Makevars.win like this:
+# via a line in Makevars[.win] like this:
 #
 #   PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "RcppParallel::LdFlags()")
 #
-# Note that this is only required for Windows builds (on Linux and OS X no 
-# explicit link to TBB is required).
-RcppParallelLibs <- function() {
+LdFlags <- function() {
    cat(tbbLdFlags())
 }
 
+# alias for backward compatibility
+RcppParallelLibs <- function() {
+   LdFlags()
+}
 
-# Inline plugin used by sourceCpp to link to the TBB library
+# Inline plugin used by sourceCpp.
 inlineCxxPlugin <- function() {
    list(
       env = list(
-         PKG_CXXFLAGS = paste(tbbCxxFlags(), mtuneFlags()),
+         PKG_CXXFLAGS = paste(tbbCxxFlags()),
          PKG_LIBS = tbbLdFlags()
       ),
       includes = "#include <RcppParallel.h>",
@@ -27,19 +40,19 @@ inlineCxxPlugin <- function() {
    )
 }
 
-mtuneFlags <- function() {
-   switch(Sys.info()[["sysname"]],
-          "Linux"   = "-mtune=native",
-          "Darwin"  = "-mtune=core2",
-          "Windows" = "-mtune=core2",
-          ""
-   )
-}
-
-tbbCxxFlags <- function() {
+tbbCxxFlags <- function(simd = FALSE) {
+   
+   # request use of C++11 when possible
    flags <- "$(CXX1XSTD)"
+   
+   # opt-in to TBB on Windows
    if (Sys.info()['sysname'] == "Windows")
       flags <- paste(flags, "-DRCPP_PARALLEL_USE_TBB=1")
+   
+   # reflect requested use of boost::simd
+   if (isTRUE(simd))
+      flags <- paste(flags, "-DRCPP_PARALLEL_USE_SIMD=1")
+   
    flags
 }
 
diff --git a/examples/.gitignore b/examples/.gitignore
@@ -0,0 +1 @@
+*.html
diff --git a/examples/boost-simd-abssum.cpp b/examples/boost-simd-abssum.cpp
@@ -1,5 +1,6 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;
 
diff --git a/examples/boost-simd-accumulate.cpp b/examples/boost-simd-accumulate.cpp
@@ -1,5 +1,6 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;
 
diff --git a/examples/boost-simd-capabilities.cpp b/examples/boost-simd-capabilities.cpp
@@ -1,5 +1,6 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;
 
diff --git a/examples/boost-simd-dot.cpp b/examples/boost-simd-dot.cpp
@@ -1,5 +1,6 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;
 
diff --git a/examples/boost-simd-hello-world.cpp b/examples/boost-simd-hello-world.cpp
@@ -1,5 +1,6 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;
 
diff --git a/examples/boost-simd-transform.cpp b/examples/boost-simd-transform.cpp
@@ -1,5 +1,6 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;
 
diff --git a/examples/rcpp-simd-transform.cpp b/examples/rcpp-simd-transform.cpp
@@ -1,5 +1,6 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 
 using namespace Rcpp;
diff --git a/examples/simd-operations.Rmd b/examples/simd-operations.Rmd
@@ -9,15 +9,18 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ---
 
+## SIMD Basics
+
 Modern CPU processors are built with new, extended instruction sets that optimize for certain operations. A class of these allow for vectorized operations, called Single Instruction / Multiple Data (SIMD) instructions. Although modern compilers will use these instructions when possible, it is often not possible for the compiler to reason about whether or not a particular block of code can be executed using SIMD instructions.
 
-`Boost.SIMD` is a C++ header-only libary that makes it possible to explicitly request the use of SIMD instructions when possible, while falling back to regular scalar operations if not. `RcppParallel` wraps and exposes this library for use with R vectors.
+`Boost.SIMD` is a C++ header-only library that makes it possible to explicitly request the use of SIMD instructions when possible, while falling back to regular scalar operations if not. `RcppParallel` wraps and exposes this library for use with R vectors.
 
-Here's a quick example of how we might compute the sum of elements in a vector, using `Boost.SIMD`. 
+Here's a quick example of how we might compute the sum of elements in a vector, using `Boost.SIMD`. Note that we've added `#define RCPP_PARALLEL_USE_SIMD 1` before including `RcppParallel.h` since SIMD features are not included by default. 
 
 ```{r, engine='Rcpp'}
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 
 using namespace RcppParallel;
@@ -48,18 +51,22 @@ if (requireNamespace("microbenchmark", quietly = TRUE)) {
 }
 ```
 
+
+## SIMD Algorithms
+
 Boost.SIMD provides two primary abstractions for the implementation of SIMD algorithms:
 
 - `simd::accumulate()`, for vector -> scalar transformations, and
 - `simd::transform()`,  for vector -> vector transformations.
 
 These functions operate like their `std::` counterparts, but expect a functor with a templated call operator. By making the call operator templated, `Boost.SIMD` can generate code using its own optimized SIMD functions when appropriate, and fall back to a default implementation (based on the types provided) when not.
 
-`Boost.SIMD` also provides a number of builtin functions, which can be used effectively with `simd::accumulate()` or `simd::transform()`. For example, let's use SIMD instructions to compute the minimum:
+`Boost.SIMD` also provides a number of built in functions, which can be used effectively with `simd::accumulate()` or `simd::transform()`. For example, let's use SIMD instructions to compute the minimum:
 
 ```{r, engine='Rcpp'}
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#define RCPP_PARALLEL_USE_SIMD 1
+#include <RcppParallel.h>
 #include <Rcpp.h>
 
 #include <boost/simd/arithmetic/functions/min.hpp>
@@ -71,4 +78,92 @@ using namespace Rcpp;
 NumericVector simd_min(NumericVector data) {
    return simd::transform(data, boost::simd::tag::min_());
 }
-```
+```
+
+## Using SIMD in an R Package
+
+To build an R package that uses Boost.SIMD you need to make some modifications to the standard RcppParallel configuration:
+
+1. Add definitions to `PKG_CXXFLAGS` to opt-in to Boost.SIMD 
+2. Add the **BH** package as a LinkingTo dependency
+
+Here's the complete recipe for using RcppParallel with Boost.SIMD in an R package:
+
+**DESCRIPTION**
+
+```yaml
+Imports: RcppParallel
+LinkingTo: RcppParallel, BH
+SystemRequirements: GNU make
+```
+
+**NAMESPACE**
+
+```R
+importFrom(RcppParallel, RcppParallelLibs)
+```
+
+**src/Makevars**
+
+```make
+PKG_CXXFLAGS += $(shell ${R_HOME}/bin/Rscript -e "RcppParallel::CxxFlags(simd = TRUE)")
+PKG_LIBS += $(shell ${R_HOME}/bin/Rscript -e "RcppParallel::LdFlags()")
+```
+
+**src/Makevars.win**
+
+```make
+PKG_CXXFLAGS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" \ 
+                   -e "RcppParallel::CxxFlags(simd = TRUE)")
+PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" \
+               -e "RcppParallel::LdFlags()")
+```
+
+### Platform Compatibility
+
+Note that Boost.SIMD requires a C++11 conformant compiler. This means that packages making use of SIMD features may not compile on platforms with older compilers including Windows and RedHat/CentOS Linux. You can however create a package that takes advantage of Boost.SIMD where available and falls back to a non-SIMD implementation elsewhere.
+
+The result of specifying `simd = TRUE` in Makevars to to define the `RCPP_PARALLEL_USE_SIMD` preprocessor variable. This is interpreted as a *request* for Boost.SIMD. If the current compiler doesn't support C++11 (as determined by `__cplusplus <= 199711L`) the variable will be undefined. This allows you to write code like this:
+
+```cpp
+#define RCPP_PARALLEL_USE_SIMD
+#include <RcppParallel.h>
+
+#if RCPP_PARALLEL_USE_SIMD
+
+#include <boost/simd/sdk/simd/pack.hpp>
+
+IntegerVector transformData(IntegerVector x) {
+
+  // Implement with Boost.SIMD
+
+}
+
+#else
+
+IntegerVector transformData(IntegerVector x) {
+
+  // Implement without Boost.SIMD
+
+}
+
+#endif
+```
+
+Note that the two functions have the same name (only one will be compiled and linked based on whether the target platform supports Boost.SIMD).
+
+
+
+
+
+
+
+
+
+
+   
+
+
+
+
+
diff --git a/inst/include/RcppParallel.h b/inst/include/RcppParallel.h
@@ -52,4 +52,12 @@ inline void parallelReduce(std::size_t begin, std::size_t end,
 
 } // namespace RcppParallel
 
+// Enable SIMD if requested (requires C++11)
+#if RCPP_PARALLEL_USE_SIMD && (__cplusplus <= 199711L)
+  #undef RCPP_PARALLEL_USE_SIMD
+#endif
+#if RCPP_PARALLEL_USE_SIMD
+  #include "RcppParallel/SIMD.h"
+#endif
+
 #endif // __RCPP_PARALLEL__
diff --git a/inst/include/RcppParallelSIMD.h b/inst/include/RcppParallelSIMD.h
diff --git a/man/RcppParallelFlags.Rd b/man/RcppParallelFlags.Rd
@@ -0,0 +1,32 @@
+\name{RcppParallelFlags}
+\alias{RcppParallelLibs}
+\alias{LdFlags}
+\alias{CxxFlags}
+\title{
+Compilation flags for RcppParallel
+}
+\description{
+Output the compiler or linker flags required to build against RcppParallel.
+}
+\usage{
+CxxFlags(simd = FALSE)
+LdFlags()
+RcppParallelLibs()
+}
+\arguments{
+  \item{simd}{
+      \code{TRUE} to enable use of Boost.SIMD.
+   }
+}
+\details{
+These functions are typically called from \code{Makevars} as follows:
+
+\code{PKG_LIBS += $(shell "${R_HOME}/bin/Rscript/" -e "RcppParallel::LdFlags()")}
+
+}
+
+\value{
+  Returns \code{NULL} invisibly. The function is not called for it's
+  return value rather for the side effect of outputting the flags.
+}
+
diff --git a/man/RcppParallelLibs.Rd b/man/RcppParallelLibs.Rd
