Go to main content
Oracle Developer Studio 12.5 Man Pages

Exit Print View

Updated: June 2017
 
 

dspsvx (3p)

Name

dspsvx - use the diagonal pivoting factorization A = U*D*U**T or A = L*D*L**T to compute the solution to a real system of linear equations A * X = B, where A is an N-by-N symmetric matrix stored in packed format and X and B are N-by-NRHS matrices

Synopsis

SUBROUTINE DSPSVX(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X, LDX,
RCOND, FERR, BERR, WORK, WORK2, INFO)

CHARACTER*1 FACT, UPLO
INTEGER N, NRHS, LDB, LDX, INFO
INTEGER IPIVOT(*), WORK2(*)
DOUBLE PRECISION RCOND
DOUBLE PRECISION AP(*), AF(*), B(LDB,*),  X(LDX,*),  FERR(*),  BERR(*),
WORK(*)

SUBROUTINE DSPSVX_64(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X,
LDX, RCOND, FERR, BERR, WORK, WORK2, INFO)

CHARACTER*1 FACT, UPLO
INTEGER*8 N, NRHS, LDB, LDX, INFO
INTEGER*8 IPIVOT(*), WORK2(*)
DOUBLE PRECISION RCOND
DOUBLE  PRECISION  AP(*),  AF(*), B(LDB,*), X(LDX,*), FERR(*), BERR(*),
WORK(*)




F95 INTERFACE
SUBROUTINE SPSVX(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X,
LDX, RCOND, FERR, BERR, WORK, WORK2, INFO)

CHARACTER(LEN=1) :: FACT, UPLO
INTEGER :: N, NRHS, LDB, LDX, INFO
INTEGER, DIMENSION(:) :: IPIVOT, WORK2
REAL(8) :: RCOND
REAL(8), DIMENSION(:) :: AP, AF, FERR, BERR, WORK
REAL(8), DIMENSION(:,:) :: B, X

SUBROUTINE SPSVX_64(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X,
LDX, RCOND, FERR, BERR, WORK, WORK2, INFO)

CHARACTER(LEN=1) :: FACT, UPLO
INTEGER(8) :: N, NRHS, LDB, LDX, INFO
INTEGER(8), DIMENSION(:) :: IPIVOT, WORK2
REAL(8) :: RCOND
REAL(8), DIMENSION(:) :: AP, AF, FERR, BERR, WORK
REAL(8), DIMENSION(:,:) :: B, X




C INTERFACE
#include <sunperf.h>

void dspsvx(char fact, char uplo, int n, int nrhs,  double  *a,  double
*af,  int  *ipivot,  double  *b, int ldb, double *x, int ldx,
double *rcond, double *ferr, double *berr, int *info);

void dspsvx_64(char fact, char uplo, long n, long nrhs, double *a, dou-
ble  *af,  long *ipivot, double *b, long ldb, double *x, long
ldx, double *rcond, double *ferr, double *berr, long *info);

Description

Oracle Solaris Studio Performance Library                           dspsvx(3P)



NAME
       dspsvx  -  use  the diagonal pivoting factorization A = U*D*U**T or A =
       L*D*L**T to compute the solution to a real system of linear equations A
       *  X = B, where A is an N-by-N symmetric matrix stored in packed format
       and X and B are N-by-NRHS matrices


