1CGTSVX(1) LAPACK routine (version 3.1) CGTSVX(1)
2
6 CGTSVX - the LU factorization to compute the solution to a complex sys‐
7 tem of linear equations A * X = B, A**T * X = B, or A**H * X = B,
8
10 SUBROUTINE CGTSVX( FACT, TRANS, N, NRHS, DL, D, DU, DLF, DF, DUF, DU2,
11 IPIV, B, LDB, X, LDX, RCOND, FERR, BERR, WORK,
12 RWORK, INFO )
13 CHARACTER FACT, TRANS
15 INTEGER INFO, LDB, LDX, N, NRHS
17 REAL RCOND
19 INTEGER IPIV( * )
21 REAL BERR( * ), FERR( * ), RWORK( * )
23 COMPLEX B( LDB, * ), D( * ), DF( * ), DL( * ), DLF( * ), DU(
25 * ), DU2( * ), DUF( * ), WORK( * ), X( LDX, * )
26
28 CGTSVX uses the LU factorization to compute the solution to a complex
29 system of linear equations A * X = B, A**T * X = B, or A**H * X = B,
30 where A is a tridiagonal matrix of order N and X and B are N-by-NRHS
31 matrices.
32 Error bounds on the solution and a condition estimate are also pro‐
34 vided.
35
38 The following steps are performed:
39 1. If FACT = 'N', the LU decomposition is used to factor the matrix A
41 as A = L * U, where L is a product of permutation and unit lower
42 bidiagonal matrices and U is upper triangular with nonzeros in
43 only the main diagonal and first two superdiagonals.
44 2. If some U(i,i)=0, so that U is exactly singular, then the routine
46 returns with INFO = i. Otherwise, the factored form of A is used
47 to estimate the condition number of the matrix A. If the
48 reciprocal of the condition number is less than machine precision,
49 INFO = N+1 is returned as a warning, but the routine still goes on
50 to solve for X and compute error bounds as described below.
51 3. The system of equations is solved for X using the factored form
53 of A.
54 4. Iterative refinement is applied to improve the computed solution
56 matrix and calculate error bounds and backward error estimates
57 for it.
58
61 FACT (input) CHARACTER*1
62 Specifies whether or not the factored form of A has been sup‐
63 plied on entry. = 'F': DLF, DF, DUF, DU2, and IPIV contain
64 the factored form of A; DL, D, DU, DLF, DF, DUF, DU2 and IPIV
65 will not be modified. = 'N': The matrix will be copied to
66 DLF, DF, and DUF and factored.
67 TRANS (input) CHARACTER*1
69 Specifies the form of the system of equations:
70 = 'N': A * X = B (No transpose)
71 = 'T': A**T * X = B (Transpose)
72 = 'C': A**H * X = B (Conjugate transpose)
73 N (input) INTEGER
75 The order of the matrix A. N >= 0.
76 NRHS (input) INTEGER
78 The number of right hand sides, i.e., the number of columns of
79 the matrix B. NRHS >= 0.
80 DL (input) COMPLEX array, dimension (N-1)
82 The (n-1) subdiagonal elements of A.
83 D (input) COMPLEX array, dimension (N)
85 The n diagonal elements of A.
86 DU (input) COMPLEX array, dimension (N-1)
88 The (n-1) superdiagonal elements of A.
89 DLF (input or output) COMPLEX array, dimension (N-1)
91 If FACT = 'F', then DLF is an input argument and on entry con‐
92 tains the (n-1) multipliers that define the matrix L from the
93 LU factorization of A as computed by CGTTRF.
94 If FACT = 'N', then DLF is an output argument and on exit con‐
96 tains the (n-1) multipliers that define the matrix L from the
97 LU factorization of A.
98 DF (input or output) COMPLEX array, dimension (N)
100 If FACT = 'F', then DF is an input argument and on entry con‐
101 tains the n diagonal elements of the upper triangular matrix U
102 from the LU factorization of A.
103 If FACT = 'N', then DF is an output argument and on exit con‐
105 tains the n diagonal elements of the upper triangular matrix U
106 from the LU factorization of A.
107 DUF (input or output) COMPLEX array, dimension (N-1)
109 If FACT = 'F', then DUF is an input argument and on entry con‐
110 tains the (n-1) elements of the first superdiagonal of U.
111 If FACT = 'N', then DUF is an output argument and on exit con‐
113 tains the (n-1) elements of the first superdiagonal of U.
114 DU2 (input or output) COMPLEX array, dimension (N-2)
116 If FACT = 'F', then DU2 is an input argument and on entry con‐
117 tains the (n-2) elements of the second superdiagonal of U.
118 If FACT = 'N', then DU2 is an output argument and on exit con‐
120 tains the (n-2) elements of the second superdiagonal of U.
121 IPIV (input or output) INTEGER array, dimension (N)
123 If FACT = 'F', then IPIV is an input argument and on entry con‐
124 tains the pivot indices from the LU factorization of A as com‐
125 puted by CGTTRF.
126 If FACT = 'N', then IPIV is an output argument and on exit con‐
128 tains the pivot indices from the LU factorization of A; row i
129 of the matrix was interchanged with row IPIV(i). IPIV(i) will
130 always be either i or i+1; IPIV(i) = i indicates a row inter‐
131 change was not required.
132 B (input) COMPLEX array, dimension (LDB,NRHS)
134 The N-by-NRHS right hand side matrix B.
135 LDB (input) INTEGER
137 The leading dimension of the array B. LDB >= max(1,N).
138 X (output) COMPLEX array, dimension (LDX,NRHS)
140 If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X.
141 LDX (input) INTEGER
143 The leading dimension of the array X. LDX >= max(1,N).
144 RCOND (output) REAL
146 The estimate of the reciprocal condition number of the matrix
147 A. If RCOND is less than the machine precision (in particular,
148 if RCOND = 0), the matrix is singular to working precision.
149 This condition is indicated by a return code of INFO > 0.
150 FERR (output) REAL array, dimension (NRHS)
152 The estimated forward error bound for each solution vector X(j)
153 (the j-th column of the solution matrix X). If XTRUE is the
154 true solution corresponding to X(j), FERR(j) is an estimated
155 upper bound for the magnitude of the largest element in (X(j) -
156 XTRUE) divided by the magnitude of the largest element in X(j).
157 The estimate is as reliable as the estimate for RCOND, and is
158 almost always a slight overestimate of the true error.
159 BERR (output) REAL array, dimension (NRHS)
161 The componentwise relative backward error of each solution vec‐
162 tor X(j) (i.e., the smallest relative change in any element of
163 A or B that makes X(j) an exact solution).
164 WORK (workspace) COMPLEX array, dimension (2*N)
166 RWORK (workspace) REAL array, dimension (N)
168 INFO (output) INTEGER
170 = 0: successful exit
171 < 0: if INFO = -i, the i-th argument had an illegal value
172 > 0: if INFO = i, and i is
173 <= N: U(i,i) is exactly zero. The factorization has not been
174 completed unless i = N, but the factor U is exactly singular,
175 so the solution and error bounds could not be computed. RCOND
176 = 0 is returned. = N+1: U is nonsingular, but RCOND is less
177 than machine precision, meaning that the matrix is singular to
178 working precision. Nevertheless, the solution and error bounds
179 are computed because there are a number of situations where the
180 computed solution can be more accurate than the value of RCOND
181 would suggest.
182 LAPACK routine (version 3.1) November 2006 CGTSVX(1)