Sign

The matrix sign function can be written as

\[\text{sgn}(A) = A(A^2)^{-1/2},\]

as long as \(A\) does not have any pure-imaginary eigenvalues.

General

The current implementation for \(n \times n\) matrices makes use of a globally-convergent Newton iteration with several scaling options. Each iteration takes the form

\[X_{k+1} := \frac{1}{2} ( \mu_k X_k + \mu_k^{-1} X_k^{-1} ),\]

where \(\mu_k\) is the scaling factor computed from \(X_k\). Convergence is determined to occur when

\[\| X_{k+1} - X_k \|_1 \le \| X_{k+1} \|_1^{q+1} \text{tol},\]

where the exponent \(q\) is typically one, and the relative tolerance, tol, defaults to \(n \epsilon\), where \(\epsilon\) is the machine precision. Please see Nicholas J. Higham and Awad H. Al-Mohy’s Computing Matrix Functions for more details.

C++ API

void Sign(Matrix<F> &A, SignCtrl<Base<F>> signCtrl = SignCtrl<Base<F>>())

void Sign(AbstractDistMatrix<F> &A, SignCtrl<Base<F>> signCtrl = SignCtrl<Base<F>>())

Overwrite \(A\) with \(\text{sgn}(A)\)

void Sign(Matrix<F> &A, Matrix<F> &N, SignCtrl<Base<F>> signCtrl = SignCtrl<Base<F>>())

void Sign(AbstractDistMatrix<F> &A, AbstractDistMatrix<F> &N, SignCtrl<Base<F>> signCtrl = SignCtrl<Base<F>>())

Compute the polar decomposition \(A = S N\), where \(S=\text{sgn}(A)\), overwriting \(A\) with \(S\) on exit

type SignScaling

An enum which can be set to one of

• SIGN_SCALE_NONE

• SIGN_SCALE_DET

• SIGN_SCALE_FROB

template<>
type SignCtrl<Real>

int maxIts

Real tol

Real power

SignScaling scaling

bool progress

template<>
type SignCtrl<Base<F>>

A particular case where the datatype is the base of the potentially complex datatype F.

C API

ElError ElSign_s(ElMatrix_s A)

ElError ElSign_d(ElMatrix_d A)

ElError ElSign_c(ElMatrix_c A)

ElError ElSign_z(ElMatrix_z A)

ElError ElSignDist_s(ElDistMatrix_s A)

ElError ElSignDist_d(ElDistMatrix_d A)

ElError ElSignDist_c(ElDistMatrix_c A)

ElError ElSignDist_z(ElDistMatrix_z A)

Overwrite \(A\) with \(\text{sgn}(A)\)

ElError ElSignDecomp_s(ElMatrix_s A, ElMatrix_s N)

ElError ElSignDecomp_d(ElMatrix_d A, ElMatrix_d N)

ElError ElSignDecomp_c(ElMatrix_c A, ElMatrix_c N)

ElError ElSignDecomp_z(ElMatrix_z A, ElMatrix_z N)

ElError ElSignDecompDist_s(ElDistMatrix_s A, ElDistMatrix_s N)

ElError ElSignDecompDist_d(ElDistMatrix_d A, ElDistMatrix_d N)

ElError ElSignDecompDist_c(ElDistMatrix_c A, ElDistMatrix_c N)

ElError ElSignDecompDist_z(ElDistMatrix_z A, ElDistMatrix_z N)

Compute the polar decomposition \(A = S N\), where \(S=\text{sgn}(A)\), overwriting \(A\) with \(S\) on exit

TODO: Add an expert interface

ElSignCtrl_s

ElInt maxIts

float tol

float power

ElSignScaling scaling

bool progress

ElSignCtrl_d

ElInt maxIts

double tol

double power

ElSignScaling scaling

bool progress

ElSignScaling

An enum which can be set to one of

• EL_SIGN_SCALE_NONE

• EL_SIGN_SCALE_DET

• EL_SIGN_SCALE_FROB

Hermitian

Compute the Hermitian EVD, replace the eigenvalues with their sign, and then reform the matrix. Optionally return the full decomposition, \(A=SN\), where \(A\) is overwritten by \(S\). Note that this will also be a polar decomposition.

C++ API

void HermitianSign(UpperOrLower uplo, Matrix<F> &A)

void HermitianSign(UpperOrLower uplo, AbstractDistMatrix<F> &A)

Overwrite \(A\) with \(\text{sgn}(A)\)

void HermitianSign(UpperOrLower uplo, Matrix<F> &A, Matrix<F> &N)

void HermitianSign(UpperOrLower uplo, AbstractDistMatrix<F> &A, AbstractDistMatrix<F> &N)

Compute the polar decomposition \(A = S N\), where \(S=\text{sgn}(A)\), overwriting \(A\) with \(S\) on exit

C API

ElError ElHermitianSign_s(ElUpperOrLower uplo, ElMatrix_s A)

ElError ElHermitianSign_d(ElUpperOrLower uplo, ElMatrix_d A)

ElError ElHermitianSign_c(ElUpperOrLower uplo, ElMatrix_c A)

ElError ElHermitianSign_z(ElUpperOrLower uplo, ElMatrix_z A)

ElError ElHermitianSignDist_s(ElUpperOrLower uplo, ElDistMatrix_s A)

ElError ElHermitianSignDist_d(ElUpperOrLower uplo, ElDistMatrix_d A)

ElError ElHermitianSignDist_c(ElUpperOrLower uplo, ElDistMatrix_c A)

ElError ElHermitianSignDist_z(ElUpperOrLower uplo, ElDistMatrix_z A)

Overwrite \(A\) with \(\text{sgn}(A)\)

ElError ElHermitianSignDecomp_s(ElUpperOrLower uplo, ElMatrix_s A, ElMatrix_s N)

ElError ElHermitianSignDecomp_d(ElUpperOrLower uplo, ElMatrix_d A, ElMatrix_d N)

ElError ElHermitianSignDecomp_c(ElUpperOrLower uplo, ElMatrix_c A, ElMatrix_c N)

ElError ElHermitianSignDecomp_z(ElUpperOrLower uplo, ElMatrix_z A, ElMatrix_z N)

ElError ElHermitianSignDecompDist_s(ElUpperOrLower uplo, ElDistMatrix_s A, ElDistMatrix_s N)

ElError ElHermitianSignDecompDist_d(ElUpperOrLower uplo, ElDistMatrix_d A, ElDistMatrix_d N)

ElError ElHermitianSignDecompDist_c(ElUpperOrLower uplo, ElDistMatrix_c A, ElDistMatrix_c N)

ElError ElHermitianSignDecompDist_z(ElUpperOrLower uplo, ElDistMatrix_z A, ElDistMatrix_z N)

Compute the polar decomposition \(A = S N\), where \(S=\text{sgn}(A)\), overwriting \(A\) with \(S\) on exit