DSYSVX(l)	     LAPACK driver routine (version 1.1)	    DSYSVX(l)

NAME
  DSYSVX - use the diagonal pivoting factorization to compute the solution to
  a real system	of linear equations A *	X = B,

SYNOPSIS

  SUBROUTINE DSYSVX( FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, IPIV, B, LDB, X,
		     LDX, RCOND, FERR, BERR, WORK, LWORK, IWORK, INFO )

      CHARACTER	     FACT, UPLO

      INTEGER	     INFO, LDA,	LDAF, LDB, LDX,	LWORK, N, NRHS

      DOUBLE	     PRECISION RCOND

      INTEGER	     IPIV( * ),	IWORK( * )

      DOUBLE	     PRECISION A( LDA, * ), AF(	LDAF, *	), B( LDB, * ),	BERR(
		     * ), FERR(	* ), WORK( * ),	X( LDX,	* )

PURPOSE
  DSYSVX uses the diagonal pivoting factorization to compute the solution to
  a real system	of linear equations A *	X = B, where A is an N-by-N symmetric
  matrix and X and B are N-by-NRHS matrices.

  Error	bounds on the solution and a condition estimate	are also provided.

DESCRIPTION
  The following	steps are performed:

  1. If	FACT = 'N', the	diagonal pivoting method is used to factor A.
     The form of the factorization is
	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. 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, steps	3 and 4	are skipped.

  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) CHARACTER*1
	  Specifies whether or not the factored	form of	A has been supplied
	  on entry.  = 'F':  On	entry, AF and IPIV contain the factored	form
	  of A.	 AF and	IPIV will not be modified.  = 'N':  The	matrix A will
	  be copied to AF and factored.

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

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

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

  A	  (input) DOUBLE PRECISION array, dimension (LDA,N)
	  The symmetric	matrix A.  If UPLO = 'U', the leading N-by-N upper
	  triangular part of A contains	the upper triangular part of the
	  matrix A, and	the strictly lower triangular part of A	is not refer-
	  enced.  If UPLO = 'L', the leading N-by-N lower triangular part of
	  A contains the lower triangular part of the matrix A,	and the
	  strictly upper triangular part of A is not referenced.

  LDA	  (input) INTEGER
	  The leading dimension	of the array A.	 LDA >=	max(1,N).

  AF	  (input or output) DOUBLE PRECISION array, dimension (LDAF,N)
	  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
	  factor U or L	from the factorization A = U*D*U**T or A = L*D*L**T
	  as computed by DSYTRF.

	  If FACT = 'N', then AF is an output argument and on exit returns
	  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.

  LDAF	  (input) INTEGER
	  The leading dimension	of the array AF.  LDAF >= max(1,N).

  IPIV	  (input or output) INTEGER array, dimension (N)
	  If FACT = 'F', then IPIV is an input argument	and on entry contains
	  details of the interchanges and the block structure of D, as deter-
	  mined	by DSYTRF.  If IPIV(k) > 0, then rows and columns k and
	  IPIV(k) were interchanged and	D(k,k) is a 1-by-1 diagonal block.
	  If UPLO = 'U'	and IPIV(k) = IPIV(k-1)	< 0, then rows and columns
	  k-1 and -IPIV(k) were	interchanged and D(k-1:k,k-1:k)	is a 2-by-2
	  diagonal block.  If UPLO = 'L' and IPIV(k) = IPIV(k+1) < 0, then
	  rows and columns k+1 and -IPIV(k) were interchanged and
	  D(k:k+1,k:k+1) is a 2-by-2 diagonal block.

	  If FACT = 'N', then IPIV is an output	argument and on	exit contains
	  details of the interchanges and the block structure of D, as deter-
	  mined	by DSYTRF.

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

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

  X	  (output) DOUBLE PRECISION array, dimension (LDX,NRHS)
	  If INFO = 0, the N-by-NRHS solution matrix X.

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

  RCOND	  (output) DOUBLE PRECISION
	  The estimate of the reciprocal condition number of the matrix	A.
	  If RCOND is less than	the machine precision (in particular, if
	  RCOND	= 0), the matrix is singular to	working	precision.  This con-
	  dition is indicated by a return code of INFO > 0, and	the solution
	  and error bounds are not computed.

  FERR	  (output) DOUBLE PRECISION array, dimension (NRHS)
	  The estimated	forward	error bounds for each solution vector X(j)
	  (the j-th column of the solution matrix X).  If XTRUE	is the true
	  solution, FERR(j) bounds the magnitude of the	largest	entry in
	  (X(j)	- XTRUE) divided by the	magnitude of the largest entry in
	  X(j).	 The quality of	the error bound	depends	on the quality of the
	  estimate of norm(inv(A)) computed in the code; if the	estimate of
	  norm(inv(A)) is accurate, the	error bound is guaranteed.

  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 entry	of A or	B
	  that makes X(j) an exact solution).

  WORK	  (workspace) DOUBLE PRECISION array, dimension	(LWORK)
	  On exit, if INFO = 0,	WORK(1)	returns	the optimal LWORK.

  LWORK	  (input) INTEGER
	  The length of	WORK.  LWORK >=	3*N, and for best performance LWORK
	  >= N*NB, where NB is the optimal blocksize for DSYTRF.

  IWORK	  (workspace) INTEGER array, dimension (N)

  INFO	  (output) INTEGER
	  = 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 has been	com-
	  pleted, but the block	diagonal matrix	D is exactly singular, so the
	  solution and error bounds could not be computed.  = N+1: the block
	  diagonal matrix D is nonsingular, but	RCOND is less than machine
	  precision.  The factorization	has been completed, but	the matrix is
	  singular to working precision, so the	solution and error bounds
	  have not been	computed.


Back to the listing of expert driver routines