Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_matop_real_gen_tridiag_lu (f01le)

## Purpose

nag_matop_real_gen_tridiag_lu (f01le) computes an LU$LU$ factorization of a real tridiagonal matrix, using Gaussian elimination with partial pivoting.

## Syntax

[a, b, c, d, ipiv, ifail] = f01le(a, lambda, b, c, tol, 'n', n)
[a, b, c, d, ipiv, ifail] = nag_matop_real_gen_tridiag_lu(a, lambda, b, c, tol, 'n', n)

## Description

The matrix TλI$T-\lambda I$, where T$T$ is a real n$n$ by n$n$ tridiagonal matrix, is factorized as
 T − λI = PLU, $T-λI=PLU,$
where P$P$ is a permutation matrix, L$L$ is a unit lower triangular matrix with at most one nonzero subdiagonal element per column, and U$U$ is an upper triangular matrix with at most two nonzero superdiagonal elements per column.
The factorization is obtained by Gaussian elimination with partial pivoting and implicit row scaling.
An indication of whether or not the matrix TλI$T-\lambda I$ is nearly singular is returned in the n$n$th element of the array ipiv. If it is important that TλI$T-\lambda I$ is nonsingular, as is usually the case when solving a system of tridiagonal equations, then it is strongly recommended that ipiv(n)${\mathbf{ipiv}}\left(n\right)$ is inspected on return from nag_matop_real_gen_tridiag_lu (f01le). (See the parameter ipiv and Section [Further Comments] for further details.)
The parameter λ$\lambda$ is included in the function so that nag_matop_real_gen_tridiag_lu (f01le) may be used, in conjunction with nag_linsys_real_tridiag_fac_solve (f04le), to obtain eigenvectors of T$T$ by inverse iteration.

## References

Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford
Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra Springer–Verlag

## Parameters

### Compulsory Input Parameters

