Integer, Intent (In)	::	n, lal, nrow(n), ir, ldb, iselct, ldx
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	al(lal), d(*), b(ldb,ir)
Real (Kind=nag_wp), Intent (Inout)	::	x(ldx,ir)

C Header Interface

#include <nag.h>

void	f04mcf_ (const Integer n, const double al[], const Integer lal, const double d[], const Integer nrow[], const Integer ir, const double b[], const Integer ldb, const Integer iselct, double x[], const Integer ldx, Integer *ifail)

The routine may be called by the names f04mcf or nagf_linsys_real_posdef_vband_solve.

3 Description

The normal use of this routine is the solution of the systems

A X = B

, following a call of f01mcf to determine the Cholesky factorization

A = L D L^{T}

of the symmetric positive definite variable-bandwidth matrix

A

However, the routine may be used to solve any one of the following systems of linear algebraic equations:

1. $L D L^{T} X = B$ (usual system),
2. $L D X = B$ (lower triangular system),
3. $D L^{T} X = B$ (upper triangular system),
4. $L L^{T} X = B$
5. $L X = B$ (unit lower triangular system),
6. $L^{T} X = B$ (unit upper triangular system).

L

denotes a unit lower triangular variable-bandwidth matrix of order

n

D

a diagonal matrix of order

n

, and

B

a set of right-hand sides.

The matrix

L

is represented by the elements lying within its envelope, i.e., between the first nonzero of each row and the diagonal. The width

nrow (i)

of the

i

th row is the number of elements between the first nonzero element and the element on the diagonal inclusive.

4 References

Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra Springer–Verlag

5 Arguments

1: $n$ – Integer Input

On entry:

n

, the order of the matrix

L

Constraint:

n \geq 1

2: $al (lal)$ – Real (Kind=nag_wp) array Input

On entry: the elements within the envelope of the lower triangular matrix

L

, taken in row by row order, as returned by f01mcf. The unit diagonal elements of

L

must be stored explicitly.

3: $lal$ – Integer Input

On entry: the dimension of the array al as declared in the (sub)program from which f04mcf is called.

Constraint:

lal \geq nrow (1) + nrow (2) + \dots + nrow (n)

4: $d (*)$ – Real (Kind=nag_wp) array Input

Note: the dimension of the array d must be at least

1

iselct \geq 4

, and at least

n

otherwise.

On entry: the diagonal elements of the diagonal matrix

D

. d is not referenced if

iselct \geq 4

5: $nrow (n)$ – Integer array Input

On entry:

nrow (i)

must contain the width of row

i

L

, i.e., the number of elements between the first (leftmost) nonzero element and the element on the diagonal, inclusive.

Constraint:

1 \leq nrow (i) \leq i

6: $ir$ – Integer Input

On entry:

r

, the number of right-hand sides.

Constraint:

ir \geq 1

7: $b (ldb, ir)$ – Real (Kind=nag_wp) array Input

On entry: the

n \times r

right-hand side matrix

B

. See also Section 9.

8: $ldb$ – Integer Input

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

Constraint:

ldb \geq n

9: $iselct$ – Integer Input

On entry: must specify the type of system to be solved, as follows:

$iselct = 1$: Solve $L D L^{T} X = B$ .
$iselct = 2$: Solve $L D X = B$ .
$iselct = 3$: Solve $D L^{T} X = B$ .
$iselct = 4$: Solve $L L^{T} X = B$ .
$iselct = 5$: Solve $L X = B$ .
$iselct = 6$: Solve $L^{T} X = B$ .

Constraint:

iselct = 1

2

3

4

5

6

10: $x (ldx, ir)$ – Real (Kind=nag_wp) array Output

On exit: the

n \times r

solution matrix

X

. See also Section 9.

11: $ldx$ – Integer Input

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

Constraint:

ldx \geq n

12: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

1

to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of

0

causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of

−1

means that an error message is printed while a value of

1

means that it is not.

If halting is not appropriate, the value

−1

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, $I = ⟨ value ⟩$ and $nrow (I) = ⟨ value ⟩$ .
Constraint: $nrow (I) \geq 1$ and $nrow (I) \leq I$ .

On entry, $lal = ⟨ value ⟩$ and $nrow (1) + \dots + nrow (n) = ⟨ value ⟩$ .
Constraint: $lal \geq nrow (1) + \dots + nrow (n)$ .

On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 1$ .

$ifail = 2$: On entry, $ir = ⟨ value ⟩$ .
Constraint: $ir \geq 1$ .

On entry, $ldb = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $ldb \geq n$ .

On entry, $ldx = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $ldx \geq n$ .

$ifail = 3$: On entry, $iselct = ⟨ value ⟩$ .
Constraint: $iselct \geq 1$ and $iselct \leq 6$ .

$ifail = 4$: On entry, $I = ⟨ value ⟩$ .
Constraint: $d (I) \neq 0.0$ .

$ifail = 5$: At least one diagonal entry of al is not unit.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The usual backward error analysis of the solution of triangular system applies: each computed solution vector is exact for slightly perturbed matrices

L

and

D

, as appropriate (see pages 25–27 and 54–55 of Wilkinson and Reinsch (1971)).

8 Parallelism and Performance

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

f04mcf is not threaded in any implementation.

9 Further Comments

The time taken by f04mcf is approximately proportional to

p r

, where

p = nrow (1) + nrow (2) + \dots + nrow (n)

Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same actual array supplied for the arguments b and x, in which case the solution matrix will overwrite the right-hand side matrix. However this is not standard Fortran and may not work in all implementations.

10 Example

This example solves the system of equations

A X = B

, where

A = (\begin{array}{r} 1 & 2 & 0 & 0 & 5 & 0 \\ 2 & 5 & 3 & 0 & 14 & 0 \\ 0 & 3 & 13 & 0 & 18 & 0 \\ 0 & 0 & 0 & 16 & 8 & 24 \\ 5 & 14 & 18 & 8 & 55 & 17 \\ 0 & 0 & 0 & 24 & 17 & 77 \end{array}) and B = (\begin{array}{r} 6 & −10 \\ 15 & −21 \\ 11 & −3 \\ 0 & 24 \\ 51 & −39 \\ 46 & 67 \end{array})

Here

A

is symmetric and positive definite and must first be factorized by f01mcf.

f04mc: FL CL CPP AD PY MB

NAG FL Interfacef04mcf (real_​posdef_​vband_​solve)

▸▿ 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
f04mcf (real_posdef_vband_solve)