Integer, Intent (In)	::	m, n, kl, ku, ldab
Integer, Intent (Out)	::	info
Real (Kind=nag_wp), Intent (Out)	::	r(m), c(n), rowcnd, colcnd, amax
Complex (Kind=nag_wp), Intent (In)	::	ab(ldab,*)

C Header Interface

#include <nag.h>

void	f07btf_ (const Integer m, const Integer n, const Integer kl, const Integer ku, const Complex ab[], const Integer ldab, double r[], double c[], double rowcnd, double colcnd, double amax, Integer *info)

The routine may be called by the names f07btf, nagf_lapacklin_zgbequ or its LAPACK name zgbequ.

3 Description

f07btf computes the diagonal scaling matrices. The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix

B

given by

B = D_{R} A D_{C}

have absolute value

1

. The diagonal elements of

D_{R}

and

D_{C}

are restricted to lie in the safe range

(δ, 1 / δ)

, where

δ

is the value returned by routine x02amf. Use of these scaling factors is not guaranteed to reduce the condition number of

A

but works well in practice.

4 References

None.

5 Arguments

1: $m$ – Integer Input

On entry:

m

, the number of rows of the matrix

A

Constraint:

m \geq 0

2: $n$ – Integer Input

On entry:

n

, the number of columns of the matrix

A

Constraint:

n \geq 0

3: $kl$ – Integer Input

On entry:

k_{l}

, the number of subdiagonals of the matrix

A

Constraint:

kl \geq 0

4: $ku$ – Integer Input

On entry:

k_{u}

, the number of superdiagonals of the matrix

A

Constraint:

ku \geq 0

5: $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

m \times n

band matrix

A

whose scaling factors are to be computed.

The matrix is stored in rows

1

k_{l} + k_{u} + 1

, more precisely, the element

A_{i j}

must be stored in

ab (k_{u} + 1 + i - j, j) for ​ \max (1, j - k_{u}) \leq i \leq \min (m, j + k_{l}) .

See Section 9 in f07bnf for further details.

6: $ldab$ – Integer Input

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

Constraint:

ldab \geq kl + ku + 1

7: $r (m)$ – Real (Kind=nag_wp) array Output

On exit: if

info = 0

info > m

, r contains the row scale factors, the diagonal elements of

D_{R}

. The elements of r will be positive.

8: $c (n)$ – Real (Kind=nag_wp) array Output

On exit: if

info = 0

, c contains the column scale factors, the diagonal elements of

D_{C}

. The elements of c will be positive.

9: $rowcnd$ – Real (Kind=nag_wp) Output

On exit: if

info = 0

info > m

, rowcnd contains the ratio of the smallest value of

r (i)

to the largest value of

r (i)

. If

rowcnd \geq 0.1

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

D_{R}

10: $colcnd$ – Real (Kind=nag_wp) Output

On exit: if

info = 0

, colcnd contains the ratio of the smallest value of

c (i)

to the largest value of

c (i)

colcnd \geq 0.1

, it is not worth scaling by

D_{C}

11: $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.

12: $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 and info \leq m$: Row $⟨ value ⟩$ of $A$ is exactly zero.

$info > m$: Column $⟨ value ⟩$ of $A$ is exactly zero.

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.

f07btf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The real analogue of this routine is f07bff.

10 Example

This example equilibrates the complex band matrix

A

given by

A = (\begin{array}{l} - 1.65 + 2.26 i & (- 2.05 - 0.85 i) \times 10^{−10} & 0.97 - 2.84 i & 0 \\ 0.00 + 6.30 i & (- 1.48 - 1.75 i) \times 10^{−10} & - 3.99 + 4.01 i & 0.59 - 0.48 i \\ 0 & - 0.77 + 2.83 i & (- 1.06 + 1.94 i) \times 10^{10} & (3.33 - 1.04 i) \times 10^{10} \\ 0 & 0 & 0.48 - 1.09 i & - 0.46 - 1.72 i \end{array}) .

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

f07bt: FL CL CPP AD PY MB

NAG FL Interfacef07btf (zgbequ)

▸▿ 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
f07btf (zgbequ)