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

C Header Interface

#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.

3 Description

f07htf computes a diagonal scaling matrix

S

chosen so that

s_{j} = 1 / \sqrt{a_{j j}} .

This means that the matrix

B

given by

B = S A S,

has diagonal elements equal to unity. This in turn means that the condition number of

B

κ_{2} (B)

, 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)).

4 References

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

5 Arguments

1: $uplo$ – Character(1) Input

On entry: indicates whether the upper or lower triangular part of

A

is stored in the array ab, as follows:

$uplo ='U'$: The upper triangle of $A$ is stored.
$uplo ='L'$: The lower triangle of $A$ is stored.

Constraint:

uplo ='U'

'L'

2: $n$ – Integer Input

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 0

3: $kd$ – Integer Input

On entry:

k_{d}

, the number of superdiagonals of the matrix

A

uplo ='U'

, or the number of subdiagonals if

uplo ='L'

Constraint:

kd \geq 0

4: $ab (ldab, *)$ – Complex (Kind=nag_wp) array Input

Note: the second dimension of the array ab must be at least

\max (1, n)

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

k_{d} + 1

, more precisely,

if $uplo ='U'$ , the elements of the upper triangle of $A$ within the band must be stored with element $A_{i j}$ in $ab (k_{d} + 1 + i - j, j) for \max (1, j - k_{d}) \leq i \leq j$ ;
if $uplo ='L'$ , the elements of the lower triangle of $A$ within the band must be stored with element $A_{i j}$ in $ab (1 + i - j, j) for j \leq i \leq \min (n, j + k_{d}) .$

Only the elements of the array ab corresponding to the diagonal elements of

A

are referenced. (Row

(k_{d} + 1)

of ab when

uplo ='U'

, row

1

of ab when

uplo ='L'

5: $ldab$ – Integer Input

On entry: the first dimension of the array ab as declared in the (sub)program from which f07htf is called.

Constraint:

ldab \geq kd + 1

6: $s (n)$ – Real (Kind=nag_wp) array Output

On exit: if

info = 0

, s contains the diagonal elements of the scaling matrix

S

7: $scond$ – Real (Kind=nag_wp) Output

On exit: if

info = 0

, scond contains the ratio of the smallest value of s to the largest value of s. If

scond \geq 0.1

and amax is neither too large nor too small, it is not worth scaling by

S

8: $amax$ – Real (Kind=nag_wp) Output

On exit:

\max | a_{i j} |

. If amax is very close to overflow or underflow, the matrix

A

should be scaled.

9: $info$ – Integer Output

On exit:

info = 0

unless the routine detects an error (see Section 6).

6 Error Indicators and Warnings

$info < 0$: If $info = - i$ , argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

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

7 Accuracy

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

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

f07htf is not threaded in any implementation.

9 Further Comments

The real analogue of this routine is f07hff.

10 Example

This example equilibrates the Hermitian positive definite matrix

A

given by

A = (\begin{array}{l} 9.39 & 1.08 - 1.73 i & 0 & 0 \\ 1.08 + 1.73 i & 1.69 & (- 0.04 + 0.29 i) \times 10^{10} & 0 \\ 0 & (- 0.04 - 0.29 i) \times 10^{10} & 2.65 \times 10^{20} & (- 0.33 + 2.24 i) \times 10^{10} \\ 0 & 0 & (- 0.33 - 2.24 i) \times 10^{10} & 2.17 \end{array}) .

Details of the scaling factors and the scaled matrix are output.

f07ht: FL CL CPP AD PY MB

NAG FL Interfacef07htf (zpbequ)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
f07htf (zpbequ)