NAG Library Function Document

nag_superlu_solve_lu (f11mfc)

void	nag_superlu_solve_lu (Nag_OrderType order, Nag_TransType trans, Integer n, const Integer iprm[], const Integer il[], const double lval[], const Integer iu[], const double uval[], Integer nrhs, double b[], Integer pdb, NagError *fail)

3 Description

nag_superlu_solve_lu (f11mfc) solves a real system of linear equations with multiple right-hand sides

A X = B

A^{T} X = B

, according to the value of the argument trans, where the matrix factorization

P_{r} A P_{c} = L U

corresponds to an

L U

decomposition of a sparse matrix stored in compressed column (Harwell–Boeing) format, as computed by nag_superlu_lu_factorize (f11mec).

In the above decomposition

L

is a lower triangular sparse matrix with unit diagonal elements and

U

is an upper triangular sparse matrix;

P_{r}

and

P_{c}

are permutation matrices.

4 References

None.

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 whether

A X = B

A^{T} X = B

is solved.

$trans = Nag_NoTrans$: $A X = B$ is solved.
$trans = Nag_Trans$: $A^{T} X = B$ is solved.

Constraint:

trans = Nag_NoTrans

Nag_Trans

3: n – IntegerInput

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 0

4: iprm[ $7 \times n$ ] – const IntegerInput

On entry: the column permutation which defines

P_{c}

, the row permutation which defines

P_{r}

, plus associated data structures as computed by nag_superlu_lu_factorize (f11mec).

5: il[ $\dim$ ] – const IntegerInput

Note: the dimension, dim, of the array il must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records the sparsity pattern of matrix

L

as computed by nag_superlu_lu_factorize (f11mec).

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

Note: the dimension, dim, of the array lval must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records the nonzero values of matrix

L

and some nonzero values of matrix

U

as computed by nag_superlu_lu_factorize (f11mec).

7: iu[ $\dim$ ] – const IntegerInput

Note: the dimension, dim, of the array iu must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records the sparsity pattern of matrix

U

as computed by nag_superlu_lu_factorize (f11mec).

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

Note: the dimension, dim, of the array uval must be at least as large as the dimension of the array of the same name in nag_superlu_lu_factorize (f11mec).

On entry: records some nonzero values of matrix

U

as computed by nag_superlu_lu_factorize (f11mec).

9: nrhs – IntegerInput

On entry:

nrhs

, the number of right-hand sides in

B

Constraint:

nrhs \geq 0

10: b[ $\dim$ ] – doubleInput/Output

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

nrhs

right-hand side matrix

B

On exit: the

n

nrhs

solution matrix

X

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

12: 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 number $〈value〉$ had an illegal value.; 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$ .
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)$ .
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_INVALID_PERM_COL: Incorrect Column Permutations in array iprm.
NE_INVALID_PERM_ROW: Incorrect Row Permutations in array iprm.

7 Accuracy

For each right-hand side vector

b

, the computed solution

x

is the exact solution of a perturbed system of equations

(A + E) x = b

, where

|E| \leq c (n) ε |L| |U|,

c (n)

is a modest linear function of

n

, and

ε

is the machine precision, when partial pivoting is used.

\hat{x}

is the true solution, then the computed solution

x

satisfies a forward error bound of the form

\frac{{‖x - \hat{x}‖}_{\infty}}{{‖x‖}_{\infty}} \leq c (n) cond (A, x) ε

where

cond (A, x) = {‖|A^{- 1}| |A| |x|‖}_{\infty} / {‖x‖}_{\infty} \leq cond (A) = {‖|A^{- 1}| |A|‖}_{\infty} \leq κ_{\infty} (A)

. Note that

cond (A, x)

can be much smaller than

cond (A)

, and

cond (A^{T})

can be much larger (or smaller) than

cond (A)

Forward and backward error bounds can be computed by calling nag_superlu_refine_lu (f11mhc), and an estimate for

κ_{\infty} (A)

can be obtained by calling nag_superlu_condition_number_lu (f11mgc).

8 Further Comments

nag_superlu_solve_lu (f11mfc) may be followed by a call to nag_superlu_refine_lu (f11mhc) to refine the solution and return an error estimate.

9 Example

This example solves the system of equations

A X = B

, where

A = (\begin{matrix} 2.00 & 1.00 & 0 & 0 & 0 \\ 0 & 0 & 1.00 & - 1.00 & 0 \\ 4.00 & 0 & 1.00 & 0 & 1.00 \\ 0 & 0 & 0 & 1.00 & 2.00 \\ 0 & - 2.00 & 0 & 0 & 3.00 \end{matrix}) and B = (\begin{matrix} 1.56 & 3.12 \\ - 0.25 & - 0.50 \\ 3.60 & 7.20 \\ 1.33 & 2.66 \\ 0.52 & 1.04 \end{matrix}) .

Here

A

is nonsymmetric and must first be factorized by nag_superlu_lu_factorize (f11mec).

NAG Library Function Documentnag_superlu_solve_lu (f11mfc)

+− 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_superlu_solve_lu (f11mfc)