[Rcpp-commits] r1266 - in pkg/RcppArmadillo/inst: . announce

[noreply at r-forge.r-project.org]

Author: romain
Date: 2010-05-18 08:46:31 +0200 (Tue, 18 May 2010)
New Revision: 1266

Added:
   pkg/RcppArmadillo/inst/announce/
   pkg/RcppArmadillo/inst/announce/ANNOUNCE-0.2.0.txt
Log:
first pass at an announce file for RcppArmadillo 0.2.0

Added: pkg/RcppArmadillo/inst/announce/ANNOUNCE-0.2.0.txt
===================================================================
--- pkg/RcppArmadillo/inst/announce/ANNOUNCE-0.2.0.txt	                        (rev 0)
+++ pkg/RcppArmadillo/inst/announce/ANNOUNCE-0.2.0.txt	2010-05-18 06:46:31 UTC (rev 1266)
@@ -0,0 +1,130 @@
+
+===== Armadillo =====
+
+Armadillo is a C++ linear algebra library (matrix maths) aiming towards a 
+good balance between speed and ease of use. Integer, floating point and complex
+numbers are supported, as well as a subset of trigonometric and statistics 
+functions. Various matrix decompositions are provided through optional 
+integration with LAPACK and ATLAS libraries.
+
+A delayed evaluation approach is employed (during compile time) to combine several
+operations into one and reduce (or eliminate) the need for temporaries. 
+This is accomplished through recursive templates and template meta-programming.
+
+This library is useful if C++ has been decided as the language of choice 
+(due to speed and/or integration capabilities), rather than another language 
+like Matlab ¨ or Octave. It is distributed under a license that is useful in 
+both open-source and commercial contexts.
+
+Armadillo is primarily developed at NICTA (Australia), with contributions from around the world.
+
+
+===== RcppArmadillo =====
+
+RcppArmadillo is an R package that facilitates using armadillo classes
+in R packages through Rcpp. It achieves the integration by extending Rcpp's
+data interchange concepts to armadillo classes. 
+
+
+===== Example =====
+
+Here is a simple implementation of a fast linear regression (provided by RcppArmadillo via the fastLm() function):
+
+#include <RcppArmadillo.h>
+
+extern "C" SEXP fastLm(SEXP ys, SEXP Xs) {
+
+    Rcpp::NumericVector yr(ys);                 // creates Rcpp vector from SEXP
+    Rcpp::NumericMatrix Xr(Xs);                 // creates Rcpp matrix from SEXP
+    int n = Xr.nrow(), k = Xr.ncol();
+
+    arma::mat X(Xr.begin(), n, k, false);       // reuses memory and avoids extra copy
+    arma::colvec y(yr.begin(), yr.size(), false);
+
+    arma::colvec coef = arma::solve(X, y);      // fit model y ~ X
+    arma::colvec resid = y - X*coef;            // residuals
+
+    double sig2 = arma::as_scalar( arma::trans(resid)*resid/(n-k) );
+                                                // std.error of estimate
+    arma::colvec stderrest = arma::sqrt( sig2 * arma::diagvec( arma::inv(arma::trans(X)*X)) );
+
+    return Rcpp::List::create(
+        Rcpp::Named("coefficients") = coef,
+        Rcpp::Named("stderr")       = stderrest
+    ) ;
+
+}
+
+
+===== Using RcppArmadillo in other packages =====
+
+RcppArmadillo is designed so that its classes are used from other packages. 
+Using RcppArmadillo requires: 
+ - Using the header files provided by Rcpp and RcppArmadillo. This is 
+   typically achieved by adding this line in the DESCRIPTION file of the 
+   client package:
+   
+   LinkingTo : Rcpp, RcppArmadillo
+   
+   and the following line in the package code: 
+   
+   #include <RcppArmadillo.h>
+   
+ - Linking against Rcpp dynamic or shared library and librairies needed
+   by armadillo, which is achieved by adding this line in the src/Makevars
+   file of the client package: 
+   
+   PKG_LIBS = $(shell $(R_HOME)/bin/Rscript -e "Rcpp:::LdFlags()" ) $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)
+
+   and this line in the file src/Makevars.win: 
+   
+   PKG_LIBS = $(shell Rscript.exe -e "Rcpp:::LdFlags()") $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)
+
+RcppArmadillo contains a function RcppArmadillo.package.skeleton, modelled
+after package.skeleton from the utils package in base r, that creates a 
+skeleton of a package using RcppArmadillo, including example code.
+
+
+===== Quality Assurance =====
+
+RcppArmadillo uses the RUnit package by Matthias Burger et al to provide 
+unit testing. RcppArmadillo currently has 19 unit tests (called from 8 unit 
+test functions). 
+
+Source code for unit test functions are stored in the unitTests directory 
+of the installed package and the results are collected in the 
+"RcppArmadillo-unitTests" vignette. 
+
+We run unit tests before sending the package to CRAN on as many systems
+as possible, including Mac OSX (Snow Leopard), Debian, Ubuntu, Fedora 12 (64bit), 
+Win 32 and Win64. 
+
+Unit tests can also be run from the installed package by executing
+
+	RcppArmadillo:::test()
+
+where an output directory can be provided as an optional first argument.
+
+
+===== Links =====
+
+Armadillo : http://arma.sourceforge.net/
+RcppArmadillo main page: http://dirk.eddelbuettel.com/code/rcpp.armadillo.html
+R-forge Rcpp project page: http://r-forge.r-project.org/projects/rcpp/
+Dirk's blog : http://dirk.eddelbuettel.com/blog/code/rcpp/
+Romain's blog : http://romainfrancois.blog.free.fr/index.php?category/R-package/RcppArmadillo
+
+
+===== Support =====
+
+Questions about RcppArmadillo should be directed to the Rcpp-devel mailing list
+https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel
+
+Questions about Armadillo itself should be directed to its forum
+http://sourceforge.net/apps/phpbb/arma/
+
+
+ -- Doug Bates, Dirk Eddelbuettel and Romain Francois
+    Chicago, IL, USA, and Montpellier, France
+	May 2010
+