\name{expand-methods}
\title{Expand Matrix Factorizations}
%
\docType{methods}
\keyword{algebra}
\keyword{array}
\keyword{methods}
%
\alias{expand}
\alias{expand-methods}
\alias{expand1}
\alias{expand1-methods}
\alias{expand2}
\alias{expand2-methods}
%
\alias{expand,CHMfactor-method}
\alias{expand,denseLU-method}
\alias{expand,sparseLU-method}
%
\alias{expand1,BunchKaufman-method}
\alias{expand1,CHMsimpl-method}
\alias{expand1,CHMsuper-method}
\alias{expand1,Cholesky-method}
\alias{expand1,Schur-method}
\alias{expand1,denseLU-method}
\alias{expand1,pBunchKaufman-method}
\alias{expand1,pCholesky-method}
\alias{expand1,sparseLU-method}
\alias{expand1,sparseQR-method}
%
\alias{expand2,BunchKaufman-method}
\alias{expand2,CHMsimpl-method}
\alias{expand2,CHMsuper-method}
\alias{expand2,Cholesky-method}
\alias{expand2,Schur-method}
\alias{expand2,denseLU-method}
\alias{expand2,pBunchKaufman-method}
\alias{expand2,pCholesky-method}
\alias{expand2,sparseLU-method}
\alias{expand2,sparseQR-method}
%
\description{
  \code{expand1} and \code{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, \dots)
expand2(x, \dots)

expand (x, \dots)
}
\arguments{
  \item{x}{a matrix factorization, typically inheriting from
    virtual class \code{\linkS4class{MatrixFactorization}}.}
  \item{which}{a character string indicating a matrix factor.}
  \item{\dots}{further arguments passed to or from methods.}
}
\value{
  \code{expand1} returns an object inheriting from virtual class
  \code{\linkS4class{Matrix}}, representing the factor indicated
  by \code{which}, always without row and column names.

  \code{expand2} returns a list of factors, typically with names
  using conventional notation, as in \code{list(L=, U=)}.
  The first and last factors get the row and column names of the
  factorized matrix, which are preserved in the \code{Dimnames}
  slot of \code{x}.
}
\details{
  Methods for \code{expand} are retained only for backwards
  compatibility with \pkg{Matrix} \code{< 1.6-0}.  New code
  should use \code{expand1} and \code{expand2}, whose methods
  provide more control and behave more consistently.  Notably,
  \code{expand2} obeys the rule that the product of the matrix
  factors in the returned list should reproduce
  (within some tolerance) the factorized matrix,
  \emph{including} its \code{dimnames}.
  
  Hence if \code{x} is a matrix and \code{y} is its factorization,
  then
  \preformatted{    all.equal(as(x, "matrix"), as(Reduce(`\%*\%`, expand2(y)), "matrix"))}
  should in most cases return \code{TRUE}.
}
\section{Methods}{
  The following table lists methods for \code{expand1} together with
  allowed values of argument \code{which}.

  \tabular{rl}{
    \code{class(x)} \tab \code{which}\cr
    \code{\linkS4class{Schur}} \tab \code{c("Q", "T", "Q.")}\cr
    \code{\linkS4class{denseLU}} \tab \code{c("P1", "P1.", "L", "U")}\cr
    \code{\linkS4class{sparseLU}} \tab \code{c("P1", "P1.", "P2", "P2.", "L", "U")}\cr
    \code{\linkS4class{sparseQR}} \tab \code{c("P1", "P1.", "P2", "P2.", "Q", "Q1", "R", "R1")}\cr
    \code{\linkS4class{BunchKaufman}}, \code{\linkS4class{pBunchKaufman}} \tab \code{c("U", "DU", "U.", "L", "DL", "L.")}\cr
    \code{\linkS4class{Cholesky}}, \code{\linkS4class{pCholesky}} \tab \code{c("P1", "P1.", "L1", "D", "L1.", "L", "L.")}\cr
    \code{\linkS4class{CHMsimpl}}, \code{\linkS4class{CHMsimpl}} \tab \code{c("P1", "P1.", "L1", "D", "L1.", "L", "L.")}
  }

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

  The virtual class \code{\linkS4class{MatrixFactorization}}
  of matrix factorizations.
  
  Generic functions \code{\link{Cholesky}}, \code{\link{BunchKaufman}},
  \code{\link{Schur}}, \code{\link{lu}}, and \code{\link{qr}} for
  \emph{computing} factorizations.
}
\examples{
\dontshow{ % for R_DEFAULT_PACKAGES=NULL
library(stats, pos = "package:base", verbose = FALSE)
}
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
}