NAG Library Function Document

nag_dgtrfs (f07chc)

factorization returned by nag_dgttrf (f07cdc) and an initial solution returned by nag_dgttrs (f07cec). Iterative refinement is used to reduce the backward error as much as possible.

2 Specification

#include <nag.h>

#include <nagf07.h>

void

nag_dgtrfs (Nag_OrderType order, Nag_TransType trans, Integer n, Integer nrhs, const double dl[], const double d[], const double du[], const double dlf[], const double df[], const double duf[], const double du2[], const Integer ipiv[], const double b[], Integer pdb, double x[], Integer pdx, double ferr[], double berr[], NagError *fail)

3 Description

nag_dgtrfs (f07chc) should normally be preceded by calls to nag_dgttrf (f07cdc) and nag_dgttrs (f07cec). nag_dgttrf (f07cdc) uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix

A

A = P L U,

where

P

is a permutation matrix,

L

is unit lower triangular with at most one nonzero subdiagonal element in each column, and

U

is an upper triangular band matrix, with two superdiagonals. nag_dgttrs (f07cec) then utilizes the factorization to compute a solution,

\hat{X}

, to the required equations. Letting

\hat{x}

denote a column of

\hat{X}

, nag_dgtrfs (f07chc) computes a component-wise backward error,

β

, the smallest relative perturbation in each element of

A

and

b

such that

\hat{x}

is the exact solution of a perturbed system

(A + E) \hat{x} = b + f, with |e_{i j}| \leq β |a_{i j}|, and |f_{j}| \leq β |b_{j}| .

The function also estimates a bound for the component-wise forward error in the computed solution defined by

\max |x_{i} - \hat{x_{i}}| / \max |\hat{x_{i}}|

, where

x

is the corresponding column of the exact solution,

X

4 References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug

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

or Nag_ColMajor.

2: trans – Nag_TransTypeInput

On entry: specifies the equations to be solved as follows:

$trans = Nag_NoTrans$: Solve $A X = B$ for $X$ .
$trans = Nag_Trans$ or $Nag_ConjTrans$: Solve $A^{T} X = B$ for $X$ .

Constraint:

trans = Nag_NoTrans

Nag_Trans

Nag_ConjTrans

3: n – IntegerInput

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 0

4: nrhs – IntegerInput

On entry:

r

, the number of right-hand sides, i.e., the number of columns of the matrix

B

Constraint:

nrhs \geq 0

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

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

\max (1, n - 1)

On entry: must contain the

(n - 1)

subdiagonal elements of the matrix

A

6: d[ $\dim$ ] – const doubleInput

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

\max (1, n)

On entry: must contain the

n

diagonal elements of the matrix

A

7: du[ $\dim$ ] – const doubleInput

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

\max (1, n - 1)

On entry: must contain the

(n - 1)

superdiagonal elements of the matrix

A

8: dlf[ $\dim$ ] – const doubleInput

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

\max (1, n - 1)

On entry: must contain the

(n - 1)

multipliers that define the matrix

L

of the

L U

factorization of

A

9: df[ $\dim$ ] – const doubleInput

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

\max (1, n)

On entry: must contain the

n

diagonal elements of the upper triangular matrix

U

from the

L U

factorization of

A

10: duf[ $\dim$ ] – const doubleInput

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

\max (1, n - 1)

On entry: must contain the

(n - 1)

elements of the first superdiagonal of

U

11: du2[ $\dim$ ] – const doubleInput

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

\max (1, n - 2)

On entry: must contain the

(n - 2)

elements of the second superdiagonal of

U

12: ipiv[ $\dim$ ] – const IntegerInput

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

\max (1, n)

On entry: must contain the

n

pivot indices that define the permutation matrix

P

. At the

i

th step, row

i

of the matrix was interchanged with row

ipiv [i - 1]

, and

ipiv [i - 1]

must always be either

i

(i + 1)

ipiv [i - 1] = i

indicating that a row interchange was not performed.

13: b[ $\dim$ ] – const doubleInput

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

$\max (1, pdb \times nrhs)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdb)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

B

is stored in

