[Rcpp-commits] r3283 - pkg/RcppEigen/vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Nov 5 03:09:08 CET 2011
Author: edd
Date: 2011-11-05 03:09:08 +0100 (Sat, 05 Nov 2011)
New Revision: 3283
Added:
pkg/RcppEigen/vignettes/RcppEigen-intro-jss.tex
Log:
committed after just adding
Added: pkg/RcppEigen/vignettes/RcppEigen-intro-jss.tex
===================================================================
--- pkg/RcppEigen/vignettes/RcppEigen-intro-jss.tex (rev 0)
+++ pkg/RcppEigen/vignettes/RcppEigen-intro-jss.tex 2011-11-05 02:09:08 UTC (rev 3283)
@@ -0,0 +1,318 @@
+
+\documentclass[shortnames,article]{jss}
+%\VignetteIndexEntry{RcppEigen-intro}
+%\VignetteKeywords{linear algebra, template programming, C++, R, Rcpp}
+%\VignettePackage{RcppEigen}
+
+\usepackage{booktabs,flafter}
+
+\newcommand{\R}{\proglang{R}\ } % NB forces a space so not good before % fullstop etc.
+\newcommand{\Cpp}{\proglang{C++}\ }
+
+\author{Douglas Bates\\U Wisconsin/Madison \And Dirk Eddelbuettel\\Debian Project \And Romain Fran\c{c}ois\\R Enthusiasts}
+\title{An Introduction to \pkg{RcppEigen}}
+
+\Plainauthor{Douglas Bates, Dirk Eddelbuettel, Romain Fran\c{c}ois}
+\Plaintitle{An Introduction to RcppEigen}
+\Shorttitle{An Introduction to RcppEigen}
+
+\Abstract{
+ \noindent
+ \noindent
+ The \pkg{RcppEigen} package provides access from \proglang{R}
+ \citep{R:Main} to the \pkg{Eigen} \citep*{Eigen:Web} \proglang{C++}
+ template library for numerical linear algebra. \pkg{Rcpp}
+ \citep{JSS:Rcpp,CRAN:Rcpp} classes and specializations of the
+ \proglang{C++} templated functions \code{as} and \code{wrap} from
+ \pkg{Rcpp} provide the ``glue'' for passing objects from \proglang{R} to
+ \proglang{C++} and back.
+}
+
+\Keywords{Linear algebra, template programming, \proglang{R}, \proglang{C++}, \pkg{Rcpp}} %% at least one keyword must be supplied
+\Plainkeywords{Linear algebra, template programmig, R, C++, Rcpp} %% without formatting
+
+\Address{
+ Douglas Bates \\
+ Department of Statistics \\
+ University of Wisconsin - Madison \\
+ Madison, WI, USA \\
+ E-mail: \email{bates at stat.wisc.edu} \\
+ URL: \url{http://www.stat.wisc.edu/~bates/}\\
+
+ Dirk Eddelbuettel \\
+ Debian Project \\
+ River Forest, IL, USA\\
+ E-mail: \email{edd at debian.org}\\
+ URL: \url{http://dirk.eddelbuettel.com}\\
+
+ Romain Fran\c{c}ois\\
+ Professional R Enthusiast\\
+ 1 rue du Puits du Temple, 34 000 Montpellier\\
+ FRANCE \\
+ E-mail: \email{romain at r-enthusiasts.com}\\
+ URL: \url{http://romainfrancois.blog.free.fr}
+}
+
+%% need no \usepackage{Sweave.sty}
+
+\newcommand{\rank}{\operatorname{rank}}
+
+%% highlights macros
+%% Style definition file generated by highlight 2.7, http://www.andre-simon.de/
+% Highlighting theme definition:
+\newcommand{\hlstd}[1]{\textcolor[rgb]{0,0,0}{#1}}
+\newcommand{\hlnum}[1]{\textcolor[rgb]{0,0,0}{#1}}
+\newcommand{\hlopt}[1]{\textcolor[rgb]{0,0,0}{#1}}
+\newcommand{\hlesc}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
+%\newcommand{\hlstr}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
+\newcommand{\hlstr}[1]{\textcolor[rgb]{0.90,0.15,0.15}{#1}}
+%green: \newcommand{\hlstr}[1]{\textcolor[rgb]{0.13,0.67,0.13}{#1}} % 0.74 -> % 0.90; 0.55 -> 0.25
+\newcommand{\hldstr}[1]{\textcolor[rgb]{0.74,0.55,0.55}{#1}}
+\newcommand{\hlslc}[1]{\textcolor[rgb]{0.67,0.13,0.13}{\it{#1}}}
+\newcommand{\hlcom}[1]{\textcolor[rgb]{0.67,0.13,0.13}{\it{#1}}}
+\newcommand{\hldir}[1]{\textcolor[rgb]{0,0,0}{#1}}
+\newcommand{\hlsym}[1]{\textcolor[rgb]{0,0,0}{#1}}
+\newcommand{\hlline}[1]{\textcolor[rgb]{0.33,0.33,0.33}{#1}}
+\newcommand{\hlkwa}[1]{\textcolor[rgb]{0.61,0.13,0.93}{\bf{#1}}}
+\newcommand{\hlkwb}[1]{\textcolor[rgb]{0.13,0.54,0.13}{#1}}
+\newcommand{\hlkwc}[1]{\textcolor[rgb]{0,0,1}{#1}}
+\newcommand{\hlkwd}[1]{\textcolor[rgb]{0,0,0}{#1}}
+\definecolor{bgcolor}{rgb}{1,1,1}
+
+
+% ------------------------------------------------------------------------
+
+\begin{document}
+
+%\SweaveOpts{engine=R,eps=FALSE}
+
+\section{Introduction}
+\label{sec:intro}
+
+Linear algebra is an essential building block of statistical computing.
+Operations such as matrix decompositions, linear program solvers, and
+eigenvalue / eigenvector computations are used in many estimation and
+analysis routines. As such, libraries supporting linear algebra have long been
+provided by statistical programmers for different programming languages and
+environments. \proglang{C++}, one of the central modern languages for numerical
+and statistical computing, can be extended particularly well due to its
+object-oriented nature, and numerous class libraries providing linear algebra
+routines have been written over the years.
+% Could cite Eddelbuettel (1996) here, but a real survey would be better.
+
+As both the \proglang{C++} language and standards have evolved
+\citep{Meyers:2005:EffectiveC++,Meyers:1995:MoreEffectiveC++}, so have the
+compilers implementing the language. Relatively modern language constructs
+such as template meta-programming are particularly useful. It provides both
+overloading of operations (allowing expressive code in the compiled language
+similar to what can be done in scripting languages) and can shift some of the
+computational burden from the run-time to the compile-time (though a more
+detailed discussions of template programming is however beyond this
+paper). \cite{Veldhuizen:1998:Blitz} provided an early and influential
+implementation that already demonstrated key features of this approach. Its
+usage however was held back at the time by the somewhat limited availability
+of compilers implementing all necessary features of the \proglang{C++}
+language.
+
+This situation has greatly improved over the last decade, and many more such
+libraries have been contributed. One such \proglang{C++} library is
+\pkg{Eigen} by \citet*{Eigen:Web}. \pkg{Eigen} started as a sub-project to
+KDE (a popular Linux desktop environment), initially focussing on fixed-size
+matrices which are projections in a visualization application. \pkg{Eigen}
+grew from there and has over the course of about a decade produced three
+major releases with ``Eigen3'' being the current version.
+
+\pkg{Eigen} is of interest as the \proglang{R} system for statistical
+computation and graphics \citep{R:Main} is itself easily extensible. This is
+particular true via the \proglang{C} language that most of \proglang{R}'s
+compiled core parts are written in, but also for the \proglang{C++} language
+which can interface with \proglang{C}-based systems rather easily. The manual
+``Writing R Extensions'' \citep{R:Extensions} is the basic reference for
+extending \proglang{R} with either \proglang{C} or \proglang{C++}.
+
+The \pkg{Rcpp} package by \citet{JSS:Rcpp,CRAN:Rcpp} facilitates extending
+\proglang{R} with \proglang{C++} code by providing seamless object mapping
+between both languages.
+%
+As stated in the \pkg{Rcpp} \citep{CRAN:Rcpp} vignette, ``Extending \pkg{Rcpp}''
+\begin{quote}
+ \pkg{Rcpp} facilitates data interchange between \proglang{R} and
+ \proglang{C++} through the templated functions \texttt{Rcpp::as} (for
+ conversion of objects from \proglang{R} to \proglang{C++}) and
+ \texttt{Rcpp::wrap} (for conversion from \proglang{C++} to \proglang{R}).
+\end{quote}
+The \pkg{RcppEigen} package provides the header files composing the
+\pkg{Eigen} \proglang{C++} template library and implementations of
+\texttt{Rcpp::as} and \texttt{Rcpp::wrap} for the \proglang{C++}
+classes defined in \pkg{Eigen}.
+
+The \pkg{Eigen} classes themselves provide high-performance,
+versatile and comprehensive representations of dense and sparse
+matrices and vectors, as well as decompositions and other functions
+to be applied to these objects. The next section introduces some
+of these classes and shows how to interface to them from \proglang{R}.
+
+\section{Eigen classes}
+\label{sec:eclasses}
+
+\pkg{Eigen} \citep*{Eigen:Web} is a \proglang{C++} template
+library providing classes for many forms of matrices, vectors, arrays
+and decompositions. These classes are flexible and comprehensive
+allowing for both high performance and well structured code
+representing high-level operations. \proglang{C++} code based on Eigen
+is often more like \proglang{R} code, working on the ``whole object'',
+rather than compiled code in other languages where operations often must be
+coded in loops.
+
+As in many \proglang{C++} template libraries using template meta-programming
+\citep{Abrahams+Gurtovoy:2004:TemplateMetaprogramming}, the templates
+themselves can be very complicated. However, \pkg{Eigen} provides
+\code{typedef}s for common classes that correspond to \proglang{R} matrices and
+vectors, as shown in Table~\ref{tab:REigen}, and this paper will use these
+\code{typedef}s throughout this document.
+\begin{table}[tb]
+ \caption{Correspondence between R matrix and vector types and classes in the \code{Eigen} namespace.}
+ \label{tab:REigen}
+ \centering
+ \begin{tabular}{l l}
+ \toprule
+ \multicolumn{1}{c}{\proglang{R} object type} & \multicolumn{1}{c}{\pkg{Eigen} class typedef}\\
+ \midrule
+ numeric matrix & \code{MatrixXd}\\
+ integer matrix & \code{MatrixXi}\\
+ complex matrix & \code{MatrixXcd}\\
+ numeric vector & \code{VectorXd}\\
+ integer vector & \code{VectorXi}\\
+ complex vector & \code{VectorXcd}\\
+ \code{Matrix::dgCMatrix} \phantom{XXX} & \code{SparseMatrix<double>}\\
+ \bottomrule
+ \end{tabular}
+\end{table}
+
+The \proglang{C++} classes shown in Table~\ref{tab:REigen} are in the
+\code{Eigen} namespace, which means that they must be written as
+\code{Eigen::MatrixXd}. However, if one prefaces the use of these class
+names with a declaration like
+
+%% Alternatively, use 'highlight --enclose-pre --no-doc --latex --style=emacs --syntax=C++'
+%% as the command invoked from C-u M-|
+%% For version 3.5 of highlight this should be
+%% highlight --enclose-pre --no-doc --out-format=latex --syntax=C++
+%%
+%% keep one copy to redo later
+%%
+%% using Eigen::MatrixXd;
+%%
+\begin{quote}
+ \noindent
+ \ttfamily
+ \hlstd{}\hlkwa{using\ }\hlstd{Eigen}\hlopt{::}\hlstd{MatrixXd}\hlopt{;}\hlstd{}\hspace*{\fill}\\
+ \mbox{}
+ \normalfont
+ \normalsize
+\end{quote}
+then one can use these names without the namespace qualifier.
+
+\subsection{Mapped matrices in Eigen}
+\label{sec:mapped}
+
+Storage for the contents of matrices from the classes shown in
+Table~\ref{tab:REigen} is allocated and controlled by the class
+constructors and destructors. Creating an instance of such a class
+from an \proglang{R} object involves copying its contents. An
+alternative is to have the contents of the \proglang{R} matrix or
+vector mapped to the contents of the object from the Eigen class. For
+dense matrices one can use the Eigen templated class \code{Map}, and for
+sparse matrices one can deploy the Eigen templated class \code{MappedSparseMatrix}.
+
+One must, of course, be careful not to modify the contents of the
+\proglang{R} object in the \proglang{C++} code. A recommended
+practice is always to declare mapped objects as {\ttfamily\hlkwb{const}\normalfont}.
+
+\subsection{Arrays in Eigen}
+\label{sec:arrays}
+
+For matrix and vector classes \pkg{Eigen} overloads the \texttt{`*'}
+operator to indicate matrix multiplication. Occasionally
+component-wise operations instead of matrix operations are preferred. The
+\code{Array} templated classes are used in \pkg{Eigen} for
+component-wise operations. Most often the \code{array()} method is used
+for Matrix or Vector objects to create the array. On those occasions
+when one wishes to convert an array to a matrix or vector object
+the \code{matrix()} method is used.
+
+\subsection{Structured matrices in \pkg{Eigen}}
+\label{sec:structured}
+
+There are \pkg{Eigen} classes for matrices with special structure such
+as symmetric matrices, triangular matrices and banded matrices. For
+dense matrices, these special structures are described as ``views'',
+meaning that the full dense matrix is stored but only part of the
+matrix is used in operations. For a symmetric matrix one needs to
+specify whether the lower triangle or the upper triangle is to be used as
+the contents, with the other triangle defined by the implicit symmetry.
+
+\section{Some simple examples}
+\label{sec:simple}
+
+\proglang{C++} functions to perform simple operations on matrices or
+vectors can follow a pattern of:
+\begin{enumerate}
+\item Map the \proglang{R} objects passed as arguments into Eigen objects.
+\item Create the result.
+\item Return \code{Rcpp::wrap} applied to the result.
+\end{enumerate}
+
+An idiom for the first step is
+%\begin{lstlisting}[language=C++]
+% using Eigen::Map;
+% using Eigen::MatrixXd;
+% using Rcpp::as;
+
+% const Map<MatrixXd> A(as<Map<MatrixXd> >(AA));
+%\end{lstlisting}
+\begin{quote}
+ \noindent
+ \ttfamily
+ \hlstd{}\hlkwa{using\ }\hlstd{Eigen}\hlsym{::}\hlstd{Map}\hlsym{;}\hspace*{\fill}\\
+ \hlstd{}\hlkwa{using\ }\hlstd{Eigen}\hlsym{::}\hlstd{MatrixXd}\hlsym{;}\hspace*{\fill}\\
+ \hlstd{}\hlkwa{using\ }\hlstd{Rcpp}\hlsym{::}\hlstd{as}\hlsym{;}\hspace*{\fill}\\
+ \hlstd{}\hspace*{\fill}\\
+ \hlkwb{const\ }\hlstd{Map}\hlsym{$<$}\hlstd{MatrixXd}\hlsym{$>$}\hlstd{\ \ }\hlsym{}\hlstd{}\hlkwd{A}\hlstd{}\hlsym{(}\hlstd{as}\hlsym{$<$}\hlstd{Map}\hlsym{$<$}\hlstd{MatrixXd}\hlsym{$>$\ $>$(}\hlstd{AA}\hlsym{));}\hlstd{}\hspace*{\fill}\\
+ \mbox{}
+ \normalfont
+\end{quote}
+where \code{AA} is the name of the R object (called an \code{SEXP} in
+\proglang{C} and \proglang{C++}) passed to the \proglang{C++} function.
+
+The \code{cxxfunction} from the \pkg{inline} package \citep*{CRAN:inline} for
+\proglang{R} and its \pkg{RcppEigen} plugin provide a convenient way of
+developing and debugging the \proglang{C++} code. For actual production code
+one generally incorporates the \proglang{C++} source code files in a package
+and include the line \code{LinkingTo: Rcpp, RcppEigen} in the package's
+\code{DESCRIPTION} file. The \code{RcppEigen.package.skeleton} function
+provides a quick way of generating the skeleton of a package using
+\pkg{RcppEigen} facilities.
+
+The \code{cxxfunction} with the \code{"Rcpp"} or \code{"RcppEigen"}
+plugins has the \code{as} and \code{wrap} functions already defined as
+\code{Rcpp::as} and \code{Rcpp::wrap}. In the examples below
+these declarations are omitted. It is important to remember that they are
+needed in actual \proglang{C++} source code for a package.
+
+The first few examples are simply for illustration as the operations
+shown could be more effectively performed directly in \proglang{R}.
+Finally, the results from \pkg{Eigen} are compared to those from the direct
+\proglang{R} results.
+
+\bibliography{Rcpp}
+
+\end{document}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% End:
+
+
+
More information about the Rcpp-commits
mailing list