SYNOPSIS
       SUBROUTINE DSPSVX(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X, LDX,
             RCOND, FERR, BERR, WORK, WORK2, INFO)

       CHARACTER*1 FACT, UPLO
       INTEGER N, NRHS, LDB, LDX, INFO
       INTEGER IPIVOT(*), WORK2(*)
       DOUBLE PRECISION RCOND
       DOUBLE PRECISION AP(*), AF(*), B(LDB,*),  X(LDX,*),  FERR(*),  BERR(*),
       WORK(*)

       SUBROUTINE DSPSVX_64(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X,
             LDX, RCOND, FERR, BERR, WORK, WORK2, INFO)

       CHARACTER*1 FACT, UPLO
       INTEGER*8 N, NRHS, LDB, LDX, INFO
       INTEGER*8 IPIVOT(*), WORK2(*)
       DOUBLE PRECISION RCOND
       DOUBLE  PRECISION  AP(*),  AF(*), B(LDB,*), X(LDX,*), FERR(*), BERR(*),
       WORK(*)




   F95 INTERFACE
       SUBROUTINE SPSVX(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X,
              LDX, RCOND, FERR, BERR, WORK, WORK2, INFO)

       CHARACTER(LEN=1) :: FACT, UPLO
       INTEGER :: N, NRHS, LDB, LDX, INFO
       INTEGER, DIMENSION(:) :: IPIVOT, WORK2
       REAL(8) :: RCOND
       REAL(8), DIMENSION(:) :: AP, AF, FERR, BERR, WORK
       REAL(8), DIMENSION(:,:) :: B, X

       SUBROUTINE SPSVX_64(FACT, UPLO, N, NRHS, AP, AF, IPIVOT, B, LDB, X,
              LDX, RCOND, FERR, BERR, WORK, WORK2, INFO)

       CHARACTER(LEN=1) :: FACT, UPLO
       INTEGER(8) :: N, NRHS, LDB, LDX, INFO
       INTEGER(8), DIMENSION(:) :: IPIVOT, WORK2
       REAL(8) :: RCOND
       REAL(8), DIMENSION(:) :: AP, AF, FERR, BERR, WORK
       REAL(8), DIMENSION(:,:) :: B, X




   C INTERFACE
       #include <sunperf.h>

       void dspsvx(char fact, char uplo, int n, int nrhs,  double  *a,  double
                 *af,  int  *ipivot,  double  *b, int ldb, double *x, int ldx,
                 double *rcond, double *ferr, double *berr, int *info);

       void dspsvx_64(char fact, char uplo, long n, long nrhs, double *a, dou-
                 ble  *af,  long *ipivot, double *b, long ldb, double *x, long
                 ldx, double *rcond, double *ferr, double *berr, long *info);



PURPOSE
       DSPSVX uses the diagonal pivoting factorization A =  U*D*U**T  or  A  =
       L*D*L**T to compute the solution to a real system of linear equations A
       * X = B, where A is an N-by-N symmetric matrix stored in packed  format
       and X and B are N-by-NRHS matrices.

       Error  bounds  on  the  solution and a condition estimate are also pro-
       vided.

       The following steps are performed:

       1. If FACT = 'N', the diagonal pivoting method is used to factor A as
             A = U * D * U**T,  if UPLO = 'U', or
             A = L * D * L**T,  if UPLO = 'L',
          where U (or L) is a product of permutation and unit upper (lower)
          triangular matrices and D is symmetric and block diagonal with
          1-by-1 and 2-by-2 diagonal blocks.

       2. If some D(i,i)=0, so that D is exactly singular, then the routine
          returns with INFO = i. Otherwise, the factored form of A is used
          to estimate the condition number of the matrix A.  If the
          reciprocal of the condition number is less than machine precision,
          INFO = N+1 is returned as a warning, but the routine still goes on
          to solve for X and compute error bounds as described below.

       3. The system of equations is solved for X using the factored form
          of A.

       4. Iterative refinement is applied to improve the computed solution
          matrix and calculate error bounds and backward error estimates
          for it.


