1CSYSVX(1) LAPACK driver routine (version 3.2) CSYSVX(1)
2
6 CSYSVX - uses the diagonal pivoting factorization to compute the solu‐
7 tion to a complex system of linear equations A * X = B,
8
10 SUBROUTINE CSYSVX( FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, IPIV, B, LDB,
11 X, LDX, RCOND, FERR, BERR, WORK, LWORK, RWORK, INFO
12 )
13 CHARACTER FACT, UPLO
15 INTEGER INFO, LDA, LDAF, LDB, LDX, LWORK, N, NRHS
17 REAL RCOND
19 INTEGER IPIV( * )
21 REAL BERR( * ), FERR( * ), RWORK( * )
23 COMPLEX A( LDA, * ), AF( LDAF, * ), B( LDB, * ), WORK( * ),
25 X( LDX, * )
26
28 CSYSVX uses the diagonal pivoting factorization to compute the solution
29 to a complex system of linear equations A * X = B, where A is an N-by-N
30 symmetric matrix and X and B are N-by-NRHS matrices.
31 Error bounds on the solution and a condition estimate are also pro‐
32 vided.
33
35 The following steps are performed:
36 1. If FACT = 'N', the diagonal pivoting method is used to factor A.
37 The form of the factorization is
38 A = U * D * U**T, if UPLO = 'U', or
39 A = L * D * L**T, if UPLO = 'L',
40 where U (or L) is a product of permutation and unit upper (lower)
41 triangular matrices, and D is symmetric and block diagonal with
42 1-by-1 and 2-by-2 diagonal blocks.
43 2. If some D(i,i)=0, so that D is exactly singular, then the routine
44 returns with INFO = i. Otherwise, the factored form of A is used
45 to estimate the condition number of the matrix A. If the
46 reciprocal of the condition number is less than machine precision,
47 INFO = N+1 is returned as a warning, but the routine still goes on
48 to solve for X and compute error bounds as described below. 3. The
49 system of equations is solved for X using the factored form
50 of A.
51 4. Iterative refinement is applied to improve the computed solution
52 matrix and calculate error bounds and backward error estimates
53 for it.
54
56 FACT (input) CHARACTER*1
57 Specifies whether or not the factored form of A has been sup‐
58 plied on entry. = 'F': On entry, AF and IPIV contain the fac‐
59 tored form of A. A, AF and IPIV will not be modified. = 'N':
60 The matrix A will be copied to AF and factored.
61 UPLO (input) CHARACTER*1
63 = 'U': Upper triangle of A is stored;
64 = 'L': Lower triangle of A is stored.
65 N (input) INTEGER
67 The number of linear equations, i.e., the order of the matrix
68 A. N >= 0.
69 NRHS (input) INTEGER
71 The number of right hand sides, i.e., the number of columns of
72 the matrices B and X. NRHS >= 0.
73 A (input) COMPLEX array, dimension (LDA,N)
75 The symmetric matrix A. If UPLO = 'U', the leading N-by-N
76 upper triangular part of A contains the upper triangular part
77 of the matrix A, and the strictly lower triangular part of A is
78 not referenced. If UPLO = 'L', the leading N-by-N lower trian‐
79 gular part of A contains the lower triangular part of the
80 matrix A, and the strictly upper triangular part of A is not
81 referenced.
82 LDA (input) INTEGER
84 The leading dimension of the array A. LDA >= max(1,N).
85 AF (input or output) COMPLEX array, dimension (LDAF,N)
87 If FACT = 'F', then AF is an input argument and on entry con‐
88 tains the block diagonal matrix D and the multipliers used to
89 obtain the factor U or L from the factorization A = U*D*U**T or
90 A = L*D*L**T as computed by CSYTRF. If FACT = 'N', then AF is
91 an output argument and on exit returns the block diagonal
92 matrix D and the multipliers used to obtain the factor U or L
93 from the factorization A = U*D*U**T or A = L*D*L**T.
94 LDAF (input) INTEGER
96 The leading dimension of the array AF. LDAF >= max(1,N).
97 IPIV (input or output) INTEGER array, dimension (N)
99 If FACT = 'F', then IPIV is an input argument and on entry con‐
100 tains details of the interchanges and the block structure of D,
101 as determined by CSYTRF. If IPIV(k) > 0, then rows and columns
102 k and IPIV(k) were interchanged and D(k,k) is a 1-by-1 diagonal
103 block. If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then rows
104 and columns k-1 and -IPIV(k) were interchanged and
105 D(k-1:k,k-1:k) is a 2-by-2 diagonal block. If UPLO = 'L' and
106 IPIV(k) = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k)
107 were interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal
108 block. If FACT = 'N', then IPIV is an output argument and on
109 exit contains details of the interchanges and the block struc‐
110 ture of D, as determined by CSYTRF.
111 B (input) COMPLEX array, dimension (LDB,NRHS)
113 The N-by-NRHS right hand side matrix B.
114 LDB (input) INTEGER
116 The leading dimension of the array B. LDB >= max(1,N).
117 X (output) COMPLEX array, dimension (LDX,NRHS)
119 If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X.
120 LDX (input) INTEGER
122 The leading dimension of the array X. LDX >= max(1,N).
123 RCOND (output) REAL
125 The estimate of the reciprocal condition number of the matrix
126 A. If RCOND is less than the machine precision (in particular,
127 if RCOND = 0), the matrix is singular to working precision.
128 This condition is indicated by a return code of INFO > 0.
129 FERR (output) REAL array, dimension (NRHS)
131 The estimated forward error bound for each solution vector X(j)
132 (the j-th column of the solution matrix X). If XTRUE is the
133 true solution corresponding to X(j), FERR(j) is an estimated
134 upper bound for the magnitude of the largest element in (X(j) -
135 XTRUE) divided by the magnitude of the largest element in X(j).
136 The estimate is as reliable as the estimate for RCOND, and is
137 almost always a slight overestimate of the true error.
138 BERR (output) REAL array, dimension (NRHS)
140 The componentwise relative backward error of each solution vec‐
141 tor X(j) (i.e., the smallest relative change in any element of
142 A or B that makes X(j) an exact solution).
143 WORK (workspace/output) COMPLEX array, dimension (MAX(1,LWORK))
145 On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
146 LWORK (input) INTEGER
148 The length of WORK. LWORK >= max(1,2*N), and for best perfor‐
149 mance, when FACT = 'N', LWORK >= max(1,2*N,N*NB), where NB is
150 the optimal blocksize for CSYTRF. If LWORK = -1, then a
151 workspace query is assumed; the routine only calculates the
152 optimal size of the WORK array, returns this value as the first
153 entry of the WORK array, and no error message related to LWORK
154 is issued by XERBLA.
155 RWORK (workspace) REAL array, dimension (N)
157 INFO (output) INTEGER
159 = 0: successful exit
160 < 0: if INFO = -i, the i-th argument had an illegal value
161 > 0: if INFO = i, and i is
162 <= N: D(i,i) is exactly zero. The factorization has been com‐
163 pleted but the factor D is exactly singular, so the solution
164 and error bounds could not be computed. RCOND = 0 is returned.
165 = N+1: D is nonsingular, but RCOND is less than machine preci‐
166 sion, meaning that the matrix is singular to working precision.
167 Nevertheless, the solution and error bounds are computed
168 because there are a number of situations where the computed
169 solution can be more accurate than the value of RCOND would
170 suggest.
171 LAPACK driver routine (version 3.N2o)vember 2008 CSYSVX(1)