expand-methods: Expand Matrix Factorizations
In Matrix: Sparse and Dense Matrix Classes and Methods

expand-methods

R Documentation

Expand Matrix Factorizations

Description

expand1 and expand2 construct matrix factors from objects specifying matrix factorizations. Such objects typically do not store the factors explicitly, employing instead a compact representation to save memory.

Usage

expand1(x, which, ...)
expand2(x, ...)

expand (x, ...)

Arguments

`x`	a matrix factorization, typically inheriting from virtual class `MatrixFactorization`.
`which`	a character string indicating a matrix factor.
`...`	further arguments passed to or from methods.

Details

Methods for expand are retained only for backwards compatibility with Matrix < 1.6-0. New code should use expand1 and expand2, whose methods provide more control and behave more consistently. Notably, expand2 obeys the rule that the product of the matrix factors in the returned list should reproduce (within some tolerance) the factorized matrix, including its dimnames.

Hence if x is a matrix and y is its factorization, then

    all.equal(as(x, "matrix"), as(Reduce(`%*%`, expand2(y)), "matrix"))

should in most cases return TRUE.

Value

expand1 returns an object inheriting from virtual class Matrix, representing the factor indicated by which, always without row and column names.

expand2 returns a list of factors, typically with names using conventional notation, as in list(L=, U=). The first and last factors get the row and column names of the factorized matrix, which are preserved in the Dimnames slot of x.

Methods

The following table lists methods for expand1 together with allowed values of argument which.

`class(x)`	`which`
`Schur`	`c("Q", "T", "Q.")`
`denseLU`	`c("P1", "P1.", "L", "U")`
`sparseLU`	`c("P1", "P1.", "P2", "P2.", "L", "U")`
`sparseQR`	`c("P1", "P1.", "P2", "P2.", "Q", "Q1", "R", "R1")`
`BunchKaufman`, `pBunchKaufman`	`c("U", "DU", "U.", "L", "DL", "L.")`
`Cholesky`, `pCholesky`	`c("P1", "P1.", "L1", "D", "L1.", "L", "L.")`
`CHMsimpl`, `CHMsimpl`	`c("P1", "P1.", "L1", "D", "L1.", "L", "L.")`

Methods for expand2 and expand are described below. Factor names and classes apply also to expand1.

expand2: signature(x = "CHMsimpl"): expands the factorization A = P_{1}' L_{1} D L_{1}' P_{1} = P_{1}' L L' P_{1} as list(P1., L1, D, L1., P1) (the default) or as list(P1., L, L., P1), depending on optional logical argument LDL. P1 and P1. are pMatrix, L1, L1., L, and L. are dtCMatrix, and D is a ddiMatrix.
expand2: signature(x = "CHMsuper"): as CHMsimpl, but the triangular factors are stored as dgCMatrix.
expand2: signature(x = "p?Cholesky"): expands the factorization A = L_{1} D L_{1}' = L L' as list(L1, D, L1.) (the default) or as list(L, L.), depending on optional logical argument LDL. L1, L1., L, and L. are dtrMatrix or dtpMatrix, and D is a ddiMatrix.
expand2: signature(x = "p?BunchKaufman"): expands the factorization A = U D_{U} U' = L D_{L} L' where U = \prod_{k = 1}^{b_{U}} P_{k} U_{k} and L = \prod_{k = 1}^{b_{L}} P_{k} L_{k} as list(U, DU, U.) or list(L, DL, L.), depending on x@uplo. If optional argument complete is TRUE, then an unnamed list giving the full expansion with 2 b_{U} + 1 or 2 b_{L} + 1 matrix factors is returned instead. P_{k} are represented as pMatrix, U_{k} and L_{k} are represented as dtCMatrix, and D_{U} and D_{L} are represented as dsCMatrix.
expand2: signature(x = "Schur"): expands the factorization A = Q T Q' as list(Q, T, Q.). Q and Q. are x@Q and t(x@Q) modulo Dimnames, and T is x@T.
expand2: signature(x = "sparseLU"): expands the factorization A = P_{1}' L U P_{2}' as list(P1., L, U, P2.). P1. and P2. are pMatrix, and L and U are dtCMatrix.
expand2: signature(x = "denseLU"): expands the factorization A = P_{1}' L U as list(P1., L, U). P1. is a pMatrix, and L and U are dtrMatrix if square and dgeMatrix otherwise.
expand2: signature(x = "sparseQR"): expands the factorization A = P_{1}' Q R P_{2}' = P_{1}' Q_{1} R_{1} P_{2}' as list(P1., Q, R, P2.) or list(P1., Q1, R1, P2.), depending on optional logical argument complete. P1. and P2. are pMatrix, Q and Q1 are dgeMatrix, R is a dgCMatrix, and R1 is a dtCMatrix.
expand: signature(x = "CHMfactor"): as expand2, but returning list(P, L). expand(x)[["P"]] and expand2(x)[["P1"]] represent the same permutation matrix P_{1} but have opposite margin slots and inverted perm slots. The components of expand(x) do not preserve x@Dimnames.
expand: signature(x = "sparseLU"): as expand2, but returning list(P, L, U, Q). expand(x)[["Q"]] and expand2(x)[["P2."]] represent the same permutation matrix P_{2}' but have opposite margin slots and inverted perm slots. expand(x)[["P"]] represents the permutation matrix P_{1} rather than its transpose P_{1}'; it is expand2(x)[["P1."]] with an inverted perm slot. expand(x)[["L"]] and expand2(x)[["L"]] represent the same unit lower triangular matrix L, but with diag slot equal to "N" and "U", respectively. expand(x)[["L"]] and expand(x)[["U"]] store the permuted first and second components of x@Dimnames in their Dimnames slots.
expand: signature(x = "denseLU"): as expand2, but returning list(L, U, P). expand(x)[["P"]] and expand2(x)[["P1."]] are identical modulo Dimnames. The components of expand(x) do not preserve x@Dimnames.

Examples


showMethods("expand1", inherited = FALSE)
showMethods("expand2", inherited = FALSE)
set.seed(0)

(A <- Matrix(rnorm(9L, 0, 10), 3L, 3L))
(lu.A <- lu(A))
(e.lu.A <- expand2(lu.A))
stopifnot(exprs = {
    is.list(e.lu.A)
    identical(names(e.lu.A), c("P1.", "L", "U"))
    all(sapply(e.lu.A, is, "Matrix"))
    all.equal(as(A, "matrix"), as(Reduce(`%*%`, e.lu.A), "matrix"))
})

## 'expand1' and 'expand2' give equivalent results modulo
## dimnames and representation of permutation matrices;
## see also function 'alt' in example("Cholesky-methods")
(a1 <- sapply(names(e.lu.A), expand1, x = lu.A, simplify = FALSE))
all.equal(a1, e.lu.A)

## see help("denseLU-class") and others for more examples

Matrix documentation built on Aug. 13, 2024, 3:01 p.m.