Merge pull request #21 from RcppCore/feature/boost-simd-refinements

jjallaire · jjallaire · commit 88abf0318f72 · 2016-01-15T16:49:09.000-05:00
Various refinements to Boost.SIMD implementation
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
@@ -12,12 +12,16 @@ Authors@R: c(
     person(family = "RStudio", role = "cph"),
     person(family = "Intel", role = c("aut", "cph"),
        comment = "Intel TBB library, https://www.threadingbuildingblocks.org/"),
-    person(family = "Microsoft", role = "cph")
+    person(family = "Microsoft", role = "cph"),
+    person("Joel", "Falcou", role = "aut"),
+    person(family = "UMR 8623 CNRS/Univ Paris Sud XI", role = "cph",
+      comment = "Boost.SIMD library, https://www.lri.fr/~falcou/pub/pact-2012.pdf")
     )
 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/NAMESPACE b/NAMESPACE
@@ -1,4 +1,7 @@
 export(setThreadOptions)
 export(defaultNumThreads)
 export(RcppParallelLibs)
+export(CxxFlags)
+export(LdFlags)
+
 
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 = TRUE) {
+   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("$(CXX1XSTD)", tbbCxxFlags()),
          PKG_LIBS = tbbLdFlags()
       ),
       includes = "#include <RcppParallel.h>",
@@ -27,19 +40,18 @@ inlineCxxPlugin <- function() {
    )
 }
 
-mtuneFlags <- function() {
-   switch(Sys.info()[["sysname"]],
-          "Linux"   = "-mtune=native",
-          "Darwin"  = "-mtune=core2",
-          "Windows" = "-mtune=core2",
-          ""
-   )
-}
-
-tbbCxxFlags <- function() {
-   flags <- "$(CXX1XSTD)"
+tbbCxxFlags <- function(simd = TRUE) {
+   
+   flags <- c()
+   
+   # 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 (!simd)
+      flags <- paste(flags, "-DRCPP_PARALLEL_USE_SIMD=0")
+   
    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,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#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,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#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,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#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,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#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,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#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,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#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,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#include <RcppParallel.h>
 #include <Rcpp.h>
 
 using namespace Rcpp;
diff --git a/examples/simd-operations.Rmd b/examples/simd-operations.Rmd
@@ -9,15 +9,17 @@ 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`.
 
 ```{r, engine='Rcpp'}
 // [[Rcpp::depends(RcppParallel)]]
-#include <RcppParallelSIMD.h>
+#include <RcppParallel.h>
 #include <Rcpp.h>
 
 using namespace RcppParallel;
@@ -48,18 +50,21 @@ 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>
+#include <RcppParallel.h>
 #include <Rcpp.h>
 
 #include <boost/simd/arithmetic/functions/min.hpp>
@@ -71,4 +76,113 @@ 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. Make sure you call the `CxxFlags` and `LdFlags` functions in `Makevars`
+2. Add the **BH** package as a LinkingTo dependency
+3. Add C++11 as a SystemRequirement
+
+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, C++11
+```
+
+**NAMESPACE**
+
+```R
+importFrom(RcppParallel, RcppParallelLibs)
+```
+
+**src/Makevars**
+
+```make
+PKG_CXXFLAGS += $(shell ${R_HOME}/bin/Rscript -e "RcppParallel::CxxFlags()")
+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()")
+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.
+
+You can test for the availability of Boost.SIMD on a given platform using the `RCPP_PARALLEL_USE_SIMD` preprocessor variable. 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
+#include <RcppParallel.h>
+
+#if RCPP_PARALLEL_USE_SIMD
+
+#include <boost/simd/sdk/simd/pack.hpp>
+
+IntegerVector transformDataImpl(IntegerVector x) {
+
+  // Implement with Boost.SIMD
+
+}
+
+#else
+
+IntegerVector transformDataImpl(IntegerVector x) {
+
+  // Implement without Boost.SIMD
+
+}
+
+#endif
+
+// [[Rcpp::export]]
+IntegerVector transformData(IntegerVector x) {
+   return transformDataImpl(x);
+}
+
+```
+
+The two `transformDataImpl` functions have the same name, but only one will be compiled and linked based on whether the target platform supports Boost.SIMD. 
+
+Note that if you conditionally compile all uses of Boost.SIMD within your package then you can actually drop the `C++11` from `SystemRequirements` (it's no longer required as a result of your fallback implementation).
+
+## Disabling SIMD
+
+If you don't want to use Boost.SIMD at all you can explicitly disable it as follows:
+
+1. For `sourceCpp` you can define `RCPP_PARALLEL_USE_TBB`:
+
+    ```cpp
+    #define RCPP_PARALLEL_USE_TBB 0
+    ```
+
+2. For R packages you can pass `simd = FALSE` to the CxxFlags function:
+
+    ```make
+    PKG_CXXFLAGS += $(shell ${R_HOME}/bin/Rscript -e "RcppParallel::CxxFlags(simd = FALSE)")
+    ```
+   
+
+   
+
+
+
+
+
+
+   
+
+
+
+
+
diff --git a/inst/include/RcppParallel.h b/inst/include/RcppParallel.h
@@ -52,4 +52,14 @@ inline void parallelReduce(std::size_t begin, std::size_t end,
 
 } // namespace RcppParallel
 
+// Auto enable/disable SIMD unless it's been explicitly set (requires C++11)
+#ifndef RCPP_PARALLEL_USE_SIMD
+#if (__cplusplus > 199711L)
+      #define RCPP_PARALLEL_USE_SIMD 1
+   #endif
+#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 = TRUE)
+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
