naginterfaces.library.lapacklin.zpbequ

naginterfaces.library.lapacklin.zpbequ(uplo, n, kd, ab)

zpbequ computes a diagonal scaling matrix $S$ intended to equilibrate a complex $n\times n$ Hermitian positive definite band matrix $A$, with bandwidth $(2k_d+1)$, and reduce its condition number.

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

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

Parameters

uplostr, length 1

Indicates whether the upper or lower triangular part of $A$ is stored in the array $ab$, 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$.

kdint

$k_d$, the number of superdiagonals of the matrix $A$ if $uplo=\text{'U'}$, or the number of subdiagonals if $uplo=\text{'L'}$.

abcomplex, array-like, shape $(kd+1,n)$

The upper or lower triangle of the Hermitian positive definite band matrix $A$ whose scaling factors are to be computed.

Only the elements of the array $ab$ corresponding to the diagonal elements of $A$ are referenced. (Row $(k_d+1)$ of $ab$ when $uplo=\text{'U'}$, row $1$ of $ab$ when $uplo=\text{'L'}$.)

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 $-3$)

On entry, error in parameter $kd$.

Constraint: $kd\ge 0$.

(errno $i>0$)

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

Notes

zpbequ 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