RcppGSL: Rcpp Integration for GNU GSL Vectors and Matrices

Build Status License CRAN Debian package Downloads Last Commit

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 which are most often invoked automatically for you anyway
  • 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 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>

// [[Rcpp::export]]
Rcpp::NumericVector colNorm(const RcppGSL::Matrix & G) {
    int k = G.ncol();
    Rcpp::NumericVector n(k);           // to store results
    for (int j = 0; j < k; j++) {
        RcppGSL::VectorView colview = gsl_matrix_const_column (G, j);
        n[j] = gsl_blas_dnrm2(colview);
    }
    return n;                           // return vector
}

This example shows how a RcppGSL::Matrix object (a typedef shortcut to the templated double representation) gets passed down from R; we can use standard const & interface as well. Inside the function 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 hold the result which is returned to R.

To compute the column norms, we loop over all columns. The norm is computed after we extract a column as a const 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.

Previous versions then had to free the memory of the matrix object; this is now done automagically. By using Rcpp Attributes, 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 a CRAN package, lives otherwise in its own habitat at GitHub 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.

Initially created: Thu Mar 11 11:14:31 CST 2010
Last modified: Fri Jul 31 16:12:54 CDT 2020