7 min read

Sparse Matrix Support in RcppArmadillo

Binxiang Ni 2017/08/01

Introduction

The documentation is intended for RcppArmadillo sparse matrix user’s convenience based on the documentation of library Matrix and Armadillo. The Unofficial Rcpp API also helps during integration of this documentation.

There are 31 types of sparse matrices in the package “Matrix” that can be directly used. But for now, only 12 of them are supported in RcppArmadillo: dgCMatrix, dtCMatrix, dsCMatrix, dgTMatrix, dtTMatrix, dsTMatrix, dgRMatrix, dtRMatrix, dsRMatrix, indMatrix, pMatrix, and ddiMatrix.

In the library “Armadillo”, sparse matrix is currently stored as CSC format. When a sparse matrix from the library “Matrix” is passed through RcppArmadillo, it will be converted or mapped to CSC format, then undertaken operations on, and finally ouput as dgCMatrix in R.

Sparse Matrix

dgCMatrix

  • Description: general column-oriented numeric sparse matrix.
  • Constructor
    • new("dgCMatrix", ...)
    • Matrix(*, sparse = TRUE)
    • sparseMatrix()
  • Coercion
    • as(*, "CsparseMatrix")
    • as(*, "dgCMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat sqrt_(sp_mat X) {
  return sqrt(X);
}

/*** R
library(Matrix)
i <- c(1,3:8); j <- c(2,9,6:10); x <- 7 * (1:7)
A <- sparseMatrix(i, j, x = x) 
sqrt_(A)

# Output
# > sqrt_(A)
# 8 x 10 sparse Matrix of class "dgCMatrix"
# 
# [1,] . 2.645751 . . . .        .        .       .        .
# [2,] . .        . . . .        .        .       .        .
# [3,] . .        . . . .        .        .       3.741657 .
# [4,] . .        . . . 4.582576 .        .       .        .
# [5,] . .        . . . .        5.291503 .       .        .
# [6,] . .        . . . .        .        5.91608 .        .
# [7,] . .        . . . .        .        .       6.480741 .
# [8,] . .        . . . .        .        .       .        7
*/

dtCMatrix

  • Description: triangular column-oriented numeric sparse matrix.
  • Constructor
    • new("dtCMatrix", ...)
    • Matrix(*, sparse = TRUE)
    • sparseMatrix(*, triangular=TRUE)
  • Coercion
    • as(*, "triangularMatrix")
    • as(*, "dtCMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat symmatl_(sp_mat X) {
  return symmatl(X);
}

/*** R
library(Matrix)
dtC <- new("dtCMatrix", Dim = c(5L, 5L), uplo = "L",
           x = c(10, 1, 3, 10, 1, 10, 1, 10, 10),
           i = c(0L, 2L, 4L, 1L, 3L,2L, 4L, 3L, 4L),
           p = c(0L, 3L, 5L, 7:9))
symmatl_(dtC)
  
# Output
# > symmatl_(dtC)
# 5 x 5 sparse Matrix of class "dtCMatrix"
#                    
# [1,] 10  .  1  .  3
# [2,]  . 10  .  1  .
# [3,]  1  . 10  .  1
# [4,]  .  1  . 10  .
# [5,]  3  .  1  . 10
*/

dsCMatrix

  • Description: symmetric column-oriented numeric sparse matrix.
  • Constructor
    • new("dsCMatrix", ...)
    • Matrix(*, sparse = TRUE)
    • sparseMatrix(*, symmetric = TRUE)
  • Coercion
    • as(*, "symmetricMatrix")
    • as(*, "dsCMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat trimatu_(sp_mat X) {
  return trimatu(X);
}