ARGUMENTS
       FACT (input)
                 Specifies whether or not the factored form of A has been sup-
                 plied  on entry.  = 'F':  On entry, AF and IPIVOT contain the
                 factored form of A.  AP, AF and IPIVOT will not be  modified.
                 = 'N':  The matrix A will be copied to AF and factored.


       UPLO (input)
                 = 'U':  Upper triangle of A is stored;
                 = 'L':  Lower triangle of A is stored.


       N (input) The number of linear equations, i.e., the order of the matrix
                 A.  N >= 0.


       NRHS (input)
                 The number of right hand sides, i.e., the number  of  columns
                 of the matrices B and X.  NRHS >= 0.


       AP (input)
                 Double  precision  array,  dimension (N*(N+1)/2) The upper or
                 lower triangle of the symmetric matrix A,  packed  columnwise
                 in  a  linear  array.   The j-th column of A is stored in the
                 array AP as follows: if UPLO  =  'U',  AP(i  +  (j-1)*j/2)  =
                 A(i,j)  for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) =
                 A(i,j) for j<=i<=n.  See below for further details.


       AF (input or output)
                 Double precision array, dimension (N*(N+1)/2) If FACT =  'F',
                 then  AF is an input argument and on entry contains the block
                 diagonal matrix D and the multipliers used to obtain the fac-
                 tor  U  or  L  from  the  factorization  A  = U*D*U**T or A =
                 L*D*L**T as computed by DSPTRF, stored as a packed triangular
                 matrix in the same storage format as A.

                 If FACT = 'N', then AF is an output argument and on exit con-
                 tains the block diagonal matrix D and the multipliers used to
                 obtain  the factor U or L from the factorization A = U*D*U**T
                 or A = L*D*L**T as computed by DSPTRF,  stored  as  a  packed
                 triangular matrix in the same storage format as A.


       IPIVOT (input or output)
                 Integer array, dimension (N) If FACT = 'F', then IPIVOT is an
                 input argument and on entry contains details  of  the  inter-
                 changes  and  the block structure of D, as determined by DSP-
                 TRF.  If IPIVOT(k) > 0, then rows and columns k and IPIVOT(k)
                 were  interchanged and D(k,k) is a 1-by-1 diagonal block.  If
                 UPLO = 'U' and IPIVOT(k) = IPIVOT(k-1) <  0,  then  rows  and
                 columns    k-1   and   -IPIVOT(k)   were   interchanged   and
                 D(k-1:k,k-1:k) is a 2-by-2 diagonal block.  If UPLO = 'L' and
                 IPIVOT(k)  =  IPIVOT(k+1)  < 0, then rows and columns k+1 and
                 -IPIVOT(k) were interchanged and D(k:k+1,k:k+1) is  a  2-by-2
                 diagonal block.

                 If  FACT = 'N', then IPIVOT is an output argument and on exit
                 contains details of the interchanges and the block  structure
                 of D, as determined by DSPTRF.


       B (input) Double  precision  array, dimension (LDB, NRHS) The N-by-NRHS
                 right hand side matrix B.


       LDB (input)
                 The leading dimension of the array B.  LDB >= max(1,N).


       X (output)
                 Double precision array, dimension (LDX, NRHS) If INFO = 0  or
                 INFO = N+1, the N-by-NRHS solution matrix X.


       LDX (input)
                 The leading dimension of the array X.  LDX >= max(1,N).


       RCOND (output)
                 The estimate of the reciprocal condition number of the matrix
                 A.  If RCOND is less than the machine precision (in  particu-
                 lar,  if RCOND = 0), the matrix is singular to working preci-
                 sion.  This condition is indicated by a return code of INFO >
                 0.


       FERR (output)
                 Double  precision  array, dimension (NRHS) The estimated for-
                 ward error bound for each solution vector X(j) (the j-th col-
                 umn of the solution matrix X).  If XTRUE is the true solution
                 corresponding to X(j), FERR(j) is an  estimated  upper  bound
                 for  the  magnitude  of the largest element in (X(j) - XTRUE)
                 divided by the magnitude of the largest element in X(j).  The
                 estimate  is  as  reliable  as the estimate for RCOND, and is
                 almost always a slight overestimate of the true error.


       BERR (output)
                 Double precision array, dimension  (NRHS)  The  componentwise
                 relative  backward  error of each solution vector X(j) (i.e.,
                 the smallest relative change in any element of A  or  B  that
                 makes X(j) an exact solution).


       WORK (workspace)
                 Double precision array, dimension(3*N)

       WORK2 (workspace)
                 Integer array, dimension(N)


       INFO (output)
                 = 0: successful exit
                 < 0: if INFO = -i, the i-th argument had an illegal value
                 > 0:  if INFO = i, and i is
                 <=  N:   D(i,i)  is exactly zero.  The factorization has been
                 completed but the factor D is exactly singular, so the  solu-
                 tion  and  error  bounds  could not be computed. RCOND = 0 is
                 returned.  = N+1: D is nonsingular, but RCOND  is  less  than
                 machine  precision,  meaning  that  the matrix is singular to
                 working precision.   Nevertheless,  the  solution  and  error
                 bounds  are computed because there are a number of situations
                 where the computed solution can be  more  accurate  than  the
                 value of RCOND would suggest.

FURTHER DETAILS
       The  packed storage scheme is illustrated by the following example when
       N = 4, UPLO = 'U':

       Two-dimensional storage of the symmetric matrix A:

          a11 a12 a13 a14
              a22 a23 a24
                  a33 a34     (aij = aji)
                      a44

       Packed storage of the upper triangle of A:

       AP = [ a11, a12, a22, a13, a23, a33, a14, a24, a34, a44 ]




                                  7 Nov 2015                        dspsvx(3P)