isSymmetric(<matrix>) gains optional trans = "C"

git-svn-id: https://svn.r-project.org/R/trunk@88000 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: maechler

doc/NEWS.Rd

@@ -236,14 +236,18 @@
 
       \item New datasets \code{penguins} and \code{penguins_raw} thanks to
       \I{Ella Kaye}, \I{Heather Turner}, and \I{Kristen Gorman}.
+
+      \item \code{isSymmetric(<matrix>)} gains a new option \code{trans = "C"};
+      when set to non-default, it tests for \dQuote{simple} symmetry of
+      complex matrices.
     }
   }
 
   \subsection{BLAS and LAPACK}{
     \itemize{
       \item The bundled BLAS and LAPACK sources have been updated to
       those shipped as part of January 2025's LAPACK 3.12.1.
-      
+
       \item It is intended that this will be the last update to BLAS and
       LAPACK in the \R sources.  Those building \R from source are
       encouraged to use external BLAS and LAPACK and this will be required in
@@ -270,7 +274,7 @@
       \item Windows builds currently use the internal LAPACK and by
       default the internal BLAS: notes on how to swap the latter
       \emph{via} \file{Rblas.dll} are in file
-      \file{src/extra/blas/Makefile.win}. 
+      \file{src/extra/blas/Makefile.win}.
     }
   }
 

src/library/base/R/eigen.R

@@ -1,7 +1,7 @@
 #  File src/library/base/R/eigen.R
 #  Part of the R package, https://www.R-project.org
 #
-#  Copyright (C) 1995-2019 The R Core Team
+#  Copyright (C) 1995-2025 The R Core Team
 #
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -19,13 +19,14 @@
 
 isSymmetric <- function(object, ...) UseMethod("isSymmetric")
 
-isSymmetric.matrix <- function(object, tol = 100*.Machine$double.eps, tol1 = 8*tol, ...)
+isSymmetric.matrix <- function(object, tol = 100*.Machine$double.eps,
+                               tol1 = 8*tol, trans = "C", ...)
 {
     if(!is.matrix(object)) return(FALSE) ## we test for  symmetric *matrix*
     ## cheap pretest: is it square?
     d <- dim(object)
     if((n <- d[1L]) != d[2L]) return(FALSE)
-    iCplx <- is.complex(object)
+    iCplx <- is.complex(object) && trans == "C"
     if(n > 1L && length(tol1)) {
 	## initial pre-tests, fast for large non-symmetric:
 	Cj <- if(iCplx) Conj else identity
@@ -36,7 +37,7 @@ isSymmetric.matrix <- function(object, tol = 100*.Machine$double.eps, tol1 = 8*t
     test <-
         if(iCplx)
             all.equal.numeric(object, Conj(t(object)), tolerance = tol, ...)
-        else # numeric, character, ..
+        else # numeric, character, {complex, trans != "C"}, ..
             all.equal(object, t(object), tolerance = tol, ...)
     isTRUE(test)
 }

src/library/base/man/isSymmetric.Rd

@@ -1,6 +1,6 @@
 % File src/library/base/man/isSymmetric.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2018 R Core Team
+% Copyright 1995-2025 R Core Team
 % Distributed under GPL 2 or later
 
 \name{isSymmetric}
@@ -11,12 +11,14 @@
   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.
+  \code{isSymmetric(Z)} to be true, and
+  (since \R >= 4.5.0),
+  \code{isSymmetric(Z, trans = "T")} checks for \dQuote{simple} symmetry.
 }
 \usage{
 isSymmetric(object, \dots)
 \method{isSymmetric}{matrix}(object, tol = 100 * .Machine$double.eps,
-            tol1 = 8 * tol, \dots)
+            tol1 = 8 * tol, trans = "C", \dots)
 }
 \arguments{
   \item{object}{any \R object; a \code{\link{matrix}} for the matrix method.}
@@ -26,6 +28,11 @@ isSymmetric(object, \dots)
     \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{trans}{a single \code{\link{character}}, only relevant for a
+    \code{\link{complex}} matrix \code{Z}: if it is \code{"C"} (as by
+    default), \code{Conj(t(Z))} must be the same as \code{Z} whereas
+    otherwise (typically it is \code{"T"}) \code{t(Z)} must equal
+    \code{Z}.  The argument name is inherited from LAPACK.}
   \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
@@ -55,8 +62,9 @@ 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
+z <- sqrt(matrix(-1:2 + 0i, 2)); Z <- t(Conj(z)) \%*\% z
+ZtZ <- t(z) \%*\% z
+Z ; ZtZ
 isSymmetric(Z)      # TRUE
 isSymmetric(Z + 1)  # TRUE
 isSymmetric(Z + 1i) # FALSE -- a Hermitian matrix has a *real* diagonal