NAG FL Interfacef07htf (zpbequ)

▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

1Purpose

f07htf computes a diagonal scaling matrix $S$ intended to equilibrate a complex $n×n$ Hermitian positive definite band matrix $A$, with bandwidth $\left(2{k}_{d}+1\right)$, and reduce its condition number.

2Specification

Fortran Interface
 Subroutine f07htf ( uplo, n, kd, ab, ldab, s, amax, info)
 Integer, Intent (In) :: n, kd, ldab Integer, Intent (Out) :: info Real (Kind=nag_wp), Intent (Out) :: s(n), scond, amax Complex (Kind=nag_wp), Intent (In) :: ab(ldab,*) Character (1), Intent (In) :: uplo
#include <nag.h>
 void f07htf_ (const char *uplo, const Integer *n, const Integer *kd, const Complex ab[], const Integer *ldab, double s[], double *scond, double *amax, Integer *info, const Charlen length_uplo)
The routine may be called by the names f07htf, nagf_lapacklin_zpbequ or its LAPACK name zpbequ.

3Description

f07htf computes a diagonal scaling matrix $S$ chosen so that
 $sj=1 / ajj .$
This means that the matrix $B$ given by
 $B=SAS ,$
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)).

4References

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

5Arguments

1: $\mathbf{uplo}$Character(1) Input
On entry: indicates whether the upper or lower triangular part of $A$ is stored in the array ab, as follows:
${\mathbf{uplo}}=\text{'U'}$
The upper triangle of $A$ is stored.
${\mathbf{uplo}}=\text{'L'}$
The lower triangle of $A$ is stored.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
2: $\mathbf{n}$Integer Input
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
3: $\mathbf{kd}$Integer Input
On entry: ${k}_{d}$, the number of superdiagonals of the matrix $A$ if ${\mathbf{uplo}}=\text{'U'}$, or the number of subdiagonals if ${\mathbf{uplo}}=\text{'L'}$.
Constraint: ${\mathbf{kd}}\ge 0$.
4: $\mathbf{ab}\left({\mathbf{ldab}},*\right)$Complex (Kind=nag_wp) array Input
Note: the second dimension of the array ab must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry: the upper or lower triangle of the Hermitian positive definite band matrix $A$ whose scaling factors are to be computed.
The matrix is stored in rows $1$ to ${k}_{d}+1$, more precisely,
• if ${\mathbf{uplo}}=\text{'U'}$, the elements of the upper triangle of $A$ within the band must be stored with element ${A}_{ij}$ in ${\mathbf{ab}}\left({k}_{d}+1+i-j,j\right)\text{​ for ​}\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,j-{k}_{d}\right)\le i\le j$;
• if ${\mathbf{uplo}}=\text{'L'}$, the elements of the lower triangle of $A$ within the band must be stored with element ${A}_{ij}$ in ${\mathbf{ab}}\left(1+i-j,j\right)\text{​ for ​}j\le i\le \mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,j+{k}_{d}\right)\text{.}$
Only the elements of the array ab corresponding to the diagonal elements of $A$ are referenced. (Row $\left({k}_{d}+1\right)$ of ab when ${\mathbf{uplo}}=\text{'U'}$, row $1$ of ab when ${\mathbf{uplo}}=\text{'L'}$.)
5: $\mathbf{ldab}$Integer Input
On entry: the first dimension of the array ab as declared in the (sub)program from which f07htf is called.
Constraint: ${\mathbf{ldab}}\ge {\mathbf{kd}}+1$.
6: $\mathbf{s}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
On exit: if ${\mathbf{info}}={\mathbf{0}}$, s contains the diagonal elements of the scaling matrix $S$.
7: $\mathbf{scond}$Real (Kind=nag_wp) Output
On exit: if ${\mathbf{info}}={\mathbf{0}}$, scond contains the ratio of the smallest value of s to the largest value of s. If ${\mathbf{scond}}\ge 0.1$ and amax is neither too large nor too small, it is not worth scaling by $S$.
8: $\mathbf{amax}$Real (Kind=nag_wp) Output
On exit: $\mathrm{max}|{a}_{ij}|$. If amax is very close to overflow or underflow, the matrix $A$ should be scaled.
9: $\mathbf{info}$Integer Output
On exit: ${\mathbf{info}}=0$ unless the routine detects an error (see Section 6).

6Error Indicators and Warnings

${\mathbf{info}}<0$
If ${\mathbf{info}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.
${\mathbf{info}}>0$
The $⟨\mathit{\text{value}}⟩$th diagonal element of $A$ is not positive (and hence $A$ cannot be positive definite).

7Accuracy

The computed scale factors will be close to the exact scale factors.

8Parallelism and Performance

f07htf is not threaded in any implementation.

The real analogue of this routine is f07hff.

10Example

This example equilibrates the Hermitian positive definite matrix $A$ given by
 $A = ( 9.39 -i1.08-1.73i -i0 -i0 1.08+1.73i -i1.69 (-0.04+0.29i)×1010 -i0 0 (-0.04-0.29i)×1010 2.65×1020 (-0.33+2.24i)×1010 0 -i0 (-0.33-2.24i)×1010 -i2.17 ) .$
Details of the scaling factors and the scaled matrix are output.

10.1Program Text

Program Text (f07htfe.f90)

10.2Program Data

Program Data (f07htfe.d)

10.3Program Results

Program Results (f07htfe.r)