[Rcpp-commits] r1222 - in pkg/RcppGSL/inst: . doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu May 13 14:08:40 CEST 2010
Author: romain
Date: 2010-05-13 14:08:39 +0200 (Thu, 13 May 2010)
New Revision: 1222
Added:
pkg/RcppGSL/inst/doc/
pkg/RcppGSL/inst/doc/Makefile
pkg/RcppGSL/inst/doc/RcppGSL.Rnw
Log:
first pass at a small vignette
Added: pkg/RcppGSL/inst/doc/Makefile
===================================================================
--- pkg/RcppGSL/inst/doc/Makefile (rev 0)
+++ pkg/RcppGSL/inst/doc/Makefile 2010-05-13 12:08:39 UTC (rev 1222)
@@ -0,0 +1,12 @@
+
+all: clean index.html RcppGSL.pdf
+
+clean:
+ touch RcppGSL.pdf
+ rm RcppGSL.pdf
+
+RcppGSL.pdf:
+ R CMD Sweave RcppGSL.Rnw
+ Rscript -e "tools::texi2dvi( 'RcppGSL.tex', pdf = TRUE, clean = TRUE )"
+ rm -fr RcppGSL.tex
+
Added: pkg/RcppGSL/inst/doc/RcppGSL.Rnw
===================================================================
--- pkg/RcppGSL/inst/doc/RcppGSL.Rnw (rev 0)
+++ pkg/RcppGSL/inst/doc/RcppGSL.Rnw 2010-05-13 12:08:39 UTC (rev 1222)
@@ -0,0 +1,241 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{RcppGSL}
+
+\usepackage{url}
+\usepackage[colorlinks]{hyperref}
+\setlength{\oddsidemargin}{0pt}
+\setlength{\textwidth}{17cm} % uh-oh, I use letter :)
+
+<<echo=FALSE,print=FALSE>>=
+library( "RcppGSL" )
+options("width"=65)
+rcppgsl.version <- packageDescription( "RcppGSL" )$Version
+prettyDate <- format(Sys.Date(), "%B %e, %Y")
+@
+% closing $ needed here
+
+
+\usepackage[colorlinks]{hyperref}
+\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
+\title{RcppGSL}
+\date{Version \Sexpr{rcppgsl.version} as of \Sexpr{prettyDate}}
+
+\begin{document}
+\maketitle
+
+\abstract{
+ \noindent
+ The GNU Scientific Library \texttt{GSL} is a numerical library for
+ C and C++ programmers. It is free software under the GNU General Public License.
+ The library provides a wide range of mathematical routines such as random number
+ generators, special functions and least-squares fitting.
+ There are over 1000 functions in total with an extensive test suite.
+
+ The \texttt{Rcpp} package is a simple package that provides a bridge
+ between \texttt{GSL} data structures and \texttt{Rcpp}.
+}
+
+\section{vectors}
+
+\subsection{gsl vectors}
+
+\texttt{GSL} defines various vector types to manipulate one-dimensionnal
+data, similar to R arrays. For example the \verb|gsl_vector| and \verb|gsl_vector_int|
+structs are defined as:
+
+\begin{verbatim}
+typedef struct{
+ size_t size;
+ size_t stride;
+ double * data;
+ gsl_block * block;
+ int owner;
+} gsl_vector;
+
+typedef struct {
+ size_t size;
+ size_t stride;
+ int *data;
+ gsl_block_int *block;
+ int owner;
+}
+gsl_vector_int;
+\end{verbatim}
+
+A typical use of the \verb|gsl_vector| struct is given below:
+
+\begin{verbatim}
+int i;
+
+// allocate a gsl_vector of size 3
+gsl_vector * v = gsl_vector_alloc (3);
+
+// fill the vector
+for (i = 0; i < 3; i++) {
+ gsl_vector_set (v, i, 1.23 + i);
+}
+
+// access elements
+double sum = 0.0 ;
+for (i = 0; i < 3; i++) {
+ sum += gsl_vector_set( v, i ) ;
+}
+
+// free the memory
+gsl_vector_free (v);
+\end{verbatim}
+
+\subsection{RcppGSL::vector}
+
+\texttt{RcppGSL} defines the template \texttt{RcppGSL::vector<T>} to manipulate
+\verb|gsl_vector| pointers taking advantage of C++ templates. Using the
+template the previous example becomes:
+
+\begin{verbatim}
+int i;
+
+// allocate a gsl_vector of size 3
+RcppGSL::vector<double> v(3);
+
+// fill the vector
+for (i = 0; i < 3; i++) {
+ gsl_vector_set (v, i, 1.23 + i);
+}
+
+// access elements
+double sum = 0.0 ;
+for (i = 0; i < 3; i++) {
+ sum += gsl_vector_set( v, i ) ;
+}
+
+// free the memory
+v.free() ;
+\end{verbatim}
+
+The class \texttt{RcppGSL::vector<double>} is a smart pointer, that can be used
+anywhere where a raw pointer \verb|gsl_vector| can be used, such as the
+\verb|gsl_vector_set| and \verb|gsl_vector_get| functions above.
+
+Beyond the convenience of a nicer syntax for allocation and release of memory,
+the \texttt{RcppGSL::vector} template faciliates interchange of \texttt{GSL}
+vectors with \texttt{Rcpp} concepts. The following example defines a \texttt{.Call}
+compatible function called \verb|sum_gsl_vector_int|
+that operates on a \verb|gsl_vector_int| through the \texttt{RcppGSL::vector<int>}
+template specialization:
+
+\begin{verbatim}
+RCPP_FUNCTION_1( int, sum_gsl_vector_int, RcppGSL::vector<int> vec){
+ int n = vec->size ;
+ int res ;
+ for( int i=0; i<n; i++){
+ res += gsl_vector_int_get( vec, i ) ;
+ }
+ vec.free() ;
+ return res ;
+}
+\end{verbatim}
+
+The function can then simply be called from R :
+
+\begin{verbatim}
+> .Call( "sum_gsl_vector_int", 1:10 )
+[1] 55
+\end{verbatim}
+
+A second example shows a simple function that grabs elements of an
+R list as \verb|gsl_vector| objects using implicit conversion mechanisms
+of Rcpp
+
+\begin{verbatim}
+RCPP_FUNCTION_1( double, gsl_vector_sum_2, Rcpp::List data ){
+ // grab "x" as a gsl_vector through
+ // the RcppGSL::vector<double> class
+ RcppGSL::vector<double> x = data["x"] ;
+
+ // grab "y" as a gsl_vector through
+ // the RcppGSL::vector<int> class
+ RcppGSL::vector<int> y = data["y"] ;
+ double res = 0.0 ;
+ for( int i=0; i< x->size; i++){
+ res += gsl_vector_get( x, i) * gsl_vector_int_get( y, i) ;
+ }
+
+ // as usual with GSL, we need to explicitely free the
+ // memory
+ x.free() ;
+ y.free() ;
+
+ // return the result
+ return res ;
+}
+\end{verbatim}
+
+called from R :
+
+\begin{verbatim}
+> data <- list( x = seq(0,1,length=10), y = 1:10 )
+> .Call( "gsl_vector_sum_2", data )
+[1] 36.66667
+\end{verbatim}
+
+
+\subsection{Mapping}
+
+\begin{table}
+\centering
+\begin{small}
+\begin{tabular}{ll}
+\hline
+gsl vector & RcppGSL \\
+\hline
+\texttt{gsl\_vector} & \texttt{RcppGSL::vector<double>} \\
+\texttt{gsl\_vector\_int} & \texttt{RcppGSL::vector<int>} \\
+\texttt{gsl\_vector\_float} & \texttt{RcppGSL::vector<float>} \\
+\texttt{gsl\_vector\_long} & \texttt{RcppGSL::vector<long>} \\
+\texttt{gsl\_vector\_char} & \texttt{RcppGSL::vector<char>} \\
+\texttt{gsl\_vector\_complex} & \texttt{RcppGSL::vector<gsl\_complex>} \\
+\texttt{gsl\_vector\_complex\_float} & \texttt{RcppGSL::vector<gsl\_complex\_float>} \\
+\texttt{gsl\_vector\_complex\_long\_double} & \texttt{RcppGSL::vector<gsl\_complex\_long\_double>} \\
+\texttt{gsl\_vector\_long\_double} & \texttt{RcppGSL::vector<long double>} \\
+\texttt{gsl\_vector\_short} & \texttt{RcppGSL::vector<short>} \\
+\texttt{gsl\_vector\_uchar} & \texttt{RcppGSL::vector<unsigned char>} \\
+\texttt{gsl\_vector\_uint} & \texttt{RcppGSL::vector<unsigned int>} \\
+\texttt{gsl\_vector\_ushort} & \texttt{RcppGSL::vector<insigned short>} \\
+\texttt{gsl\_vector\_ulong} & \texttt{RcppGSL::vector<unsigned long>} \\
+
+\hline
+\end{tabular}
+\end{small}
+\caption{Correspondance between GSL vector types and templates defined
+in RcppGSL.}
+\end{table}
+
+\section{vector views}
+
+Several \texttt{GSL} algorithms return GSL vector views as result. \texttt{RcppGSL}
+defines implicit converters that allow vector views to be used in
+\texttt{Rcpp} data structures. For example, this code first creates
+a GSL vector, then extract the odd and even parts using GSL functions:
+
+\begin{verbatim}
+extern "C" SEXP test_gsl_vector_view(){
+ int n = 10 ;
+ gsl_vector *v = gsl_vector_calloc (n);
+ for( int i=0 ; i<n; i++){
+ gsl_vector_set( v, i, i ) ;
+ }
+ gsl_vector_view v_even = gsl_vector_subvector_with_stride(v, 0, 2, n/2);
+ gsl_vector_view v_odd = gsl_vector_subvector_with_stride(v, 1, 2, n/2);
+
+ List res = List::create(
+ _["even"] = v_even,
+ _["odd" ] = v_odd
+ ) ;
+ gsl_vector_free(v);
+
+ return res ;
+}
+\end{verbatim}
+
+\end{document}
+
More information about the Rcpp-commits
mailing list