CGEIR(3)

SYNOPSIS
SUBROUTINE CGEIR (A, LDA, N, V, ITASK, IND, WORK, IWORK)

NAME
cgeir - Solve a general system of linear equations. Iterative refinement is used to obtain an error estimate.

LIBRARY
SLATEC

CATEGORY
D2C1

TYPE
COMPLEX (SGEIR-S, CGEIR-C)

KEYWORDS
COMPLEX LINEAR EQUATIONS, GENERAL MATRIX, GENERAL SYSTEM OF LINEAR EQUATIONS

AUTHOR
Voorhees, E. A., (LANL)

DESCRIPTION
Subroutine CGEIR solves a general NxN system of complex linear equations using LINPACK subroutines CGEFA and CGESL. One pass of iterative refinement is used only to obtain an estimate of the accuracy. That is, if A is an NxN complex matrix and if X and B are complex N-vectors, then CGEIR solves the equation A*X=B. The matrix A is first factored into upper and lower tri- angular matrices U and L using partial pivoting. These factors and the pivoting information are used to calculate the solution, X. Then the residual vector is found and used to calculate an estimate of the relative error, IND. IND estimates the accuracy of the solution only when the input matrix and the right hand side are represented exactly in the computer and does not take into account any errors in the input data. If the equation A*X=B is to be solved for more than one vector B, the factoring of A does not need to be performed again and the option to only solve (ITASK .GT. 1) will be faster for the succeeding solutions. In this case, the contents of A, LDA, N, WORK, and IWORK must not have been altered by the user following factorization (ITASK=1). IND will not be changed by CGEIR in this case. Argument Description *** A COMPLEX(LDA,N) the doubly subscripted array with dimension (LDA,N) which contains the coefficient matrix. A is not altered by the routine. LDA INTEGER the leading dimension of the array A. LDA must be great- er than or equal to N. (Terminal error message IND=-1) N INTEGER the order of the matrix A. The first N elements of the array A are the elements of the first column of matrix A. N must be greater than or equal to 1. (Terminal error message IND=-2) V COMPLEX(N) on entry, the singly subscripted array(vector) of di- mension N which contains the right hand side B of a system of simultaneous linear equations A*X=B. on return, V contains the solution vector, X . ITASK INTEGER if ITASK=1, the matrix A is factored and then the linear equation is solved. if ITASK .GT. 1, the equation is solved using the existing factored matrix A (stored in work). if ITASK .LT. 1, then terminal error message IND=-3 is printed. IND INTEGER GT.0 IND is a rough estimate of the number of digits of accuracy in the solution, X. IND=75 means that the solution vector X is zero. LT.0 see error message corresponding to IND below. WORK COMPLEX(N*(N+1)) a singly subscripted array of dimension at least N*(N+1). IWORK INTEGER(N) a singly subscripted array of dimension at least N. Error Messages Printed *** IND=-1 terminal N is greater than LDA. IND=-2 terminal N is less than one. IND=-3 terminal ITASK is less than one. IND=-4 terminal The matrix A is computationally singular. A solution has not been computed. IND=-10 warning The solution has no apparent significance. The solution may be inaccurate or the matrix A may be poorly scaled. NOTE- The above terminal(*fatal*) error messages are designed to be handled by XERMSG in which LEVEL=1 (recoverable) and IFLAG=2 . LEVEL=0 for warning error messages from XERMSG. Unless the user provides otherwise, an error message will be printed followed by an abort.

REFERENCES
J. J. Dongarra, J. R. Bunch, C. B. Moler, and G. W. Stewart, LINPACK Users' Guide, SIAM, 1979.

ROUTINES CALLED
CCOPY, CDCDOT, CGEFA, CGESL, R1MACH, SCASUM, XERMSG

REVISION HISTORY (YYMMDD)
800502 DATE WRITTEN
890531 Changed all specific intrinsics to generic. (WRB)
890831 Modified array declarations. (WRB)
890831 REVISION DATE from Version 3.2
891214 Prologue converted to Version 4.0 format. (BAB)
900315 CALLs to XERROR changed to CALLs to XERMSG. (THJ)
900510 Convert XERRWV calls to XERMSG calls, cvt GOTO's to IF-THEN-ELSE. (RWC)
920501 Reformatted the REFERENCES section. (WRB)