LAPACK 3.12.0 LAPACK: Linear Algebra PACKage
Searching...
No Matches
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
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 principal minor of order i is not positive,
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 principal minor of order i of A
281*> is not positive, so the factorization could not
282*> be completed, and the solution has not been
283*> 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 posvx
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 xerbla(srname, info)
Definition cblat2.f:3285
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 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
subroutine spocon(uplo, n, a, lda, anorm, rcond, work, iwork, info)
SPOCON
Definition spocon.f:121
subroutine spoequ(n, a, lda, s, scond, amax, info)
SPOEQU
Definition spoequ.f:112
subroutine sporfs(uplo, n, nrhs, a, lda, af, ldaf, b, ldb, x, ldx, ferr, berr, work, iwork, info)
SPORFS
Definition sporfs.f:183
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 spotrf(uplo, n, a, lda, info)
SPOTRF
Definition spotrf.f:107
subroutine spotrs(uplo, n, nrhs, a, lda, b, ldb, info)
SPOTRS
Definition spotrs.f:110