LAPACK  3.9.0 LAPACK: Linear Algebra PACKage
csysv_rk.f
Go to the documentation of this file.
1 *> \brief <b> CSYSV_RK computes the solution to system of linear equations A * X = B for SY matrices</b>
2 *
3 * =========== DOCUMENTATION ===========
4 *
5 * Online html documentation available at
6 * http://www.netlib.org/lapack/explore-html/
7 *
8 *> \htmlonly
10 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/csysv_rk.f">
11 *> [TGZ]</a>
12 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/csysv_rk.f">
13 *> [ZIP]</a>
14 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/csysv_rk.f">
15 *> [TXT]</a>
16 *> \endhtmlonly
17 *
18 * Definition:
19 * ===========
20 *
21 * SUBROUTINE CSYSV_RK( UPLO, N, NRHS, A, LDA, E, IPIV, B, LDB,
22 * WORK, LWORK, INFO )
23 *
24 * .. Scalar Arguments ..
25 * CHARACTER UPLO
26 * INTEGER INFO, LDA, LDB, LWORK, N, NRHS
27 * ..
28 * .. Array Arguments ..
29 * INTEGER IPIV( * )
30 * COMPLEX A( LDA, * ), B( LDB, * ), E( * ), WORK( * )
31 * ..
32 *
33 *
34 *> \par Purpose:
35 * =============
36 *>
37 *> \verbatim
38 *> CSYSV_RK computes the solution to a complex system of linear
39 *> equations A * X = B, where A is an N-by-N symmetric matrix
40 *> and X and B are N-by-NRHS matrices.
41 *>
42 *> The bounded Bunch-Kaufman (rook) diagonal pivoting method is used
43 *> to factor A as
44 *> A = P*U*D*(U**T)*(P**T), if UPLO = 'U', or
45 *> A = P*L*D*(L**T)*(P**T), if UPLO = 'L',
46 *> where U (or L) is unit upper (or lower) triangular matrix,
47 *> U**T (or L**T) is the transpose of U (or L), P is a permutation
48 *> matrix, P**T is the transpose of P, and D is symmetric and block
49 *> diagonal with 1-by-1 and 2-by-2 diagonal blocks.
50 *>
51 *> CSYTRF_RK is called to compute the factorization of a complex
52 *> symmetric matrix. The factored form of A is then used to solve
53 *> the system of equations A * X = B by calling BLAS3 routine CSYTRS_3.
54 *> \endverbatim
55 *
56 * Arguments:
57 * ==========
58 *
59 *> \param[in] UPLO
60 *> \verbatim
61 *> UPLO is CHARACTER*1
62 *> Specifies whether the upper or lower triangular part of the
63 *> symmetric matrix A is stored:
64 *> = 'U': Upper triangle of A is stored;
65 *> = 'L': Lower triangle of A is stored.
66 *> \endverbatim
67 *>
68 *> \param[in] N
69 *> \verbatim
70 *> N is INTEGER
71 *> The number of linear equations, i.e., the order of the
72 *> matrix A. N >= 0.
73 *> \endverbatim
74 *>
75 *> \param[in] NRHS
76 *> \verbatim
77 *> NRHS is INTEGER
78 *> The number of right hand sides, i.e., the number of columns
79 *> of the matrix B. NRHS >= 0.
80 *> \endverbatim
81 *>
82 *> \param[in,out] A
83 *> \verbatim
84 *> A is COMPLEX array, dimension (LDA,N)
85 *> On entry, the symmetric matrix A.
86 *> If UPLO = 'U': the leading N-by-N upper triangular part
87 *> of A contains the upper triangular part of the matrix A,
88 *> and the strictly lower triangular part of A is not
89 *> referenced.
90 *>
91 *> If UPLO = 'L': the leading N-by-N lower triangular part
92 *> of A contains the lower triangular part of the matrix A,
93 *> and the strictly upper triangular part of A is not
94 *> referenced.
95 *>
96 *> On exit, if INFO = 0, diagonal of the block diagonal
97 *> matrix D and factors U or L as computed by CSYTRF_RK:
98 *> a) ONLY diagonal elements of the symmetric block diagonal
99 *> matrix D on the diagonal of A, i.e. D(k,k) = A(k,k);
100 *> (superdiagonal (or subdiagonal) elements of D
101 *> are stored on exit in array E), and
102 *> b) If UPLO = 'U': factor U in the superdiagonal part of A.
103 *> If UPLO = 'L': factor L in the subdiagonal part of A.
104 *>
106 *> \endverbatim
107 *>
108 *> \param[in] LDA
109 *> \verbatim
110 *> LDA is INTEGER
111 *> The leading dimension of the array A. LDA >= max(1,N).
112 *> \endverbatim
113 *>
114 *> \param[out] E
115 *> \verbatim
116 *> E is COMPLEX array, dimension (N)
117 *> On exit, contains the output computed by the factorization
118 *> routine CSYTRF_RK, i.e. the superdiagonal (or subdiagonal)
119 *> elements of the symmetric block diagonal matrix D
120 *> with 1-by-1 or 2-by-2 diagonal blocks, where
121 *> If UPLO = 'U': E(i) = D(i-1,i), i=2:N, E(1) is set to 0;
122 *> If UPLO = 'L': E(i) = D(i+1,i), i=1:N-1, E(N) is set to 0.
123 *>
124 *> NOTE: For 1-by-1 diagonal block D(k), where
125 *> 1 <= k <= N, the element E(k) is set to 0 in both
126 *> UPLO = 'U' or UPLO = 'L' cases.
127 *>
129 *> \endverbatim
130 *>
131 *> \param[out] IPIV
132 *> \verbatim
133 *> IPIV is INTEGER array, dimension (N)
134 *> Details of the interchanges and the block structure of D,
135 *> as determined by CSYTRF_RK.
136 *>
138 *> \endverbatim
139 *>
140 *> \param[in,out] B
141 *> \verbatim
142 *> B is COMPLEX array, dimension (LDB,NRHS)
143 *> On entry, the N-by-NRHS right hand side matrix B.
144 *> On exit, if INFO = 0, the N-by-NRHS solution matrix X.
145 *> \endverbatim
146 *>
147 *> \param[in] LDB
148 *> \verbatim
149 *> LDB is INTEGER
150 *> The leading dimension of the array B. LDB >= max(1,N).
151 *> \endverbatim
152 *>
153 *> \param[out] WORK
154 *> \verbatim
155 *> WORK is COMPLEX array, dimension ( MAX(1,LWORK) ).
156 *> Work array used in the factorization stage.
157 *> On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
158 *> \endverbatim
159 *>
160 *> \param[in] LWORK
161 *> \verbatim
162 *> LWORK is INTEGER
163 *> The length of WORK. LWORK >= 1. For best performance
164 *> of factorization stage LWORK >= max(1,N*NB), where NB is
165 *> the optimal blocksize for CSYTRF_RK.
166 *>
167 *> If LWORK = -1, then a workspace query is assumed;
168 *> the routine only calculates the optimal size of the WORK
169 *> array for factorization stage, returns this value as
170 *> the first entry of the WORK array, and no error message
171 *> related to LWORK is issued by XERBLA.
172 *> \endverbatim
173 *>
174 *> \param[out] INFO
175 *> \verbatim
176 *> INFO is INTEGER
177 *> = 0: successful exit
178 *>
179 *> < 0: If INFO = -k, the k-th argument had an illegal value
180 *>
181 *> > 0: If INFO = k, the matrix A is singular, because:
182 *> If UPLO = 'U': column k in the upper
183 *> triangular part of A contains all zeros.
184 *> If UPLO = 'L': column k in the lower
185 *> triangular part of A contains all zeros.
186 *>
187 *> Therefore D(k,k) is exactly zero, and superdiagonal
188 *> elements of column k of U (or subdiagonal elements of
189 *> column k of L ) are all zeros. The factorization has
190 *> been completed, but the block diagonal matrix D is
191 *> exactly singular, and division by zero will occur if
192 *> it is used to solve a system of equations.
193 *>
194 *> NOTE: INFO only stores the first occurrence of
195 *> a singularity, any subsequent occurrence of singularity
196 *> is not stored in INFO even though the factorization
197 *> always completes.
198 *> \endverbatim
199 *
200 * Authors:
201 * ========
202 *
203 *> \author Univ. of Tennessee
204 *> \author Univ. of California Berkeley
205 *> \author Univ. of Colorado Denver
206 *> \author NAG Ltd.
207 *
208 *> \date December 2016
209 *
210 *> \ingroup complexSYsolve
211 *
212 *> \par Contributors:
213 * ==================
214 *>
215 *> \verbatim
216 *>
217 *> December 2016, Igor Kozachenko,
218 *> Computer Science Division,
219 *> University of California, Berkeley
220 *>
221 *> September 2007, Sven Hammarling, Nicholas J. Higham, Craig Lucas,
222 *> School of Mathematics,
223 *> University of Manchester
224 *>
225 *> \endverbatim
226 *
227 * =====================================================================
228  SUBROUTINE csysv_rk( UPLO, N, NRHS, A, LDA, E, IPIV, B, LDB, WORK,
229  \$ LWORK, INFO )
230 *
231 * -- LAPACK driver routine (version 3.7.0) --
232 * -- LAPACK is a software package provided by Univ. of Tennessee, --
233 * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
234 * December 2016
235 *
236 * .. Scalar Arguments ..
237  CHARACTER UPLO
238  INTEGER INFO, LDA, LDB, LWORK, N, NRHS
239 * ..
240 * .. Array Arguments ..
241  INTEGER IPIV( * )
242  COMPLEX A( LDA, * ), B( LDB, * ), E( * ), WORK( * )
243 * ..
244 *
245 * =====================================================================
246 *
247 * .. Local Scalars ..
248  LOGICAL LQUERY
249  INTEGER LWKOPT
250 * ..
251 * .. External Functions ..
252  LOGICAL LSAME
253  EXTERNAL lsame
254 * ..
255 * .. External Subroutines ..
256  EXTERNAL xerbla, csytrf_rk, csytrs_3
257 * ..
258 * .. Intrinsic Functions ..
259  INTRINSIC max
260 * ..
261 * .. Executable Statements ..
262 *
263 * Test the input parameters.
264 *
265  info = 0
266  lquery = ( lwork.EQ.-1 )
267  IF( .NOT.lsame( uplo, 'U' ) .AND. .NOT.lsame( uplo, 'L' ) ) THEN
268  info = -1
269  ELSE IF( n.LT.0 ) THEN
270  info = -2
271  ELSE IF( nrhs.LT.0 ) THEN
272  info = -3
273  ELSE IF( lda.LT.max( 1, n ) ) THEN
274  info = -5
275  ELSE IF( ldb.LT.max( 1, n ) ) THEN
276  info = -9
277  ELSE IF( lwork.LT.1 .AND. .NOT.lquery ) THEN
278  info = -11
279  END IF
280 *
281  IF( info.EQ.0 ) THEN
282  IF( n.EQ.0 ) THEN
283  lwkopt = 1
284  ELSE
285  CALL csytrf_rk( uplo, n, a, lda, e, ipiv, work, -1, info )
286  lwkopt = work(1)
287  END IF
288  work( 1 ) = lwkopt
289  END IF
290 *
291  IF( info.NE.0 ) THEN
292  CALL xerbla( 'CSYSV_RK ', -info )
293  RETURN
294  ELSE IF( lquery ) THEN
295  RETURN
296  END IF
297 *
298 * Compute the factorization A = U*D*U**T or A = L*D*L**T.
299 *
300  CALL csytrf_rk( uplo, n, a, lda, e, ipiv, work, lwork, info )
301 *
302  IF( info.EQ.0 ) THEN
303 *
304 * Solve the system A*X = B with BLAS3 solver, overwriting B with X.
305 *
306  CALL csytrs_3( uplo, n, nrhs, a, lda, e, ipiv, b, ldb, info )
307 *
308  END IF
309 *
310  work( 1 ) = lwkopt
311 *
312  RETURN
313 *
314 * End of CSYSV_RK
315 *
316  END
csysv_rk
subroutine csysv_rk(UPLO, N, NRHS, A, LDA, E, IPIV, B, LDB, WORK, LWORK, INFO)
CSYSV_RK computes the solution to system of linear equations A * X = B for SY matrices
Definition: csysv_rk.f:230
csytrs_3
subroutine csytrs_3(UPLO, N, NRHS, A, LDA, E, IPIV, B, LDB, INFO)
CSYTRS_3
Definition: csytrs_3.f:167
csytrf_rk
subroutine csytrf_rk(UPLO, N, A, LDA, E, IPIV, WORK, LWORK, INFO)
CSYTRF_RK computes the factorization of a complex symmetric indefinite matrix using the bounded Bunch...
Definition: csytrf_rk.f:261
xerbla
subroutine xerbla(SRNAME, INFO)
XERBLA
Definition: xerbla.f:62