naginterfaces.library.lapacklin.zppequ

naginterfaces.library.lapacklin.zppequ(uplo, n, ap)

zppequ computes a diagonal scaling matrix $S$ intended to equilibrate a complex $n\times n$ Hermitian positive definite matrix $A$, stored in packed format, and reduce its condition number.

For full information please refer to the NAG Library document for f07gt

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f07/f07gtf.html

Parameters

uplostr, length 1

Indicates whether the upper or lower triangular part of $A$ is stored in the array $ap$, as follows:

$uplo=\text{'U'}$

The upper triangle of $A$ is stored.

$uplo=\text{'L'}$

The lower triangle of $A$ is stored.

nint

$n$, the order of the matrix $A$.

apcomplex, array-like, shape $(n\times (n+1)/2)$

The $n\times n$ Hermitian matrix $A$, packed by columns.

Only the elements of $ap$ corresponding to the diagonal elements $A$ are referenced.

Returns

sfloat, ndarray, shape $\left(n\right)$

If no exception or warning is raised, $s$ contains the diagonal elements of the scaling matrix $S$.

scondfloat

If no exception or warning is raised, $scond$ contains the ratio of the smallest value of $s$ to the largest value of $s$. If $scond\ge 0.1$ and $amax$ is neither too large nor too small, it is not worth scaling by $S$.

amaxfloat

$max\left|a_{ij}\right|$. If $amax$ is very close to overflow or underflow, the matrix $A$ should be scaled.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $uplo$.

Constraint: $uplo=\text{'U'}$ or $\text{'L'}$.

(errno $-2$)

On entry, error in parameter $n$.

Constraint: $n\ge 0$.

(errno $i>0$)

The $⟨value⟩$th diagonal element of $A$ is not positive (and hence $A$ cannot be positive definite).

Notes

zppequ computes a diagonal scaling matrix $S$ chosen so that

$$s_j=1/\sqrt{a_{jj}}\text{.}$$

This means that the matrix $B$ given by

$$B=SAS\text{,}$$

has diagonal elements equal to unity. This in turn means that the condition number of $B$, ${\kappa }_2\left(B\right)$, is within a factor $n$ of the matrix of smallest possible condition number over all possible choices of diagonal scalings (see Corollary 7.6 of Higham (2002)).

References

Higham, N J, 2002, Accuracy and Stability of Numerical Algorithms, (2nd Edition), SIAM, Philadelphia