Expand Matrix Factorizations
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.
methods
expand1(x, which, ...) expand2(x, ...) expand (x, ...)
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.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 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.
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
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
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
where $U = prod(Pk * Uk : k = 1,...,bU)$
and $L = prod(Pk * Lk : k = 1,...,bL)$
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*bU+1$ or $2*bL+1$ matrix factors is returned instead. $Pk$ are represented as `pMatrix`, $Uk$ and $Lk$ are represented as `dtCMatrix`, and $DU$ and $DL$ are represented as `dsCMatrix`.
expand2: signature(x = "Schur"): expands the factorization
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
as `list(P1., L, U, P2.)`. `P1.` and `P2.` are `pMatrix`, and `L` and `U` are `dtCMatrix`.
expand2: signature(x = "denseLU"): expands the factorization
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
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 $P1$
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 $P2'$
but have opposite `margin` slots and inverted `perm` slots. `expand(x)[["P"]]` represents the permutation matrix $P1$ rather than its transpose $P1'$; 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`.
The virtual class MatrixFactorization
of matrix factorizations.
Generic functions Cholesky, BunchKaufman, Schur, lu, and qr for computing factorizations.
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
Useful links