NAG Library Function Document

nag_dpbequ (f07hfc)

void	nag_dpbequ (Nag_OrderType order, Nag_UploType uplo, Integer n, Integer kd, const double ab[], Integer pdab, double s[], double scond, double amax, NagError *fail)

3 Description

nag_dpbequ (f07hfc) 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: order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

Nag_ColMajor

2: uplo – Nag_UploTypeInput

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

A

is stored in the array ab, as follows:

$uplo = Nag_Upper$: The upper triangle of $A$ is stored.
$uplo = Nag_Lower$: The lower triangle of $A$ is stored.

Constraint:

uplo = Nag_Upper

Nag_Lower

3: n – IntegerInput

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 0

4: kd – IntegerInput

On entry:

k_{d}

, the number of superdiagonals of the matrix

A

uplo = Nag_Upper

, or the number of subdiagonals if

uplo = Nag_Lower

Constraint:

kd \geq 0

5: ab[ $\dim$ ] – const doubleInput

Note: the dimension, dim, of the array ab must be at least

\max (1, pdab \times n)

On entry: the upper or lower triangle of the symmetric positive definite band matrix

A

whose scaling factors are to be computed.

This is stored as a notional two-dimensional array with row elements or column elements stored contiguously. The storage of elements of

A_{i j}

, depends on the order and uplo arguments as follows:

if $order = Nag_ColMajor$ and $uplo = Nag_Upper$ ,
$A_{i j}$ is stored in $ab [k_{d} + i - j + (j - 1) \times pdab]$ , for $j = 1, \dots, n$ and $i = \max (1, j - k_{d}), \dots, j$ ;
if $order = Nag_ColMajor$ and $uplo = Nag_Lower$ ,
$A_{i j}$ is stored in $ab [i - j + (j - 1) \times pdab]$ , for $j = 1, \dots, n$ and $i = j, \dots, \min (n, j + k_{d})$ ;
if $order = Nag_RowMajor$ and $uplo = Nag_Upper$ ,
$A_{i j}$ is stored in $ab [j - i + (i - 1) \times pdab]$ , for $i = 1, \dots, n$ and $j = i, \dots, \min (n, i + k_{d})$ ;
if $order = Nag_RowMajor$ and $uplo = Nag_Lower$ ,
$A_{i j}$ is stored in $ab [k_{d} + j - i + (i - 1) \times pdab]$ , for $i = 1, \dots, n$ and $j = \max (1, i - k_{d}), \dots, i$ .

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

A

are referenced. (Row

(k_{d} + 1)

of ab when

uplo = Nag_Upper

, row

1

of ab when

uplo = Nag_Lower

6: pdab – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) of the matrix

A

in the array ab.

Constraint:

pdab \geq kd + 1

7: s[n] – doubleOutput

On exit: if

fail . code =

NE_NOERROR, s contains the diagonal elements of the scaling matrix

S

8: scond – double *Output

On exit: if

fail . code =

NE_NOERROR, 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

9: amax – double *Output

On exit:

\max |a_{i j}|

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

A

should be scaled.

10: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_BAD_PARAM: On entry, argument $⟨value⟩$ had an illegal value.
NE_INT: On entry, $kd = ⟨value⟩$ .
Constraint: $kd \geq 0$ .
On entry, $n = ⟨value⟩$ .
Constraint: $n \geq 0$ .
On entry, $pdab = ⟨value⟩$ .
Constraint: $pdab > 0$ .
NE_INT_2: On entry, $pdab = ⟨value⟩$ and $kd = ⟨value⟩$ .
Constraint: $pdab \geq kd + 1$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_MAT_NOT_POS_DEF: 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

Not applicable.

9 Further Comments

The complex analogue of this function is nag_zpbequ (f07htc).

10 Example

This example equilibrates the symmetric positive definite matrix

A

given by

A = (\begin{array}{l} 5.49 & 2.68 \times 10^{10} & 0 & 0 \\ 2.68 \times 10^{10} & 5.63 \times 10^{20} & - 2.39 \times 10^{10} & 0 \\ 0 & - 2.39 \times 10^{10} & 2.60 & - 2.22 \\ 0 & 0 & - 2.22 & 5.17 \end{array}) .

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

NAG Library Function Documentnag_dpbequ (f07hfc)

+− 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 Library Function Document

nag_dpbequ (f07hfc)