1:     a(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
The diagonal elements of T$T$.
2:     lambda – double scalar
The scalar λ$\lambda$. nag_matop_real_gen_tridiag_lu (f01le) factorizes TλI$T-\lambda I$.
3:     b(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
The superdiagonal elements of T$T$, stored in b(2)${\mathbf{b}}\left(2\right)$ to b(n)${\mathbf{b}}\left(n\right)$; b(1)${\mathbf{b}}\left(1\right)$ is not used.
4:     c(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
The subdiagonal elements of T$T$, stored in c(2)${\mathbf{c}}\left(2\right)$ to c(n)${\mathbf{c}}\left(n\right)$; c(1)${\mathbf{c}}\left(1\right)$ is not used.
5:     tol – double scalar
A relative tolerance used to indicate whether or not the matrix (TλI$T-\lambda I$) is nearly singular. tol should normally be chosen as approximately the largest relative error in the elements of T$T$. For example, if the elements of T$T$ are correct to about 4$4$ significant figures, then tol should be set to about 5 × 104$5×{10}^{-4}$. See Section [Further Comments] for further details on how tol is used. If tol is supplied as less than ε$\epsilon$, where ε$\epsilon$ is the machine precision, then the value ε$\epsilon$ is used in place of tol.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the arrays a, b, c. (An error is raised if these dimensions are not equal.)
n$n$, the order of the matrix T$T$.
Constraint: n1${\mathbf{n}}\ge 1$.

None.

### Output Parameters

1:     a(n) – double array
The diagonal elements of the upper triangular matrix U$U$.
2:     b(n) – double array
The elements of the first superdiagonal of U$U$, stored in b(2)${\mathbf{b}}\left(2\right)$ to b(n)${\mathbf{b}}\left(n\right)$.
3:     c(n) – double array
The subdiagonal elements of L$L$, stored in c(2)${\mathbf{c}}\left(2\right)$ to c(n)${\mathbf{c}}\left(n\right)$.
4:     d(n) – double array
The elements of the second superdiagonal of U$U$, stored in d(3)${\mathbf{d}}\left(3\right)$ to d(n)${\mathbf{d}}\left(n\right)$; d(1)${\mathbf{d}}\left(1\right)$ and d(2)${\mathbf{d}}\left(2\right)$ are not used.
5:     ipiv(n) – int64int32nag_int array
Details of the permutation matrix P$P$. If an interchange occurred at the k$k$th step of the elimination, then ipiv(k) = 1${\mathbf{ipiv}}\left(k\right)=1$, otherwise ipiv(k) = 0${\mathbf{ipiv}}\left(k\right)=0$. If a diagonal element of U$U$ is small, indicating that (TλI)$\left(T-\lambda I\right)$ is nearly singular, then the element ipiv(n)${\mathbf{ipiv}}\left(n\right)$ is returned as positive. Otherwise ipiv(n)${\mathbf{ipiv}}\left(n\right)$ is returned as 0$0$. See Section [Further Comments] for further details. If the application is such that it is important that (TλI)$\left(T-\lambda I\right)$ is not nearly singular, then it is strongly recommended that ipiv(n)${\mathbf{ipiv}}\left(n\right)$ is inspected on return.
6:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 1${\mathbf{n}}<1$.

## Accuracy

The computed factorization will satisfy the equation
 PLU = (T − λI) + E, $PLU=(T-λI)+E,$
where
 ‖E‖1 ≤ 9 × maxi ≥ j (|lij|,|lij|2) ε ‖T − λI‖1 $‖E‖1≤ 9×maxi≥j (|lij|,|lij|2) ε ‖T-λ I‖1$
where ε$\epsilon$ is the machine precision.

The time taken by nag_matop_real_gen_tridiag_lu (f01le) is approximately proportional to n$n$.
The factorization of a tridiagonal matrix proceeds in (n1)$\left(n-1\right)$ steps, each step eliminating one subdiagonal element of the tridiagonal matrix. In order to avoid small pivot elements and to prevent growth in the size of the elements of L$L$, rows k$k$ and (k + 1$k+1$) will, if necessary, be interchanged at the k$k$th step prior to the elimination.
The element ipiv(n)${\mathbf{ipiv}}\left(n\right)$ returns the smallest integer, j$j$, for which
 |ujj| ≤ ‖(T − λI)j‖1 × tol, $|ujj|≤‖(T-λI)j‖1×tol,$
where (TλI)j1${‖{\left(T-\lambda I\right)}_{j}‖}_{1}$ denotes the sum of the absolute values of the j$j$th row of the matrix (TλI$T-\lambda I$). If no such j$j$ exists, then ipiv(n)${\mathbf{ipiv}}\left(n\right)$ is returned as zero. If such a j$j$ exists, then |ujj|$|{u}_{jj}|$ is small and hence (TλI$T-\lambda I$) is singular or nearly singular.
This function may be followed by nag_linsys_real_tridiag_fac_solve (f04le) to solve systems of tridiagonal equations. If you wish to solve single systems of tridiagonal equations you should be aware of nag_lapack_dgtsv (f07ca), which solves tridiagonal systems with a single call. nag_lapack_dgtsv (f07ca) requires less storage and will generally be faster than the combination of nag_matop_real_gen_tridiag_lu (f01le) and nag_linsys_real_tridiag_fac_solve (f04le), but no test for near singularity is included in nag_lapack_dgtsv (f07ca) and so it should only be used when the equations are known to be nonsingular.

## Example

function nag_matop_real_gen_tridiag_lu_example
a = [3;
2.3;
-5;
-0.9;
7.1];
lambda = 0;
b = [0;
2.1;
-1;
1.9;
8];
c = [0;
3.4;
3.6;
7;
-6];
tol = 5e-05;
[aOut, bOut, cOut, d, ipiv, ifail] = nag_matop_real_gen_tridiag_lu(a, lambda, b, c, tol)

aOut =

3.0000
3.6000
7.0000
-6.0000
1.1508

bOut =

0
2.1000
-5.0000
-0.9000
7.1000

cOut =

0
1.1333
-0.0222
-0.1587
0.0168

d =

0
0
0
1.9000
8.0000

ipiv =

0
1
1
1
0

ifail =

0

function f01le_example
a = [3;
2.3;
-5;
-0.9;
7.1];
lambda = 0;
b = [0;
2.1;
-1;
1.9;
8];
c = [0;
3.4;
3.6;
7;
-6];
tol = 5e-05;
[aOut, bOut, cOut, d, ipiv, ifail] = f01le(a, lambda, b, c, tol)

aOut =

3.0000
3.6000
7.0000
-6.0000
1.1508

bOut =

0
2.1000
-5.0000
-0.9000
7.1000

cOut =

0
1.1333
-0.0222
-0.1587
0.0168

d =

0
0
0
1.9000
8.0000

ipiv =

0
1
1
1
0

ifail =

0