/*** R
library(Matrix)
i <- c(1,3:8); j <- c(2,9,6:10); x <- 7 * (1:7)
dsC <- sparseMatrix(i, j, x = x, symmetric = TRUE)
trimatu_(dsC)
  
# Output
# > trimatu_(dsC)
# 10 x 10 sparse Matrix of class "dgCMatrix"
# 
# [1,] . 7 . . .  .  .  .  .  .
# [2,] . . . . .  .  .  .  .  .
# [3,] . . . . .  .  .  . 14  .
# [4,] . . . . . 21  .  .  .  .
# [5,] . . . . .  . 28  .  .  .
# [6,] . . . . .  .  . 35  .  .
# [7,] . . . . .  .  .  . 42  .
# [8,] . . . . .  .  .  .  . 49
# [9,] . . . . .  .  .  .  .  .
# [10,] . . . . .  .  .  .  .  .
*/

dgTMatrix

  • Description: general numeric sparse matrix in triplet form.
  • Constructor
    • new("dgTMatrix", ...)
    • sparseMatrix(*, giveCsparse=FALSE)
    • spMatrix()
  • Coercion
    • as(*, "TsparseMatrix")
    • as(*, "dgTMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat multiply(sp_mat A, sp_mat B) {
  return A * B;
}

//[[Rcpp::export]]
sp_mat trans_(sp_mat X) {
  return trans(X);
}

//[[Rcpp::export]]
int trace_(sp_mat X) {
  return trace(X);
}

/*** R
library(Matrix)
dgT <- new("dgTMatrix",
           i = c(1L,1L,0L,3L,3L),
           j = c(2L,2L,4L,0L,0L), x=10*1:5, Dim=4:5)
dgT_t <- trans_(dgT)
prod <- multiply(dgT, dgT_t)
trace_(prod)

# Output
# > trace_(prod)
# [1] 9900
*/

dtTMatrix

  • Description: triangular numeric sparse matrix in triplet form.
  • Constructor
    • new("dtTMatrix", ...)
    • sparseMatrix(*, triangular=TRUE, giveCsparse=FALSE)
  • Coercion
    • as(*, "triangularMatrix")
    • as(*, "dtTMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat diag_ones(sp_mat X) {
  X.diag().ones();
  return X;
}

/*** R
library(Matrix)
dtT <- new("dtTMatrix", x= c(3,7), 
          i= 0:1, j=3:2, Dim= as.integer(c(4,4)))
diag_ones(dtT)

# Output
# > diag_ones(dtT)
# 4 x 4 sparse Matrix of class "dgCMatrix"
# 
# [1,] 1 . . 3
# [2,] . 1 7 .
# [3,] . . 1 .
# [4,] . . . 1
*/

