blob: 6e36cbdd888e73166b65bc71402c4c9bb344cd70 [file] [log] [blame]
% File src/library/base/man/isSymmetric.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2018 R Core Team
% Distributed under GPL 2 or later
\name{isSymmetric}
\alias{isSymmetric}
\alias{isSymmetric.matrix}
\title{Test if a Matrix or other Object is Symmetric (Hermitian)}
\description{
Generic function to test if \code{object} is symmetric or not.
Currently only a matrix method is implemented, where a
\code{\link{complex}} matrix \code{Z} must be \dQuote{Hermitian} for
\code{isSymmetric(Z)} to be true.
}
\usage{
isSymmetric(object, \dots)
\method{isSymmetric}{matrix}(object, tol = 100 * .Machine$double.eps,
tol1 = 8 * tol, \dots)
}
\arguments{
\item{object}{any \R object; a \code{\link{matrix}} for the matrix method.}
\item{tol}{numeric scalar >= 0. Smaller differences are not
considered, see \code{\link{all.equal.numeric}}.}
\item{tol1}{numeric scalar >= 0. \code{isSymmetric.matrix()}
\sQuote{pre-tests} the first and last few rows for fast detection of
\sQuote{obviously} asymmetric cases with this tolerance. Setting it
to length zero will skip the pre-tests.}
\item{\dots}{further arguments passed to methods; the matrix method
passes these to \code{\link{all.equal}}. If the row and column
names of \code{object} are allowed to differ for the symmetry check
do use \code{check.attributes = FALSE}!}
}
\value{
logical indicating if \code{object} is symmetric or not.
}
\details{
The \code{\link{matrix}} method is used inside \code{\link{eigen}} by
default to test symmetry of matrices \emph{up to rounding error}, using
\code{\link{all.equal}}. It might not be appropriate in all
situations.
Note that a matrix \code{m} is only symmetric if its \code{rownames} and
\code{colnames} are identical. Consider using \code{\link{unname}(m)}.
}
\seealso{\code{\link{eigen}} which calls \code{isSymmetric} when its
\code{symmetric} argument is missing.
}
\examples{
isSymmetric(D3 <- diag(3)) # -> TRUE
D3[2, 1] <- 1e-100
D3
isSymmetric(D3) # TRUE
isSymmetric(D3, tol = 0) # FALSE for zero-tolerance
## Complex Matrices - Hermitian or not
Z <- sqrt(matrix(-1:2 + 0i, 2)); Z <- t(Conj(Z)) \%*\% Z
Z
isSymmetric(Z) # TRUE
isSymmetric(Z + 1) # TRUE
isSymmetric(Z + 1i) # FALSE -- a Hermitian matrix has a *real* diagonal
colnames(D3) <- c("X", "Y", "Z")
isSymmetric(D3) # FALSE (as row and column names differ)
isSymmetric(D3, check.attributes=FALSE) # TRUE (as names are not checked)
}
\keyword{array}
\keyword{utilities}