Triangular, (compressed) sparse column matrices

The "dtCMatrix" class is a class of triangular, sparse matrices in the compressed, column-oriented format. In this implementation the non-zero elements in the columns are sorted into increasing row order.

The "dtTMatrix" class is a class of triangular, sparse matrices in triplet format.

Objects from the Class

Objects can be created by calls of the form new("dtCMatrix", ...) or calls of the form new("dtTMatrix", ...), but more typically automatically via Matrix() or coercions such as as(x, "triangularMatrix").

Slots

uplo:: Object of class "character". Must be either "U", for upper triangular, and "L", for lower triangular.
diag:: Object of class "character". Must be either "U", for unit triangular (diagonal is all ones), or "N"; see triangularMatrix.
p:: (only present in "dtCMatrix":) an integer vector for providing pointers, one for each column, see the detailed description in CsparseMatrix.
i:: Object of class "integer" of length nnzero (number of non-zero elements). These are the row numbers for each non-zero element in the matrix.
j:: Object of class "integer" of length nnzero (number of non-zero elements). These are the column numbers for each non-zero element in the matrix. (Only present in the dtTMatrix class.)
x:: Object of class "numeric" - the non-zero elements of the matrix.
Dim,Dimnames:: The dimension (a length-2 "integer") and corresponding names (or NULL), inherited from the Matrix, see there.

Extends

Class "dgCMatrix", directly. Class "triangularMatrix", directly. Class "dMatrix", "sparseMatrix", and more by class "dgCMatrix" etc, see the examples.

Methods

solve: signature(a = "dtCMatrix", b = "...."): sparse triangular solve (aka “backsolve” or “forwardsolve”), see solve-methods.
t: signature(x = "dtCMatrix"): returns the transpose of x
t: signature(x = "dtTMatrix"): returns the transpose of x

Examples

showClass("dtCMatrix")
#> Class "dtCMatrix" [package "Matrix"]
#> 
#> Slots:
#>                                                                             
#> Name:          i         p       Dim  Dimnames         x      uplo      diag
#> Class:   integer   integer   integer      list   numeric character character
#> 
#> Extends: 
#> Class "CsparseMatrix", directly
#> Class "dsparseMatrix", directly
#> Class "triangularMatrix", directly
#> Class "dMatrix", by class "dsparseMatrix", distance 2
#> Class "sparseMatrix", by class "dsparseMatrix", distance 2
#> Class "Matrix", by class "triangularMatrix", distance 2
showClass("dtTMatrix")
#> Class "dtTMatrix" [package "Matrix"]
#> 
#> Slots:
#>                                                                             
#> Name:          i         j       Dim  Dimnames         x      uplo      diag
#> Class:   integer   integer   integer      list   numeric character character
#> 
#> Extends: 
#> Class "TsparseMatrix", directly
#> Class "dsparseMatrix", directly
#> Class "triangularMatrix", directly
#> Class "dMatrix", by class "dsparseMatrix", distance 2
#> Class "sparseMatrix", by class "dsparseMatrix", distance 2
#> Class "Matrix", by class "triangularMatrix", distance 2
t1 <- new("dtTMatrix", x= c(3,7), i= 0:1, j=3:2, Dim= as.integer(c(4,4)))
t1
#> 4 x 4 sparse Matrix of class "dtTMatrix"
#>             
#> [1,] . . . 3
#> [2,] . . 7 .
#> [3,] . . . .
#> [4,] . . . .
## from  0-diagonal to unit-diagonal {low-level step}:
tu <- t1 ; tu@diag <- "U"
tu
#> 4 x 4 sparse Matrix of class "dtTMatrix" (unitriangular)
#>             
#> [1,] I . . 3
#> [2,] . I 7 .
#> [3,] . . I .
#> [4,] . . . I
(cu <- as(tu, "CsparseMatrix"))
#> 4 x 4 sparse Matrix of class "dtCMatrix" (unitriangular)
#>             
#> [1,] I . . 3
#> [2,] . I 7 .
#> [3,] . . I .
#> [4,] . . . I
str(cu)# only two entries in @i and @x
#> Formal class 'dtCMatrix' [package "Matrix"] with 7 slots
#>   ..@ i       : int [1:2] 1 0
#>   ..@ p       : int [1:5] 0 0 0 1 2
#>   ..@ Dim     : int [1:2] 4 4
#>   ..@ Dimnames:List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
#>   ..@ x       : num [1:2] 7 3
#>   ..@ uplo    : chr "U"
#>   ..@ diag    : chr "U"
stopifnot(cu@i == 1:0,
          all(2 * symmpart(cu) == Diagonal(4) + forceSymmetric(cu)))

t1[1,2:3] <- -1:-2
diag(t1) <- 10*c(1:2,3:2)
t1 # still triangular
#> 4 x 4 sparse Matrix of class "dtTMatrix"
#>                 
#> [1,] 10 -1 -2  3
#> [2,]  . 20  7  .
#> [3,]  .  . 30  .
#> [4,]  .  .  . 20
(it1 <- solve(t1))
#> 4 x 4 sparse Matrix of class "dtCMatrix"
#>                                  
#> [1,] 0.1 0.005  0.00550000 -0.015
#> [2,] .   0.050 -0.01166667  .    
#> [3,] .   .      0.03333333  .    
#> [4,] .   .      .           0.050
t1. <- solve(it1)
all(abs(t1 - t1.) < 10 * .Machine$double.eps)
#> [1] TRUE

## 2nd example
U5 <- new("dtCMatrix", i= c(1L, 0:3), p=c(0L,0L,0:2, 5L), Dim = c(5L, 5L),
          x = rep(1, 5), diag = "U")
U5
#> 5 x 5 sparse Matrix of class "dtCMatrix" (unitriangular)
#>               
#> [1,] I . . 1 .
#> [2,] . I 1 . 1
#> [3,] . . I . 1
#> [4,] . . . I 1
#> [5,] . . . . I
(iu <- solve(U5)) # contains one '0'
#> 5 x 5 sparse Matrix of class "dtCMatrix"
#>                  
#> [1,] 1 .  . -1  1
#> [2,] . 1 -1  .  .
#> [3,] . .  1  . -1
#> [4,] . .  .  1 -1
#> [5,] . .  .  .  1
validObject(iu2 <- solve(U5, Diagonal(5)))# failed in earlier versions
#> [1] TRUE

I5 <- iu  %*% U5 # should equal the identity matrix
i5 <- iu2 %*% U5
m53 <- matrix(1:15, 5,3, dimnames=list(NULL,letters[1:3]))
asDiag <- function(M) as(drop0(M), "diagonalMatrix")
stopifnot(
   all.equal(Diagonal(5), asDiag(I5), tolerance=1e-14) ,
   all.equal(Diagonal(5), asDiag(i5), tolerance=1e-14) ,
   identical(list(NULL, dimnames(m53)[[2]]), dimnames(solve(U5, m53)))
)