https://github.com/cran/Matrix
Tip revision: 8f0083c101114457cf9f9a00dc7cd8420b4c89a2 authored by Martin Maechler on 11 January 2024, 17:50:15 UTC
version 1.6-5
version 1.6-5
Tip revision: 8f0083c
BunchKaufman-methods.Rd
\name{BunchKaufman-methods}
\title{Methods for Bunch-Kaufman Factorization}
%
\docType{methods}
\keyword{algebra}
\keyword{array}
\keyword{methods}
%
\alias{BunchKaufman}
\alias{BunchKaufman-methods}
%
\alias{BunchKaufman,dspMatrix-method}
\alias{BunchKaufman,dsyMatrix-method}
\alias{BunchKaufman,matrix-method}
%
\description{
Computes the Bunch-Kaufman factorization of an \eqn{n \times n}{n-by-n}
real, symmetric matrix \eqn{A}, which has the general form
\deqn{A = U D_{U} U' = L D_{L} L'}{A = U * DU * U' = L * DL * L'}
where
\eqn{D_{U}}{DU} and \eqn{D_{L}}{DL} are symmetric, block diagonal
matrices composed of \eqn{b_{U}}{bU} and \eqn{b_{L}}{bL}
\eqn{1 \times 1}{1-by-1} or \eqn{2 \times 2}{2-by-2} diagonal blocks;
\eqn{U = \prod_{k = 1}^{b_{U}} P_{k} U_{k}}{U = prod(Pk * Uk : k = 1,...,bU)}
is the product of \eqn{b_{U}}{bU} row-permuted unit upper triangular
matrices, each having nonzero entries above the diagonal in 1 or 2 columns;
and
\eqn{L = \prod_{k = 1}^{b_{L}} P_{k} L_{k}}{L = prod(Pk * Lk : k = 1,...,bL)}
is the product of \eqn{b_{L}}{bL} row-permuted unit lower triangular
matrices, each having nonzero entries below the diagonal in 1 or 2 columns.
Methods are built on LAPACK routines \code{dsytrf} and \code{dsptrf}.
}
\usage{
BunchKaufman(x, \dots)
\S4method{BunchKaufman}{dsyMatrix}(x, warnSing = TRUE, \dots)
\S4method{BunchKaufman}{dspMatrix}(x, warnSing = TRUE, \dots)
\S4method{BunchKaufman}{matrix}(x, uplo = "U", \dots)
}
\arguments{
\item{x}{a \link[=is.finite]{finite} symmetric matrix or
\code{\linkS4class{Matrix}} to be factorized.
If \code{x} is square but not symmetric, then it will be
\emph{treated} as symmetric; see \code{uplo}.}
\item{warnSing}{a logical indicating if a \link{warning} should
be signaled for singular \code{x}.}
\item{uplo}{a string, either \code{"U"} or \code{"L"},
indicating which triangle of \code{x} should be used
to compute the factorization.}
\item{\dots}{further arguments passed to or from methods.}
}
\value{
An object representing the factorization, inheriting from
virtual class \code{\linkS4class{BunchKaufmanFactorization}}.
The specific class is \code{\linkS4class{BunchKaufman}} unless
\code{x} inherits from virtual class \code{\linkS4class{packedMatrix}},
in which case it is \code{\linkS4class{pBunchKaufman}}.
}
\seealso{
Classes \code{\linkS4class{BunchKaufman}} and
\code{\linkS4class{pBunchKaufman}} and their methods.
Classes \code{\linkS4class{dsyMatrix}} and
\code{\linkS4class{dspMatrix}}.
Generic functions \code{\link{expand1}} and \code{\link{expand2}},
for constructing matrix factors from the result.
Generic functions \code{\link{Cholesky}}, \code{\link{Schur}},
\code{\link{lu}}, and \code{\link{qr}},
for computing other factorizations.
}
\references{
The LAPACK source code, including documentation; see
\url{https://netlib.org/lapack/double/dsytrf.f} and
\url{https://netlib.org/lapack/double/dsptrf.f}.
Golub, G. H., & Van Loan, C. F. (2013).
\emph{Matrix computations} (4th ed.).
Johns Hopkins University Press.
\doi{10.56021/9781421407944}
}
\examples{
\dontshow{ % for R_DEFAULT_PACKAGES=NULL
library(utils, pos = "package:base", verbose = FALSE)
}
showMethods("BunchKaufman", inherited = FALSE)
set.seed(0)
data(CAex, package = "Matrix")
class(CAex) # dgCMatrix
isSymmetric(CAex) # symmetric, but not formally
A <- as(CAex, "symmetricMatrix")
class(A) # dsCMatrix
## Have methods for denseMatrix (unpacked and packed),
## but not yet sparseMatrix ...
\dontrun{
(bk.A <- BunchKaufman(A))
}
(bk.A <- BunchKaufman(as(A, "unpackedMatrix")))
## A ~ U DU U' in floating point
str(e.bk.A <- expand2(bk.A), max.level = 2L)
stopifnot(all.equal(as(A, "matrix"), as(Reduce(`\%*\%`, e.bk.A), "matrix")))
}