dpbsvx man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

dpbsvx(3P)		    Sun Performance Library		    dpbsvx(3P)

NAME
       dpbsvx  -  use  the  Cholesky factorization A = U**T*U or A = L*L**T to
       compute the solution to a real system of linear equations  A * X = B,

SYNOPSIS
       SUBROUTINE DPBSVX(FACT, UPLO, N, KD, NRHS, A, LDA, AF, LDAF,
	     EQUED, S, B, LDB, X, LDX, RCOND, FERR, BERR, WORK, WORK2,
	     INFO)

       CHARACTER * 1 FACT, UPLO, EQUED
       INTEGER N, KD, NRHS, LDA, LDAF, LDB, LDX, INFO
       INTEGER WORK2(*)
       DOUBLE PRECISION RCOND
       DOUBLE  PRECISION  A(LDA,*),  AF(LDAF,*),  S(*),	 B(LDB,*),   X(LDX,*),
       FERR(*), BERR(*), WORK(*)

       SUBROUTINE DPBSVX_64(FACT, UPLO, N, KD, NRHS, A, LDA, AF, LDAF,
	     EQUED, S, B, LDB, X, LDX, RCOND, FERR, BERR, WORK, WORK2,
	     INFO)

       CHARACTER * 1 FACT, UPLO, EQUED
       INTEGER*8 N, KD, NRHS, LDA, LDAF, LDB, LDX, INFO
       INTEGER*8 WORK2(*)
       DOUBLE PRECISION RCOND
       DOUBLE	PRECISION  A(LDA,*),  AF(LDAF,*),  S(*),  B(LDB,*),  X(LDX,*),
       FERR(*), BERR(*), WORK(*)

   F95 INTERFACE
       SUBROUTINE PBSVX(FACT, UPLO, [N], KD, [NRHS], A, [LDA], AF, [LDAF],
	      EQUED, S, B, [LDB], X, [LDX], RCOND, FERR, BERR, [WORK],
	      [WORK2], [INFO])

       CHARACTER(LEN=1) :: FACT, UPLO, EQUED
       INTEGER :: N, KD, NRHS, LDA, LDAF, LDB, LDX, INFO
       INTEGER, DIMENSION(:) :: WORK2
       REAL(8) :: RCOND
       REAL(8), DIMENSION(:) :: S, FERR, BERR, WORK
       REAL(8), DIMENSION(:,:) :: A, AF, B, X

       SUBROUTINE PBSVX_64(FACT, UPLO, [N], KD, [NRHS], A, [LDA], AF,
	      [LDAF], EQUED, S, B, [LDB], X, [LDX], RCOND, FERR, BERR,
	      [WORK], [WORK2], [INFO])

       CHARACTER(LEN=1) :: FACT, UPLO, EQUED
       INTEGER(8) :: N, KD, NRHS, LDA, LDAF, LDB, LDX, INFO
       INTEGER(8), DIMENSION(:) :: WORK2
       REAL(8) :: RCOND
       REAL(8), DIMENSION(:) :: S, FERR, BERR, WORK
       REAL(8), DIMENSION(:,:) :: A, AF, B, X

   C INTERFACE
       #include <sunperf.h>

       void dpbsvx(char fact, char uplo, int n, int kd, int nrhs,  double  *a,
		 int lda, double *af, int ldaf, char *equed, double *s, double
		 *b, int ldb, double *x, int ldx, double *rcond, double *ferr,
		 double *berr, int *info);

       void dpbsvx_64(char fact, char uplo, long n, long kd, long nrhs, double
		 *a, long lda, double *af, long ldaf, char *equed, double  *s,
		 double *b, long ldb, double *x, long ldx, double *rcond, dou‐
		 ble *ferr, double *berr, long *info);

PURPOSE
       dpbsvx uses the Cholesky factorization A = U**T*U or A = L*L**T to com‐
       pute the solution to a real system of linear equations
	  A  *	X  =  B, where A is an N-by-N symmetric positive definite band
       matrix 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 = 'E', real scaling factors are computed to equilibrate
	  the system:
	     diag(S) * A * diag(S) * inv(diag(S)) * X = diag(S) * B
	  Whether or not the system will be equilibrated depends on the
	  scaling of the matrix A, but if equilibration is used, A is
	  overwritten by diag(S)*A*diag(S) and B by diag(S)*B.

       2. If FACT = 'N' or 'E', the Cholesky decomposition is used to
	  factor the matrix A (after equilibration if FACT = 'E') as
	     A = U**T * U,  if UPLO = 'U', or
	     A = L * L**T,  if UPLO = 'L',
	  where U is an upper triangular band matrix, and L is a lower
	  triangular band matrix.

       3. If the leading i-by-i principal minor is not positive definite,
	  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.

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

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

       6. If equilibration was used, the matrix X is premultiplied by
	  diag(S) so that it solves the original system before
	  equilibration.

