NAG FL Interface
f04mcf (real_​posdef_​vband_​solve)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

f04mcf computes the approximate solution of a system of real linear equations with multiple right-hand sides, AX=B, where A is a symmetric positive definite variable-bandwidth matrix, which has previously been factorized by f01mcf. Related systems may also be solved.

2 Specification

Fortran Interface
Subroutine f04mcf ( n, al, lal, d, nrow, ir, b, ldb, iselct, x, ldx, ifail)
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 AX=B, following a call of f01mcf to determine the Cholesky factorization A=LDLT 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. 1.LDLTX=B (usual system),
  2. 2.LDX=B (lower triangular system),
  3. 3.DLTX=B (upper triangular system),
  4. 4.LLTX=B
  5. 5.LX=B (unit lower triangular system),
  6. 6.LTX=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 ith 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: n1.
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: lalnrow(1)+nrow(2)++nrow(n).
4: d(*) Real (Kind=nag_wp) array Input
Note: the dimension of the array d must be at least 1 if iselct4, and at least n otherwise.
On entry: the diagonal elements of the diagonal matrix D. d is not referenced if iselct4.
5: nrow(n) Integer array Input
On entry: nrow(i) must contain the width of row i of L, i.e., the number of elements between the first (leftmost) nonzero element and the element on the diagonal, inclusive.
Constraint: 1nrow(i)i.
6: ir Integer Input
On entry: r, the number of right-hand sides.
Constraint: ir1.
7: b(ldb,ir) Real (Kind=nag_wp) array Input
On entry: the n×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: ldbn.
9: iselct Integer Input
On entry: must specify the type of system to be solved, as follows:
iselct=1
Solve LDLTX=B.
iselct=2
Solve LDX=B.
iselct=3
Solve DLTX=B.
iselct=4
Solve LLTX=B.
iselct=5
Solve LX=B.
iselct=6
Solve LTX=B.
Constraint: iselct=1, 2, 3, 4, 5 or 6.
10: x(ldx,ir) Real (Kind=nag_wp) array Output
On exit: the n×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: ldxn.
12: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 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 or 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 or −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)1 and nrow(I)I.
On entry, lal=value and nrow(1)++nrow(n)=value.
Constraint: lalnrow(1)++nrow(n).
On entry, n=value.
Constraint: n1.
ifail=2
On entry, ir=value.
Constraint: ir1.
On entry, ldb=value and n=value.
Constraint: ldbn.
On entry, ldx=value and n=value.
Constraint: ldxn.
ifail=3
On entry, iselct=value.
Constraint: iselct1 and iselct6.
ifail=4
On entry, I=value.
Constraint: d(I)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 pr, where p=nrow(1)+nrow(2)++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 AX=B, where
A=( 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 )   and  B=( 6 −10 15 −21 11 −3 0 24 51 −39 46 67 )  
Here A is symmetric and positive definite and must first be factorized by f01mcf.

10.1 Program Text

Program Text (f04mcfe.f90)

10.2 Program Data

Program Data (f04mcfe.d)

10.3 Program Results

Program Results (f04mcfe.r)