$b [(j - 1) \times pdb + i - 1]$ when $order = Nag_ColMajor$ ;
$b [(i - 1) \times pdb + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

n

r

matrix of right-hand sides

B

14: pdb – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array b.

Constraints:

if $order = Nag_ColMajor$ , $pdb \geq \max (1, n)$ ;
if $order = Nag_RowMajor$ , $pdb \geq \max (1, nrhs)$ .

15: x[ $\dim$ ] – doubleInput/Output

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

$\max (1, pdx \times nrhs)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdx)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

X

is stored in

$x [(j - 1) \times pdx + i - 1]$ when $order = Nag_ColMajor$ ;
$x [(i - 1) \times pdx + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

n

r

initial solution matrix

X

On exit: the

n

r

refined solution matrix

X

16: pdx – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array x.

Constraints:

if $order = Nag_ColMajor$ , $pdx \geq \max (1, n)$ ;
if $order = Nag_RowMajor$ , $pdx \geq \max (1, nrhs)$ .

17: ferr[nrhs] – doubleOutput

On exit: estimate of the forward error bound for each computed solution vector, such that

{‖{\hat{x}}_{j} - x_{j}‖}_{\infty} / {‖{\hat{x}}_{j}‖}_{\infty} \leq ferr [j - 1]

, where

{\hat{x}}_{j}

is the

j

th column of the computed solution returned in the array x and

x_{j}

is the corresponding column of the exact solution

X

. The estimate is almost always a slight overestimate of the true error.

18: berr[nrhs] – doubleOutput

On exit: estimate of the component-wise relative backward error of each computed solution vector

{\hat{x}}_{j}

(i.e., the smallest relative change in any element of

A

B

that makes

{\hat{x}}_{j}

an exact solution).

19: fail – NagError *Input/Output

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

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $nrhs = 〈value〉$ .
Constraint: $nrhs \geq 0$ .; On entry, $pdb = 〈value〉$ .
Constraint: $pdb > 0$ .; On entry, $pdx = 〈value〉$ .
Constraint: $pdx > 0$ .
NE_INT_2: On entry, $pdb = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdb \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $nrhs = 〈value〉$ .
Constraint: $pdb \geq \max (1, nrhs)$ .; On entry, $pdx = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdx \geq \max (1, n)$ .; On entry, $pdx = 〈value〉$ and $nrhs = 〈value〉$ .
Constraint: $pdx \geq \max (1, nrhs)$ .
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.

7 Accuracy

The computed solution for a single right-hand side,

\hat{x}

, satisfies an equation of the form

(A + E) \hat{x} = b,

where

{‖E‖}_{\infty} = O (ε) {‖A‖}_{\infty}

and

ε

is the machine precision. An approximate error bound for the computed solution is given by

\frac{{‖\hat{x} - x‖}_{\infty}}{{‖x‖}_{\infty}} \leq κ (A) \frac{{‖E‖}_{\infty}}{{‖A‖}_{\infty}},

where

κ (A) = {‖A^{- 1}‖}_{\infty} {‖A‖}_{\infty}

, the condition number of

A

with respect to the solution of the linear equations. See Section 4.4 of Anderson et al. (1999) for further details.

Function nag_dgtcon (f07cgc) can be used to estimate the condition number of

A

8 Further Comments

The total number of floating point operations required to solve the equations

A X = B

A^{T} X = B

is proportional to

n r

. At most five steps of iterative refinement are performed, but usually only one or two steps are required.

The complex analogue of this function is nag_zgtrfs (f07cvc).

9 Example

This example solves the equations

A X = B,

where

A

is the tridiagonal matrix

A = (\begin{array}{r} 3.0 & 2.1 & 0 & 0 & 0 \\ 3.4 & 2.3 & - 1.0 & 0 & 0 \\ 0 & 3.6 & - 5.0 & 1.9 & 0 \\ 0 & 0 & 7.0 & - 0.9 & 8.0 \\ 0 & 0 & 0 & - 6.0 & 7.1 \end{array}) and B = (\begin{matrix} 2.7 & 6.6 \\ - 0.5 & 10.8 \\ 2.6 & - 3.2 \\ 0.6 & - 11.2 \\ 2.7 & 19.1 \end{matrix}) .

Estimates for the backward errors and forward errors are also output.

NAG Library Function Documentnag_dgtrfs (f07chc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_dgtrfs (f07chc)