dsTMatrix

  • Description: symmetric numeric sparse matrix in triplet form.
  • Constructor
    • new("dsTMatrix", ...)
    • sparseMatrix(*, symmetric=TRUE, giveCsparse=FALSE)
  • Coercion
    • as(*, "symmetricMatrix")
    • as(*, "dsTMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
int trace_(sp_mat X) {
  return trace(X);
}

/*** R
library(Matrix)
mm <- Matrix(toeplitz(c(10, 0, 1, 0, 3)), sparse = TRUE)
mT <- as(mm, "dgTMatrix")
dsT <- as(mT, "symmetricMatrix")
trace_(dsT)

# Output
# > trace_(dsT)
# [1] 50
*/

dgRMatrix

  • Description: general row-oriented numeric sparse matrix.
  • Constructor
    • new("dgRMatrix", ...)
  • Coercion
    • as(*, "RsparseMatrix")
    • as(*, "dgRatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat square_(sp_mat X) {
  return square(X);
}

/*** R
library(Matrix)
dgR <- new("dgRMatrix", j=c(0L,2L,1L,3L),
          p=c(0L,2L,3L,3L,4L),
          x=c(3,1,2,1),
          Dim=rep(4L,2))
square_(dgR)

# Output
# > square_(dgR)
# 4 x 4 sparse Matrix of class "dgCMatrix"
# 
# [1,] 9 . 1 .
# [2,] . 4 . .
# [3,] . . . .
# [4,] . . . 1
*/

dtRMatrix

  • Description: triangular row-oriented numeric sparse matrix.
  • Constructor
    • new("dtRMatrix", ...)
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat repmat_(sp_mat X, int i, int j) {
  return repmat(X, i, j);
}

/*** R
library(Matrix)
dtR <- new("dtRMatrix", Dim = c(2L,2L),
           x = c(5, 1:2), p = c(0L,2:3), j= c(0:1,1L))
repmat_(dtR, 2, 2)

# Output
# > repmat_(dtR, 2, 2)
# 4 x 4 sparse Matrix of class "dgCMatrix"
# 
# [1,] 5 1 5 1
# [2,] . 2 . 2
# [3,] 5 1 5 1
# [4,] . 2 . 2
*/

dsRMatrix

  • Description: symmetric row-oriented numeric sparse matrix.
  • Constructor
    • new("dsRMatrix", ...)
  • Coercion
    • as("dsCMatrix", "dsRMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat sign_(sp_mat X) {
  return sign(X);
}

/*** R
library(Matrix)
dsR <- new("dsRMatrix", Dim = c(2L,2L),
           x = c(-3,1), j = c(1L,1L), p = 0:2)
sign_(dsR)

# Output
# > sign_(dsR)
# 2 x 2 sparse Matrix of class "dgCMatrix"
# 
# [1,]  . -1
# [2,] -1  1
*/

indMatrix

  • Description: index matrix.
  • Constructor
    • new("indMatrix", ...)
  • Coercion
    • as(*, "indMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat multiply(sp_mat A, sp_mat B) {
  return A * B;
}

/*** R
library(Matrix)
ind <- as(2:4, "indMatrix")
dgT <- new("dgTMatrix",
           i = c(1L,1L,0L,3L,3L),
           j = c(2L,2L,4L,0L,0L), 
           x=10*1:5, Dim=4:5)
multiply(ind, dgT)

# Output
# > multiply(ind, dgT)
# 3 x 5 sparse Matrix of class "dgCMatrix"
# 
# [1,]  . . 30 . .
# [2,]  . .  . . .
# [3,] 90 .  . . .
*/

pMatrix

  • Description: permutation matrix.
  • Constructor
    • new("pMatrix", ...)
  • Coercion
    • as(*, "pMatrix")
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat multiply(sp_mat A, sp_mat B) {
  return A * B;
}

/*** R
library(Matrix)
pM <- as(c(2,3,1,4), "pMatrix")
dgT <- new("dgTMatrix",
           i = c(1L,1L,0L,3L,3L),
           j = c(2L,2L,4L,0L,0L), 
           x=10*1:5, Dim=4:5)
multiply(pM, dgT)

# Output
# > multiply(pM, dgT)
# 4 x 5 sparse Matrix of class "dgCMatrix"
# 
# [1,]  . . 30 .  .
# [2,]  . .  . .  .
# [3,]  . .  . . 30
# [4,] 90 .  . .  .
*/

ddiMatrix

  • Description: numeric diagonal Matrix.
  • Constructor
    • new("ddiMatrix", ...)
    • Diagonal(*)
  • Examples
#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

using namespace Rcpp;
using namespace arma;

// [[Rcpp::export]]
sp_mat multiply(sp_mat A, sp_mat B) {
  return A * B;
}

/*** R
library(Matrix)
ddi <- Diagonal(4)
dgR <- new("dgRMatrix", j=c(0L,2L,1L,3L),
            p=c(0L,2L,3L,3L,4L),
            x=c(3,1,2,1),
            Dim=rep(4L,2))
multiply(ddi, dgR)

# Output
# > multiply(ddi, dgR)
# 4 x 4 sparse Matrix of class "dgCMatrix"
# 
# [1,] 3 . 1 .
# [2,] . 2 . .
# [3,] . . . .
# [4,] . . . 1
*/