# expand: 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`.

The virtual class `compMatrix` of factorizable matrices.

The virtual class `MatrixFactorization` of matrix factorizations.

Generic functions `Cholesky`, `BunchKaufman`, `Schur`, `lu`, and `qr` for computing factorizations.

### 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;
(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 Nov. 14, 2023, 5:06 p.m.