LAPACK  3.10.1
LAPACK: Linear Algebra PACKage
sposvx.f
Go to the documentation of this file.
1 *> \brief <b> SPOSVX computes the solution to system of linear equations A * X = B for PO matrices</b>
2 *
3 * =========== DOCUMENTATION ===========
4 *
5 * Online html documentation available at
6 * http://www.netlib.org/lapack/explore-html/
7 *
8 *> \htmlonly
9 *> Download SPOSVX + dependencies
10 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/sposvx.f">
11 *> [TGZ]</a>
12 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/sposvx.f">
13 *> [ZIP]</a>
14 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/sposvx.f">
15 *> [TXT]</a>
16 *> \endhtmlonly
17 *
18 * Definition:
19 * ===========
20 *
21 * SUBROUTINE SPOSVX( FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, EQUED,
22 * S, B, LDB, X, LDX, RCOND, FERR, BERR, WORK,
23 * IWORK, INFO )
24 *
25 * .. Scalar Arguments ..
26 * CHARACTER EQUED, FACT, UPLO
27 * INTEGER INFO, LDA, LDAF, LDB, LDX, N, NRHS
28 * REAL RCOND
29 * ..
30 * .. Array Arguments ..
31 * INTEGER IWORK( * )
32 * REAL A( LDA, * ), AF( LDAF, * ), B( LDB, * ),
33 * $ BERR( * ), FERR( * ), S( * ), WORK( * ),
34 * $ X( LDX, * )
35 * ..
36 *
37 *
38 *> \par Purpose:
39 * =============
40 *>
41 *> \verbatim
42 *>
43 *> SPOSVX uses the Cholesky factorization A = U**T*U or A = L*L**T to
44 *> compute the solution to a real system of linear equations
45 *> A * X = B,
46 *> where A is an N-by-N symmetric positive definite matrix and X and B
47 *> are N-by-NRHS matrices.
48 *>
49 *> Error bounds on the solution and a condition estimate are also
50 *> provided.
51 *> \endverbatim
52 *
53 *> \par Description:
54 * =================
55 *>
56 *> \verbatim
57 *>
58 *> The following steps are performed:
59 *>
60 *> 1. If FACT = 'E', real scaling factors are computed to equilibrate
61 *> the system:
62 *> diag(S) * A * diag(S) * inv(diag(S)) * X = diag(S) * B
63 *> Whether or not the system will be equilibrated depends on the
64 *> scaling of the matrix A, but if equilibration is used, A is
65 *> overwritten by diag(S)*A*diag(S) and B by diag(S)*B.
66 *>
67 *> 2. If FACT = 'N' or 'E', the Cholesky decomposition is used to
68 *> factor the matrix A (after equilibration if FACT = 'E') as
69 *> A = U**T* U, if UPLO = 'U', or
70 *> A = L * L**T, if UPLO = 'L',
71 *> where U is an upper triangular matrix and L is a lower triangular
72 *> matrix.
73 *>
74 *> 3. If the leading i-by-i principal minor is not positive definite,
75 *> then the routine returns with INFO = i. Otherwise, the factored
76 *> form of A is used to estimate the condition number of the matrix
77 *> A. If the reciprocal of the condition number is less than machine
78 *> precision, INFO = N+1 is returned as a warning, but the routine
79 *> still goes on to solve for X and compute error bounds as
80 *> described below.
81 *>
82 *> 4. The system of equations is solved for X using the factored form
83 *> of A.
84 *>
85 *> 5. Iterative refinement is applied to improve the computed solution
86 *> matrix and calculate error bounds and backward error estimates
87 *> for it.
88 *>
89 *> 6. If equilibration was used, the matrix X is premultiplied by
90 *> diag(S) so that it solves the original system before
91 *> equilibration.
92 *> \endverbatim
93 *
94 * Arguments:
95 * ==========
96 *
97 *> \param[in] FACT
98 *> \verbatim
99 *> FACT is CHARACTER*1
100 *> Specifies whether or not the factored form of the matrix A is
101 *> supplied on entry, and if not, whether the matrix A should be
102 *> equilibrated before it is factored.
103 *> = 'F': On entry, AF contains the factored form of A.
104 *> If EQUED = 'Y', the matrix A has been equilibrated
105 *> with scaling factors given by S. A and AF will not
106 *> be modified.
107 *> = 'N': The matrix A will be copied to AF and factored.
108 *> = 'E': The matrix A will be equilibrated if necessary, then
109 *> copied to AF and factored.
110 *> \endverbatim
111 *>
112 *> \param[in] UPLO
113 *> \verbatim
114 *> UPLO is CHARACTER*1
115 *> = 'U': Upper triangle of A is stored;
116 *> = 'L': Lower triangle of A is stored.
117 *> \endverbatim
118 *>
119 *> \param[in] N
120 *> \verbatim
121 *> N is INTEGER
122 *> The number of linear equations, i.e., the order of the
123 *> matrix A. N >= 0.
124 *> \endverbatim
125 *>
126 *> \param[in] NRHS
127 *> \verbatim
128 *> NRHS is INTEGER
129 *> The number of right hand sides, i.e., the number of columns
130 *> of the matrices B and X. NRHS >= 0.
131 *> \endverbatim
132 *>
133 *> \param[in,out] A
134 *> \verbatim
135 *> A is REAL array, dimension (LDA,N)
136 *> On entry, the symmetric matrix A, except if FACT = 'F' and
137 *> EQUED = 'Y', then A must contain the equilibrated matrix
138 *> diag(S)*A*diag(S). If UPLO = 'U', the leading
139 *> N-by-N upper triangular part of A contains the upper
140 *> triangular part of the matrix A, and the strictly lower
141 *> triangular part of A is not referenced. If UPLO = 'L', the
142 *> leading N-by-N lower triangular part of A contains the lower
143 *> triangular part of the matrix A, and the strictly upper
144 *> triangular part of A is not referenced. A is not modified if
145 *> FACT = 'F' or 'N', or if FACT = 'E' and EQUED = 'N' on exit.
146 *>
147 *> On exit, if FACT = 'E' and EQUED = 'Y', A is overwritten by
148 *> diag(S)*A*diag(S).
149 *> \endverbatim
150 *>
151 *> \param[in] LDA
152 *> \verbatim
153 *> LDA is INTEGER
154 *> The leading dimension of the array A. LDA >= max(1,N).
155 *> \endverbatim
156 *>
157 *> \param[in,out] AF
158 *> \verbatim
159 *> AF is REAL array, dimension (LDAF,N)
160 *> If FACT = 'F', then AF is an input argument and on entry
161 *> contains the triangular factor U or L from the Cholesky
162 *> factorization A = U**T*U or A = L*L**T, in the same storage
163 *> format as A. If EQUED .ne. 'N', then AF is the factored form
164 *> of the equilibrated matrix diag(S)*A*diag(S).
165 *>
166 *> If FACT = 'N', then AF is an output argument and on exit
167 *> returns the triangular factor U or L from the Cholesky
168 *> factorization A = U**T*U or A = L*L**T of the original
169 *> matrix A.
170 *>
171 *> If FACT = 'E', then AF is an output argument and on exit
172 *> returns the triangular factor U or L from the Cholesky
173 *> factorization A = U**T*U or A = L*L**T of the equilibrated
174 *> matrix A (see the description of A for the form of the
175 *> equilibrated matrix).
176 *> \endverbatim
177 *>
178 *> \param[in] LDAF
179 *> \verbatim
180 *> LDAF is INTEGER
181 *> The leading dimension of the array AF. LDAF >= max(1,N).
182 *> \endverbatim
183 *>
184 *> \param[in,out] EQUED
185 *> \verbatim
186 *> EQUED is CHARACTER*1
187 *> Specifies the form of equilibration that was done.
188 *> = 'N': No equilibration (always true if FACT = 'N').
189 *> = 'Y': Equilibration was done, i.e., A has been replaced by
190 *> diag(S) * A * diag(S).
191 *> EQUED is an input argument if FACT = 'F'; otherwise, it is an
192 *> output argument.
193 *> \endverbatim
194 *>
195 *> \param[in,out] S
196 *> \verbatim
197 *> S is REAL array, dimension (N)
198 *> The scale factors for A; not accessed if EQUED = 'N'. S is
199 *> an input argument if FACT = 'F'; otherwise, S is an output
200 *> argument. If FACT = 'F' and EQUED = 'Y', each element of S
201 *> must be positive.
202 *> \endverbatim
203 *>
204 *> \param[in,out] B
205 *> \verbatim
206 *> B is REAL array, dimension (LDB,NRHS)
207 *> On entry, the N-by-NRHS right hand side matrix B.
208 *> On exit, if EQUED = 'N', B is not modified; if EQUED = 'Y',
209 *> B is overwritten by diag(S) * B.
210 *> \endverbatim
211 *>
212 *> \param[in] LDB
213 *> \verbatim
214 *> LDB is INTEGER
215 *> The leading dimension of the array B. LDB >= max(1,N).
216 *> \endverbatim
217 *>
218 *> \param[out] X
219 *> \verbatim
220 *> X is REAL array, dimension (LDX,NRHS)
221 *> If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X to
222 *> the original system of equations. Note that if EQUED = 'Y',
223 *> A and B are modified on exit, and the solution to the
224 *> equilibrated system is inv(diag(S))*X.
225 *> \endverbatim
226 *>
227 *> \param[in] LDX
228 *> \verbatim
229 *> LDX is INTEGER
230 *> The leading dimension of the array X. LDX >= max(1,N).
231 *> \endverbatim
232 *>
233 *> \param[out] RCOND
234 *> \verbatim
235 *> RCOND is REAL
236 *> The estimate of the reciprocal condition number of the matrix
237 *> A after equilibration (if done). If RCOND is less than the
238 *> machine precision (in particular, if RCOND = 0), the matrix
239 *> is singular to working precision. This condition is
240 *> indicated by a return code of INFO > 0.
241 *> \endverbatim
242 *>
243 *> \param[out] FERR
244 *> \verbatim
245 *> FERR is REAL array, dimension (NRHS)
246 *> The estimated forward error bound for each solution vector
247 *> X(j) (the j-th column of the solution matrix X).
248 *> If XTRUE is the true solution corresponding to X(j), FERR(j)
249 *> is an estimated upper bound for the magnitude of the largest
250 *> element in (X(j) - XTRUE) divided by the magnitude of the
251 *> largest element in X(j). The estimate is as reliable as
252 *> the estimate for RCOND, and is almost always a slight
253 *> overestimate of the true error.
254 *> \endverbatim
255 *>
256 *> \param[out] BERR
257 *> \verbatim
258 *> BERR is REAL array, dimension (NRHS)
259 *> The componentwise relative backward error of each solution
260 *> vector X(j) (i.e., the smallest relative change in
261 *> any element of A or B that makes X(j) an exact solution).
262 *> \endverbatim
263 *>
264 *> \param[out] WORK
265 *> \verbatim
266 *> WORK is REAL array, dimension (3*N)
267 *> \endverbatim
268 *>
269 *> \param[out] IWORK
270 *> \verbatim
271 *> IWORK is INTEGER array, dimension (N)
272 *> \endverbatim
273 *>
274 *> \param[out] INFO
275 *> \verbatim
276 *> INFO is INTEGER
277 *> = 0: successful exit
278 *> < 0: if INFO = -i, the i-th argument had an illegal value
279 *> > 0: if INFO = i, and i is
280 *> <= N: the leading minor of order i of A is
281 *> not positive definite, so the factorization
282 *> could not be completed, and the solution has not
283 *> been computed. RCOND = 0 is returned.
284 *> = N+1: U is nonsingular, but RCOND is less than machine
285 *> precision, meaning that the matrix is singular
286 *> to working precision. Nevertheless, the
287 *> solution and error bounds are computed because
288 *> there are a number of situations where the
289 *> computed solution can be more accurate than the
290 *> value of RCOND would suggest.
291 *> \endverbatim
292 *
293 * Authors:
294 * ========
295 *
296 *> \author Univ. of Tennessee
297 *> \author Univ. of California Berkeley
298 *> \author Univ. of Colorado Denver
299 *> \author NAG Ltd.
300 *
301 *> \ingroup realPOsolve
302 *
303 * =====================================================================
304  SUBROUTINE sposvx( FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, EQUED,
305  $ S, B, LDB, X, LDX, RCOND, FERR, BERR, WORK,
306  $ IWORK, INFO )
307 *
308 * -- LAPACK driver routine --
309 * -- LAPACK is a software package provided by Univ. of Tennessee, --
310 * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
311 *
312 * .. Scalar Arguments ..
313  CHARACTER EQUED, FACT, UPLO
314  INTEGER INFO, LDA, LDAF, LDB, LDX, N, NRHS
315  REAL RCOND
316 * ..
317 * .. Array Arguments ..
318  INTEGER IWORK( * )
319  REAL A( LDA, * ), AF( LDAF, * ), B( LDB, * ),
320  $ berr( * ), ferr( * ), s( * ), work( * ),
321  $ x( ldx, * )
322 * ..
323 *
324 * =====================================================================
325 *
326 * .. Parameters ..
327  REAL ZERO, ONE
328  PARAMETER ( ZERO = 0.0e+0, one = 1.0e+0 )
329 * ..
330 * .. Local Scalars ..
331  LOGICAL EQUIL, NOFACT, RCEQU
332  INTEGER I, INFEQU, J
333  REAL AMAX, ANORM, BIGNUM, SCOND, SMAX, SMIN, SMLNUM
334 * ..
335 * .. External Functions ..
336  LOGICAL LSAME
337  REAL SLAMCH, SLANSY
338  EXTERNAL lsame, slamch, slansy
339 * ..
340 * .. External Subroutines ..
341  EXTERNAL slacpy, slaqsy, spocon, spoequ, sporfs, spotrf,
342  $ spotrs, xerbla
343 * ..
344 * .. Intrinsic Functions ..
345  INTRINSIC max, min
346 * ..
347 * .. Executable Statements ..
348 *
349  info = 0
350  nofact = lsame( fact, 'N' )
351  equil = lsame( fact, 'E' )
352  IF( nofact .OR. equil ) THEN
353  equed = 'N'
354  rcequ = .false.
355  ELSE
356  rcequ = lsame( equed, 'Y' )
357  smlnum = slamch( 'Safe minimum' )
358  bignum = one / smlnum
359  END IF
360 *
361 * Test the input parameters.
362 *
363  IF( .NOT.nofact .AND. .NOT.equil .AND. .NOT.lsame( fact, 'F' ) )
364  $ THEN
365  info = -1
366  ELSE IF( .NOT.lsame( uplo, 'U' ) .AND. .NOT.lsame( uplo, 'L' ) )
367  $ THEN
368  info = -2
369  ELSE IF( n.LT.0 ) THEN
370  info = -3
371  ELSE IF( nrhs.LT.0 ) THEN
372  info = -4
373  ELSE IF( lda.LT.max( 1, n ) ) THEN
374  info = -6
375  ELSE IF( ldaf.LT.max( 1, n ) ) THEN
376  info = -8
377  ELSE IF( lsame( fact, 'F' ) .AND. .NOT.
378  $ ( rcequ .OR. lsame( equed, 'N' ) ) ) THEN
379  info = -9
380  ELSE
381  IF( rcequ ) THEN
382  smin = bignum
383  smax = zero
384  DO 10 j = 1, n
385  smin = min( smin, s( j ) )
386  smax = max( smax, s( j ) )
387  10 CONTINUE
388  IF( smin.LE.zero ) THEN
389  info = -10
390  ELSE IF( n.GT.0 ) THEN
391  scond = max( smin, smlnum ) / min( smax, bignum )
392  ELSE
393  scond = one
394  END IF
395  END IF
396  IF( info.EQ.0 ) THEN
397  IF( ldb.LT.max( 1, n ) ) THEN
398  info = -12
399  ELSE IF( ldx.LT.max( 1, n ) ) THEN
400  info = -14
401  END IF
402  END IF
403  END IF
404 *
405  IF( info.NE.0 ) THEN
406  CALL xerbla( 'SPOSVX', -info )
407  RETURN
408  END IF
409 *
410  IF( equil ) THEN
411 *
412 * Compute row and column scalings to equilibrate the matrix A.
413 *
414  CALL spoequ( n, a, lda, s, scond, amax, infequ )
415  IF( infequ.EQ.0 ) THEN
416 *
417 * Equilibrate the matrix.
418 *
419  CALL slaqsy( uplo, n, a, lda, s, scond, amax, equed )
420  rcequ = lsame( equed, 'Y' )
421  END IF
422  END IF
423 *
424 * Scale the right hand side.
425 *
426  IF( rcequ ) THEN
427  DO 30 j = 1, nrhs
428  DO 20 i = 1, n
429  b( i, j ) = s( i )*b( i, j )
430  20 CONTINUE
431  30 CONTINUE
432  END IF
433 *
434  IF( nofact .OR. equil ) THEN
435 *
436 * Compute the Cholesky factorization A = U**T *U or A = L*L**T.
437 *
438  CALL slacpy( uplo, n, n, a, lda, af, ldaf )
439  CALL spotrf( uplo, n, af, ldaf, info )
440 *
441 * Return if INFO is non-zero.
442 *
443  IF( info.GT.0 )THEN
444  rcond = zero
445  RETURN
446  END IF
447  END IF
448 *
449 * Compute the norm of the matrix A.
450 *
451  anorm = slansy( '1', uplo, n, a, lda, work )
452 *
453 * Compute the reciprocal of the condition number of A.
454 *
455  CALL spocon( uplo, n, af, ldaf, anorm, rcond, work, iwork, info )
456 *
457 * Compute the solution matrix X.
458 *
459  CALL slacpy( 'Full', n, nrhs, b, ldb, x, ldx )
460  CALL spotrs( uplo, n, nrhs, af, ldaf, x, ldx, info )
461 *
462 * Use iterative refinement to improve the computed solution and
463 * compute error bounds and backward error estimates for it.
464 *
465  CALL sporfs( uplo, n, nrhs, a, lda, af, ldaf, b, ldb, x, ldx,
466  $ ferr, berr, work, iwork, info )
467 *
468 * Transform the solution matrix X to a solution of the original
469 * system.
470 *
471  IF( rcequ ) THEN
472  DO 50 j = 1, nrhs
473  DO 40 i = 1, n
474  x( i, j ) = s( i )*x( i, j )
475  40 CONTINUE
476  50 CONTINUE
477  DO 60 j = 1, nrhs
478  ferr( j ) = ferr( j ) / scond
479  60 CONTINUE
480  END IF
481 *
482 * Set INFO = N+1 if the matrix is singular to working precision.
483 *
484  IF( rcond.LT.slamch( 'Epsilon' ) )
485  $ info = n + 1
486 *
487  RETURN
488 *
489 * End of SPOSVX
490 *
491  END
subroutine slacpy(UPLO, M, N, A, LDA, B, LDB)
SLACPY copies all or part of one two-dimensional array to another.
Definition: slacpy.f:103
subroutine xerbla(SRNAME, INFO)
XERBLA
Definition: xerbla.f:60
subroutine spotrf(UPLO, N, A, LDA, INFO)
SPOTRF
Definition: spotrf.f:107
subroutine spocon(UPLO, N, A, LDA, ANORM, RCOND, WORK, IWORK, INFO)
SPOCON
Definition: spocon.f:121
subroutine sporfs(UPLO, N, NRHS, A, LDA, AF, LDAF, B, LDB, X, LDX, FERR, BERR, WORK, IWORK, INFO)
SPORFS
Definition: sporfs.f:183
subroutine spoequ(N, A, LDA, S, SCOND, AMAX, INFO)
SPOEQU
Definition: spoequ.f:112
subroutine spotrs(UPLO, N, NRHS, A, LDA, B, LDB, INFO)
SPOTRS
Definition: spotrs.f:110
subroutine sposvx(FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, EQUED, S, B, LDB, X, LDX, RCOND, FERR, BERR, WORK, IWORK, INFO)
SPOSVX computes the solution to system of linear equations A * X = B for PO matrices
Definition: sposvx.f:307
subroutine slaqsy(UPLO, N, A, LDA, S, SCOND, AMAX, EQUED)
SLAQSY scales a symmetric/Hermitian matrix, using scaling factors computed by spoequ.
Definition: slaqsy.f:133