NAG Library Routine Document
F01LEF
1 Purpose
F01LEF computes an LU factorization of a real tridiagonal matrix, using Gaussian elimination with partial pivoting.
2 Specification
| SUBROUTINE F01LEF ( | N, A, LAMBDA, B, C, TOL, D, IPIV, IFAIL) |
| INTEGER | N, IPIV(N), IFAIL |
| double precision | A(N), LAMBDA, B(N), C(N), TOL, D(N) |
3 Description
The matrix
T-λI, where
T is a real
n by
n tridiagonal matrix, is factorized as
where
P is a permutation matrix,
L is a unit lower triangular matrix with at most one nonzero subdiagonal element per column, and
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 is nearly singular is returned in the
nth element of the array
IPIV. If it is important that
T-λI is nonsingular, as is usually the case when solving a system of tridiagonal equations, then it is strongly recommended that
IPIVn is inspected on return from F01LEF. (See the parameter
IPIV and
Section 8 for further details.)
The parameter
λ is included in the routine so that F01LEF may be used, in conjunction with
F04LEF, to obtain eigenvectors of
T by inverse iteration.
4 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
5 Parameters
- 1: N – INTEGERInput
On entry:
n, n, the order of the matrix T.
Constraint:
N≥1.
- 2: A(N) – double precision arrayInput/Output
On entry: the diagonal elements of T.
On exit: the diagonal elements of the upper triangular matrix U.
- 3: LAMBDA – double precisionInput
On entry: the scalar λ. F01LEF factorizes T-λI.
- 4: B(N) – double precision arrayInput/Output
On entry: the superdiagonal elements of T, stored in B2 to Bn; B1 is not used.
On exit: the elements of the first superdiagonal of U, stored in B2 to Bn.
- 5: C(N) – double precision arrayInput/Output
On entry: the subdiagonal elements of T, stored in C2 to Cn; C1 is not used.
On exit: the subdiagonal elements of L, stored in C2 to Cn.
- 6: TOL – double precisionInput
On entry: a relative tolerance used to indicate whether or not the matrix (
T-λI) is nearly singular.
TOL should normally be chosen as approximately the largest relative error in the elements of
T. For example, if the elements of
T are correct to about
4 significant figures, then
TOL should be set to about
5×10-4. See
Section 8 for further details on how
TOL is used. If
TOL is supplied as less than
ε, where
ε is the
machine precision, then the value
ε is used in place of
TOL.
- 7: D(N) – double precision arrayOutput
On exit: the elements of the second superdiagonal of U, stored in D3 to Dn; D1 and D2 are not used.
- 8: IPIV(N) – INTEGER arrayOutput
On exit: details of the permutation matrix
P. If an interchange occurred at the
kth step of the elimination, then
IPIVk=1, otherwise
IPIVk=0. If a diagonal element of
U is small, indicating that
T-λI is nearly singular, then the element
IPIVn is returned as positive. Otherwise
IPIVn is returned as
0. See
Section 8 for further details. If the application is such that it is important that
T-λI is not nearly singular, then it is strongly recommended that
IPIVn is inspected on return.
- 9: IFAIL – INTEGERInput/Output
-
On entry:
IFAIL must be set to
0,
-1 or 1. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
On exit:
IFAIL=0 unless the routine detects an error (see
Section 6).
For environments where it might be inappropriate to halt program execution when an error is detected, the value
-1 or 1 is recommended. If the output of error messages is undesirable, then the value
1 is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is
0.
When the value -1 or 1 is used it is essential to test the value of IFAIL on exit.
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
-
7 Accuracy
The computed factorization will satisfy the equation
where
where
ε is the
machine precision.
8 Further Comments
The time taken by F01LEF is approximately proportional to n.
The factorization of a tridiagonal matrix proceeds in n-1 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, rows k and (k+1) will, if necessary, be interchanged at the kth step prior to the elimination.
The element
IPIVn returns the smallest integer,
j, for which
where
T-λIj1 denotes the sum of the absolute values of the
jth row of the matrix (
T-λI). If no such
j exists, then
IPIVn is returned as zero. If such a
j exists, then
ujj is small and hence (
T-λI) is singular or nearly singular.
This routine may be followed by
F04LEF to solve systems of tridiagonal equations. If you wish to solve single systems of tridiagonal equations you should be aware of
F07CAF (DGTSV), which solves tridiagonal systems with a single call.
F07CAF (DGTSV) requires less storage and will generally be faster than the combination of F01LEF and
F04LEF, but no test for near singularity is included in
F07CAF (DGTSV) and so it should only be used when the equations are known to be nonsingular.
9 Example
This example factorizes the tridiagonal matrix
T where
and then to solve the equations
Tx=y, where
by a call to
F04LEF. The example program sets
TOL=5×10-5 and, of course, sets
LAMBDA=0.
9.1 Program Text
Program Text (f01lefe.f)
9.2 Program Data
Program Data (f01lefe.d)
9.3 Program Results
Program Results (f01lefe.r)