ARGUMENTS
       FACT (input)
		 Specifies whether or not the factored form of the matrix A is
		 supplied on entry, and if not, whether the matrix A should be
		 equilibrated  before  it  is  factored.  = 'F':  On entry, AF
		 contains the factored form of A.  If EQUED = 'Y', the	matrix
		 A  has	 been equilibrated with scaling factors given by S.  A
		 and AF will not be modified.  = 'N':  The matrix  A  will  be
		 copied to AF and factored.
		 =  'E':  The matrix A will be equilibrated if necessary, then
		 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.

       KD (input)
		 The  number  of superdiagonals of the matrix A if UPLO = 'U',
		 or the number of subdiagonals if UPLO = 'L'.  KD >= 0.

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

       A (input/output)
		 On  entry,  the upper or lower triangle of the symmetric band
		 matrix A, stored in the first KD+1 rows of the array,	except
		 if  FACT = 'F' and EQUED = 'Y', then A must contain the equi‐
		 librated matrix diag(S)*A*diag(S).  The j-th column of	 A  is
		 stored	 in the j-th column of the array A as follows: if UPLO
		 = 'U', A(KD+1+i-j,j) = A(i,j) for max(1,j-KD)<=i<=j; if  UPLO
		 =  'L',  A(1+i-j,j)	 =  A(i,j) for j<=i<=min(N,j+KD).  See
		 below for further details.

		 On exit, if FACT = 'E' and EQUED = 'Y', A is  overwritten  by
		 diag(S)*A*diag(S).

       LDA (input)
		 The leading dimension of the array A.	LDA >= KD+1.

       AF (input or output)
		 If FACT = 'F', then AF is an input argument and on entry con‐
		 tains the triangular factor U or L from the Cholesky  factor‐
		 ization A = U**T*U or A = L*L**T of the band matrix A, in the
		 same storage format as A (see A).  If EQUED = 'Y', then AF is
		 the factored form of the equilibrated matrix A.

		 If  FACT  =  'N',  then  AF is an output argument and on exit
		 returns the triangular factor U or L from the	Cholesky  fac‐
		 torization A = U**T*U or A = L*L**T.

		 If  FACT  =  'E',  then  AF is an output argument and on exit
		 returns the triangular factor U or L from the	Cholesky  fac‐
		 torization  A	=  U**T*U  or  A  = L*L**T of the equilibrated
		 matrix A (see the description of A for the form of the	 equi‐
		 librated matrix).

       LDAF (input)
		 The leading dimension of the array AF.	 LDAF >= KD+1.

       EQUED (input or output)
		 Specifies  the	 form  of equilibration that was done.	= 'N':
		 No equilibration (always true if FACT = 'N').
		 = 'Y':	 Equilibration was done, i.e., A has been replaced  by
		 diag(S)  * A * diag(S).  EQUED is an input argument if FACT =
		 'F'; otherwise, it is an output argument.

       S (input or output)
		 The scale factors for A; not accessed if EQUED = 'N'.	 S  is
		 an  input  argument  if FACT = 'F'; otherwise, S is an output
		 argument.  If FACT = 'F' and EQUED = 'Y', each element	 of  S
		 must be positive.

       B (input/output)
		 On  entry,  the N-by-NRHS right hand side matrix B.  On exit,
		 if EQUED = 'N', B is not modified; if EQUED = 'Y', B is over‐
		 written by diag(S) * B.

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

       X (output)
		 If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X to
		 the original system of equations.  Note that if EQUED =  'Y',
		 A and B are modified on exit, and the solution to the equili‐
		 brated system is inv(diag(S))*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  after  equilibration (if done).  If RCOND is less than the
		 machine precision (in particular, if RCOND = 0),  the	matrix
		 is  singular  to  working precision.  This condition is indi‐
		 cated by a return code of INFO > 0.

       FERR (output)
		 The estimated forward error bound for	each  solution	vector
		 X(j) (the j-th column of the solution matrix X).  If XTRUE is
		 the true solution corresponding to X(j), FERR(j) is an	 esti‐
		 mated upper bound for the magnitude of the largest element in
		 (X(j) - XTRUE) divided by the magnitude of the	 largest  ele‐
		 ment  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)
		 The  componentwise  relative  backward error of each solution
		 vector X(j) (i.e., the smallest relative change in  any  ele‐
		 ment of A or B that makes X(j) an exact solution).

       WORK (workspace)
		 dimension(3*N)

       WORK2 (workspace)
		 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:	the leading minor of order i of A is not positive def‐
		 inite, so the factorization could not be completed,  and  the
		 solution  has	not  been  computed. RCOND = 0 is returned.  =
		 N+1: U is nonsingular, but RCOND is less than machine	preci‐
		 sion,	meaning	 that the matrix is singular to working preci‐
		 sion.	Nevertheless, the solution and error bounds  are  com‐
		 puted because there are a number of situations where the com‐
		 puted solution can be more accurate than the value  of	 RCOND
		 would suggest.

FURTHER DETAILS
       The band storage scheme is illustrated by the following example, when N
       = 6, KD = 2, and UPLO = 'U':

       Two-dimensional storage of the symmetric matrix A:

	  a11  a12  a13
	       a22  a23	 a24
		    a33	 a34  a35
			 a44  a45  a46
			      a55  a56
	  (aij=conjg(aji))	   a66

       Band storage of the upper triangle of A:

	   *	*   a13	 a24  a35  a46
	   *   a12  a23	 a34  a45  a56
	  a11  a22  a33	 a44  a55  a66

       Similarly, if UPLO = 'L' the format of A is as follows:

	  a11  a22  a33	 a44  a55  a66
	  a21  a32  a43	 a54  a65   *
	  a31  a42  a53	 a64   *    *

       Array elements marked * are not used by the routine.

				  6 Mar 2009			    dpbsvx(3P)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net