bring back 'mapReduce'; tweak examples, etc

Author: kevinushey

examples/boost-simd-abssum.cpp

@@ -11,7 +11,7 @@ double simd_abssum(NumericVector x)
    using boost::simd::load;
    using boost::simd::aligned_load;
 
-   typedef std::vector< double, boost::simd::allocator<double> > vector_type;
+   typedef std::vector<double, boost::simd::allocator<double>> vector_type;
    typedef pack<double> packed_type;
 
    vector_type data(x.begin(), x.end());

examples/boost-simd-accumulate.cpp

@@ -1,5 +1,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#define RCPP_PARALLEL_USE_SIMD 1
+#define RCPP_PARALLEL_USE_SIMD
 #include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;

examples/boost-simd-capabilities.cpp

@@ -1,5 +1,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#define RCPP_PARALLEL_USE_SIMD 1
+#define RCPP_PARALLEL_USE_SIMD
 #include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;

examples/boost-simd-dot.cpp

@@ -1,5 +1,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#define RCPP_PARALLEL_USE_SIMD 1
+#define RCPP_PARALLEL_USE_SIMD
 #include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;

examples/boost-simd-hello-world.cpp

@@ -1,5 +1,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#define RCPP_PARALLEL_USE_SIMD 1
+#define RCPP_PARALLEL_USE_SIMD
 #include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;

examples/boost-simd-transform.cpp

@@ -1,5 +1,5 @@
 // [[Rcpp::depends(RcppParallel)]]
-#define RCPP_PARALLEL_USE_SIMD 1
+#define RCPP_PARALLEL_USE_SIMD
 #include <RcppParallel.h>
 #include <Rcpp.h>
 using namespace Rcpp;

examples/rcpp-simd-transform.cpp

@@ -11,24 +11,27 @@ vignette: >
 
 ## 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, they are
-often unable to reason about whether or not a particular block of code can be
-executed using SIMD instructions.
-
-`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`.
+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, they are often unable to reason about whether or
+not a particular block of code can be executed using SIMD
+instructions.
+
+`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`.
 
 ```{r, engine='Rcpp'}
 // [[Rcpp::depends(RcppParallel)]]
-#define RCPP_PARALLEL_USE_SIMD 1
+#define RCPP_PARALLEL_USE_SIMD
 #include <RcppParallel.h>
 #include <Rcpp.h>
 
@@ -46,7 +49,6 @@ struct add_two {
 
 // [[Rcpp::export]]
 double simd_sum(NumericVector x) {
-   
    return boost::simd::accumulate(x.begin(), x.end(), 0.0, add_two());
 }
 ```
@@ -62,48 +64,65 @@ if (requireNamespace("microbenchmark", quietly = TRUE)) {
 
 ## SIMD Algorithms
 
-Boost.SIMD provides two primary abstractions for the implementation of 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.
+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.
 
 ## 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 the **BH** package as a LinkingTo dependency
-2. Add C++11 as a SystemRequirement
+To build an R package that uses `Boost.SIMD`, you need to
+make some modifications to the standard RcppParallel 
+configuration. Within the `DESCRIPTION` file of your package,
+you need to:
 
+1. Add the **BH** package as a `LinkingTo` dependency, and
+2. Add `C++11` as a `SystemRequirement`
 
 ### 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 (even if you defined it explicitly). This allows you to write code like this:
+`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 otherwise.
+
+You can opt-in to the use of `Boost.SIMD` by defining the 
+`RCPP_PARALLEL_USE_SIMD` macro before including
+`<RcppParallel.h>`, e.g.
+
+    #define RCPP_PARALLEL_USE_SIMD
+    
+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 (even if you defined it explicitly). This allows
+you to write code like this:
 
 ```cpp
-#define RCPP_PARALLEL_USE_SIMD 1
+#define RCPP_PARALLEL_USE_SIMD
 #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
@@ -115,9 +134,14 @@ IntegerVector transformData(IntegerVector 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. 
+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).
+Note that if you conditionally compile all uses of
+`Boost.SIMD` within your package, then you can drop
+the `C++11` from `SystemRequirements` (it's no longer
+required as a result of your fallback implementation).