Overview

RcppGSL provides an interface from R to the vector and matrix classes of the GNU GSL, a collection of numerical routines for scientifc computing.

It is particularly useful for C and C++ programs as it provides a standard C interface to a wide range of mathematical routines such as special functions, permutations, combinations, fast fourier transforms, eigensystems, random numbers, quadrature, random distributions, quasi-random sequences, Monte Carlo integration, N-tuples, differential equations, simulated annealing, numerical differentiation, interpolation, series acceleration, Chebyshev approximations, root-finding, discrete Hankel transforms physical constants, basis splines and wavelets. There are over 1000 functions in total with an extensive test suite.

The RcppGSL package provides an easy-to-use interface between GSL data structures and GNU R using concepts from Rcpp which is itself a package that eases the interfaces between R and C++.

What can RcppGSL do?

The RcppGSL package does a few things, in particular for vectors and matrices:
  • templated vector and matrix classes: these are similar to Rcpp's own vector and matrix classes, but really are just smart pointers around the C structure expected by the library
  • this means you can transfer data from R to your GSL-using programs in pretty much the same way you would in other C++ programs using Rcpp---by relying on the Rcpp::as() and Rcpp::wrap() converterrs
  • at the C++ level you can use these GSL vectors in a more C++-alike way (using eg foo[i] to access an element at index i)
  • yet at the same time you can just pass these vector and matrix objects to the GSL functions expecting its C objects: thanks to some cleverness in these classes they pass the right object on (see the example below)
  • we also provide the lightweight views for vectors and matrices as the GSL API uses these in many places.

In sum, these features aim to make it a lot easier to use functionality from the (excellent) GNU GSL in a way that is more natural to a user of C++ and R (and of course Rcpp). The package vignette. has a few more details.

So give me an example!

Here is a simple implementation of a column norm (which we could easily compute directly in R, but we are simply re-using an example from Section 8.4.14 of the GSL manual).

#include <RcppGSL.h>
#include <gsl/gsl_matrix.h>
#include <gsl/gsl_blas.h>

extern "C" SEXP colNorm(SEXP sM) {

  try {

        RcppGSL::matrix<double> M = sM;     // create gsl data structures from SEXP
        int k = M.ncol();
        Rcpp::NumericVector n(k);           // to store results

        for (int j = 0; j < k; j++) {
            RcppGSL::vector_view<double> colview = gsl_matrix_column (M, j);
            n[j] = gsl_blas_dnrm2(colview);
        }
        M.free() ;
        return n;                           // return vector

  } catch( std::exception &ex ) {
        forward_exception_to_r( ex );

  } catch(...) {
        ::Rf_error( "c++ exception (unknown reason)" );
  }
  return R_NilValue; // -Wall
}
This example shows how a RcppGSL matrix object (templated to a double) gets intialised from the matrix passed down from R. We then read the number of columns from a member function ncol() (using the same name as in R). We assign a standard Rcpp vector of the corresponding size k.

To compute the column norms, we loop over all columns. The norm is computed after we extract a col as a view (see the GSL manual for details: this is essentially a lightweight slice referring back to the original object). This column can be passed directly to a GSL function expecting a vector -- very nice. The actual computation is done by a standard GSL function, here gsl_blas_dnrm2, which expects a standard GSL vector -- which our classes transparently provide in this context.

Before returning the result, we then free the memory of the matrix object (something we have to do here as the objects are C-alike and cannot do the reference counting tricks we can do in C++) and return the result vector. All this is wrapped in a try/catch block as is standard with Rcpp.

Another example function for a faster compiled implementation of lm() using the model fitting code in the GSL is also included in the package.

Where do I get it

RcppGSL is now a CRAN package, lives otherwise in its own habitat on R-Forge within Rcpp and can also be downloaded from the local Rcpp archive which also has a copy of the vignette describing the package.

Authors

RcppGSL is being written by Dirk Eddelbuettel and Romain Francois using Rcpp.

License

RcppGSL is licensed under the GNU GPL version 2 or later.

Last modified: Tue Nov 30 21:31:07 CST 2010