\begin{page}{manpageXXf}{NAG On-line Documentation: f} \beginscroll \begin{verbatim} F(3NAG) Foundation Library (12/10/92) F(3NAG) F -- Linear Algebra Introduction -- F Chapter F Linear Algebra 1. Introduction The F Chapters of the Library are concerned with linear algebra and cover a large area. This general introduction is intended to help users decide which particular F Chapter is relevant to their problem. There are F Chapters with the following titles: F01 -- Matrix Factorizations F02 -- Eigenvalues and Eigenvectors F04 -- Simultaneous Linear Equations F06 -- Linear Algebra Support Routines F07 -- Linear Equations (LAPACK) The principal problem areas addressed by the above Chapters are: Systems of linear equations Linear least-squares problems Eigenvalue and singular value problems The solution of these problems usually involves several matrix operations, such as a matrix factorization followed by the solution of the factorized form, and the routines for these operations themselves utilize lower level support routines; typically routines from Chapter F06. Most users will not normally need to be concerned with these support routines. NAG has been involved in a project, called LAPACK [1], to develop a linear algebra package for modern high-performance computers and some of the routines developed within that project are incorporated into the Library as Chapter F07. It should be emphasised that, while the LAPACK project has been concerned with high-performance computers, the routines do not compromise efficiency on conventional machines. For background information on numerical algorithms for the solution of linear algebra problems see Golub and Van Loan [4]. For some problem areas the user has the choice of selecting a single routine to solve the problem, a so-called Black Box routine, or selecting more than one routine to solve the problem, such as a factorization routine followed by a solve routine, so- called General Purpose routines. The following sections indicate which chapters are relevant to particular problem areas. 2. Linear Equations The Black Box routines for solving linear equations of the form Ax=b and AX=B, where A is an n by n real or complex, non-singular matrix, are to be found in Chapter F04. Such equations can also be solved by selecting a General Purpose factorization routine from Chapter F01 and combining it with a solve routine in Chapter F04, or by selecting a factorization and a solve routine from Chapter F07. There are routines to cater for a variety of types of matrix, including general, symmetric or Hermitian, symmetric or Hermitian positive definite, tridiagonal, skyline and sparse matrices. In order to select the appropriate routine, users are recommended to consult the F04 Chapter Introduction in the first instance. 3. Linear Least-squares Routines for solving linear least-squares problems of the form T minimize r r, where r=b-Ax, x where A is an m by n, possibly rank deficient, matrix are to be found in Chapter F04. Linear least-squares problems can also be solved by routines in the statistical Chapter G02. In order to select the appropriate routine, users are recommended to consult the F04 Chapter Introduction in the first instance, but users with additional statistical requirements may prefer to consult the G02 Chapter Introduction. 4. Eigenvalue Problems and Singular Value Problems Routines for solving standard matrix eigenvalue problems of the form Ax=(lambda)x, where A is an n by n real or complex matrix, and generalized matrix eigenvalue problems of the form Ax=(lambda)Bx where B is also an n by n matrix are to be found in Chapter F02. There are routines to cater for various types of matrices, including general, symmetric or Hermitian and sparse matrices. Similarly, the routines for finding singular values and/or singular vectors of an m by n real or complex matrix A are to be found in Chapter F02. In order to select the appropriate routine, users are recommended to consult the F02 Chapter Introduction in the first instance. 5. Matrix Factorizations Routines for various sorts of matrix factorization are to be found in Chapters F01 and F07 together with associated transformation routines. In order to select the appropriate routine users are recommended to consult the F01 Chapter Introduction in the first instance. 6. Support Routines Chapter F06 contains a variety of routines to perform elementary algebraic operations involving scalars, vectors and matrices, such as setting up a plane rotation, performing a dot product and computing a matrix-vector product. Chapter F06 contains routines that meet the specification of the BLAS (Basic Linear Algebra Subprograms) [5, 3, 2]. The routines in this chapter will not normally be required by the general user, but are intended for use by those who require to build specialist linear algebra modules. The BLAS are extensively used by other NAG Foundation Library routines. References [1] Anderson E, Bai Z, Bischof C, Demmel J, Dongarra J J, Du Croz J, Greenbaum A, Hammarling S, McKenney A, Ostrouchov S and Sorensen D (1992) LAPACK Users' Guide. SIAM Philadelphia. [2] Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990) A Set of Level 3 Basic Linear Algebra Subprograms. ACM Trans. Math. Softw. 16 1--28. [3] Dongarra J J, Du Croz J J, Hammarling S and Hanson R J (1988) An Extended Set of FORTRAN Basic Linear Algebra Subprograms. ACM Trans. Math. Softw. 14 1--32. [4] Golub G H and Van Loan C F (1989) Matrix Computations (2nd Edition). Johns Hopkins University Press, Baltimore, Maryland. [5] Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic Linear Algebra Subprograms for Fortran Usage. ACM Trans. Math. Softw. 5 308--325. [6] Parlett B N (1980) The Symmetric Eigenvalue Problem. Prentice-Hall. [7] Wilkinson J H (1965) The Algebraic Eigenvalue Problem. Clarendon Press. [8] Wilkinson J H (1977) Some Recent Advances in Numerical Linear Algebra. The State of the Art in Numerical Analysis. (ed D A H Jacobs) Academic Press. [9] Wilkinson J H (1978) Singular Value Decomposition -- Basic Aspects. Numerical Software -- Needs and Availability. (ed D A H Jacobs) Academic Press. [10] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01}{NAG On-line Documentation: f01} \beginscroll \begin{verbatim} F01(3NAG) Foundation Library (12/10/92) F01(3NAG) F01 -- Matrix Factorization Introduction -- F01 Chapter F01 Matrix Factorization 1. Scope of the Chapter This chapter provides facilities for matrix factorizations and associated transformations. 2. Background to the Problems An n by n matrix may be factorized as T A=PLUQ , where L and U are respectively lower and uper triangular matrices, and P and Q are permutation matrices. This is called an LU factorization. For general dense matrices it is usual to choose Q=I and to then choose P to ensure that the factorization is numerically stable. For sparse matrices, judicious choice of P and Q ensures numerical stability as well as maintaining as much sparsity as possible in the factors L and U. The LU factorization is normally used in connection with the solution of the linear equations Ax=b, whose solution, x, may then be obtained by solving in succession the simpler equations T Ly=P b, Uz=y, x=Qz the first by forward substitution and the second by backward substitution. Routines to perform this solution are to be found in Chapter F04. T When A is symmetric positive-definite then we can choose U=L and Q=P, to give the Cholesky factorization. This factorization is numerically stable without permutations, but in the sparse case the permutations can again be used to try to maintain sparsity. The Cholesky factorization is sometimes expressed as T T A=PLDL P , where D is a diagonal matrix with positive diagonal elements and L is unit lower triangular. The LU factorization can also be performed on rectangular matrices, but in this case it is more usual to perform a QR factorization. When A is an m by n (m>=n) matrix this is given by (R) A=Q(0), where R is an n by n upper triangular matrix and Q is an orthogonal (unitary in the complex case) matrix. 3. Recommendations on Choice and Use of Routines Routine F07ADF performs the LU factorization of a real m by n dense matrix. The LU factorization of a sparse matrix is performed by routine F01BRF. Following the use of F01BRF, matrices with the same sparsity pattern may be factorized by routine F01BSF. The Cholesky factorization of a real symmetric positive-definite dense matrix is performed by routine F07FDF. Routine F01MCF performs the Cholesky factorization of a real symmetric positive-definite variable band (skyline) matrix, and a general sparse symmetric positive-definite matrix may be factorized using routine F01MAF. The QR factorization of an m by n (m>=n) matrix is performed by routine F01QCF in the real case, and F01RCF in the complex case. Following the use of F01QCF, operations with Q may be performed using routine F01QDF and some, or all, of the columns of Q may be formed using routine F01QEF. Routines F01RDF and F01REF perform the same tasks following the use of F01RCF. F01 -- Matrix Factorizations Contents -- F01 Chapter F01 Matrix Factorizations F01BRF LU factorization of real sparse matrix F01BSF LU factorization of real sparse matrix with known sparsity pattern T F01MAF LL factorization of real sparse symmetric positive- definite matrix T F01MCF LDL factorization of real symmetric positive-definite variable-bandwidth matrix F01QCF QR factorization of real m by n matrix (m>=n) T F01QDF Operations with orthogonal matrices, compute QB or Q B after factorization by F01QCF F01QEF Operations with orthogonal matrices, form columns of Q after factorization by F01QCF F01RCF QR factorization of complex m by n matrix (m>=n) H F01RDF Operations with unitary matrices, compute QB or Q B after factorization by F01RCF F01REF Operations with unitary matrices, form columns of Q after factorization by F01RCF \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01brf}{NAG On-line Documentation: f01brf} \beginscroll \begin{verbatim} F01BRF(3NAG) Foundation Library (12/10/92) F01BRF(3NAG) F01 -- Matrix Factorizations F01BRF F01BRF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01BRF factorizes a real sparse matrix. The routine either forms the LU factorization of a permutation of the entire matrix, or, optionally, first permutes the matrix to block lower triangular form and then only factorizes the diagonal blocks. 2. Specification SUBROUTINE F01BRF (N, NZ, A, LICN, IRN, LIRN, ICN, PIVOT, 1 IKEEP, IW, W, LBLOCK, GROW, ABORT, 2 IDISP, IFAIL) INTEGER N, NZ, LICN, IRN(LIRN), LIRN, ICN(LICN), 1 IKEEP(5*N), IW(8*N), IDISP(10), IFAIL DOUBLE PRECISION A(LICN), PIVOT, W(N) LOGICAL LBLOCK, GROW, ABORT(4) 3. Description Given a real sparse matrix A, this routine may be used to obtain the LU factorization of a permutation of A, PAQ=LU where P and Q are permutation matrices, L is unit lower triangular and U is upper triangular. The routine uses a sparse variant of Gaussian elimination, and the pivotal strategy is designed to compromise between maintaining sparsity and controlling loss of accuracy through round-off. Optionally the routine first permutes the matrix into block lower triangular form and then only factorizes the diagonal blocks. For some matrices this gives a considerable saving in storage and execution time. Extensive data checks are made; duplicated non-zeros can be accumulated. The factorization is intended to be used by F04AXF to solve T sparse systems of linear equations Ax=b or A x=b. If several matrices of the same sparsity pattern are to be factorized, F01BSF should be used for the second and subsequent matrices. The method is fully described by Duff [1]. 4. References [1] Duff I S (1977) MA28 -- a set of Fortran subroutines for sparse unsymmetric linear equations. A.E.R.E. Report R.8730. HMSO. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N > 0. 2: NZ -- INTEGER Input On entry: the number of non-zero elements in the matrix A. Constraint: NZ > 0. 3: A(LICN) -- DOUBLE PRECISION array Input/Output On entry: A(i), for i = 1,2,...,NZ must contain the non- zero elements of the sparse matrix A. They can be in any order since the routine will reorder them. On exit: the non- zero elements in the LU factorization. The array must not be changed by the user between a call of this routine and a call of F04AXF. 4: LICN -- INTEGER Input On entry: the dimension of the arrays A and ICN as declared in the (sub)program from which F01BRF is called. Since the factorization is returned in A and ICN, LICN should be large enough to accommodate this and should ordinarily be 2 to 4 times as large as NZ. Constraint: LICN >= NZ. 5: IRN(LIRN) -- INTEGER array Input/Output On entry: IRN(i), for i = 1,2,...,NZ must contain the row index of the non-zero element stored in A(i). On exit: the array is overwritten and is not needed for subsequent calls of F01BSF or F04AXF. 6: LIRN -- INTEGER Input On entry: the dimension of the array IRN as declared in the (sub)program from which F01BRF is called. It need not be as large as LICN; normally it will not need to be very much greater than NZ. Constraint: LIRN >= NZ. 7: ICN(LICN) -- INTEGER array Input/Output On entry: ICN(i), for i = 1,2,...,NZ must contain the column index of the non-zero element stored in A(i). On exit: the column indices of the non-zero elements in the factorization. The array must not be changed by the user between a call of this routine and subsequent calls of F01BSF or F04AXF. 8: PIVOT -- DOUBLE PRECISION Input On entry: PIVOT should have a value in the range 0.0 <= PIVOT <= 0.9999 and is used to control the choice of pivots. If PIVOT < 0.0, the value 0.0 is assumed, and if PIVOT > 0. 9999, the value 0.9999 is assumed. When searching a row for a pivot, any element is excluded which is less than PIVOT times the largest of those elements in the row available as pivots. Thus decreasing PIVOT biases the algorithm to maintaining sparsity at the expense of stability. Suggested value: PIVOT = 0.1 has been found to work well on test examples. 9: IKEEP(5*N) -- INTEGER array Output On exit: indexing information about the factorization. The array must not be changed by the user between a call of this routine and calls of F01BSF or F04AXF. 10: IW(8*N) -- INTEGER array Workspace 11: W(N) -- DOUBLE PRECISION array Output On exit: if GROW = .TRUE., W(1) contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see GROW); the rest of the array is used as workspace. If GROW = .FALSE., the array is not used. 12: LBLOCK -- LOGICAL Input On entry: if LBLOCK = .TRUE., the matrix is pre-ordered into block lower triangular form before the LU factorization is performed; otherwise the entire matrix is factorized. Suggested value: LBLOCK = .TRUE. unless the matrix is known to be irreducible. 13: GROW -- LOGICAL Input On entry: if GROW = .TRUE., then on exit W(1) contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization. If the matrix is well-scaled (see Section 8.2), then a high value for W(1) indicates that the LU factorization may be inaccurate and the user should be wary of the results and perhaps increase the parameter PIVOT for subsequent runs (see Section 7). Suggested value: GROW = .TRUE.. 14: ABORT(4) -- LOGICAL array Input On entry: if ABORT(1) = .TRUE., the routine will exit immediately on detecting a structural singularity (one that depends on the pattern of non-zeros) and return IFAIL = 1; otherwise it will complete the factorization (see Section 8.3). If ABORT(2) = .TRUE., the routine will exit immediately on detecting a numerical singularity (one that depends on the numerical values) and return IFAIL = 2; otherwise it will complete the factorization (see Section 8.3). If ABORT(3) = .TRUE., the routine will exit immediately (with IFAIL = 5) when the arrays A and ICN are filled up by the previously factorized, active and unfactorized parts of the matrix; otherwise it continues so that better guidance on necessary array sizes can be given in IDISP(6) and IDISP(7), and will exit with IFAIL in the range 4 to 6. Note that there is always an immediate error exit if the array IRN is too small. If ABORT(4) = .TRUE., the routine exits immediately (with IFAIL = 13) if it finds duplicate elements in the input matrix. If ABORT(4) = .FALSE., the routine proceeds using a value equal to the sum of the duplicate elements. In either case details of each duplicate element are output on the current advisory message unit (see X04ABF), unless suppressed by the value of IFAIL on entry. Suggested values: ABORT(1) = .TRUE. ABORT(2) = .TRUE. ABORT(3) = .FALSE. ABORT(4) = .TRUE.. 15: IDISP(10) -- INTEGER array Output On exit: IDISP is used to communicate information about the factorization to the user and also between a call of F01BRF and subsequent calls to F01BSF or F04AXF. IDISP(1) and IDISP(2), indicate the position in arrays A and ICN of the first and last elements in the LU factorization of the diagonal blocks. (IDISP(2) gives the number of non-zeros in the factorization.) IDISP(3) and IDISP(4), monitor the adequacy of 'elbow room' in the arrays IRN and A/ICN respectively, by giving the number of times that the data in these arrays has been compressed during the factorization to release more storage. If either IDISP(3) or IDISP(4) is quite large (say greater than 10), it will probably pay the user to increase the size of the corresponding array(s) for subsequent runs. If either is very low or zero, then the user can perhaps save storage by reducing the size of the corresponding array(s). IDISP(5), gives an upper bound on the rank of the matrix. IDISP(6) and IDISP(7), give the minimum size of arrays IRN and A/ICN respectively which would enable a successful run on an identical matrix (but some ' elbow-room' should be allowed - see Section 8). IDISP(8) to (10), are only used if LBLOCK = .TRUE.. IDISP(8), gives the structural rank of the matrix. IDISP(9), gives the number of diagonal blocks. IDISP(10), gives the size of the largest diagonal block. IDISP(1) and IDISP(2), must not be changed by the user between a call of F01BRF and subsequent calls to F01BSF or F04AXF. 16: IFAIL -- INTEGER Input/Output For this routine, the normal use of IFAIL is extended to control the printing of error and warning messages as well as specifying hard or soft failure (see the Essential Introduction). Before entry, IFAIL must be set to a value with the decimal expansion cba, where each of the decimal digits c, b and a must have a value of 0 or 1. a=0 specifies hard failure, otherwise soft failure; b=0 suppresses error messages, otherwise error messages will be printed (see Section 6); c=0 suppresses warning messages, otherwise warning messages will be printed (see Section 6). The recommended value for inexperienced users is 110 (i.e., hard failure with all messages printed). Unless the routine detects an error (see Section 6), IFAIL contains 0 on exit. 6. Error Indicators and Warnings Errors detected by the routine: For each error, an explanatory error message is output on the current error message unit (as defined by X04AAF), unless suppressed by the value of IFAIL on entry. IFAIL=-2 Successful factorization of a numerically singular matrix (which may also be structurally singular) (see Section 8.3). IFAIL=-1 Successful factorization of a structurally singular matrix (see Section 8.3). IFAIL= 1 The matrix is structurally singular and the factorization has been abandoned (ABORT(1) was .TRUE. on entry). IFAIL= 2 The matrix is numerically singular and the factorization has been abandoned (ABORT(2) was .TRUE. on entry). IFAIL= 3 LIRN is too small: there is not enough space in the array IRN to continue the factorization. The user is recommended to try again with LIRN (and the length of IRN) equal to at least IDISP(6) + N/2. IFAIL= 4 LICN is much too small: there is much too little space in the arrays A and ICN to continue the factorization. IFAIL= 5 LICN is too small: there is not enough space in the arrays A and ICN to store the factorization. If ABORT(3) was .FALSE. on entry, the factorization has been completed but some of the LU factors have been discarded to create space, IDISP(7) then gives the minimum value of LICN (i.e., the minimum length of A and ICN) required for a successful factorization of the same matrix. IFAIL= 6 LICN and LIRN are both too small: effectively this is a combination of IFAIL = 3 and IFAIL = 5 (with ABORT(3) = . FALSE.). IFAIL= 7 LICN is too small: there is not enough space in the arrays A and ICN for the permutation to block triangular form. IFAIL= 8 On entry N <= 0. IFAIL= 9 On entry NZ <= 0. IFAIL= 10 On entry LICN < NZ. IFAIL= 11 On entry LIRN < NZ. IFAIL= 12 On entry an element of the input matrix has a row or column index (i.e., an element of IRN or ICN) outside the range 1 to N. IFAIL= 13 Duplicate elements have been found in the input matrix and the factorization has been abandoned (ABORT(4) = .TRUE. on entry). 7. Accuracy The factorization obtained is exact for a perturbed matrix whose (i,j)th element differs from a by less than 3(epsilon)(rho)m ij ij where (epsilon) is the machine precision, (rho) is the growth value returned in W(1) if GROW = .TRUE., and m the number of ij Gaussian elimination operations applied to element (i,j). The value of m is not greater than n and is usually much less. ij Small (rho) values therefore guarantee accurate results, but unfortunately large (rho) values may give a very pessimistic indication of accuracy. 8. Further Comments 8.1. Timing The time required may be estimated very roughly from the number (tau) of non-zeros in the factorized form (output as IDISP(2)) and for this routine and its associates is 2 F01BRF: 5(tau) /n units 2 F01BSF: (tau) /n units F04AXF: 2(tau) units where our unit is the time for the inner loop of a full matrix 1 3 code (e.g. solving a full set of equations takes about -n 3 units). Note that the faster F01BSF time makes it well worthwhile to use this for a sequence of problems with the same pattern. It should be appreciated that (tau) varies widely from problem to problem. For network problems it may be little greater than NZ, the number of non-zeros in A; for discretisation of 2-dimensional and 3-dimensional partial differential equations it may be about 1 5/3 3nlog n and -n , respectively. 2 2 The time taken to find the block lower triangular form (LBLOCK = it is not found (LBLOCK = .FALSE.). If the matrix is irreducible (IDISP(9) = 1 after a call with LBLOCK = .TRUE.) then this time is wasted. Otherwise, particularly if the largest block is small (IDISP(10)< 0. 2: NZ -- INTEGER Input On entry: the number of non-zeros in the matrix A. Constraint: NZ > 0. 3: A(LICN) -- DOUBLE PRECISION array Input/Output On entry: A(i), for i = 1,2,...,NZ must contain the non- zero elements of the sparse matrix A. They can be in any order since the routine will reorder them. On exit: the non- zero elements in the factorization. The array must not be changed by the user between a call of this routine and a call of F04AXF. 4: LICN -- INTEGER Input On entry: the dimension of the arrays A and ICN as declared in the (sub)program from which F01BSF is called. It should have the same value as it had for F01BRF. Constraint: LICN >= NZ. 5: IVECT(NZ) -- INTEGER array Input 6: JVECT(NZ) -- INTEGER array Input On entry: IVECT(i) and JVECT(i), for i = 1,2,...,NZ must contain the row index and the column index respectively of the non-zero element stored in A(i). 7: ICN(LICN) -- INTEGER array Input On entry: the same information as output by F01BRF. It must not be changed by the user between a call of this routine and a call of F04AXF. 8: IKEEP(5*N) -- INTEGER array Input On entry: the same indexing information about the factorization as output from F01BRF. It must not be changed between a call of this routine and a call of F04AXF. 9: IW(8*N) -- INTEGER array Workspace 10: W(N) -- DOUBLE PRECISION array Output On exit: if GROW = .TRUE., W(1) contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see GROW); the rest of the array is used as workspace. If GROW = .FALSE., the array is not used. 11: GROW -- LOGICAL Input On entry: if GROW = .TRUE., then on exit W(1) contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization. If the matrix is well-scaled (see Section 8.2), then a high value for W(1) indicates that the LU factorization may be inaccurate and the user should be wary of the results and perhaps increase the parameter PIVOT for subsequent runs (see Section 7). 12: ETA -- DOUBLE PRECISION Input On entry: the relative pivot threshold below which an error diagnostic is provoked and IFAIL is set to 7. If ETA is greater than 1.0, then no check on pivot size is made. -4 Suggested value: ETA = 10 . 13: RPMIN -- DOUBLE PRECISION Output On exit: if ETA is less than 1.0, then RPMIN gives the smallest ratio of the pivot to the largest element in the row of the corresponding upper triangular factor thus monitoring the stability of the factorization. If RPMIN is very small it may be advisable to perform a new factorization using F01BRF. 14: ABORT -- LOGICAL Input On entry: if ABORT = .TRUE., the routine exits immediately (with IFAIL = 8) if it finds duplicate elements in the input matrix. If ABORT = .FALSE., the routine proceeds using a value equal to the sum of the duplicate elements. In either case details of each duplicate element are output on the current advisory message unit (see X04ABF), unless suppressed by the value of IFAIL on entry. Suggested value: ABORT = .TRUE.. 15: IDISP(2) -- INTEGER array Input On entry: IDISP(1) and IDISP(2) must be unchanged since the previous call of F01BRF. 16: IFAIL -- INTEGER Input/Output For this routine, the normal use of IFAIL is extended to control the printing of error and warning messages as well as specifying hard or soft failure (see the Essential Introduction). Before entry, IFAIL must be set to a value with the decimal expansion cba, where each of the decimal digits c, b and a must have a value of 0 or 1. a=0 specifies hard failure, otherwise soft failure; b=0 suppresses error messages, otherwise error messages will be printed (see Section 6); c=0 suppresses warning messages, otherwise warning messages will be printed (see Section 6). The recommended value for inexperienced users is 110 (i.e., hard failure with all messages printed). Unless the routine detects an error (see Section 6), IFAIL contains 0 on exit. 6. Error Indicators and Warnings Errors detected by the routine: For each error, an explanatory error message is output on the current error message unit (as defined by X04AAF), unless suppressed by the value of IFAIL on entry. IFAIL= 1 On entry N <= 0. IFAIL= 2 On entry NZ <= 0. IFAIL= 3 On entry LICN < NZ. IFAIL= 4 On entry an element of the input matrix has a row or column index (i.e., an element of IVECT or JVECT) outside the range 1 to N. IFAIL= 5 The input matrix is incompatible with the matrix factorized by the previous call of F01BRF (see Section 8). IFAIL= 6 The input matrix is numerically singular. IFAIL= 7 A very small pivot has been detected (see Section 5, ETA). The factorization has been completed but is potentially unstable. IFAIL= 8 Duplicate elements have been found in the input matrix and the factorization has been abandoned (ABORT = .TRUE. on entry). 7. Accuracy The factorization obtained is exact for a perturbed matrix whose (i,j)th element differs from a by less than 3(epsilon)(rho)m ij ij where (epsilon) is the machine precision, (rho) is the growth value returned in W(1) if GROW = .TRUE., and m the number of ij Gaussian elimination operations applied to element (i,j). If (rho) = W(1) is very large or RPMIN is very small, then a fresh call of F01BRF is recommended. 8. Further Comments If the user has a sequence of problems with the same sparsity pattern then this routine is recommended after F01BRF has been called for one such problem. It is typically 4 to 7 times faster but is potentially unstable since the previous pivotal sequence is used. Further details on timing are given in document F01BRF. If growth estimation is performed (GROW = .TRUE.), then the time increases by between 5% and 10%. Pivot size monitoring (ETA <= 1. 0) involves a similar overhead. We normally expect this routine to be entered with a matrix having the same pattern of non-zeros as was earlier presented to F01BRF. However there is no record of this pattern, but rather a record of the pattern including all fill-ins. Therefore we permit additional non-zeros in positions corresponding to fill-ins. If singular matrices are being treated then it is also required that the present matrix be sufficiently like the previous one for the same permutations to be suitable for factorization with the same set of zero pivots. 9. Example To factorize the real sparse matrices ( 5 0 0 0 0 0) ( 0 2 -1 2 0 0) ( 0 0 3 0 0 0) (-2 0 0 1 1 0) (-1 0 0 -1 2 -3) (-1 -1 0 0 0 6) and (10 0 0 0 0 0) ( 0 12 -3 -1 0 0) ( 0 0 15 0 0 0) (-2 0 0 10 -1 0). (-1 0 0 -5 1 -1) (-1 -2 0 0 0 6) This example program simply prints the values of W(1) and RPMIN returned by F01BSF. Normally the calls of F01BRF and F01BSF would be followed by calls of F04AXF. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01maf}{NAG On-line Documentation: f01maf} \beginscroll \begin{verbatim} F01MAF(3NAG) Foundation Library (12/10/92) F01MAF(3NAG) F01 -- Matrix Factorizations F01MAF F01MAF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01MAF computes an incomplete Cholesky factorization of a real sparse symmetric positive-definite matrix A. 2. Specification SUBROUTINE F01MAF (N, NZ, A, LICN, IRN, LIRN, ICN, DROPTL, 1 DENSW, WKEEP, IKEEP, IWORK, ABORT, 2 INFORM, IFAIL) INTEGER N, NZ, LICN, IRN(LIRN), LIRN, ICN(LICN), 1 IKEEP(2*N), IWORK(6*N), INFORM(4), IFAIL DOUBLE PRECISION A(LICN), DROPTL, DENSW, WKEEP(3*N) LOGICAL ABORT(3) 3. Description F01MAF computes an incomplete Cholesky factorization T T C=PLDL P , WAW=C+E for the sparse symmetric positive-definite matrix A, where P is a permutation matrix, L is a unit lower triangular matrix, D is a diagonal matrix with positive diagonal elements, E is an error matrix representing elements dropped during the factorization and diagonal elements that have been modified to ensure that C is positive-definite, and W is a diagonal matrix, chosen to make the diagonal elements of WAW unity. -1 -1 W CW is a pre-conditioning matrix for A, and the factorization of C is intended to be used by F04MAF to solve systems of linear equations Ax=b. The permutation matrix P is chosen to reduce the amount of fill- in that occurs in L and the user-supplied parameter DROPTL can also be used to control the amount of fill-in that occurs. Full details on the factorization can be found in Munksgaard [1]. F01MAF is based on the Harwell Library routine MA31A. 4. References [1] Munksgaard N (1980) Solving Sparse Symmetric Sets of Linear Equations by Pre-conditioned Conjugate Gradients. ACM Trans. Math. Softw. 6 206--219. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 1. 2: NZ -- INTEGER Input On entry: the number of non-zero elements in the upper triangular part of the matrix A, including the number of elements on the leading diagonal. Constraint: NZ >= N. 3: A(LICN) -- DOUBLE PRECISION array Input/Output On entry: the first NZ elements of the array A must contain the non-zero elements of the upper triangular part of the sparse positive-definite symmetric matrix A, including the elements on the leading diagonal. On exit: the first (NZ-N) elements of A contain the elements above the diagonal of the matrix WAW, where W is a diagonal matrix whose ith diagonal -1/2 element is w =a . These elements are returned in order by i ii rows and the value returned in ICN(k) gives the column index of the element returned in A(k). The value w is returned in i the ith element of the array WKEEP. The remaining LROW-NZ+N elements of A, where LROW is the value returned in INFORM(1), return details of the factorization for use by F04MAF. 4: LICN -- INTEGER Input On entry: the dimension of the array A as declared in the (sub)program from which F01MAF is called. If fill-in is expected during the factorization, then a larger value of LICN will allow fewer elements to be dropped during the factorization, thus giving a more accurate factorization, which in turn will almost certainly mean that fewer iterations will be required by F04MAF. Constraint: LICN>=2*NZ. 5: IRN(LIRN) -- INTEGER array Input/Output On entry: IRN(k), for k = 1,2,...,NZ must contain the row index of the non-zero element of the matrix A supplied in A (k). On exit: the first LCOL elements of IRN, where LCOL is the value returned in INFORM(2), return details of the factorization for use by F04MAF. 6: LIRN -- INTEGER Input On entry: the dimension of the array IRN as declared in the (sub)program from which F01MAF is called. LIRN must be at least NZ, but, as with LICN, if fill-in is expected then a larger value of LIRN will allow a more accurate factorization. For this purpose LIRN should exceed NZ by the same amount that LICN exceeds 2*NZ. Constraint: LIRN >= NZ. 7: ICN(LICN) -- INTEGER array Input/Output On entry: ICN(k), for k = 1,2,...,NZ must contain the column index of the non-zero element of the matrix A supplied in A (k). Thus a =A(k), where i = IRN(k) and j = ICN(k). On ij exit: the first (NZ-N) elements of ICN give the column indices of the first (NZ-N) elements returned in A. The remaining LROW - NZ + N elements of ICN return details of the factorization for use by F04MAF. 8: DROPTL -- DOUBLE PRECISION Input/Output On entry: a value in the range [-1.0,1.0] to be used as a tolerance in deciding whether or not to drop elements during (k+1) the factorization. At the kth pivot step the element a ij is dropped if it would cause fill-in and if (k+1) / (k) (k) |a |<|DROPTL|* / a a . ij \/ ii jj If DROPTL is supplied as negative, then it is not altered during the factorization and so is unchanged on exit, but if DROPTL is supplied as positive then it may be altered by the routine with the aim of obtaining an accurate factorization in the space available. If DROPTL is supplied as -1.0, then no fill-in will occur during the factorization; and if DROPTL is supplied as 0.0 then a complete factorization is performed. On exit: may be overwritten with the value used by the routine in order to obtain an accurate factorization in the space available, if DROPTL > 0.0 on entry. 9: DENSW -- DOUBLE PRECISION Input/Output On entry: a value in the range [0.0,1.0] to be used in deciding whether or not to regard the active part of the matrix at the kth pivot step as being full. If the ratio of non-zero elements to the total number of elements is greater than or equal to DENSW, then the active part is regarded as full. If DENSW < 1.0, then the storage used is likely to increase compared to the case where DENSW = 0, but the execution time is likely to decrease. Suggested value: DENSW = 0.8. On exit: if on entry DENSW is not in the range [0.0,1.0], then it is set to 0.8. Otherwise it is unchanged. 10: WKEEP(3*N) -- DOUBLE PRECISION array Output On exit: information which must be passed unchanged to F04MAF. The first N elements contain the values w , for i i=1,2,...,n, and the next N elements contain the diagonal elements of D. 11: IKEEP(2*N) -- INTEGER array Output On exit: information which must be passed unchanged to F04MAF. 12: IWORK(6*N) -- INTEGER array Workspace 13: ABORT(3) -- LOGICAL array Input On entry: if ABORT(1) = .TRUE., the routine will exit immediately on detecting duplicate elements and return IFAIL = 5. Otherwise when ABORT(1) = .FALSE., the calculations will continue using the sum of the duplicate entries. In either case details of the duplicate elements are output on the current advisory message unit (see X04ABF), unless suppressed by the value of IFAIL on entry. If ABORT(2) = .TRUE., the routine will exit immediately on detecting a zero or negative pivot element and return IFAIL = 6. Otherwise when ABORT(2) = .FALSE., the zero or negative pivot element will be modified to ensure positive-definiteness and a message will be printed on the current advisory message unit, unless suppressed by the value of IFAIL on entry. If ABORT(3) = .TRUE., the routine will exit immediately if the arrays A and ICN have been filled up and return IFAIL = 7. Otherwise when ABORT(3) = . FALSE., the data in the arrays is compressed to release more storage and a message will be printed on the current advisory message unit, unless suppressed by the value of IFAIL on entry. If DROPTL is positive on entry, it may be modified in order to allow a factorization to be completed in the available space. Suggested values: ABORT(1) = .TRUE., ABORT(2) = .TRUE., ABORT(3) = .TRUE.. 14: INFORM(4) -- INTEGER array Output On exit: INFORM(1) returns the number of elements of A and ICN that have been used by the routine. Thus at least the first INFORM(1) elements of A and of ICN must be supplied to F04MAF. Similarly, INFORM(2) returns the number of elements of IRN that have been used by the routine and so at least the first INFORM(2) elements must be supplied to F04MAF. INFORM(3) returns the number of entries supplied in A that corresponded to diagonal and duplicate elements. If no duplicate entries were found, then INFORM(3) will return the value of N. INFORM(4) returns the value k of the pivot step from which the active matrix was regarded as full. INFORM must be passed unchanged to F04MAF. 15: IFAIL -- INTEGER Input/Output For this routine, the normal use of IFAIL is extended to control the printing of error and warning messages as well as specifying hard or soft failure (see the Essential Introduction). Before entry, IFAIL must be set to a value with the decimal expansion cba, where each of the decimal digits c, b and a must have a value of 0 or 1. a=0 specifies hard failure, otherwise soft failure; b=0 suppresses error messages, otherwise error messages will be printed (see Section 6); c=0 suppresses warning messages, otherwise warning messages will be printed (see Section 6). The recommended value for inexperienced users is 110 (i.e., hard failure with all messages printed). Unless the routine detects an error (see Section 6), IFAIL contains 0 on exit. 6. Error Indicators and Warnings Errors detected by the routine: For each error, an explanatory error message is output on the current error message unit (as defined by X04AAF), unless suppressed by the value of IFAIL on entry. IFAIL= 1 On entry N < 1, or NZ < N, or LIRN < NZ, or LICN<2*NZ. IFAIL= 2 One of the conditions 0 < IRN(k) <= ICN(k) <= N is not satisfied so that A(k) is not in the upper triangle of the matrix. No further computation is attempted. IFAIL= 3 One of the diagonal elements of the matrix A is zero or negative so that A is not positive-definite. No further computation is attempted. IFAIL= 4 The available space has been used and no further compressions are possible. The user should either increase DROPTL, or allocate more space to A, IRN and ICN. For all the remaining values of IFAIL the computations will continue in the case of soft failure, so that more than one advisory message may be printed. IFAIL= 5 Duplicate elements have been detected and ABORT(1) = .TRUE.. IFAIL= 6 A zero or negative pivot element has been detected during the factorization and ABORT(2) = .TRUE.. This should not happen if A is an M-matrix (see Munksgaard [1]), but may occur for other types of positive-definite matrix. IFAIL= 7 The available space has been used and ABORT(3) = .TRUE.. 7. Accuracy The accuracy of the factorization will be determined by the size of the elements that are dropped and the size of the modifications made to the diagonal elements. If these sizes are small then the computed factors will correspond to a matrix close to A and the number of iterations required by F04MAF will be small. The more incomplete the factorization, the higher the number of iterations required by F04MAF. 8. Further Comments The time taken by the routine will depend upon the sparsity pattern of the matrix and the number of fill-ins that occur during the factorization. At the very least the time taken can be expected to be roughly proportional to n(tau), where (tau) is the number of non-zeros. The routine is intended for use with positive-definite matrices, but the user is warned that it will not necessarily detect non- positive-definiteness. Indeed the routine may return a factorization that can satisfactorily be used by F04MAF even when A is not positive-definite, but this should not be relied upon as F04MAF may not converge. 9. Example The example program illustrates the use of F01MAF in conjunction with F04MAF to solve the 16 linear equations Ax=b, where (1 z z ) (z 1 z z ) ( z 1 z z ) ( z 1 0 z ) (z 0 1 z z ) ( z z 1 z z ) ( z z 1 z z ) ( z z 1 0 z ) A=( z 0 1 z z ). ( z z 1 z z ) ( z z 1 z z ) ( z z 1 0 z) ( z 0 1 z ) ( z z 1 z ) ( z z 1 z) ( z z 1) T ( 1 1 1 1 1 1 1 1 1 1 1 1) b =( - - - - - 0 0 - - 0 0 - - - - -), ( 2 4 4 2 4 4 4 4 2 4 4 2) 1 where z=- -. 4 The n by n matrix A arises in the solution of Laplace's equation in a unit square, using a 5-point formula with a 6 by 6 discretisation, with unity on the boundaries. The drop tolerance, DROPTL, is taken as 0.1, and the density factor, DENSW, is taken as 0.8. The value IFAIL = 111 is used so that advisory and error messages will be printed, but soft failure would occur if IFAIL were returned as non-zero. A relative accuracy of about 0.0001 is requested in the solution from F04MAF, with a maximum of 50 iterations. The example program for F02FJF illustrates the use of F01MAF and F04MAF in solving an eigenvalue problem. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01mcf}{NAG On-line Documentation: f01mcf} \beginscroll \begin{verbatim} F01MCF(3NAG) Foundation Library (12/10/92) F01MCF(3NAG) F01 -- Matrix Factorizations F01MCF F01MCF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01MCF computes the Cholesky factorization of a real symmetric positive-definite variable-bandwidth matrix. 2. Specification SUBROUTINE F01MCF (N, A, LAL, NROW, AL, D, IFAIL) INTEGER N, LAL, NROW(N), IFAIL DOUBLE PRECISION A(LAL), AL(LAL), D(N) 3. Description This routine determines the unit lower triangular matrix L and T the diagonal matrix D in the Cholesky factorization A=LDL of a symmetric positive-definite variable-bandwidth matrix A of order n. (Such a matrix is sometimes called a 'sky-line' matrix.) The matrix A is represented by the elements lying within the envelope of its lower triangular part, that is, between the first non-zero of each row and the diagonal (see Section 9 for an example). The width NROW(i) of the ith row is the number of elements between the first non-zero element and the element on the diagonal, inclusive. Although, of course, any matrix possesses an envelope as defined, this routine is primarily intended for the factorization of symmetric positive-definite matrices with an average bandwidth which is small compared with n (also see Section 8). The method is based on the property that during Cholesky factorization there is no fill-in outside the envelope. The determination of L and D is normally the first of two steps in the solution of the system of equations Ax=b. The remaining T step, viz. the solution of LDL x=b may be carried out using F04MCF. 4. References [1] Jennings A (1966) A Compact Storage Scheme for the Solution of Symmetric Linear Simultaneous Equations. Comput. J. 9 281--285. [2] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 1. 2: A(LAL) -- DOUBLE PRECISION array Input On entry: the elements within the envelope of the lower triangle of the positive-definite symmetric matrix A, taken in row by row order. The following code assigns the matrix elements within the envelope to the correct elements of the array: K = 0 DO 20 I = 1, N DO 10 J = I-NROW(I)+1, I K = K + 1 A(K) = matrix (I,J) 10 CONTINUE 20 CONTINUE See also Section 8. 3: LAL -- INTEGER Input On entry: the smaller of the dimensions of the arrays A and AL as declared in the calling (sub)program from which F01MCF is called. Constraint: LAL >= NROW(1) + NROW(2) +... + NROW( n). 4: NROW(N) -- INTEGER array Input On entry: NROW(i) must contain the width of row i of the matrix A, i.e., the number of elements between the first (leftmost) non-zero element and the element on the diagonal, inclusive. Constraint: 1 <= NROW(i) <= i, for i=1,2,...,n. 5: AL(LAL) -- DOUBLE PRECISION array Output On exit: the elements within the envelope of the lower triangular matrix L, taken in row by row order. The envelope of L is identical to that of the lower triangle of A. The unit diagonal elements of L are stored explicitly. See also Section 8. 6: D(N) -- DOUBLE PRECISION array Output On exit: the diagonal elements of the the diagonal matrix D . Note that the determinant of A is equal to the product of these diagonal elements. If the value of the determinant is required it should not be determined by forming the product explicitly, because of the possibility of overflow or underflow. The logarithm of the determinant may safely be formed from the sum of the logarithms of the diagonal elements. 7: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 On entry N < 1, or for some i, NROW(i) < 1 or NROW(i) > i, or LAL < NROW(1) + NROW(2) +... + NROW(N). IFAIL= 2 A is not positive-definite, or this property has been destroyed by rounding errors. The factorization has not been completed. IFAIL= 3 A is not positive-definite, or this property has been destroyed by rounding errors. The factorization has been completed but may be very inaccurate (see Section 7). 7. Accuracy If IFAIL = 0 on exit, then the computed L and D satisfy the T relation LDL =A+F, where 2 ||F|| <=km (epsilon)max a 2 i ii and 2 ||F|| <=km (epsilon)||A|| , 2 2 where k is a constant of order unity, m is the largest value of NROW(i), and (epsilon) is the machine precision. See Wilkinson and Reinsch [2], pp 25--27, 54--55. If IFAIL = 3 on exit, then the factorization has been completed although the matrix was not positive-definite. However the factorization may be very inaccurate and should be used only with great caution. For instance, if it is used to solve a set of equations Ax=b using F04MCF, the residual vector b-Ax should be checked. 8. Further Comments The time taken by the routine is approximately proportional to the sum of squares of the values of NROW(i). The distribution of row widths may be very non-uniform without undue loss of efficiency. Moreover, the routine has been designed to be as competitive as possible in speed with routines designed for full or uniformly banded matrices, when applied to such matrices. Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same actual array supplied for parameters A and AL, in which case L overwrites the lower triangle of A. However this is not standard Fortran 77 and may not work in all implementations. 9. Example To obtain the Cholesky factorization of the symmetric matrix, whose lower triangle is: (1 ) (2 5 ) (0 3 13 ) (0 0 0 16 ). (5 14 18 8 55 ) (0 0 0 24 17 77) For this matrix, the elements of NROW must be set to 1, 2, 2, 1, 5, 3, and the elements within the envelope must be supplied in row order as: 1, 2, 5, 3, 13, 16, 5, 14, 18, 8, 55, 24, 17, 77. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01qcf}{NAG On-line Documentation: f01qcf} \beginscroll \begin{verbatim} F01QCF(3NAG) Foundation Library (12/10/92) F01QCF(3NAG) F01 -- Matrix Factorizations F01QCF F01QCF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01QCF finds the QR factorization of the real m by n matrix A, where m>=n. 2. Specification SUBROUTINE F01QCF (M, N, A, LDA, ZETA, IFAIL) INTEGER M, N, LDA, IFAIL DOUBLE PRECISION A(LDA,*), ZETA(*) 3. Description The m by n matrix A is factorized as (R) A=Q(0) when m>n, A=QR when m=n, where Q is an m by m orthogonal matrix and R is an n by n upper triangular matrix. The factorization is obtained by Householder's method. The kth transformation matrix, Q , which is used to k introduce zeros into the kth column of A is given in the form (I 0 ) Q =(0 T ) k ( k) where T T =I-u u , k k k ((zeta) ) ( k) u =(z ), k ( k ) (zeta) is a scalar and z is an (m-k) element vector. (zeta) k k k and z are chosen to annihilate the elements below the triangular k part of A. The vector u is returned in the kth element of the array ZETA k and in the kth column of A, such that (zeta) is in ZETA(k) and k the elements of z are in A(k+1,k),...,A(m,k). The elements of R k are returned in the upper triangular part of A. Q is given by T Q=(Q Q ...Q ) . n n-1 1 Good background descriptions to the QR factorization are given in Dongarra et al [1] and Golub and Van Loan [2], but note that this routine is not based upon LINPACK routine DQRDC. 4. References [1] Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide. SIAM, Philadelphia. [2] Golub G H and Van Loan C F (1989) Matrix Computations (2nd Edition). Johns Hopkins University Press, Baltimore, Maryland. [3] Wilkinson J H (1965) The Algebraic Eigenvalue Problem. Oxford University Press. 5. Parameters 1: M -- INTEGER Input On entry: m, the number of rows of A. Constraint: M >= N. 2: N -- INTEGER Input On entry: n, the number of columns of A. When N = 0 then an immediate return is effected. Constraint: N >= 0. 3: A(LDA,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array A must be at least max(1,n). On entry: the leading m by n part of the array A must contain the matrix to be factorized. On exit: the n by n upper triangular part of A will contain the upper triangular matrix R and the m by n strictly lower triangular part of A will contain details of the factorization as described in Section 3. 4: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F01QCF is called. Constraint: LDA >= max(1,M). 5: ZETA(*) -- DOUBLE PRECISION array Output Note: the dimension of the array ZETA must be at least max (1,n) On exit: ZETA(k) contains the scalar (zeta) for the k k th transformation. If T =I then ZETA(k)=0.0, otherwise ZETA( k k) contains (zeta) as described in Section 3 and (zeta) is k k always in the range (1.0, \/2.0). 6: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 On entry M < N, or N < 0, or LDA < M. 7. Accuracy The computed factors Q and R satisfy the relation (R) Q(0)=A+E, where |||E|||<=c(epsilon)|||A|||, and (epsilon) is the machine precision (see X02AJF(*)), c is a modest function of m and n and |||.||| denotes the spectral (two) norm. 8. Further Comments The approximate number of floating-point operations is given by 2 2n (3m-n)/3. Following the use of this routine the operations T B:=QB and B:=Q B, where B is an m by k matrix, can be performed by calls to F01QDF. The operation B:=QB can be obtained by the call: IFAIL = 0 CALL F01QDF('No transpose', 'Separate', M, N, A, LDA, ZETA, * K, B, LDB, WORK, IFAIL) T and B:=Q B can be obtained by the call: IFAIL = 0 CALL F01QDF('Transpose', 'Separate', M, N, A, LDA, ZETA, * K, B, LDB, WORK, IFAIL) In both cases WORK must be a k element array that is used as workspace. If B is a one-dimensional array (single column) then the parameter LDB can be replaced by M. See F01QDF for further details. The first k columns of the orthogonal matrix Q can either be obtained by setting B to the first k columns of the unit matrix and using the first of the above two calls, or by calling F01QEF, which overwrites the k columns of Q on the first k columns of the array A. Q is obtained by the call: CALL F01QEF('Separate', M, N, K, A, LDA, ZETA, WORK, IFAIL) As above WORK must be a k element array. If k is larger than N, then A must have been declared to have at least k columns. Operations involving the matrix R can readily be performed by the Level 2 BLAS routines DTRSV and DTRMV (see Chapter F06), but note that no test for near singularity of R is incorporated in DTRSV. If R is singular, or nearly singular then F02WUF(*) can be used to determine the singular value decomposition of R. 9. Example To obtain the QR factorization of the 5 by 3 matrix (2.0 2.5 2.5) (2.0 2.5 2.5) A=(1.6 -0.4 2.8). (2.0 -0.5 0.5) (1.2 -0.3 -2.9) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01qdf}{NAG On-line Documentation: f01qdf} \beginscroll \begin{verbatim} F01QDF(3NAG) Foundation Library (12/10/92) F01QDF(3NAG) F01 -- Matrix Factorizations F01QDF F01QDF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01QDF performs one of the transformations T B:=QB or B:=Q B, where B is an m by ncolb real matrix and Q is an m by m orthogonal matrix, given as the product of Householder transformation matrices. This routine is intended for use following F01QCF or F01QFF(*). 2. Specification SUBROUTINE F01QDF (TRANS, WHERET, M, N, A, LDA, ZETA, 1 NCOLB, B, LDB, WORK, IFAIL) INTEGER M, N, LDA, NCOLB, LDB, IFAIL DOUBLE PRECISION A(LDA,*), ZETA(*), B(LDB,*), WORK(*) CHARACTER*1 TRANS, WHERET 3. Description Q is assumed to be given by T Q=(Q Q ...Q ) , n n-1 1 Q being given in the form k (I 0 ) Q =(0 T ) k ( k) where T T =I-u u , k k k ((zeta) ) ( k) u =(z ), k ( k ) (zeta) is a scalar and z is an (m-k) element vector. z must be k k k supplied in the kth column of A in elements A(k+1,k),...,A(m,k) and (zeta) must be supplied either in A(k,k) or in ZETA(k), k depending upon the parameter WHERET. To obtain Q explicitly B may be set to I and pre-multiplied by Q. T This is more efficient than obtaining Q . 4. References [1] Golub G H and Van Loan C F (1989) Matrix Computations (2nd Edition). Johns Hopkins University Press, Baltimore, Maryland. [2] Wilkinson J H (1965) The Algebraic Eigenvalue Problem. Oxford University Press. 5. Parameters 1: TRANS -- CHARACTER*1 Input On entry: the operation to be performed as follows: TRANS = 'N' (No transpose) Perform the operation B:=QB. TRANS = 'T' or 'C' (Transpose) T Perform the operation B:=Q B. Constraint: TRANS must be one of 'N', 'T' or 'C'. 2: WHERET -- CHARACTER*1 Input On entry: indicates where the elements of (zeta) are to be found as follows: WHERET = 'I' (In A) The elements of (zeta) are in A. WHERET = 'S' (Separate) The elements of (zeta) are separate from A, in ZETA. Constraint: WHERET must be one of 'I' or 'S'. 3: M -- INTEGER Input On entry: m, the number of rows of A. Constraint: M >= N. 4: N -- INTEGER Input On entry: n, the number of columns of A. When N = 0 then an immediate return is effected. Constraint: N >= 0. 5: A(LDA,*) -- DOUBLE PRECISION array Input Note: the second dimension of the array A must be at least max(1,N). On entry: the leading m by n strictly lower triangular part of the array A must contain details of the matrix Q. In addition, when WHERET = 'I', then the diagonal elements of A must contain the elements of (zeta) as described under the argument ZETA below. When WHERET = 'S', the diagonal elements of the array A are referenced, since they are used temporarily to store the (zeta) , but they contain their original values on return. k 6: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F01QDF is called. Constraint: LDA >= max(1,M). 7: ZETA(*) -- DOUBLE PRECISION array Input Note: when WHERET = 'S', the dimension of the array ZETA must be greater than or equal to max(1,N). On entry: if WHERET = 'S', the array ZETA must contain the elements of (zeta). If ZETA(k) = 0.0 then T is assumed to be I k otherwise ZETA(k) is assumed to contain (zeta) . k When WHERET = 'I', ZETA is not referenced. 8: NCOLB -- INTEGER Input On entry: ncolb, number of columns of B. When NCOLB = 0 then an immediate return is effected. Constraint: NCOLB >= 0. 9: B(LDB,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array B must be at least max(1,NCOLB). On entry: the leading m by ncolb part of the array B must contain the matrix to be transformed. On exit: B is overwritten by the transformed matrix. 10: LDB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F01QDF is called. Constraint: LDB >= max(1,M). 11: WORK(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WORK must be at least max(1,NCOLB). 12: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 On entry TRANS /= 'N', 'T' or 'C', or WHERET /= 'I' or 'S', or M < N, or N < 0, or LDA < M, or NCOLB < 0, or LDB < M. 7. Accuracy T Letting C denote the computed matrix Q B, C satisfies the relation QC=B+E, where ||E||<=c(epsilon)||B||, and (epsilon) the machine precision (see X02AJF(*)), c is a modest function of m and |||.||| denotes the spectral (two) norm. An equivalent result holds for the computed matrix QB. See also Section 7 of F01QCF. 8. Further Comments The approximate number of floating-point operations is given by 2n(2m-n)ncolb. 9. Example T To obtain the matrix Q B for the matrix B given by ( 1.1 0.00) ( 0.9 0.00) B=( 0.6 1.32) ( 0.0 1.10) (-0.8 -0.26) following the QR factorization of the 5 by 3 matrix A given by (2.0 2.5 2.5) (2.0 2.5 2.5) A=(1.6 -0.4 2.8). (2.0 -0.5 0.5) (1.2 -0.3 -2.9) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01qef}{NAG On-line Documentation: f01qef} \beginscroll \begin{verbatim} F01QEF(3NAG) Foundation Library (12/10/92) F01QEF(3NAG) F01 -- Matrix Factorizations F01QEF F01QEF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01QEF returns the first ncolq columns of the real m by m orthogonal matrix Q, where Q is given as the product of Householder transformation matrices. This routine is intended for use following F01QCF or F01QFF(*). 2. Specification SUBROUTINE F01QEF (WHERET, M, N, NCOLQ, A, LDA, ZETA, 1 WORK, IFAIL) INTEGER M, N, NCOLQ, LDA, IFAIL DOUBLE PRECISION A(LDA,*), ZETA(*), WORK(*) CHARACTER*1 WHERET 3. Description Q is assumed to be given by T Q=(Q Q ...Q ) , n n-1 1 Q being given in the form k (I 0 ) Q =(0 T ) k ( k) where T T =I-u u , k k k ((zeta) ) ( k) u =(z ), k ( k ) (zeta) is a scalar and z is an (m-k) element vector. z must be k k k supplied in the kth column of A in elements A(k+1,k),...,A(m,k) and (zeta) must be supplied either in A(k,k) or in ZETA(k), k depending upon the parameter WHERET. 4. References [1] Golub G H and Van Loan C F (1989) Matrix Computations (2nd Edition). Johns Hopkins University Press, Baltimore, Maryland. [2] Wilkinson J H (1965) The Algebraic Eigenvalue Problem. Oxford University Press. 5. Parameters 1: WHERET -- CHARACTER*1 Input On entry: indicates where the elements of (zeta) are to be found as follows: WHERET = 'I' (In A) The elements of (zeta) are in A. WHERET = 'S' (Separate) The elements of (zeta) are separate from A, in ZETA. Constraint: WHERET must be one of 'I' or 'S'. 2: M -- INTEGER Input On entry: m, the number of rows of A. Constraint: M >= N. 3: N -- INTEGER Input On entry: n, the number of columns of A. Constraint: N >= 0. 4: NCOLQ -- INTEGER Input On entry: ncolq, the required number of columns of Q. Constraint: 0 <= NCOLQ <= M. When NCOLQ = 0 then an immediate return is effected. 5: A(LDA,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array A must be at least max(1,N,NCOLQ). On entry: the leading m by n strictly lower triangular part of the array A must contain details of the matrix Q. In addition, when WHERET = 'I', then the diagonal elements of A must contain the elements of (zeta) as described under the argument ZETA below. On exit: the first NCOLQ columns of the array A are overwritten by the first NCOLQ columns of the m by m orthogonal matrix Q. When N = 0 then the first NCOLQ columns of A are overwritten by the first NCOLQ columns of the identity matrix. 6: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F01QEF is called. Constraint: LDA >= max(1,M). 7: ZETA(*) -- DOUBLE PRECISION array Input Note: the dimension of the array ZETA must be at least max(1,N). On entry: with WHERET = 'S', the array ZETA must contain the elements of (zeta). If ZETA(k) = 0.0 then T is assumed to k be I, otherwise ZETA(k) is assumed to contain (zeta) . k When WHERET = 'I', the array ZETA is not referenced. 8: WORK(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WORK must be at least max(1,NCOLQ). 9: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 On entry WHERET /= 'I' or 'S', or M < N, or N < 0, or NCOLQ < 0 or NCOLQ > M, or LDA < M. 7. Accuracy The computed matrix Q satisfies the relation Q=P+E, where P is an exactly orthogonal matrix and ||E||<=c(epsilon) (epsilon) is the machine precision (see X02AJF(*)), c is a modest function of m and |||.||| denotes the spectral (two) norm. See also Section 7 of F01QCF. 8. Further Comments The approximate number of floating-point operations required is given by 2 -n{(3m-n)(2ncolq-n)-n(ncolq-n)}, ncolq>n, 3 2 2 -ncolq (3m-ncolq), ncolq<=n. 3 9. Example To obtain the 5 by 5 orthogonal matrix Q following the QR factorization of the 5 by 3 matrix A given by (2.0 2.5 2.5) (2.0 2.5 2.5) A=(1.6 -0.4 2.8). (2.0 -0.5 0.5) (1.2 -0.3 -2.9) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01rcf}{NAG On-line Documentation: f01rcf} \beginscroll \begin{verbatim} F01RCF(3NAG) Foundation Library (12/10/92) F01RCF(3NAG) F01 -- Matrix Factorizations F01RCF F01RCF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01RCF finds the QR factorization of the complex m by n matrix A, where m>=n. 2. Specification SUBROUTINE F01RCF (M, N, A, LDA, THETA, IFAIL) INTEGER M, N, LDA, IFAIL COMPLEX(KIND(1.0D0)) A(LDA,*), THETA(*) 3. Description The m by n matrix A is factorized as (R) A=Q(0) when m>n, A=QR when m=n, where Q is an m by m unitary matrix and R is an n by n upper triangular matrix with real diagonal elements. The factorization is obtained by Householder's method. The kth transformation matrix, Q , which is used to introduce zeros into k the kth column of A is given in the form (I 0 ) Q =(0 T ), k ( k) where H T =I-(gamma) u u , k k k k ((zeta) ) ( k) u =(z ), k ( k ) (gamma) is a scalar for which Re (gamma) =1.0, (zeta) is a real k k k scalar and z is an (m-k) element vector. (gamma) , (zeta) and k k k z are chosen to annihilate the elements below the triangular k part of A and to make the diagonal elements real. The scalar (gamma) and the vector u are returned in the kth k k element of the array THETA and in the kth column of A, such that (theta) , given by k (theta) =((zeta) ,Im(gamma) ), k k k is in THETA(k) and the elements of z are in a ,...,a . The k k+1,k m,k elements of R are returned in the upper triangular part of A. Q is given by H Q=(Q Q ...Q ) . n n-1 1 A good background description to the QR factorization is given in Dongarra et al [1], but note that this routine is not based upon LINPACK routine ZQRDC. 4. References [1] Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide. SIAM, Philadelphia. [2] Wilkinson J H (1965) The Algebraic Eigenvalue Problem. Oxford University Press. 5. Parameters 1: M -- INTEGER Input On entry: m, the number of rows of A. Constraint: M >= N. 2: N -- INTEGER Input On entry: n, the number of columns of A. Constraint: N >= 0. When N = 0 then an immediate return is effected. 3: A(LDA,*) -- COMPLEX(KIND(1.0D0)) array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the leading m by n part of the array A must contain the matrix to be factorized. On exit: the n by n upper triangular part of A will contain the upper triangular matrix R, with the imaginary parts of the diagonal elements set to zero, and the m by n strictly lower triangular part of A will contain details of the factorization as described above. 4: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F01RCF is called. Constraint: LDA >= max(1,M). 5: THETA(*) -- COMPLEX(KIND(1.0D)) array Output Note: the dimension of the array THETA must be at least max(1,N). On exit: the scalar (theta) for the kth transformation. If k T =I then THETA(k) = 0.0; if k ((alpha) 0) T =( 0 I) Re(alpha)<0.0, k then THETA(k)=(alpha); otherwise THETA(k) contains THETA(k) as described in Section 3 and Re(THETA(k)) is always in the range (1.0, \/2.0). 6: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 On entry M < N, or N < 0, or LDA < M. 7. Accuracy The computed factors Q and R satisfy the relation (R) Q(0)=A+E, where ||E||<=c(epsilon)||A||, (epsilon) being the machine precision, c is a modest function of m and n and ||.|| denotes the spectral (two) norm. 8. Further Comments The approximate number of real floating-point operations is given 2 by 8n (3m-n)/3. Following the use of this routine the operations H B:=QB and B:=Q B, where B is an m by k matrix, can be performed by calls to F01RDF. The operation B:=QB can be obtained by the call: IFAIL = 0 CALL F01RDF(`No conjugate', 'Separate', M, N, A, LDA, THETA, * K, B, LDB, WORK, IFAIL) H and B:=Q B can be obtained by the call: IFAIL = 0 CALL F01RDF(`Conjugate', 'Separate', M, N, A, LDA, THETA, * K, B, LDB, WORK, IFAIL) In both cases WORK must be a k element array that is used as workspace. If B is a one-dimensional array (single column) then the parameter LDB can be replaced by M. See F01RDF for further details. The first k columns of the unitary matrix Q can either be obtained by setting B to the first k columns of the unit matrix and using the first of the above two calls, or by calling F01REF, which overwrites the k columns of Q on the first k columns of the array A. Q is obtained by the call: CALL F01REF(`Separate', M, N, K, A, LDA, THETA, WORK, IFAIL) As above, WORK must be a k element array. If k is larger than n, then A must have been declared to have at least k columns. Operations involving the matrix R can readily be performed by the Level 2 BLAS routines ZTRSV and ZTRMV (see Chapter F06), but note that no test for near singularity of R is incorporated in ZTRSV. If R is singular, or nearly singular, then F02XUF(*) can be used to determine the singular value decomposition of R. 9. Example To obtain the QR factorization of the 5 by 3 matrix ( 0.5i -0.5+1.5i -1.0+1.0i) (0.4+0.3i 0.9+1.3i 0.2+1.4i) A=( 0.4 -0.4+0.4i 1.8 ). (0.3-0.4i 0.1+0.7i 0.0 ) ( -0.3i 0.3+0.3i 2.4i ) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01rdf}{NAG On-line Documentation: f01rdf} \beginscroll \begin{verbatim} F01RDF(3NAG) Foundation Library (12/10/92) F01RDF(3NAG) F01 -- Matrix Factorizations F01RDF F01RDF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01RDF performs one of the transformations H B:=QB or B:=Q B, where B is an m by ncolb complex matrix and Q is an m by m unitary matrix, given as the product of Householder transformation matrices. This routine is intended for use following F01RCF or F01RFF(*). 2. Specification SUBROUTINE F01RDF (TRANS, WHERET, M, N, A, LDA, THETA, 1 NCOLB, B, LDB, WORK, IFAIL) INTEGER M, N, LDA, NCOLB, LDB, IFAIL COMPLEX(KIND(1.0D0)) A(LDA,*), THETA(*), B(LDB,*), WORK(*) CHARACTER*1 TRANS, WHERET 3. Description The unitary matrix Q is assumed to be given by H Q=(Q Q ...Q ) , n n-1 1 Q being given in the form k (I 0 ) Q =(0 T ), k ( k) where H T =I-(gamma) u u , k k k k ((zeta) ) ( k) u =(z ), k ( k ) (gamma) is a scalar for which Re (gamma) =1.0, (zeta) is a real k k k scalar and z is an (m-k) element vector. k z must be supplied in the kth column of A in elements k a ,...,a and (theta) , given by k+1,k m,k k (theta) =((zeta) ,Im (gamma) ), k k k must be supplied either in a or in THETA(k), depending upon k,k the parameter WHERET. To obtain Q explicitly B may be set to I and pre-multiplied by Q. H This is more efficient than obtaining Q . Alternatively, F01REF may be used to obtain Q overwritten on A. 4. References [1] Wilkinson J H (1965) The Algebraic Eigenvalue Problem. Oxford University Press. 5. Parameters 1: TRANS -- CHARACTER*1 Input On entry: the operation to be performed as follows: TRANS = 'N' (No transpose) Perform the operation B:=QB. TRANS = 'C' (Conjugate transpose) H Perform the operation B:=Q B. Constraint: TRANS must be one of 'N' or 'C'. 2: WHERET -- CHARACTER*1 Input On entry: the elements of (theta) are to be found as follows: WHERET = 'I' (In A) The elements of (theta) are in A. WHERET = 'S' (Separate) The elements of (theta) are separate from A, in THETA. Constraint: WHERET must be one of 'I' or 'S'. 3: M -- INTEGER Input On entry: m, the number of rows of A. Constraint: M >= N. 4: N -- INTEGER Input On entry: n, the number of columns of A. Constraint: N >= 0. When N = 0 then an immediate return is effected. 5: A(LDA,*) -- COMPLEX(KIND(1.0D)) array Input Note: the second dimension of the array A must be at least max(1,N). On entry: the leading m by n strictly lower triangular part of the array A must contain details of the matrix Q. In addition, when WHERET = 'I', then the diagonal elements of A must contain the elements of (theta) as described under the argument THETA below. When WHERET = 'S', then the diagonal elements of the array A are referenced, since they are used temporarily to store the (zeta) , but they contain their original values on return. k 6: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F01RDF is called. Constraint: LDA >= max(1,M). 7: THETA(*) -- COMPLEX(KIND(1.0D)) array Input Note: the dimension of the array THETA must be at least max(1,N). On entry: with WHERET = 'S', the array THETA must contain the elements of (theta). If THETA(k)=0.0 then T is assumed k to be I; if THETA(k)=(alpha), with Re(alpha)<0.0, then T is k assumed to be of the form ((alpha) 0) T =(0 I); k otherwise THETA(k) is assumed to contain (theta) given by k (theta) =((zeta) ,Im(gamma) ). k k k When WHERET = 'I', the array THETA is not referenced, and may be dimensioned of length 1. 8: NCOLB -- INTEGER Input On entry: ncolb, the number of columns of B. Constraint: NCOLB >= 0. When NCOLB = 0 then an immediate return is effected. 9: B(LDB,*) -- COMPLEX(KIND(1.0D)) array Input/Output Note: the second dimension of the array B must be at least max(1,NCOLB). On entry: the leading m by ncolb part of the array B must contain the matrix to be transformed. On exit: B is overwritten by the transformed matrix. 10: LDB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F01RDF is called. Constraint: LDB >= max(1,M). 11: WORK(*) -- COMPLEX(KIND(1.0D)) array Workspace Note: the dimension of the array WORK must be at least max(1,NCOLB). 12: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 On entry TRANS /= 'N' or 'C', or WHERET /= 'I' or 'S', or M < N, or N < 0, or LDA < M, or NCOLB < 0, or LDB < M. 7. Accuracy Letting C denote the computed matrix Q B, C satisfies the relation QC=B+E, where ||E||<=c(epsilon)||B||, (epsilon) being the machine precision, c is a modest function of m and |||.||| denotes the spectral (two) norm. An equivalent result holds for the computed matrix QB. See also Section 7 of F01RCF. 8. Further Comments The approximate number of real floating-point operations is given by 8n(2m-n)ncolb. 9. Example H To obtain the matrix Q B for the matrix B given by (-0.55+1.05i 0.45+1.05i) ( 0.49+0.93i 1.09+0.13i) B=( 0.56-0.16i 0.64+0.16i) ( 0.39+0.23i -0.39-0.23i) ( 1.13+0.83i -1.13+0.77i) following the QR factorization of the 5 by 3 matrix A given by ( 0.5i -0.5+1.5i -1.0+1.0i) (0.4+0.3i 0.9+1.3i 0.2+1.4i) A=( 0.4 -0.4+0.4i 1.8 ). (0.3-0.4i 0.1+0.7i 0.0 ) ( -0.3i 0.3+0.3i 2.4i) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf01ref}{NAG On-line Documentation: f01ref} \beginscroll \begin{verbatim} F01REF(3NAG) Foundation Library (12/10/92) F01REF(3NAG) F01 -- Matrix Factorizations F01REF F01REF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F01REF returns the first ncolq columns of the complex m by m unitary matrix Q, where Q is given as the product of Householder transformation matrices. This routine is intended for use following F01RCF. 2. Specification SUBROUTINE F01REF (WHERET, M, N, NCOLQ, A, LDA, THETA, 1 WORK, IFAIL) INTEGER M, N, NCOLQ, LDA, IFAIL COMPLEX(KIND(1.0D0)) A(LDA,*), THETA(*), WORK(*) CHARACTER*1 WHERET 3. Description The unitary matrix Q is assumed to be given by H Q=(Q Q ...Q ) , n n-1 1 Q being given in the form k (I 0 ) Q =(0 T ), k ( k) where H T =I-(gamma) u u , k k k k ((zeta) ) ( k) u =(z ), k ( k ) (gamma) is a scalar for which Re (gamma) =1.0, (zeta) is a real k k k scalar and z is an (m-k) element vector. k z must be supplied in the kth column of A in elements k a ,...,a and (theta) , given by k+1,k m,k k (theta) =((zeta) ,Im (gamma) ), k k k must be supplied either in a or in THETA(k) depending upon the k,k parameter WHERET. 4. References [1] Wilkinson J H (1965) The Algebraic Eigenvalue Problem. Oxford University Press. 5. Parameters 1: WHERET -- CHARACTER*1 Input On entry: the elements of (theta) are to be found as follows: WHERET = 'I' (In A) The elements of (theta) are in A. WHERET = 'S' (Separate) The elements of (theta) are separate from A, in THETA. Constraint: WHERET must be one of 'I' or 'S'. 2: M -- INTEGER Input On entry: m, the number of rows of A. Constraint: M >= N. 3: N -- INTEGER Input On entry: n, the number of columns of A. Constraint: N >= 0. 4: NCOLQ -- INTEGER Input On entry: ncolq, the required number of columns of Q. Constraint: 0 <= NCOLQ <= M. When NCOLQ = 0 then an immediate return is effected. 5: A(LDA,*) -- COMPLEX(KIND(1.0D)) array Input/Output Note: the second dimension of the array A must be at least max(1,N,NCOLQ). On entry: the leading m by n strictly lower triangular part of the array A must contain details of the matrix Q. In addition, when WHERET = 'I', then the diagonal elements of A must contain the elements of (theta) as described under the argument THETA below. On exit: the first NCOLQ columns of the array A are overwritten by the first NCOLQ columns of the m by m unitary matrix Q. When N = 0 then the first NCOLQ columns of A are overwritten by the first NCOLQ columns of the unit matrix. 6: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F01REF is called. Constraint: LDA >= max(1,M). 7: THETA(*) -- COMPLEX(KIND(1.0D)) array Input Note: the dimension of the array THETA must be at least max(1,N). On entry: if WHERET = 'S', the array THETA must contain the elements of (theta). If THETA(k)=0.0 then T is assumed to k be I; if THETA(k)=(alpha), with Re(alpha)<0.0, then T is k assumed to be of the form ((alpha) 0) T =( 0 I); k otherwise THETA(k) is assumed to contain (theta) given by k (theta) =((zeta) ,Im(gamma) ). k k k When WHERET = 'I', the array THETA is not referenced. 8: WORK(*) -- COMPLEX(KIND(1.0D)) array Workspace Note: the dimension of the array WORK must be at least max(1,NCOLQ). 9: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 On entry WHERET /= 'I' or 'S', or M < N, or N < 0, or NCOLQ < 0 or NCOLQ > M, or LDA < M. 7. Accuracy The computed matrix Q satisfies the relation Q=P+E, where P is an exactly unitary matrix and ||E||<=c(epsilon), (epsilon) being the machine precision, c is a modest function of m and |||.||| denotes the spectral (two) norm. See also Section 7 of F01RCF. 8. Further Comments The approximate number of real floating-point operations required is given by 8 -n{(3m-n)(2ncolq-n)-n(ncolq-n)}, ncolq>n 3 8 2 -ncolq (3m-ncolq), ncolq<=n 3 9. Example To obtain the 5 by 5 unitary matrix Q following the QR factorization of the 5 by 3 matrix A given by ( 0.5i -0.5+1.5i -1.0+1.4i) (0.4+0.3i 0.9+1.3i 0.2+1.4i) A=(0.4 -0.4+0.4i 1.8 ). (0.3-0.4i 0.1+0.7i 0.0 ) ( -0.3i 0.3+0.3i 2.4i) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02}{NAG On-line Documentation: f02} \beginscroll \begin{verbatim} F02(3NAG) Foundation Library (12/10/92) F02(3NAG) F02 -- Eigenvalues and Eigenvectors Introduction -- F02 Chapter F02 Eigenvalues and Eigenvectors 1. Scope of the Chapter This chapter is concerned with computing -- eigenvalues and eigenvectors of a matrix -- eigenvalues and eigenvectors of generalized matrix eigenvalue problems -- singular values and singular vectors of a matrix. 2. Background to the Problems 2.1. Eigenvalue Problems In the most usual form of eigenvalue problem we are given a square n by n matrix A and wish to compute (lambda) (an eigenvalue) and x/=0 (an eigenvector) which satisfy the equation Ax=(lambda)x Such problems are called 'standard' eigenvalue problems in contrast to 'generalized' eigenvalue problems where we wish to satisfy the equation Ax=(lambda)Bx B also being a square n by n matrix. Section 2.1.1 and Section 2.1.2 discuss, respectively, standard and generalized eigenvalue problems where the matrices involved are dense; Section 2.1.3 discusses both types of problem in the case where A and B are sparse (and symmetric). 2.1.1. Standard eigenvalue problems Some of the routines in this chapter find all the n eigenvalues, some find all the n eigensolutions (eigenvalues and corresponding eigenvectors), and some find a selected group of eigenvalues and/or eigenvectors. The matrix A may be: (i) general (real or complex) (ii) real symmetric, or (iii) complex Hermitian (so that if a =(alpha)+i(beta) then ij a =(alpha)-i(beta)). ji In all cases the computation starts with a similarity -1 transformation S AS=T, where S is non-singular and is the product of fairly simple matrices, and T has an 'easier form' than A so that its eigensolutions are easily determined. The matrices A and T, of course, have the same eigenvalues, and if y is an eigenvector of T then Sy is the corresponding eigenvector of A. In case (i) (general real or complex A), the selected form of T is an upper Hessenberg matrix (t =0 if i-j>1) and S is the ij product of n-2 stabilised elementary transformation matrices. There is no easy method of computing selected eigenvalues of a Hessenberg matrix, so that all eigenvalues are always calculated. In the real case this computation is performed via the Francis QR algorithm with double shifts, and in the complex case by means of the LR algorithm. If the eigenvectors are required they are computed by back-substitution following the QR and LR algorithm. In case (ii) (real and symmetric A) the selected simple form of T is a tridiagonal matrix (t =0 if |i-j|>1), and S is the product ij of n-2 orthogonal Householder transformation matrices. If only selected eigenvalues are required, they are obtained by the method of bisection using the Sturm sequence property, and the corresponding eigenvectors of T are computed by inverse iteration. If all eigenvalues are required, they are computed from T via the QL algorithm (an adaptation of the QR algorithm), and the corresponding eigenvectors of T are the product of the transformations for the QL reduction. In all cases the corresponding eigenvectors of A are recovered from the computation of x=Sy. In case (iii) (complex Hermitian A) analogous transformations as in case (ii) are used. T has complex elements in off-diagonal positions, but a simple diagonal similarity transformation is then used to produce a real tridiagonal form, after which the QL algorithm and succeeding methods described in the previous paragraph are used to complete the solution. 2.1.2. Generalized eigenvalue problems Here we distinguish as a special case those problems in which both A and B are symmetric and B is positive-definite and well- conditioned with respect to inversion (i.e., all the eigenvalues of B are significantly greater than zero). Such problems can be satisfactorily treated by first reducing them to case (ii) of Section 2.1.1 and then using the methods described there to T compute the eigensolutions. If B is factorized as LL (L lower triangular), then Ax=(lambda)Bx is equivalent to the standard -1 T -1 T symmetric problem Ry=(lambda)y, where R=L A(L ) and y=L x. After finding an eigenvector y of R, the required x is computed T by back-substitution in y=L x. For generalized problems of the form Ax=(lambda)Bx which do not fall into the special case, the QZ algorithm is provided. In order to appreciate the domain in which this algorithm is appropriate we remark first that when B is non-singular the problem Ax=(lambda)Bx is fully equivalent to the problem -1 (B A)x=(lambda)x; both the eigenvalues and eigenvectors being the same. When A is non-singular Ax=(lambda)Bx is equivalent to -1 the problem (A B)x=(mu)x; the eigenvalues (mu) being the reciprocals of the required eigenvalues and the eigenvectors remaining the same. In theory then, provided at least one of the matrices A and B is non-singular, the generalized problem Ax=(lambda)Bx could be solved via the standard problem Cx=(lambda)x with an appropriate matrix C, and as far as economy of effort is concerned this is quite satisfactory. However, in practice, for this reduction to be satisfactory from the standpoint of numerical stability, one requires more than the -1 mere non-singularity of A or B. It is necessary that B A (or -1 A B) should not only exist but that B (or A) should be well- conditioned with respect to inversion. The nearer B (or A) is to -1 -1 singularity the more unsatisfactory B A (or A B) will be as a vehicle for determining the required eigenvalues. Unfortunately -1 one cannot counter ill-conditioning in B (or A) by computing B A -1 (or A B) accurately to single precision using iterative refinement. Well-determined eigenvalues of the original Ax=(lambda)Bx may be poorly determined even by the correctly -1 -1 rounded version of B A (or A B). The situation may in some instances be saved by the observation that if Ax=(lambda)Bx then (A-kB)x=((lambda)-k)Bx. Hence if A-kB is non-singular we may -1 solve the standard problem [(A-kB) B]x=(mu)x and for numerical stability we require only that (A-kB) be well-conditioned with respect to inversion. In practice one may well be in a situation where no k is known for which (A-kB) is well-conditioned with respect to inversion and indeed (A-kB) may be singular for all k. The QZ algorithm is designed to deal directly with the problem Ax=(lambda)Bx itself and its performance is unaffected by singularity or near- singularity of A, B or A-kB. 2.1.3. Sparse symmetric problems If the matrices A and B are large and sparse (i.e., only a small proportion of the elements are non-zero), then the methods described in the previous Section are unsuitable, because in reducing the problem to a simpler form, much of the sparsity of the problem would be lost; hence the computing time and the storage required would be very large. Instead, for symmetric problems, the method of simultaneous iteration may be used to determine selected eigenvalues and the corresponding eigenvectors. The routine provided has been designed to handle both symmetric and generalized symmetric problems. 2.2. Singular Value Problems The singular value decomposition of an m by n real matrix A is given by T A=QDP , where Q is an m by m orthogonal matrix, P is an n by n orthogonal matrix and D is an m by n diagonal matrix with non-negative diagonal elements. The first k==min(m,n) columns of Q and P are the left- and right-hand singular vectors of A and the k diagonal elements of D are the singular values. When A is complex then the singular value decomposition is given by H A=QDP , H T where Q and P are unitary, P denotes the complex conjugate of P and D is as above for the real case. If the matrix A has column means of zero, then AP is the matrix of principal components of A and the singular values are the square roots of the sample variances of the observations with respect to the principal components. (See also Chapter G03.) Routines are provided to return the singular values and vectors of a general real or complex matrix. 3. Recommendations on Choice and Use of Routines 3.1. General Discussion There is one routine, F02FJF, which is designed for sparse symmetric eigenvalue problems, either standard or generalized. The remainder of the routines are designed for dense matrices. 3.2. Eigenvalue and Eigenvector Routines These reduce the matrix A to a simpler form by a similarity -1 transformation S AS=T where T is an upper Hessenberg or tridiagonal matrix, compute the eigensolutions of T, and then recover the eigenvectors of A via the matrix S. The eigenvectors are normalised so that n -- 2 > |x | =1 -- r r=1 x being the rth component of the eigenvector x, and so that the r element of largest modulus is real if x is complex. For problems of the type Ax=(lambda)Bx with A and B symmetric and B positive- T definite, the eigenvectors are normalised so that x Bx=1, x always being real for such problems. 3.3. Singular Value and Singular Vector Routines These reduce the matrix A to real bidiagonal form, B say, by T orthogonal transformations Q AP=B in the real case, and by H unitary transformations Q AP=B in the complex case, and the singular values and vectors are computed via this bidiagonal form. The singular values are returned in descending order. 3.4. Decision Trees (i) Eigenvalues and Eigenvectors Please see figure in printed Reference Manual (ii) Singular Values and Singular Vectors Please see figure in printed Reference Manual F02 -- Eigenvalues and Eigenvectors Contents -- F02 Chapter F02 Eigenvalues and Eigenvectors F02AAF All eigenvalues of real symmetric matrix F02ABF All eigenvalues and eigenvectors of real symmetric matrix F02ADF All eigenvalues of generalized real symmetric-definite eigenproblem F02AEF All eigenvalues and eigenvectors of generalized real symmetric-definite eigenproblem F02AFF All eigenvalues of real matrix F02AGF All eigenvalues and eigenvectors of real matrix F02AJF All eigenvalues of complex matrix F02AKF All eigenvalues and eigenvectors of complex matrix F02AWF All eigenvalues of complex Hermitian matrix F02AXF All eigenvalues and eigenvectors of complex Hermitian matrix F02BBF Selected eigenvalues and eigenvectors of real symmetric matrix F02BJF All eigenvalues and optionally eigenvectors of generalized eigenproblem by QZ algorithm, real matrices F02FJF Selected eigenvalues and eigenvectors of sparse symmetric eigenproblem F02WEF SVD of real matrix F02XEF SVD of complex matrix \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02aaf}{NAG On-line Documentation: f02aaf} \beginscroll \begin{verbatim} F02AAF(3NAG) Foundation Library (12/10/92) F02AAF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AAF F02AAF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AAF calculates all the eigenvalues of a real symmetric matrix. 2. Specification SUBROUTINE F02AAF (A, IA, N, R, E, IFAIL) INTEGER IA, N, IFAIL DOUBLE PRECISION A(IA,N), R(N), E(N) 3. Description This routine reduces the real symmetric matrix A to a real symmetric tridiagonal matrix using Householder's method. The eigenvalues of the tridiagonal matrix are then determined using the QL algorithm. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,N) -- DOUBLE PRECISION array Input/Output On entry: the lower triangle of the n by n symmetric matrix A. The elements of the array above the diagonal need not be set. On exit: the elements of A below the diagonal are overwritten, and the rest of the array is unchanged. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02AAF is called. Constraint: IA >= N. 3: N -- INTEGER Input On entry: n, the order of the matrix A. 4: R(N) -- DOUBLE PRECISION array Output On exit: the eigenvalues in ascending order. 5: E(N) -- DOUBLE PRECISION array Workspace 6: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 Failure in F02AVF(*) indicating that more than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy The accuracy of the eigenvalues depends on the sensitivity of the matrix to rounding errors produced in tridiagonalisation. For a detailed error analysis see Wilkinson and Reinsch [1] pp 222 and 235. 8. Further Comments 3 The time taken by the routine is approximately proportional to n 9. Example To calculate all the eigenvalues of the real symmetric matrix: ( 0.5 0.0 2.3 -2.6) ( 0.0 0.5 -1.4 -0.7) ( 2.3 -1.4 0.5 0.0). (-2.6 -0.7 0.0 0.5) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02abf}{NAG On-line Documentation: f02abf} \beginscroll \begin{verbatim} F02ABF(3NAG) Foundation Library (12/10/92) F02ABF(3NAG) F02 -- Eigenvalue and Eigenvectors F02ABF F02ABF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02ABF calculates all the eigenvalues and eigenvectors of a real symmetric matrix. 2. Specification SUBROUTINE F02ABF (A, IA, N, R, V, IV, E, IFAIL) INTEGER IA, N, IV, IFAIL DOUBLE PRECISION A(IA,N), R(N), V(IV,N), E(N) 3. Description This routine reduces the real symmetric matrix A to a real symmetric tridiagonal matrix by Householder's method. The eigenvalues and eigenvectors are calculated using the QL algorithm. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,N) -- DOUBLE PRECISION array Input On entry: the lower triangle of the n by n symmetric matrix A. The elements of the array above the diagonal need not be set. See also Section 8. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02ABF is called. Constraint: IA >= N. 3: N -- INTEGER Input On entry: n, the order of the matrix A. 4: R(N) -- DOUBLE PRECISION array Output On exit: the eigenvalues in ascending order. 5: V(IV,N) -- DOUBLE PRECISION array Output On exit: the normalised eigenvectors, stored by columns; the ith column corresponds to the ith eigenvalue. The eigenvectors are normalised so that the sum of squares of the elements is equal to 1. 6: IV -- INTEGER Input On entry: the first dimension of the array V as declared in the (sub)program from which F02ABF is called. Constraint: IV >= N. 7: E(N) -- DOUBLE PRECISION array Workspace 8: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 Failure in F02AMF(*) indicating that more than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy The eigenvectors are always accurately orthogonal but the accuracy of the individual eigenvectors is dependent on their inherent sensitivity to changes in the original matrix. For a detailed error analysis see Wilkinson and Reinsch [1] pp 222 and 235. 8. Further Comments 3 The time taken by the routine is approximately proportional to n Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same actual array supplied for parameters A and V, in which case the eigenvectors will overwrite the original matrix. However this is not standard Fortran 77, and may not work on all systems. 9. Example To calculate all the eigenvalues and eigenvectors of the real symmetric matrix: ( 0.5 0.0 2.3 -2.6) ( 0.0 0.5 -1.4 -0.7) ( 2.3 -1.4 0.5 0.0). (-2.6 -0.7 0.0 0.5) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02adf}{NAG On-line Documentation: f02adf} \beginscroll \begin{verbatim} F02ADF(3NAG) Foundation Library (12/10/92) F02ADF(3NAG) F02 -- Eigenvalue and Eigenvectors F02ADF F02ADF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02ADF calculates all the eigenvalues of Ax=(lambda)Bx, where A is a real symmetric matrix and B is a real symmetric positive- definite matrix. 2. Specification SUBROUTINE F02ADF (A, IA, B, IB, N, R, DE, IFAIL) INTEGER IA, IB, N, IFAIL DOUBLE PRECISION A(IA,N), B(IB,N), R(N), DE(N) 3. Description The problem is reduced to the standard symmetric eigenproblem using Cholesky's method to decompose B into triangular matrices, T B=LL , where L is lower triangular. Then Ax=(lambda)Bx implies -1 -T T T (L AL )(L x)=(lambda)(L x); hence the eigenvalues of Ax=(lambda)Bx are those of Py=(lambda)y where P is the symmetric -1 -T matrix L AL . Householder's method is used to tridiagonalise the matrix P and the eigenvalues are then found using the QL algorithm. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,N) -- DOUBLE PRECISION array Input/Output On entry: the upper triangle of the n by n symmetric matrix A. The elements of the array below the diagonal need not be set. On exit: the lower triangle of the array is overwritten. The rest of the array is unchanged. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02ADF is called. Constraint: IA >= N. 3: B(IB,N) -- DOUBLE PRECISION array Input/Output On entry: the upper triangle of the n by n symmetric positive-definite matrix B. The elements of the array below the diagonal need not be set. On exit: the elements below the diagonal are overwritten. The rest of the array is unchanged. 4: IB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F02ADF is called. Constraint: IB >= N. 5: N -- INTEGER Input On entry: n, the order of the matrices A and B. 6: R(N) -- DOUBLE PRECISION array Output On exit: the eigenvalues in ascending order. 7: DE(N) -- DOUBLE PRECISION array Workspace 8: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 Failure in F01AEF(*); the matrix B is not positive-definite possibly due to rounding errors. IFAIL= 2 Failure in F02AVF(*), more than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy In general this routine is very accurate. However, if B is ill- conditioned with respect to inversion, the eigenvalues could be inaccurately determined. For a detailed error analysis see Wilkinson and Reinsch [1] pp 310, 222 and 235. 8. Further Comments 3 The time taken by the routine is approximately proportional to n 9. Example To calculate all the eigenvalues of the general symmetric eigenproblem Ax=(lambda) Bx where A is the symmetric matrix: (0.5 1.5 6.6 4.8) (1.5 6.5 16.2 8.6) (6.6 16.2 37.6 9.8) (4.8 8.6 9.8 -17.1) and B is the symmetric positive-definite matrix: (1 3 4 1) (3 13 16 11) (4 16 24 18). (1 11 18 27) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02aef}{NAG On-line Documentation: f02aef} \beginscroll \begin{verbatim} F02AEF(3NAG) Foundation Library (12/10/92) F02AEF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AEF F02AEF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AEF calculates all the eigenvalues and eigenvectors of Ax=(lambda)Bx, where A is a real symmetric matrix and B is a real symmetric positive-definite matrix. 2. Specification SUBROUTINE F02AEF (A, IA, B, IB, N, R, V, IV, DL, E, IFAIL) INTEGER IA, IB, N, IV, IFAIL DOUBLE PRECISION A(IA,N), B(IB,N), R(N), V(IV,N), DL(N), E 1 (N) 3. Description The problem is reduced to the standard symmetric eigenproblem using Cholesky's method to decompose B into triangular matrices T B=LL , where L is lower triangular. Then Ax=(lambda)Bx implies -1 -T T T (L AL )(L x)=(lambda)(L x); hence the eigenvalues of Ax=(lambda)Bx are those of Py=(lambda)y, where P is the symmetric -1 -T matrix L AL . Householder's method is used to tridiagonalise the matrix P and the eigenvalues are found using the QL algorithm. An eigenvector z of the derived problem is related to T an eigenvector x of the original problem by z=L x. The eigenvectors z are determined using the QL algorithm and are T normalised so that z z=1; the eigenvectors of the original T problem are then determined by solving L x=z, and are normalised T so that x Bx=1. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,N) -- DOUBLE PRECISION array Input/Output On entry: the upper triangle of the n by n symmetric matrix A. The elements of the array below the diagonal need not be set. On exit: the lower triangle of the array is overwritten. The rest of the array is unchanged. See also Section 8. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02AEF is called. Constraint: IA >= N. 3: B(IB,N) -- DOUBLE PRECISION array Input/Output On entry: the upper triangle of the n by n symmetric positive-definite matrix B. The elements of the array below the diagonal need not be set. On exit: the elements below the diagonal are overwritten. The rest of the array is unchanged. 4: IB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F02AEF is called. Constraint: IB >= N. 5: N -- INTEGER Input On entry: n, the order of the matrices A and B. 6: R(N) -- DOUBLE PRECISION array Output On exit: the eigenvalues in ascending order. 7: V(IV,N) -- DOUBLE PRECISION array Output On exit: the normalised eigenvectors, stored by columns; the ith column corresponds to the ith eigenvalue. The T eigenvectors x are normalised so that x Bx=1. See also Section 8. 8: IV -- INTEGER Input On entry: the first dimension of the array V as declared in the (sub)program from which F02AEF is called. Constraint: IV >= N. 9: DL(N) -- DOUBLE PRECISION array Workspace 10: E(N) -- DOUBLE PRECISION array Workspace 11: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 Failure in F01AEF(*); the matrix B is not positive-definite, possibly due to rounding errors. IFAIL= 2 Failure in F02AMF(*); more than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy In general this routine is very accurate. However, if B is ill- conditioned with respect to inversion, the eigenvectors could be inaccurately determined. For a detailed error analysis see Wilkinson and Reinsch [1] pp 310, 222 and 235. 8. Further Comments 3 The time taken by the routine is approximately proportional to n Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same actual array supplied for parameters A and V, in which case the eigenvectors will overwrite the original matrix A. However this is not standard Fortran 77, and may not work on all systems. 9. Example To calculate all the eigenvalues and eigenvectors of the general symmetric eigenproblem Ax=(lambda) Bx where A is the symmetric matrix: (0.5 1.5 6.6 4.8) (1.5 6.5 16.2 8.6) (6.6 16.2 37.6 9.8) (4.8 8.6 9.8 -17.1) and B is the symmetric positive-definite matrix: (1 3 4 1) (3 13 16 11) (4 16 24 18). (1 11 18 27) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02aff}{NAG On-line Documentation: f02aff} \beginscroll \begin{verbatim} F02AFF(3NAG) Foundation Library (12/10/92) F02AFF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AFF F02AFF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AFF calculates all the eigenvalues of a real unsymmetric matrix. 2. Specification SUBROUTINE F02AFF (A, IA, N, RR, RI, INTGER, IFAIL) INTEGER IA, N, INTGER(N), IFAIL DOUBLE PRECISION A(IA,N), RR(N), RI(N) 3. Description The matrix A is first balanced and then reduced to upper Hessenberg form using stabilised elementary similarity transformations. The eigenvalues are then found using the QR algorithm for real Hessenberg matrices. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,N) -- DOUBLE PRECISION array Input/Output On entry: the n by n matrix A. On exit: the array is overwritten. 2: IA -- INTEGER Input On entry: the dimension of the array A as declared in the (sub)program from which F02AFF is called. Constraint: IA >= N. 3: N -- INTEGER Input On entry: n, the order of the matrix A. 4: RR(N) -- DOUBLE PRECISION array Output On exit: the real parts of the eigenvalues. 5: RI(N) -- DOUBLE PRECISION array Output On exit: the imaginary parts of the eigenvalues. 6: INTGER(N) -- INTEGER array Output On exit: INTGER(i) contains the number of iterations used to find the ith eigenvalue. If INTGER(i) is negative, the i th eigenvalue is the second of a pair found simultaneously. Note that the eigenvalues are found in reverse order, starting with the nth. 7: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 More than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy The accuracy of the results depends on the original matrix and the multiplicity of the roots. For a detailed error analysis see Wilkinson and Reinsch [1] pp 352 and 367. 8. Further Comments 3 The time taken by the routine is approximately proportional to n 9. Example To calculate all the eigenvalues of the real matrix: ( 1.5 0.1 4.5 -1.5) (-22.5 3.5 12.5 -2.5) ( -2.5 0.3 4.5 -2.5). ( -2.5 0.1 4.5 2.5) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02agf}{NAG On-line Documentation: f02agf} \beginscroll \begin{verbatim} F02AGF(3NAG) Foundation Library (12/10/92) F02AGF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AGF F02AGF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AGF calculates all the eigenvalues and eigenvectors of a real unsymmetric matrix. 2. Specification SUBROUTINE F02AGF (A, IA, N, RR, RI, VR, IVR, VI, IVI, 1 INTGER, IFAIL) INTEGER IA, N, IVR, IVI, INTGER(N), IFAIL DOUBLE PRECISION A(IA,N), RR(N), RI(N), VR(IVR,N), VI 1 (IVI,N) 3. Description The matrix A is first balanced and then reduced to upper Hessenberg form using real stabilised elementary similarity transformations. The eigenvalues and eigenvectors of the Hessenberg matrix are calculated using the QR algorithm. The eigenvectors of the Hessenberg matrix are back-transformed to give the eigenvectors of the original matrix A. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,N) -- DOUBLE PRECISION array Input/Output On entry: the n by n matrix A. On exit: the array is overwritten. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02AGF is called. Constraint: IA >= N. 3: N -- INTEGER Input On entry: n, the order of the matrix A. 4: RR(N) -- DOUBLE PRECISION array Output On exit: the real parts of the eigenvalues. 5: RI(N) -- DOUBLE PRECISION array Output On exit: the imaginary parts of the eigenvalues. 6: VR(IVR,N) -- DOUBLE PRECISION array Output On exit: the real parts of the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvalue. The eigenvectors are normalised so that the sum of the squares of the moduli of the elements is equal to 1 and the element of largest modulus is real. This ensures that real eigenvalues have real eigenvectors. 7: IVR -- INTEGER Input On entry: the first dimension of the array VR as declared in the (sub)program from which F02AGF is called. Constraint: IVR >= N. 8: VI(IVI,N) -- DOUBLE PRECISION array Output On exit: the imaginary parts of the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvalue. 9: IVI -- INTEGER Input On entry: the first dimension of the array VI as declared in the (sub)program from which F02AGF is called. Constraint: IVI >= N. 10: INTGER(N) -- INTEGER array Output On exit: INTGER(i) contains the number of iterations used to find the ith eigenvalue. If INTGER(i) is negative, the i th eigenvalue is the second of a pair found simultaneously. Note that the eigenvalues are found in reverse order, starting with the nth. 11: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 More than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy The accuracy of the results depends on the original matrix and the multiplicity of the roots. For a detailed error analysis see Wilkinson and Reinsch [1] pp 352 and 390. 8. Further Comments 3 The time taken by the routine is approximately proportional to n 9. Example To calculate all the eigenvalues and eigenvectors of the real matrix: ( 1.5 0.1 4.5 -1.5) (-22.5 3.5 12.5 -2.5) ( -2.5 0.3 4.5 -2.5). ( -2.5 0.1 4.5 2.5) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02ajf}{NAG On-line Documentation: f02ajf} \beginscroll \begin{verbatim} F02AJF(3NAG) Foundation Library (12/10/92) F02AJF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AJF F02AJF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AJF calculates all the eigenvalues of a complex matrix. 2. Specification SUBROUTINE F02AJF (AR, IAR, AI, IAI, N, RR, RI, INTGER, 1 IFAIL) INTEGER IAR, IAI, N, INTGER(N), IFAIL DOUBLE PRECISION AR(IAR,N), AI(IAI,N), RR(N), RI(N) 3. Description The complex matrix A is first balanced and then reduced to upper Hessenberg form using stabilised elementary similarity transformations. The eigenvalues are then found using the modified LR algorithm for complex Hessenberg matrices. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: AR(IAR,N) -- DOUBLE PRECISION array Input/Output On entry: the real parts of the elements of the n by n complex matrix A. On exit: the array is overwritten. 2: IAR -- INTEGER Input On entry: the first dimension of the array AR as declared in the (sub)program from which F02AJF is called. Constraint: IAR >= N. 3: AI(IAI,N) -- DOUBLE PRECISION array Input/Output On entry: the imaginary parts of the elements of the n by n complex matrix A. On exit: the array is overwritten. 4: IAI -- INTEGER Input On entry: the first dimension of the array AI as declared in the (sub)program from which F02AJF is called. Constraint: IAI >= N. 5: N -- INTEGER Input On entry: n, the order of the matrix A. 6: RR(N) -- DOUBLE PRECISION array Output On exit: the real parts of the eigenvalues. 7: RI(N) -- DOUBLE PRECISION array Output On exit: the imaginary parts of the eigenvalues. 8: INTGER(N) -- INTEGER array Workspace 9: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 More than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy The accuracy of the results depends on the original matrix and the multiplicity of the roots. For a detailed error analysis see Wilkinson and Reinsch [1] pp 352 and 401. 8. Further Comments 3 The time taken by the routine is approximately proportional to n 9. Example To calculate all the eigenvalues of the complex matrix: (-21.0-5.0i 24.60i 13.6+10.2i 4.0i) ( 22.5i 26.00-5.00i 7.5-10.0i 2.5 ) ( -2.0+1.5i 1.68+2.24i 4.5-5.0i 1.5+2.0i). ( -2.5i -2.60 -2.7+3.6i 2.5-5.0i) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02akf}{NAG On-line Documentation: f02akf} \beginscroll \begin{verbatim} F02AKF(3NAG) Foundation Library (12/10/92) F02AKF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AKF F02AKF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AKF calculates all the eigenvalues and eigenvectors of a complex matrix. 2. Specification SUBROUTINE F02AKF (AR, IAR, AI, IAI, N, RR, RI, VR, IVR, 1 VI, IVI, INTGER, IFAIL) INTEGER IAR, IAI, N, IVR, IVI, INTGER(N), IFAIL DOUBLE PRECISION AR(IAR,N), AI(IAI,N), RR(N), RI(N), VR 1 (IVR,N), VI(IVI,N) 3. Description The complex matrix A is first balanced and then reduced to upper Hessenberg form by stabilised elementary similarity transformations. The eigenvalues and eigenvectors of the Hessenberg matrix are calculated using the LR algorithm. The eigenvectors of the Hessenberg matrix are back-transformed to give the eigenvectors of the original matrix. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: AR(IAR,N) -- DOUBLE PRECISION array Input/Output On entry: the real parts of the elements of the n by n complex matrix A. On exit: the array is overwritten. 2: IAR -- INTEGER Input On entry: the first dimension of the array AR as declared in the (sub)program from which F02AKF is called. Constraint: IAR >= N. 3: AI(IAI,N) -- DOUBLE PRECISION array Input/Output On entry: the imaginary parts of the elements of the n by n complex matrix A. On exit: the array is overwritten. 4: IAI -- INTEGER Input On entry: the first dimension of the array AI as declared in the (sub)program from which F02AKF is called. Constraint: IAI >= N. 5: N -- INTEGER Input On entry: n, the order of the matrix A. 6: RR(N) -- DOUBLE PRECISION array Output On exit: the real parts of the eigenvalues. 7: RI(N) -- DOUBLE PRECISION array Output On exit: the imaginary parts of the eigenvalues. 8: VR(IVR,N) -- DOUBLE PRECISION array Output On exit: the real parts of the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvalue. The eigenvectors are normalised so that the sum of squares of the moduli of the elements is equal to 1 and the element of largest modulus is real. 9: IVR -- INTEGER Input On entry: the first dimension of the array VR as declared in the (sub)program from which F02AKF is called. Constraint: IVR >= N. 10: VI(IVI,N) -- DOUBLE PRECISION array Output On exit: the imaginary parts of the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvalue. 11: IVI -- INTEGER Input On entry: the first dimension of the array VI as declared in the (sub)program from which F02AKF is called. Constraint: IVI >= N. 12: INTGER(N) -- INTEGER array Workspace 13: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 More than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy The accuracy of the results depends on the conditioning of the original matrix and the multiplicity of the roots. For a detailed error analysis see Wilkinson and Reinsch [1] pp 352 and 390. 8. Further Comments 3 The time taken by the routine is approximately proportional to n 9. Example To calculate all the eigenvalues and eigenvectors of the complex matrix: (-21.0-5.0i 24.60i 13.6+10.2i 4.0i) ( 22.5i 26.00-5.00i 7.5-10.0i 2.5 ) ( -2.0+1.5i 1.68+2.24i 4.5-5.0i 1.5+2.0i). ( -2.5i -2.60 -2.7+3.6i 2.5-5.0i) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02awf}{NAG On-line Documentation: f02awf} \beginscroll \begin{verbatim} F02AWF(3NAG) Foundation Library (12/10/92) F02AWF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AWF F02AWF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AWF calculates all the eigenvalues of a complex Hermitian matrix. 2. Specification SUBROUTINE F02AWF (AR, IAR, AI, IAI, N, R, WK1, WK2, WK3, 1 IFAIL) INTEGER IAR, IAI, N, IFAIL DOUBLE PRECISION AR(IAR,N), AI(IAI,N), R(N), WK1(N), 1 WK2(N), WK3(N) 3. Description The complex Hermitian matrix A is first reduced to a real tridiagonal matrix by n-2 unitary transformations, and a subsequent diagonal transformation. The eigenvalues are then derived using the QL algorithm, an adaptation of the QR algorithm. 4. References [1] Peters G (1967) NPL Algorithms Library. Document No. F1/04/A. [2] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: AR(IAR,N) -- DOUBLE PRECISION array Input/Output On entry: the real parts of the elements of the lower triangle of the n by n complex Hermitian matrix A. Elements of the array above the diagonal need not be set. On exit: the array is overwritten. 2: IAR -- INTEGER Input On entry: the first dimension of the array AR as declared in the (sub)program from which F02AWF is called. Constraint: IAR >= N. 3: AI(IAI,N) -- DOUBLE PRECISION array Input/Output On entry: the imaginary parts of the elements of the lower triangle of the n by n complex Hermitian matrix A. Elements of the array above the diagonal need not be set. On exit: the array is overwritten. 4: IAI -- INTEGER Input On entry: the first dimension of the array AI as declared in the (sub)program from which F02AWF is called. Constraint: IAI >= N. 5: N -- INTEGER Input On entry: n, the order of the complex Hermitian matrix, A. 6: R(N) -- DOUBLE PRECISION array Output On exit: the eigenvalues in ascending order. 7: WK1(N) -- DOUBLE PRECISION array Workspace 8: WK2(N) -- DOUBLE PRECISION array Workspace 9: WK3(N) -- DOUBLE PRECISION array Workspace 10: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 More than 30*N iterations are required to isolate all the eigenvalues. 7. Accuracy For a detailed error analysis see Peters [1] page 3 and Wilkinson and Reinsch [2] page 235. 8. Further Comments 3 The time taken by the routine is approximately proportional to n 9. Example To calculate all the eigenvalues of the complex Hermitian matrix: (0.50 0.00 1.84+1.38i 2.08-1.56i) (0.00 0.50 1.12+0.84i -0.56+0.42i) (1.84-1.38i 1.12-0.84i 0.50 0.00 ). (2.08+1.56i -0.56-0.42i 0.00 0.50 ) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02axf}{NAG On-line Documentation: f02axf} \beginscroll \begin{verbatim} F02AXF(3NAG) Foundation Library (12/10/92) F02AXF(3NAG) F02 -- Eigenvalue and Eigenvectors F02AXF F02AXF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02AXF calculates all the eigenvalues and eigenvectors of a complex Hermitian matrix. 2. Specification SUBROUTINE F02AXF (AR, IAR, AI, IAI, N, R, VR, IVR, VI, 1 IVI, WK1, WK2, WK3, IFAIL) INTEGER IAR, IAI, N, IVR, IVI, IFAIL DOUBLE PRECISION AR(IAR,N), AI(IAI,N), R(N), VR(IVR,N), VI 1 (IVI,N), WK1(N), WK2(N), WK3(N) 3. Description The complex Hermitian matrix is first reduced to a real tridiagonal matrix by n-2 unitary transformations and a subsequent diagonal transformation. The eigenvalues and eigenvectors are then derived using the QL algorithm, an adaptation of the QR algorithm. 4. References [1] Peters G (1967) NPL Algorithms Library. Document No. F2/03/A. [2] Peters G (1967) NPL Algorithms Library. Document No. F1/04/A. 5. Parameters 1: AR(IAR,N) -- DOUBLE PRECISION array Input On entry: the real parts of the elements of the lower triangle of the n by n complex Hermitian matrix A. Elements of the array above the diagonal need not be set. See also Section 8. 2: IAR -- INTEGER Input On entry: the first dimension of the array AR as declared in the (sub)program from which F02AXF is called. Constraint: IAR >= N. 3: AI(IAI,N) -- DOUBLE PRECISION array Input On entry: the imaginary parts of the elements of the lower triangle of the n by n complex Hermitian matrix A. Elements of the array above the diagonal need not be set. See also Section 8. 4: IAI -- INTEGER Input On entry: the first dimension of the array AI as declared in the (sub)program from which F02AXF is called. Constraint: IAI >= N. 5: N -- INTEGER Input On entry: n, the order of the matrix, A. 6: R(N) -- DOUBLE PRECISION array Output On exit: the eigenvalues in ascending order. 7: VR(IVR,N) -- DOUBLE PRECISION array Output On exit: the real parts of the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvector. The eigenvectors are normalised so that the sum of the squares of the moduli of the elements is equal to 1 and the element of largest modulus is real. See also Section 8. 8: IVR -- INTEGER Input On entry: the first dimension of the array VR as declared in the (sub)program from which F02AXF is called. Constraint: IVR >= N. 9: VI(IVI,N) -- DOUBLE PRECISION array Output On exit: the imaginary parts of the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvector. See also Section 8. 10: IVI -- INTEGER Input On entry: the first dimension of the array VI as declared in the (sub)program from which F02AXF is called. Constraint: IVI >= N. 11: WK1(N) -- DOUBLE PRECISION array Workspace 12: WK2(N) -- DOUBLE PRECISION array Workspace 13: WK3(N) -- DOUBLE PRECISION array Workspace 14: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 More than 30*N iterations are required to isolate all the eigenvalues. IFAIL= 2 The diagonal elements of AI are not all zero, i.e., the complex matrix is not Hermitian. 7. Accuracy The eigenvectors are always accurately orthogonal but the accuracy of the individual eigenvalues and eigenvectors is dependent on their inherent sensitivity to small changes in the original matrix. For a detailed error analysis see Peters [1] page 3 and [2] page 3. 8. Further Comments 3 The time taken by the routine is approximately proportional to n Unless otherwise stated in the implementation document, the routine may be called with the same actual array supplied for parameters AR and VR, and for AI and VI, in which case the eigenvectors will overwrite the original matrix A. However this is not standard Fortran 77, and may not work on all systems. 9. Example To calculate the eigenvalues and eigenvectors of the complex Hermitian matrix: (0.50 0.00 1.84+1.38i 2.08-1.56i) (0.00 0.50 1.12+0.84i -0.56+0.42i) (1.84-1.38i 1.12-0.84i 0.50 0.00 ). (2.08+1.56i -0.56-0.42i 0.00 0.50 ) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02bbf}{NAG On-line Documentation: f02bbf} \beginscroll \begin{verbatim} F02BBF(3NAG) Foundation Library (12/10/92) F02BBF(3NAG) F02 -- Eigenvalue and Eigenvectors F02BBF F02BBF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02BBF calculates selected eigenvalues and eigenvectors of a real symmetric matrix by reduction to tridiagonal form, bisection and inverse iteration, where the selected eigenvalues lie within a given interval. 2. Specification SUBROUTINE F02BBF (A, IA, N, ALB, UB, M, MM, R, V, IV, D, 1 E, E2, X, G, C, ICOUNT, IFAIL) INTEGER IA, N, M, MM, IV, ICOUNT(M), IFAIL DOUBLE PRECISION A(IA,N), ALB, UB, R(M), V(IV,M), D(N), E 1 (N), E2(N), X(N,7), G(N) LOGICAL C(N) 3. Description The real symmetric matrix A is reduced to a symmetric tridiagonal matrix T by Householder's method. The eigenvalues which lie within a given interval [l,u], are calculated by the method of bisection. The corresponding eigenvectors of T are calculated by inverse iteration. A back-transformation is then performed to obtain the eigenvectors of the original matrix A. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,N) -- DOUBLE PRECISION array Input/Output On entry: the lower triangle of the n by n symmetric matrix A. The elements of the array above the diagonal need not be set. On exit: the elements of A below the diagonal are overwritten, and the rest of the array is unchanged. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02BBF is called. Constraint: IA >= N. 3: N -- INTEGER Input On entry: n, the order of the matrix A. 4: ALB -- DOUBLE PRECISION Input 5: UB -- DOUBLE PRECISION Input On entry: l and u, the lower and upper end-points of the interval within which eigenvalues are to be calculated. 6: M -- INTEGER Input On entry: an upper bound for the number of eigenvalues within the interval. 7: MM -- INTEGER Output On exit: the actual number of eigenvalues within the interval. 8: R(M) -- DOUBLE PRECISION array Output On exit: the eigenvalues, not necessarily in ascending order. 9: V(IV,M) -- DOUBLE PRECISION array Output On exit: the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvalue. The eigenvectors are normalised so that the sum of the squares of the elements are equal to 1. 10: IV -- INTEGER Input On entry: the first dimension of the array V as declared in the (sub)program from which F02BBF is called. Constraint: IV >= N. 11: D(N) -- DOUBLE PRECISION array Workspace 12: E(N) -- DOUBLE PRECISION array Workspace 13: E2(N) -- DOUBLE PRECISION array Workspace 14: X(N,7) -- DOUBLE PRECISION array Workspace 15: G(N) -- DOUBLE PRECISION array Workspace 16: C(N) -- LOGICAL array Workspace 17: ICOUNT(M) -- INTEGER array Output On exit: ICOUNT(i) contains the number of iterations for the ith eigenvalue. 18: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 M is less than the number of eigenvalues in the given interval. On exit MM contains the number of eigenvalues in the interval. Rerun with this value for M. IFAIL= 2 More than 5 iterations are required to determine any one eigenvector. 7. Accuracy There is no guarantee of the accuracy of the eigenvectors as the results depend on the original matrix and the multiplicity of the roots. For a detailed error analysis see Wilkinson and Reinsch [1] pp 222 and 436. 8. Further Comments 3 The time taken by the routine is approximately proportional to n This subroutine should only be used when less than 25% of the eigenvalues and the corresponding eigenvectors are required. Also this subroutine is less efficient with matrices which have multiple eigenvalues. 9. Example To calculate the eigenvalues lying between -2.0 and 3.0, and the corresponding eigenvectors of the real symmetric matrix: ( 0.5 0.0 2.3 -2.6) ( 0.0 0.5 -1.4 -0.7) ( 2.3 -1.4 0.5 0.0). (-2.6 -0.7 0.0 0.5) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02bjf}{NAG On-line Documentation: f02bjf} \beginscroll \begin{verbatim} F02BJF(3NAG) Foundation Library (12/10/92) F02BJF(3NAG) F02 -- Eigenvalue and Eigenvectors F02BJF F02BJF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F02BJF calculates all the eigenvalues and, if required, all the eigenvectors of the generalized eigenproblem Ax=(lambda)Bx where A and B are real, square matrices, using the QZ algorithm. 2. Specification SUBROUTINE F02BJF (N, A, IA, B, IB, EPS1, ALFR, ALFI, 1 BETA, MATV, V, IV, ITER, IFAIL) INTEGER N, IA, IB, IV, ITER(N), IFAIL DOUBLE PRECISION A(IA,N), B(IB,N), EPS1, ALFR(N), ALFI(N), 1 BETA(N), V(IV,N) LOGICAL MATV 3. Description All the eigenvalues and, if required, all the eigenvectors of the generalized eigenproblem Ax=(lambda)Bx where A and B are real, square matrices, are determined using the QZ algorithm. The QZ algorithm consists of 4 stages: (a) A is reduced to upper Hessenberg form and at the same time B is reduced to upper triangular form. (b) A is further reduced to quasi-triangular form while the triangular form of B is maintained. (c) The quasi-triangular form of A is reduced to triangular form and the eigenvalues extracted. This routine does not actually produce the eigenvalues (lambda) , but instead j returns (alpha) and (beta) such that j j (lambda) =(alpha) /(beta) , j=1,2,...,.n j j j The division by (beta) becomes the responsibility of the j user's program, since (beta) may be zero indicating an j infinite eigenvalue. Pairs of complex eigenvalues occur with (alpha) /(beta) and (alpha) /(beta) complex j j j+1 j+1 conjugates, even though (alpha) and (alpha) are not j j+1 conjugate. (d) If the eigenvectors are required (MATV = .TRUE.), they are obtained from the triangular matrices and then transformed back into the original co-ordinate system. 4. References [1] Moler C B and Stewart G W (1973) An Algorithm for Generalized Matrix Eigenproblems. SIAM J. Numer. Anal. 10 241--256. [2] Ward R C (1975) The Combination Shift QZ Algorithm. SIAM J. Numer. Anal. 12 835--853. [3] Wilkinson J H (1979) Kronecker's Canonical Form and the QZ Algorithm. Linear Algebra and Appl. 28 285--303. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrices A and B. 2: A(IA,N) -- DOUBLE PRECISION array Input/Output On entry: the n by n matrix A. On exit: the array is overwritten. 3: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02BJF is called. Constraint: IA >= N. 4: B(IB,N) -- DOUBLE PRECISION array Input/Output On entry: the n by n matrix B. On exit: the array is overwritten. 5: IB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F02BJF is called. Constraint: IB >= N. 6: EPS1 -- DOUBLE PRECISION Input On entry: the tolerance used to determine negligible elements. If EPS1 > 0.0, an element will be considered negligible if it is less than EPS1 times the norm of its matrix. If EPS1 <= 0.0, machine precision is used in place of EPS1. A positive value of EPS1 may result in faster execution but less accurate results. 7: ALFR(N) -- DOUBLE PRECISION array Output 8: ALFI(N) -- DOUBLE PRECISION array Output On exit: the real and imaginary parts of (alpha) , for j j=1,2,...,n. 9: BETA(N) -- DOUBLE PRECISION array Output On exit: (beta) , for j=1,2,...,n. j 10: MATV -- LOGICAL Input On entry: MATV must be set .TRUE. if the eigenvectors are required, otherwise .FALSE.. 11: V(IV,N) -- DOUBLE PRECISION array Output On exit: if MATV = .TRUE., then (i)if the jth eigenvalue is real, the jth column of V contains its eigenvector; (ii) if the jth and (j+1)th eigenvalues form a complex pair, the jth and (j+1)th columns of V contain the real and imaginary parts of the eigenvector associated with the first eigenvalue of the pair. The conjugate of this vector is the eigenvector for the conjugate eigenvalue. Each eigenvector is normalised so that the component of largest modulus is real and the sum of squares of the moduli equal one. If MATV = .FALSE., V is not used. 12: IV -- INTEGER Input On entry: the first dimension of the array V as declared in the (sub)program from which F02BJF is called. Constraint: IV >= N. 13: ITER(N) -- INTEGER array Output On exit: ITER(j) contains the number of iterations needed to obtain the jth eigenvalue. Note that the eigenvalues are obtained in reverse order, starting with the nth. 14: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= i More than 30*N iterations are required to determine all the diagonal 1 by 1 or 2 by 2 blocks of the quasi-triangular form in the second step of the QZ algorithm. IFAIL is set to the index i of the eigenvalue at which this failure occurs. If the soft failure option is used, (alpha) and (beta) are j j correct for j=i+1,i+2,...,n, but V does not contain any correct eigenvectors. 7. Accuracy The computed eigenvalues are always exact for a problem (A+E)x=(lambda)(B+F)x where ||E||/||A|| and ||F||/||B|| are both of the order of max(EPS1,(epsilon)), EPS1 being defined as in Section 5 and (epsilon) being the machine precision. Note: interpretation of results obtained with the QZ algorithm often requires a clear understanding of the effects of small changes in the original data. These effects are reviewed in Wilkinson [3], in relation to the significance of small values of (alpha) and (beta) . It should be noted that if (alpha) and j j j (beta) are both small for any j, it may be that no reliance can j be placed on any of the computed eigenvalues (lambda) =(alpha) /(beta) . The user is recommended to study [3] i i i and, if in difficulty, to seek expert advice on determining the sensitivity of the eigenvalues to perturbations in the data. 8. Further Comments 3 The time taken by the routine is approximately proportional to n and also depends on the value chosen for parameter EPS1. 9. Example To find all the eigenvalues and eigenvectors of Ax=(lambda) Bx where (3.9 12.5 -34.5 -0.5) (4.3 21.5 -47.5 7.5) A=(4.3 21.5 -43.5 3.5) (4.4 26.0 -46.0 6.0) and (1 2 -3 1) (1 3 -5 4) B=(1 3 -4 3). (1 3 -4 4) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf02fjf}{NAG On-line Documentation: f02fjf} \beginscroll \begin{verbatim} F02FJF(3NAG) Foundation Library (12/10/92) F02FJF(3NAG) F02 -- Eigenvalue and Eigenvectors F02FJF F02FJF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose To find eigenvalues and eigenvectors of a real sparse symmetric or generalized symmetric eigenvalue problem. 2. Specification SUBROUTINE F02FJF (N, M, K, NOITS, TOL, DOT, IMAGE, MONIT, 1 NOVECS, X, NRX, D, WORK, LWORK, RWORK, 2 LRWORK, IWORK, LIWORK, IFAIL) INTEGER N, M, K, NOITS, NOVECS, NRX, LWORK, 1 LRWORK, IWORK(LIWORK), LIWORK, IFAIL DOUBLE PRECISION TOL, DOT, X(NRX,K), D(K), WORK(LWORK), 1 RWORK(LRWORK) EXTERNAL DOT, IMAGE, MONIT 3. Description F02FJF finds the m eigenvalues of largest absolute value and the corresponding eigenvectors for the real eigenvalue problem Cx=(lambda)x (1) where C is an n by n matrix such that T BC=C B (2) for a given positive-definite matrix B. C is said to be B- symmetric. Different specifications of C allow for the solution of a variety of eigenvalue problems. For example, when T C=A and B=I where A=A the routine finds the m eigenvalues of largest absolute magnitude for the standard symmetric eigenvalue problem Ax=(lambda)x. (3) The routine is intended for the case where A is sparse. As a second example, when -1 C=B A where T A=A the routine finds the m eigenvalues of largest absolute magnitude for the generalized symmetric eigenvalue problem Ax=(lambda)Bx. (4) The routine is intended for the case where A and B are sparse. The routine does not require C explicitly, but C is specified via a user-supplied routine IMAGE which, given an n element vector z, computes the image w given by w=Cz. -1 For instance, in the above example, where C=B A, routine IMAGE will need to solve the positive-definite system of equations Bw=Az for w. To find the m eigenvalues of smallest absolute magnitude of (3) -1 we can choose C=A and hence find the reciprocals of the required eigenvalues, so that IMAGE will need to solve Aw=z for -1 w, and correspondingly for (4) we can choose C=A B and solve Aw=Bz for w. A table of examples of choice of IMAGE is given in Table 3.1. It should be remembered that the routine also returns the corresponding eigenvectors and that B is positive-definite. Throughout A is assumed to be symmetric and, where necessary, non-singularity is also assumed. Eigenvalues Problem Required Ax=(lambda)x (B=I)Ax=(lambda)Bx ABx=(lambda)x Largest Compute Solve Compute w=Az Bw=Az w=ABz Smallest Solve Solve Solve (Find Aw=z Aw=Bz Av=z, Bw=(nu) 1/(lambda)) Furthest Compute Solve Compute from w=(A-(sigma)I)z Bw=(A-(sigma)B)z w=(AB-(sigma)I)z (sigma) (Find (lambda)- (sigma)) Closest to Solve Solve Solve (sigma) (A-(sigma)I)w=z (A-(sigma)B)w=Bz (AB-(sigma)I)w=z (Find 1/(( lambda)- (sigma))) Table 3.1 The Requirement of IMAGE for Various Problems The matrix B also need not be supplied explicitly, but is specified via a user-supplied routine DOT which, given n element T vectors z and w, computes the generalized dot product w Bz. F02FJF is based upon routine SIMITZ (see Nikolai [1]), which is itself a derivative of the Algol procedure ritzit (see Rutishauser [4]), and uses the method of simultaneous (subspace) iteration. (See Parlett [2] for description, analysis and advice on the use of the method.) The routine performs simultaneous iteration on k>m vectors. Initial estimates to p<=k eigenvectors, corresponding to the p eigenvalues of C of largest absolute value, may be supplied by the user to F02FJF. When possible k should be chosen so that the kth eigenvalue is not too close to the m required eigenvalues, but if k is initially chosen too small then F02FJF may be re- entered, supplying approximations to the k eigenvectors found so far and with k then increased. At each major iteration F02FJF solves an r by r (r<=k) eigenvalue sub-problem in order to obtain an approximation to the eigenvalues for which convergence has not yet occurred. This approximation is refined by Chebyshev acceleration. 4. References [1] Nikolai P J (1979) Algorithm 538: Eigenvectors and eigenvalues of real generalized symmetric matrices by simultaneous iteration. ACM Trans. Math. Softw. 5 118--125. [2] Parlett B N (1980) The Symmetric Eigenvalue Problem. Prentice-Hall. [3] Rutishauser H (1969) Computational aspects of F L Bauer's simultaneous iteration method. Num. Math. 13 4--13. [4] Rutishauser H (1970) Simultaneous iteration method for symmetric matrices. Num. Math. 16 205--223. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix C. Constraint: N >= 1. 2: M -- INTEGER Input/Output On entry: m, the number of eigenvalues required. ' Constraint: M >= 1. On exit: m, the number of eigenvalues actually found. It is equal to m if IFAIL = 0 on exit, and is less than m if IFAIL = 2, 3 or 4. See Section 6 and Section 8 for further information. 3: K -- INTEGER Input On entry: the number of simultaneous iteration vectors to be used. Too small a value of K may inhibit convergence, while a larger value of K incurs additional storage and additional work per iteration. Suggested value: K = M + 4 will often be a reasonable choice in the absence of better information. Constraint: M < K <= N. 4: NOITS -- INTEGER Input/Output On entry: the maximum number of major iterations (eigenvalue sub-problems) to be performed. If NOITS <= 0, then the value 100 is used in place of NOITS. On exit: the number of iterations actually performed. 5: TOL -- DOUBLE PRECISION Input On entry: a relative tolerance to be used in accepting eigenvalues and eigenvectors. If the eigenvalues are required to about t significant figures, then TOL should be -t set to about 10 . d is accepted as an eigenvalue as soon i as two successive approximations to d differ by less than i ~ ~ (|d |*TOL)/10, where d is the latest aproximation to d . i i i Once an eigenvalue has been accepted, then an eigenvector is accepted as soon as (d f )/(d -d )= N. 12: D(K) -- DOUBLE PRECISION array Output On exit: if IFAIL = 0, 2, 3 or 4, the first m' elements contain the first m' eigenvalues in decreasing order of magnitude; and the next k-m'-1 elements contain approximations to the next k-m'-1 eigenvalues. Here m' is the value returned in M (see above), the number of eigenvalues actually found. D(k) contains the value e where (-e,e) is the latest interval over which Chebyshev acceleration is performed. 13: WORK(LWORK) -- DOUBLE PRECISION array Workspace 14: LWORK -- INTEGER Input On entry: the length of the array WORK, as declared in the (sub)program from which F02FJF is called. Constraint: LWORK>=3*K+max(K*K,2*N). 15: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace RWORK is not used by F02FJF, but is passed directly to routines DOT and IMAGE and may be used to supply information to these routines. 16: LRWORK -- INTEGER Input On entry: the length of the array RWORK, as declared in the (sub)program from which F02FJF is called. Constraint: LRWORK >= 1. 17: IWORK(LIWORK) -- INTEGER array User Workspace IWORK is not used by F02FJF, but is passed directly to routines DOT and IMAGE and may be used to supply information to these routines. 18: LIWORK -- INTEGER Input On entry: the length of the array IWORK, as declared in the (sub)program from which F02FJF is called. Constraint: LIWORK >= 1. 19: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. Users who are unfamiliar with this parameter should refer to the Essential Introduction for details. On exit: IFAIL = 0 unless the routine detects an error or gives a warning (see Section 6). For this routine, because the values of output parameters may be useful even if IFAIL /=0 on exit, users are recommended to set IFAIL to -1 before entry. It is then essential to test the value of IFAIL on exit. To suppress the output of an error message when soft failure occurs, set IFAIL to 1. 6. Error Indicators and Warnings Errors or warnings specified by the routine: IFAIL< 0 A negative value of IFAIL indicates an exit from F02FJF because the user has set IFLAG negative in DOT or IMAGE. The value of IFAIL will be the same as the user's setting of IFLAG. IFAIL= 1 On entry N < 1, or M < 1, or M >= K, or K > N, or NRX < N, or LWORK <3*K+max(K*K*N), or LRWORK < 1, or LIWORK < 1. IFAIL= 2 Not all the requested eigenvalues and vectors have been obtained. Approximations to the rth eigenvalue are oscillating rapidly indicating that severe cancellation is occurring in the rth eigenvector and so M is returned as (r- 1). A restart with a larger value of K may permit convergence. IFAIL= 3 Not all the requested eigenvalues and vectors have been obtained. The rate of convergence of the remaining eigenvectors suggests that more than NOITS iterations would be required and so the input value of M has been reduced. A restart with a larger value of K may permit convergence. IFAIL= 4 Not all the requested eigenvalues and vectors have been obtained. NOITS iterations have been performed. A restart, possibly with a larger value of K, may permit convergence. IFAIL= 5 This error is very unlikely to occur, but indicates that convergence of the eigenvalue sub-problem has not taken place. Restarting with a different set of approximate vectors may allow convergence. If this error occurs the user should check carefully that F02FJF is being called correctly. 7. Accuracy Eigenvalues and eigenvectors will normally be computed to the accuracy requested by the parameter TOL, but eigenvectors corresponding to small or to close eigenvalues may not always be computed to the accuracy requested by the parameter TOL. Use of the routine MONIT to monitor acceptance of eigenvalues and eigenvectors is recommended. 8. Further Comments The time taken by the routine will be principally determined by the time taken to solve the eigenvalue sub-problem and the time taken by the routines DOT and IMAGE. The time taken to solve an 2 eigenvalue sub-problem is approximately proportional to nk . It is important to be aware that several calls to DOT and IMAGE may occur on each major iteration. As can be seen from Table 3.1, many applications of F02FJF will require routine IMAGE to solve a system of linear equations. For example, to find the smallest eigenvalues of Ax=(lambda)Bx, IMAGE needs to solve equations of the form Aw=Bz for w and routines from Chapters F01 and F04 of the NAG Foundation Library will frequently be useful in this context. In particular, if A is a positive-definite variable band matrix, F04MCF may be used after A has been factorized by F01MCF. Thus factorization need be performed only once prior to calling F02FJF. An illustration of this type of use is given in the example program in Section 9. ~ An approximation d , to the ith eigenvalue, is accepted as soon h ~ as d and the previous approximation differ by less than h ~ |d |*TOL/10. Eigenvectors are accepted in groups corresponding to h clusters of eigenvalues that are equal, or nearly equal, in absolute value and that have already been accepted. If d is the r last eigenvalue in such a group and we define the residual r as j r =Cx -y j j r where y is the projection of Cx , with respect to B, onto the r j space spanned by x ,x ,...,x and x is the current approximation 1 2 r j to the jth eigenvector, then the value f returned in MONIT is i given by 2 T f =max||r || /||Cx || ||x|| =x Bx i j B j B B and each vector in the group is accepted as an eigenvector if (|d |f )/(|d |-e)n, D=S, m=n, D=(S 0), m=sv >=...>=sv >=0. 1 2 min(m,n) The first min(m,n) columns of Q are the left-hand singular vectors of A, the diagonal elements of S are the singular values of A and the first min(m,n) columns of P are the right-hand singular vectors of A. Either or both of the left-hand and right-hand singular vectors of A may be requested and the matrix C given by T C=Q B, where B is an m by ncolb given matrix, may also be requested. The routine obtains the singular value decomposition by first reducing A to upper triangular form by means of Householder transformations, from the left when m>=n and from the right when m= 0. When M = 0 then an immediate return is effected. 2: N -- INTEGER Input On entry: the number of columns, n, of the matrix A. Constraint: N >= 0. When N = 0 then an immediate return is effected. 3: A(LDA,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the leading m by n part of the array A must contain the matrix A whose singular value decomposition is required. On exit: if M >= N and WANTQ = .TRUE., then the leading m by n part of A will contain the first n columns of the orthogonal matrix Q. If M < N and WANTP = .TRUE., then the leading m by n part of T A will contain the first m rows of the orthogonal matrix P . If M >= N and WANTQ = .FALSE. and WANTP = .TRUE., then the leading n by n part of A will contain the first n rows of T the orthogonal matrix P . Otherwise the leading m by n part of A is used as internal workspace. 4: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02WEF is called. Constraint: LDA >= max(1,M). 5: NCOLB -- INTEGER Input On entry: ncolb, the number of columns of the matrix B. When NCOLB = 0 the array B is not referenced. Constraint: NCOLB >= 0. 6: B(LDB,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array B must be at least max(1,ncolb) On entry: if NCOLB > 0, the leading m by ncolb part of the array B must contain the matrix to be transformed. On exit: B is overwritten by the m by ncolb T matrix Q B. 7: LDB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F02WEF is called. Constraint: if NCOLB > 0 then LDB >= max(1,M). 8: WANTQ -- LOGICAL Input On entry: WANTQ must be .TRUE., if the left-hand singular vectors are required. If WANTQ = .FALSE., then the array Q is not referenced. 9: Q(LDQ,*) -- DOUBLE PRECISION array Output Note: the second dimension of the array Q must be at least max(1,M). On exit: if M < N and WANTQ = .TRUE., the leading m by m part of the array Q will contain the orthogonal matrix Q. Otherwise the array Q is not referenced. 10: LDQ -- INTEGER Input On entry: the first dimension of the array Q as declared in the (sub)program from which F02WEF is called. Constraint: if M < N and WANTQ = .TRUE., LDQ >= max(1,M). 11: SV(*) -- DOUBLE PRECISION array Output Note: the length of SV must be at least min(M,N). On exit: the min(M,N) diagonal elements of the matrix S. 12: WANTP -- LOGICAL Input On entry: WANTP must be .TRUE. if the right-hand singular vectors are required. If WANTP = .FALSE., then the array PT is not referenced. 13: PT(LDPT,*) -- DOUBLE PRECISION array Output Note: the second dimension of the array PT must be at least max(1,N). On exit: if M >= N and WANTQ and WANTP are .TRUE., the leading n by n part of the array PT will contain the T orthogonal matrix P . Otherwise the array PT is not referenced. 14: LDPT -- INTEGER Input On entry: the first dimension of the array PT as declared in the (sub)program from which F02WEF is called. Constraint: if M >= N and WANTQ and WANTP are .TRUE., LDPT >= max(1,N). 15: WORK(*) -- DOUBLE PRECISION array Output Note: the length of WORK must be at least max(1,lwork), where lwork must be as given in the following table: M >= N WANTQ is .TRUE. and WANTP = .TRUE. 2 lwork=max(N +5*(N-1),N+NCOLB,4) WANTQ = .TRUE. and WANTP = .FALSE. 2 lwork=max(N +4*(N-1),N+NCOLB,4) WANTQ = .FALSE. and WANTP = .TRUE. lwork=max(3*(N-1),2) when NCOLB = 0 lwork=max(5*(N-1),2) when NCOLB > 0 WANTQ = .FALSE. and WANTP = .FALSE. lwork=max(2*(N-1),2) when NCOLB = 0 lwork=max(3*(N-1),2) when NCOLB > 0 M < N WANTQ = .TRUE. and WANTP = .TRUE. 2 lwork=max(M +5*(M-1),2) WANTQ = .TRUE. and WANTP = .FALSE. lwork=max(3*(M-1),1) WANTQ = .FALSE. and WANTP = .TRUE. 2 lwork=max(M +3*(M-1),2) when NCOLB = 0 2 lwork=max(M +5*(M-1),2) when NCOLB > 0 WANTQ = .FALSE. and WANTP = .FALSE. lwork=max(2*(M-1),1) when NCOLB = 0 lwork=max(3*(M-1),1) when NCOLB > 0 On exit: WORK(min(M,N)) contains the total number of iterations taken by the R algorithm. The rest of the array is used as workspace. 16: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 One or more of the following conditions holds: M < 0, N < 0, LDA < M, NCOLB < 0, LDB < M and NCOLB > 0, LDQ < M and M < N and WANTQ = .TRUE., LDPT < N and M >= N and WANTQ = .TRUE., and WANTP = . TRUE.. IFAIL> 0 The QR algorithm has failed to converge in 50*min(m,n) iterations. In this case SV(1), SV(2),..., SV(IFAIL) may not have been found correctly and the remaining singular values may not be the smallest. The matrix A will nevertheless have T been factorized as A=QEP , where the leading min(m,n) by min(m,n) part of E is a bidiagonal matrix with SV(1), SV(2), ..., SV(min(m,n)) as the diagonal elements and WORK(1), WORK (2),..., WORK(min(m,n)-1) as the super-diagonal elements. This failure is not likely to occur. 7. Accuracy The computed factors Q, D and P satisfy the relation T QDP =A+E, where ||E||<=c(epsilon)||A||, (epsilon) being the machine precision, c is a modest function of m and n and ||.|| denotes the spectral (two) norm. Note that ||A||=sv . 1 8. Further Comments Following the use of this routine the rank of A may be estimated by a call to the INTEGER FUNCTION F06KLF(*). The statement: IRANK = F06KLF(MIN(M, N), SV, 1, TOL) returns the value (k-1) in IRANK, where k is the smallest integer for which SV(k)n, D=S, m=n, D=(S 0), m=sv >=...>=sv >=0. 1 2 min(m,n) The first min(m,n) columns of Q are the left-hand singular vectors of A, the diagonal elements of S are the singular values of A and the first min(m,n) columns of P are the right-hand singular vectors of A. Either or both of the left-hand and right-hand singular vectors of A may be requested and the matrix C given by H C=Q B, where B is an m by ncolb given matrix, may also be requested. The routine obtains the singular value decomposition by first reducing A to upper triangular form by means of Householder transformations, from the left when m>=n and from the right when m= 0. When M = 0 then an immediate return is effected. 2: N -- INTEGER Input On entry: the number of columns, n, of the matrix A. Constraint: N >= 0. When N = 0 then an immediate return is effected. 3: A(LDA,*) -- COMPLEX(KIND(1.0D)) array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the leading m by n part of the array A must contain the matrix A whose singular value decomposition is required. On exit: if M >= N and WANTQ = .TRUE., then the leading m by n part of A will contain the first n columns of the unitary matrix Q. If M < N and WANTP = .TRUE., then the leading m by n part of H A will contain the first m rows of the unitary matrix P . will contain the first m rows of the unitary matrix P If M >= N and WANTQ = .FALSE. and WANTP = .TRUE., then the leading n by n part of A will contain the first n H rows of the unitary matrix P . Otherwise the leading m by n part of A is used as internal workspace. 4: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F02XEF is called. Constraint: LDA >= max(1,M). 5: NCOLB -- INTEGER Input On entry: ncolb, the number of columns of the matrix B. When NCOLB = 0 the array B is not referenced. Constraint: NCOLB >= 0. 6: B(LDB,*) -- COMPLEX(KIND(1.0D)) array Input/Output Note: the second dimension of the array B must be at least max(1,NCOLB). On entry: if NCOLB > 0, the leading m by ncolb part of the array B must contain the matrix to be transformed. On exit: H B is overwritten by the m by ncolb matrix Q B. 7: LDB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F02XEF is called. Constraint: if NCOLB > 0, then LDB >= max(1,M). 8: WANTQ -- LOGICAL Input On entry: WANTQ must be .TRUE. if the left-hand singular vectors are required. If WANTQ = .FALSE. then the array Q is not referenced. 9: Q(LDQ,*) -- COMPLEX(KIND(1.0D)) array Output Note: the second dimension of the array Q must be at least max(1,M). On exit: if M < N and WANTQ = .TRUE., the leading m by m part of the array Q will contain the unitary matrix Q. Otherwise the array Q is not referenced. 10: LDQ -- INTEGER Input On entry: the first dimension of the array Q as declared in the (sub)program from which F02XEF is called. Constraint: if M < N and WANTQ = .TRUE., LDQ >= max(1,M). 11: SV(*) -- DOUBLE PRECISION array Output Note: the length of SV must be at least min(M,N). On exit: the min(m,n) diagonal elements of the matrix S. 12: WANTP -- LOGICAL Input On entry: WANTP must be .TRUE. if the right-hand singular vectors are required. If WANTP = .FALSE. then the array PH is not referenced. 13: PH(LDPH,*) -- DOUBLE PRECISION array Output Note: the second dimension of the array PH must be at least max(1,N). On exit: if M >= N and WANTQ and WANTP are .TRUE., the leading n by n part of the array PH will contain the unitary H matrix P . Otherwise the array PH is not referenced. 14: LDPH -- INTEGER Input On entry: the first dimension of the array PH as declared in the (sub)program from which F02XEF is called. Constraint: if M >= N and WANTQ and WANTP are .TRUE., LDPH >= max(1,N). 15: RWORK(*) -- DOUBLE PRECISION array Output Note: the length of RWORK must be at least max(1,lrwork), where lrwork must satisfy: lrwork=2*(min(M,N)-1) when NCOLB = 0 and WANTQ and WANTP are .FALSE., lrwork=3*(min(M,N)-1) when either NCOLB = 0 and WANTQ = .FALSE. and WANTP = . TRUE., or WANTP = .FALSE. and one or both of NCOLB > 0 and WANTQ = .TRUE. lrwork=5*(min(M,N)-1) otherwise. On exit: RWORK(min(M,N)) contains the total number of iterations taken by the QR algorithm. The rest of the array is used as workspace. 16: CWORK(*) -- COMPLEX(KIND(1.0D)) array Workspace Note: the length of CWORK must be at least max(1,lcwork), where lcwork must satisfy: 2 lcwork=N+max(N ,NCOLB) when M >= N and WANTQ and WANTP are both .TRUE. 2 lcwork=N+max(N +N,NCOLB) when M >= N and WANTQ = .TRUE., but WANTP = .FALSE. lcwork=N+max(N,NCOLB) when M >= N and WANTQ = .FALSE. 2 lcwork=M +M when M < N and WANTP = .TRUE. lcwork = M when M < N and WANTP = .FALSE. 17: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL=-1 One or more of the following conditions holds: M < 0, N < 0, LDA < M, NCOLB < 0, LDB < M and NCOLB > 0, LDQ < M and M < N and WANTQ = .TRUE., LDPH < N and M >= N and WANTQ = .TRUE. and WANTP = . TRUE.. IFAIL> 0 The QR algorithm has failed to converge in 50*min(m,n) iterations. In this case SV(1), SV(2),..., SV(IFAIL) may not have been found correctly and the remaining singular values may not be the smallest. The matrix A will nevertheless have H been factorized as A=QEP where the leading min(m,n) by min(m,n) part of E is a bidiagonal matrix with SV(1), SV(2), ..., SV(min(m,n)) as the diagonal elements and RWORK(1), RWORK(2),..., RWORK(min(m,n)-1) as the super-diagonal elements. This failure is not likely to occur. 7. Accuracy The computed factors Q, D and P satisfy the relation H QDP =A+E, where ||E||<=c(epsilon)||A||, (epsilon) being the machine precision, c is a modest function of m and n and ||.|| denotes the spectral (two) norm. Note that ||A||=sv . 1 8. Further Comments Following the use of this routine the rank of A may be estimated by a call to the INTEGER FUNCTION F06KLF(*). The statement: IRANK = F06KLF(MIN(M, N), SV, 1, TOL) returns the value (k-1) in IRANK, where k is the smallest integer for which SV(k)n and rank(A)=n, in which case x is unique. 2.1. Unique Solution of Ax=b Most of the routines in this chapter, as well as two routines in Chapter F07, solve this particular problem. The solution is obtained by performing either an LU factorization, or a Cholesky factorization, as discussed in Section 2 of the F01 Chapter Introduction. Two of the routines in this chapter use a process called iterative refinement to improve the initial solution in order to obtain a solution that is correct to working accuracy. It should be emphasised that if A and b are not known exactly then not all the figures in this solution may be meaningful. To be more precise, if x is the exact solution of the equations Ax=b and x is the solution of the perturbed equations (A+E)x=b+e, ||E|| then, provided that (kappa)(A) -------<=1, ||A|| ||x-x|| (kappa)(A) ( ||E|| ||e|| ) ------- <= --------------------( ----- + ----- ), ||x|| ||E|| ( ||A|| ||b|| ) 1-(kappa)(A) ----- ||A|| -1 where (kappa)(A)=||A||||A || is the condition number of A with respect to inversion. Thus, if A is ill-conditioned ( (kappa)(A) is large), x may differ significantly from x. Often ||E|| (kappa)(A) -----<<1 in which case the above bound effectively ||A|| reduces to ||x-x|| ( ||E|| ||e|| ) ------- <= (kappa)(A)( ----- + ----- ). ||x|| ( ||A|| ||b|| ) 2.2. The Least-squares Solution of Ax~=b The least-squares problem is to find a vector x to minimize T r r, where r=b-Ax. When m>=n and rank(A)=n then the solution vector x is unique. For the cases where x is not unique the routines in this chapter obtain the minimal length solution, that is the vector x for T which x x is a minimum. 2.3. Calculating the Inverse of a Matrix The routines in this chapter can also be used to calculate the inverse of a square matrix A by solving the equation AX=I, where I is the identity matrix. 3. Recommendations on Choice and Use of Routines 3.1. General Purpose Routines Many of the routines in this chapter perform the complete solution of the required equations, but some of the routines, as well as the routines in Chapter F07, assume that a prior factorization has been performed, using the appropriate factorization routine from Chapter F01 or Chapter F07. These, so- called, general purpose routines can be useful when explicit information on the factorization is required, as well as the solution of the equations, or when the solution is required for multiple right-hand sides, or for a sequence of right-hand sides. Note that some of the routines that perform a complete solution also allow multiple right-hand sides. 3.2. Iterative Refinement The routines that perform iterative refinement are more costly than those that do not perform iterative refinement, both in terms of time and storage, and should only be used if the problem really warrants the additional accuracy provided by these routines. The storage requirements are approximately doubled, while the additional time is not usually prohibitive since the initial factorization is used at each iteration. 3.3. Sparse Matrix Routines The routines for sparse matrices should usually be used only when the number of non-zero elements is very small, less than 10% of the total number of elements of A. Additionally, when the matrix is symmetric positive-definite the sparse routines should generally be used only when A does not have a (variable) band structure. There are four routines for solving sparse linear equations, two for solving general real systems (F04AXF and F04QAF), one for solving symmetric positive-definite systems (F04MAF) and one for solving symmetric systems that may, or may not, be positive- definite (F04MBF). F04AXF and F04MAF utilise factorizations of the matrix A obtained by routines in Chapter F01, while the other two routines use iterative techniques and require a user-supplied T function to compute matrix-vector products Ac and A c for any given vector c. The routines requiring factorizations will usually be faster and the factorization can be utilised to solve for several right-hand sides, but the original matrix has to be explicitly supplied and is overwritten by the factorization, and the storage requirements will usually be substantially more than those of the iterative routines. Routines F04MBF and F04QAF both allow the user to supply a pre- conditioner. F04MBF can be used to solve systems of the form (A-(lambda)I)x=b, which can be useful in applications such as Rayleigh quotient iteration. F04QAF also solves sparse least-squares problems and allows the solution of damped (regularized) least-squares problems. 3.4. Decision Trees If at any stage the answer to a question is 'Don't know' this should be read as 'No'. For those routines that need to be preceded by a factorization routine, the appropriate routine name is given in brackets after the name of the routine for solving the equations. Note also that you may be directed to a routine in Chapter F07. 3.4.1. Routines for unique solution of Ax=b Please see figure in printed Reference Manual 3.4.2. Routines for Least-squares problems Please see figure in printed Reference Manual F04 -- Simultaneous Linear Equations Contents -- F04 Chapter F04 Eigenvalues and Eigenvectors F04ADF Approximate solution of complex simultaneous linear equations with multiple right-hand sides F04ARF Approximate solution of real simultaneous linear equations, one right-hand side F04ASF Accurate solution of real symmetric positive-definite simultaneous linear equations, one right-hand side F04ATF Accurate solution of real simultaneous linear equations, one right-hand side F04AXF Approximate solution of real sparse simultaneous linear equations (coefficient matrix already factorized by F01BRF or F01BSF) F04FAF Approximate solution of real symmetric positive-definite tridiagonal simultaneous linear equations, one right-hand side F04JGF Least-squares (if rank = n) or minimal least-squares (if rank =n F04MAF Real sparse symmetric positive-definite simultaneous linear equations (coefficient matrix already factorized) F04MBF Real sparse symmetric simultaneous linear equations F04MCF Approximate solution of real symmetric positive-definite variable-bandwidth simultaneous linear equations (coefficient matrix already factorized) F04QAF Sparse linear least-squares problem, m real equations in n unknowns \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04adf}{NAG On-line Documentation: f04adf} \beginscroll \begin{verbatim} F04ADF(3NAG) Foundation Library (12/10/92) F04ADF(3NAG) F04 -- Simultaneous Linear Equations F04ADF F04ADF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04ADF calculates the approximate solution of a set of complex linear equations with multiple right-hand sides, using an LU factorization with partial pivoting. 2. Specification SUBROUTINE F04ADF (A, IA, B, IB, N, M, C, IC, WKSPCE, 1 IFAIL) INTEGER IA, IB, N, M, IC, IFAIL DOUBLE PRECISION WKSPCE(*) COMPLEX(KIND(1.0D0)) A(IA,*), B(IB,*), C(IC,*) 3. Description Given a set of complex linear equations AX=B, the routine first computes an LU factorization of A with partial pivoting, PA=LU, where P is a permutation matrix, L is lower triangular and U is unit upper triangular. The columns x of the solution X are found by forward and backward substitution in Ly=Pb and Ux=y, where b is a column of the right-hand side matrix B. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,*) -- COMPLEX(KIND(1.0D)) array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the n by n matrix A. On exit: A is overwritten by the lower triangular matrix L and the off-diagonal elements of the upper triangular matrix U. The unit diagonal elements of U are not stored. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F04ADF is called. Constraint: IA >= max(1,N). 3: B(IB,*) -- COMPLEX(KIND(1.0D)) array Input Note: the second dimension of the array B must be at least max(1,M). On entry: the n by m right-hand side matrix B. See also Section 8. 4: IB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F04ADF is called. Constraint: IB >= max(1,N). 5: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 0. 6: M -- INTEGER Input On entry: m, the number of right-hand sides. Constraint: M >= 0. 7: C(IC,*) -- COMPLEX(KIND(1.0D)) array Output Note: the second dimension of the array C must be at least max(1,M). On exit: the n by m solution matrix X. See also Section 8. 8: IC -- INTEGER Input On entry: the first dimension of the array C as declared in the (sub)program from which F04ADF is called. Constraint: IC >= max(1,N). 9: WKSPCE(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WKSPCE must be at least max(1,N). 10: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL= 1 The matrix A is singular, possibly due to rounding errors. IFAIL= 2 On entry N < 0, or M < 0, or IA < max(1,N), or IB < max(1,N), or IC < max(1,N). 7. Accuracy The accuracy of the computed solution depends on the conditioning of the original matrix. For a detailed error analysis see Wilkinson and Reinsch [1] page 106. 8. Further Comments 3 The time taken by the routine is approximately proportional to n Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same actual array supplied for parameters B and C, in which case the solution vectors will overwrite the right-hand sides. However this is not standard Fortran 77, and may not work on all systems. 9. Example To solve the set of linear equations AX=B where (1 1+2i 2+10i) A=(1+i 3i -5+14i) (1+i 5i -8+20i) and (1) B=(0). (0) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04arf}{NAG On-line Documentation: f04arf} \beginscroll \begin{verbatim} F04ARF(3NAG) Foundation Library (12/10/92) F04ARF(3NAG) F04 -- Simultaneous Linear Equations F04ARF F04ARF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04ARF calculates the approximate solution of a set of real linear equations with a single right-hand side, using an LU factorization with partial pivoting. 2. Specification SUBROUTINE F04ARF (A, IA, B, N, C, WKSPCE, IFAIL) INTEGER IA, N, IFAIL DOUBLE PRECISION A(IA,*), B(*), C(*), WKSPCE(*) 3. Description Given a set of linear equations, Ax=b, the routine first computes an LU factorization of A with partial pivoting, PA=LU, where P is a permutation matrix, L is lower triangular and U is unit upper triangular. The approximate solution x is found by forward and backward substitution in Ly=Pb and Ux=y, where b is the right- hand side. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the n by n matrix A. On exit: A is overwritten by the lower triangular matrix L and the off-diagonal elements of the upper triangular matrix U. The unit diagonal elements of U are not stored. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F04ARF is called. Constraint: IA >= max(1,N). 3: B(*) -- DOUBLE PRECISION array Input Note: the dimension of the array B must be at least max(1,N). On entry: the right-hand side vector b. 4: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 0. 5: C(*) -- DOUBLE PRECISION array Output Note: the dimension of the array C must be at least max(1,N). On exit: the solution vector x. 6: WKSPCE(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WKSPCE must be at least max(1,N). 7: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL= 1 The matrix A is singular, possibly due to rounding errors. IFAIL= 2 On entry N < 0, or IA < max(1,N). 7. Accuracy The accuracy of the computed solution depends on the conditioning of the original matrix. For a detailed error analysis see Wilkinson and Reinsch [1] page 107. 8. Further Comments 3 The time taken by the routine is approximately proportional to n Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same actual array supplied for parameters B and C, in which case the solution vector will overwrite the right-hand side. However this is not standard Fortran 77, and may not work on all systems. 9. Example To solve the set of linear equations Ax=b where ( 33 16 72) A=(-24 -10 -57) ( -8 -4 -17) and (-359) b=( 281). ( 85) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04asf}{NAG On-line Documentation: f04asf} \beginscroll \begin{verbatim} F04ASF(3NAG) Foundation Library (12/10/92) F04ASF(3NAG) F04 -- Simultaneous Linear Equations F04ASF F04ASF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04ASF calculates the accurate solution of a set of real symmetric positive-definite linear equations with a single right- hand side, Ax=b, using a Cholesky factorization and iterative refinement. 2. Specification SUBROUTINE F04ASF (A, IA, B, N, C, WK1, WK2, IFAIL) INTEGER IA, N, IFAIL DOUBLE PRECISION A(IA,*), B(*), C(*), WK1(*), WK2(*) 3. Description Given a set of real linear equations Ax=b, where A is a symmetric positive-definite matrix, the routine first computes a Cholesky T factorization of A as A=LL where L is lower triangular. An approximation to x is found by forward and backward substitution. The residual vector r=b-Ax is then calculated using additional T precision and a correction d to x is found by solving LL d=r. x is then replaced by x+d, and this iterative refinement of the solution is repeated until machine accuracy is obtained. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the upper triangle of the n by n positive-definite symmetric matrix A. The elements of the array below the diagonal need not be set. On exit: the elements of the array below the diagonal are overwritten; the upper triangle of A is unchanged. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F04ASF is called. Constraint: IA >= max(1,N). 3: B(*) -- DOUBLE PRECISION array Input Note: the dimension of the array B must be at least max(1,N). On entry: the right-hand side vector b. 4: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 0. 5: C(*) -- DOUBLE PRECISION array Output Note: the dimension of the array C must be at least max(1,N). On exit: the solution vector x. 6: WK1(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WK1 must be at least max(1,N). 7: WK2(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WK2 must be at least max(1,N). 8: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL= 1 The matrix A is not positive-definite, possibly due to rounding errors. IFAIL= 2 Iterative refinement fails to improve the solution, i.e., the matrix A is too ill-conditioned. IFAIL= 3 On entry N < 0, or IA < max(1,N). 7. Accuracy The computed solutions should be correct to full machine accuracy. For a detailed error analysis see Wilkinson and Reinsch [1] page 39. 8. Further Comments 3 The time taken by the routine is approximately proportional to n The routine must not be called with the same name for parameters B and C. 9. Example To solve the set of linear equations Ax=b where (5 7 6 5) (7 10 8 7) A=(6 8 10 9) (5 7 9 10) and (23) (32) b=(33). (31) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04atf}{NAG On-line Documentation: f04atf} \beginscroll \begin{verbatim} F04ATF(3NAG) Foundation Library (12/10/92) F04ATF(3NAG) F04 -- Simultaneous Linear Equations F04ATF F04ATF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04ATF calculates the accurate solution of a set of real linear equations with a single right-hand side, using an LU factorization with partial pivoting, and iterative refinement. 2. Specification SUBROUTINE F04ATF (A, IA, B, N, C, AA, IAA, WKS1, WKS2, 1 IFAIL) INTEGER IA, N, IAA, IFAIL DOUBLE PRECISION A(IA,*), B(*), C(*), AA(IAA,*), WKS1(*), 1 WKS2(*) 3. Description Given a set of real linear equations, Ax=b, the routine first computes an LU factorization of A with partial pivoting, PA=LU, where P is a permutation matrix, L is lower triangular and U is unit upper triangular. An approximation to x is found by forward and backward substitution in Ly=Pb and Ux=y. The residual vector r=b-Ax is then calculated using additional precision, and a correction d to x is found by solving LUd=r. x is replaced by x+d , and this iterative refinement of the solution is repeated until full machine accuracy is obtained. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: A(IA,*) -- DOUBLE PRECISION array Input Note: the second dimension of the array A must be at least max(1,N). On entry: the n by n matrix A. 2: IA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F04ATF is called. Constraint: IA >= max(1,N). 3: B(*) -- DOUBLE PRECISION array Input Note: the dimension of the array B must be at least max(1,N). On entry: the right-hand side vector b. 4: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 0. 5: C(*) -- DOUBLE PRECISION array Output Note: the dimension of the array C must be at least max(1,N). On exit: the solution vector x. 6: AA(IAA,*) -- DOUBLE PRECISION array Output Note: the second dimension of the array AA must be at least max(1,N). On exit: the triangular factors L and U, except that the unit diagonal elements of U are not stored. 7: IAA -- INTEGER Input On entry: the first dimension of the array AA as declared in the (sub)program from which F04ATF is called. Constraint: IAA >= max(1,N). 8: WKS1(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WKS1 must be at least max(1,N). 9: WKS2(*) -- DOUBLE PRECISION array Workspace Note: the dimension of the array WKS2 must be at least max(1,N). 10: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: If on entry IFAIL = 0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF). IFAIL= 1 The matrix A is singular, possibly due to rounding errors. IFAIL= 2 Iterative refinement fails to improve the solution, i.e., the matrix A is too ill-conditioned. IFAIL= 3 On entry N < 0, or IA < max(1,N), or IAA < max(1,N). 7. Accuracy The computed solutions should be correct to full machine accuracy. For a detailed error analysis see Wilkinson and Reinsch [1] page 107. 8. Further Comments 3 The time taken by the routine is approximately proportional to n The routine must not be called with the same name for parameters B and C. 9. Example To solve the set of linear equations Ax=b where ( 33 16 72) A=(-24 -10 -57) ( -8 -4 -17) and (-359) b=( 281). ( 85) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04axf}{NAG On-line Documentation: f04axf} \beginscroll \begin{verbatim} F04AXF(3NAG) Foundation Library (12/10/92) F04AXF(3NAG) F04 -- Simultaneous Linear Equations F04AXF F04AXF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04AXF calculates the approximate solution of a set of real sparse linear equations with a single right-hand side, Ax=b or T A x=b, where A has been factorized by F01BRF or F01BSF. 2. Specification SUBROUTINE F04AXF (N, A, LICN, ICN, IKEEP, RHS, W, MTYPE, 1 IDISP, RESID) INTEGER N, LICN, ICN(LICN), IKEEP(5*N), MTYPE, 1 IDISP(2) DOUBLE PRECISION A(LICN), RHS(N), W(N), RESID 3. Description T To solve a system of real linear equations Ax=b or A x=b, where A is a general sparse matrix, A must first be factorized by F01BRF or F01BSF. F04AXF then computes x by block forward or backward substitution using simple forward and backward substitution within each diagonal block. The method is fully described in Duff [1]. 4. References [1] Duff I S (1977) MA28 -- a set of Fortran subroutines for sparse unsymmetric linear equations. A.E.R.E. Report R.8730. HMSO. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix A. 2: A(LICN) -- DOUBLE PRECISION array Input On entry: the non-zero elements in the factorization of the matrix A, as returned by F01BRF or F01BSF. 3: LICN -- INTEGER Input On entry: the dimension of the arrays A and ICN as declared in the (sub)program from which F04AXF is called. 4: ICN(LICN) -- INTEGER array Input On entry: the column indices of the non-zero elements of the factorization, as returned by F01BRF or F01BSF. 5: IKEEP(5*N) -- INTEGER array Input On entry: the indexing information about the factorization, as returned by F01BRF or F01BSF. 6: RHS(N) -- DOUBLE PRECISION array Input/Output On entry: the right-hand side vector b. On exit: RHS is overwritten by the solution vector x. 7: W(N) -- DOUBLE PRECISION array Workspace 8: MTYPE -- INTEGER Input On entry: MTYPE specifies the task to be performed: if MTYPE = 1, solve Ax=b, T if MTYPE /= 1, solve A x=b. 9: IDISP(2) -- INTEGER array Input On entry: the values returned in IDISP by F01BRF. 10: RESID -- DOUBLE PRECISION Output On exit: the value of the maximum residual, -- max(|b - > a x |), over all the unsatisfied equations, in i -- ij j j case F01BRF or F01BSF has been used to factorize a singular or rectangular matrix. 6. Error Indicators and Warnings None. 7. Accuracy The accuracy of the computed solution depends on the conditioning of the original matrix. Since F04AXF is always used with either F01BRF or F01BSF, the user is recommended to set GROW = .TRUE. on entry to these routines and to examine the value of W(1) on exit (see the routine documents for F01BRF and F01BSF). For a detailed error analysis see Duff [1] page 17. If storage for the original matrix is available then the error can be estimated by calculating the residual T r=b-Ax (or b-A x) and calling F04AXF again to find a correction (delta) for x by solving T A(delta)=r (or A (delta)=r). 8. Further Comments If the factorized form contains (tau) non-zeros (IDISP(2) = (tau) ) then the time taken is very approximately 2(tau) times longer than the inner loop of full matrix code. Some advantage is taken T of zeros in the right-hand side when solving A x=b (MTYPE /= 1). 9. Example To solve the set of linear equations Ax=b where ( 5 0 0 0 0 0) ( 0 2 -1 2 0 0) ( 0 0 3 0 0 0) A=(-2 0 0 1 1 0) (-1 0 0 -1 2 -3) (-1 -1 0 0 0 6) and (15) (12) (18) b=( 3). (-6) ( 0) The non-zero elements of A and indexing information are read in by the program, as described in the document for F01BRF. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04faf}{NAG On-line Documentation: f04faf} \beginscroll \begin{verbatim} F04FAF(3NAG) Foundation Library (12/10/92) F04FAF(3NAG) F04 -- Simultaneous Linear Equations F04FAF F04FAF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04FAF calculates the approximate solution of a set of real symmetric positive-definite tridiagonal linear equations. 2. Specification SUBROUTINE F04FAF (JOB, N, D, E, B, IFAIL) INTEGER JOB, N, IFAIL DOUBLE PRECISION D(N), E(N), B(N) 3. Description F04FAF is based upon the Linpack routine DPTSL (see Dongarra et al [1]) and solves the equations Tx=b, where T is a real n by n symmetric positive-definite tridiagonal matrix, using a modified symmetric Gaussian elimination algorithm T to factorize T as T=MKM , where K is diagonal and M is a matrix of multipliers as described in Section 8. When the input parameter JOB is supplied as 1, then the routine assumes that a previous call to F04FAF has already factorized T; otherwise JOB must be supplied as 0. 4. References [1] Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide. SIAM, Philadelphia. 5. Parameters 1: JOB -- INTEGER Input On entry: specifies the job to be performed by F04FAF as follows: JOB = 0 The matrix T is factorized and the equations Tx=b are solved for x. JOB = 1 The matrix T is assumed to have already been factorized by a previous call to F04FAF with JOB = 0; the equations Tx=b are solved for x. 2: N -- INTEGER Input On entry: n, the order of the matrix T. Constraint: N >= 1. 3: D(N) -- DOUBLE PRECISION array Input/Output On entry: if JOB = 0, D must contain the diagonal elements of T. If JOB = 1, D must contain the diagonal matrix K, as returned by a previous call of F04FAF with JOB = 0. On exit: if JOB = 0, D is overwritten by the diagonal matrix K of the factorization. If JOB = 1, D is unchanged. 4: E(N) -- DOUBLE PRECISION array Input/Output On entry: if JOB = 0, E must contain the super-diagonal elements of T, stored in E(2) to E(n). If JOB = 1, E must contain the off-diagonal elements of the matrix M, as returned by a previous call of F04FAF with JOB = 0. E(1) is not used. On exit: if JOB = 0, E(2) to E(n) are overwritten by the off-diagonal elements of the matrix M of the factorization. If JOB = 1, E is unchanged. 5: B(N) -- DOUBLE PRECISION array Input/Output On entry: the right-hand side vector b. On exit: B is overwritten by the solution vector x. 6: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 On entry N < 1, or JOB /= 0 or 1. IFAIL= 2 The matrix T is either not positive-definite or is nearly singular. This failure can only occur when JOB = 0 and inspection of the elements of D will give an indication of why failure has occurred. If an element of D is close to zero, then T is probably nearly singular; if an element of D is negative but not close to zero, then T is not positive- definite. IFAILOverflow If overflow occurs during the execution of this routine, then either T is very nearly singular or an element of the right-hand side vector b is very large. In this latter case the equations should be scaled so that no element of b is very large. Note that to preserve symmetry it is necessary T to scale by a transformation of the form (PTP )b=Px, where P is a diagonal matrix. IFAILUnderflow Any underflows that occur during the execution of this routine are harmless. 7. Accuracy The computed factorization (see Section 8) will satisfy the equation T MKM =T+E where ||E|| <=2(epsilon)||T|| , p=1,F,infty, p p (epsilon) being the machine precision. The computed solution of the equations Tx=b, say x, will satisfy an equation of the form (T+F)x=b, where F can be expected to satisfy a bound of the form ||F||<=(alpha)(epsilon)||T||, (alpha) being a modest constant. This implies that the relative error in x satisfies ||x-x|| -------<=c(T)(alpha)(epsilon), ||x|| where c(T) is the condition number of T with respect to inversion. Thus if T is nearly singular, x can be expected to have a large relative error. 8. Further Comments The time taken by the routine is approximately proportional to n. The routine eliminates the off-diagonal elements of T by simultaneously performing symmetric Gaussian elimination from the top and the bottom of T. The result is that T is factorized as T T=MKM , where K is a diagonal matrix and M is a matrix of the form (1 0 0 .. 0 0 0 .. 0 0 0 ) (m 1 0 .. 0 0 0 .. 0 0 0 ) ( 2 ) (0 m 1 .. 0 0 0 .. 0 0 0 ) ( 3 ) (. . . .. . . . .. . . . ) (. . . .. . . . .. . . . ) (0 0 0 .. 1 0 0 .. 0 0 0 ) M=(0 0 0 .. m 1 m .. 0 0 0 ) ( j+1 j+2 ) (0 0 0 .. 0 0 .. 1 0 0 0 ) (. . . .. . . . .. . . . ) (. . . .. . . . .. . . . ) (0 0 0 .. 0 0 0 .. 1 m 0 ) ( n-1 ) (0 0 0 .. 0 0 0 .. 0 1 m ) ( n) (0 0 0 .. 0 0 0 . . 0 0 1 ) j being the integer part of n/2. (For example when n=5,j=2.) The diagonal elements of K are returned in D with k in the ith i element of D and m is returned in the ith element of E. i The routine fails with IFAIL = 2 if any diagonal element of K is non-positive. It should be noted that T may be nearly singular even if all the diagonal elements of K are positive, but in this case at least one element of K is almost certain to be small relative to |||T|||. If there is any doubt as to whether or not T is nearly singular, then the user should consider examining the diagonal elements of K. 9. Example To solve the symmetric positive-definite equations Tx =b 1 1 and Tx =b 2 2 where ( 4 -2 0 0 0) ( 6) (10) (-2 10 -6 0 0) ( 9) ( 4) T=( 0 -6 29 15 0), b =( 2), b =( 9). ( 0 0 15 25 8) 1 (14) 2 (65) ( 0 0 0 8 5) ( 7) (23) The equations are solved by two calls to F04FAF, the first with JOB = 0 and the second, using the factorization from the first call, with JOB = 1. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04jgf}{NAG On-line Documentation: f04jgf} \beginscroll \begin{verbatim} F04JGF(3NAG) Foundation Library (12/10/92) F04JGF(3NAG) F04 -- Simultaneous Linear Equations F04JGF F04JGF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04JGF finds the solution of a linear least-squares problem, Ax=b , where A is a real m by n (m>=n) matrix and b is an m element vector. If the matrix of observations is not of full rank, then the minimal least-squares solution is returned. 2. Specification SUBROUTINE F04JGF (M, N, A, NRA, B, TOL, SVD, SIGMA, 1 IRANK, WORK, LWORK, IFAIL) INTEGER M, N, NRA, IRANK, LWORK, IFAIL DOUBLE PRECISION A(NRA,N), B(M), TOL, SIGMA, WORK(LWORK) LOGICAL SVD 3. Description The minimal least-squares solution of the problem Ax=b is the vector x of minimum (Euclidean) length which minimizes the length of the residual vector r=b-Ax. The real m by n (m>=n) matrix A is factorized as (U) A=Q(0) where Q is an m by m orthogonal matrix and U is an n by n upper triangular matrix. If U is of full rank, then the least-squares solution is given by -1 T x=(U 0)Q b. If U is not of full rank, then the singular value decomposition of U is obtained so that U is factorized as T U=RDP , where R and P are n by n orthogonal matrices and D is the n by n diagonal matrix D=diag((sigma) ,(sigma) ,...,(sigma) ), 1 2 n with (sigma) >=(sigma) >=...(sigma) >=0, these being the singular 1 2 n values of A. If the singular values (sigma) ,...,(sigma) are k+1 n negligible, but (sigma) is not negligible, relative to the data k errors in A, then the rank of A is taken to be k and the minimal least-squares solution is given by ( -1 )( T ) (S 0)(R 0) T x=P(0 0 )(0 I )Q b, where S=diag((sigma) ,(sigma) ,...,(sigma) ). 1 2 k This routine obtains the factorizations by a call to F02WDF(*). The routine also returns the value of the standard error / T / r r (sigma)= / --- , if m>k, \/ m-k T = 0, if m=k, r r being the residual sum of squares and k the rank of A. 4. References [1] Lawson C L and Hanson R J (1974) Solving Least-squares Problems. Prentice-Hall. 5. Parameters 1: M -- INTEGER Input On entry: m, the number of rows of A. Constraint: M >= N. 2: N -- INTEGER Input On entry: n, the number of columns of A. Constraint: 1 <= N <= M. 3: A(NRA,N) -- DOUBLE PRECISION array Input/Output On entry: the m by n matrix A. On exit: if SVD is returned as .FALSE., A} is overwritten by details of the QU factorization of A (see F02WDF(*) for further details). If SVD is returned as .TRUE., the first n rows of A are overwritten by the right-hand singular vectors, stored by rows; and the remaining rows of the array are used as workspace. 4: NRA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F04JGF is called. Constraint: NRA >= M. 5: B(M) -- DOUBLE PRECISION array Input/Output On entry: the right-hand side vector b. On exit: the first n elements of B contain the minimal least-squares solution vector x. The remaining m-n elements are used for workspace. 6: TOL -- DOUBLE PRECISION Input On entry: a relative tolerance to be used to determine the rank of A. TOL should be chosen as approximately the largest relative error in the elements of A. For example, if the elements of A are correct to about 4 significant figures -4 then TOL should be set to about 5*10 . See Section 8 for a description of how TOL is used to determine rank. If TOL is outside the range ((epsilon),1.0), where (epsilon) is the machine precision, then the value (epsilon) is used in place of TOL. For most problems this is unreasonably small. 7: SVD -- LOGICAL Output On exit: SVD is returned as .FALSE. if the least-squares solution has been obtained from the QU factorization of A. In this case A is of full rank. SVD is returned as .TRUE. if the least-squares solution has been obtained from the singular value decomposition of A. 8: SIGMA -- DOUBLE PRECISION Output / T On exit: the standard error, i.e., the value \/ r r/(m-k) when m>k, and the value zero when m=k. Here r is the residual vector b-Ax and k is the rank of A. 9: IRANK -- INTEGER Output On exit: k, the rank of the matrix A. It should be noted that it is possible for IRANK to be returned as n and SVD to be returned as .TRUE.. This means that the matrix U only just failed the test for non-singularity. 10: WORK(LWORK) -- DOUBLE PRECISION array Output On exit: if SVD is returned as .FALSE., then the first n elements of WORK contain information on the QU factorization of A (see parameter A above and F02WDF(*)), and WORK(n+1) -1 contains the condition number ||U|| ||U || of the E E upper triangular matrix U. If SVD is returned as .TRUE., then the first n elements of WORK contain the singular values of A arranged in descending order and WORK(n+1) contains the total number of iterations taken by the QR algorithm. The rest of WORK is used as workspace. 11: LWORK -- INTEGER Input On entry: the dimension of the array WORK as declared in the (sub)program from which F04JGF is called. Constraint: LWORK >= 4*N. 12: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 On entry N < 1, or M < N, or NRA < M, or LWORK < 4*N. IFAIL= 2 The QR algorithm has failed to converge to the singular values in 50*N iterations. This failure can only happen when the singular value decomposition is employed, but even then it is not likely to occur. 7. Accuracy T The computed factors Q, U, R, D and P satisfy the relations (U) (R 0)(D) T Q(0)=A+E , Q(0 I)(0)P =A+F, where ||E|| <=c (epsilon)||A|| , 2 1 2 ||F|| <=c (epsilon)||A|| , 2 2 2 (epsilon) being the machine precision, and c and c being modest 1 2 functions of m and n. Note that ||A|| =(sigma) . 2 1 For a fuller discussion, covering the accuracy of the solution x see Lawson and Hanson [1], especially pp 50 and 95. 8. Further Comments If the least-squares solution is obtained from the QU factorization then the time taken by the routine is approximately 2 proportional to n (3m-n). If the least-squares solution is obtained from the singular value decomposition then the time 2 taken is approximately proportional to n (3m+19n). The approximate proportionality factor is the same in each case. This routine is column biased and so is suitable for use in paged environments. Following the QU factorization of A the condition number -1 c(U)=||U|| ||U || E E is determined and if c(U) is such that c(U)*TOL>1.0 then U is regarded as singular and the singular values of A are computed. If this test is not satisfied, U is regarded as non- singular and the rank of A is set to n. When the singular values are computed the rank of A, say k, is returned as the largest integer such that (sigma) >TOL*(sigma) , k 1 unless (sigma) =0 in which case k is returned as zero. That is, 1 singular values which satisfy (sigma) <=TOL*(sigma) are regarded i 1 as negligible because relative perturbations of order TOL can make such singular values zero. 9. Example To obtain a least-squares solution for r=b-Ax, where (0.05 0.05 0.25 -0.25) (1) (0.25 0.25 0.05 -0.05) (2) (0.35 0.35 1.75 -1.75) (3) A=(1.75 1.75 0.35 -0.35), B=(4) (0.30 -0.30 0.30 0.30) (5) (0.40 -0.40 0.40 0.40) (6) -4 and the value TOL is to be taken as 5*10 . The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04maf}{NAG On-line Documentation: f04maf} \beginscroll \begin{verbatim} F04MAF(3NAG) Foundation Library (12/10/92) F04MAF(3NAG) F04 -- Simultaneous Linear Equations F04MAF F04MAF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose To solve a sparse symmetric positive-definite system of linear equations, Ax=b, using a pre-conditioned conjugate gradient method, where A has been factorized by F01MAF. 2. Specification SUBROUTINE F04MAF (N, NZ, A, LICN, IRN, LIRN, ICN, B, ACC, 1 NOITS, WKEEP, WORK, IKEEP, INFORM, 2 IFAIL) INTEGER N, NZ, LICN, IRN(LIRN), LIRN, ICN(LICN), 1 NOITS(2), IKEEP(2*N), INFORM(4), IFAIL DOUBLE PRECISION A(LICN), B(N), ACC(2), WKEEP(3*N), WORK 1 (3*N) 3. Description F04MAF solves the n linear equations Ax=b, (1) where A is a sparse symmetric positive-definite matrix, following the incomplete Cholesky factorization by F01MAF, given by T T C=PLDL P , WAW=C+E, where P is a permutation matrix, L is a unit lower triangular matrix, D is a diagonal matrix with positive diagonal elements, E is an error matrix representing elements dropped during the factorization and diagonal elements that have been modified to ensure that C is positive-definite, and W is a diagonal matrix, chosen to make the diagonal elements of WAW unity. Equation (1) is solved by applying a pre-conditioned conjugate gradient method to the equations -1 (WAW)(W x)=Wb, (2) using C as the pre-conditioning matrix. Details of the conjugate gradient method are given in Munksgaard [1]. The iterative procedure is terminated if ||Wr|| <=(eta), (3) 2 where r is the residual vector r=b-Ax, ||r|| denotes the 2 Euclidean length of r, (eta) is a user-supplied tolerance and x is the current approximation to the solution. Notice that -1 Wr=Wb-(WAW)(W x) so that Wr is the residual of the normalised equations (2). F04MAF is based on the Harwell Library routine MA31B. 4. References [1] Munksgaard N (1980) Solving Sparse Symmetric Sets of Linear Equations by Pre-conditioned Conjugate Gradients. ACM Trans. Math. Softw. 6 206--219. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 1. 2: NZ -- INTEGER Input On entry: the number of non-zero elements in the upper triangular part of the matrix A, including the number of elements on the leading diagonal. Constraint: NZ >= N. 3: A(LICN) -- DOUBLE PRECISION array Input On entry: the first LROW elements, where LROW is the value supplied in INFORM(1), must contain details of the factorization, as returned by F01MAF. 4: LICN -- INTEGER Input On entry: the length of the array A, as declared in the (sub)program from which F04MAF is called. It need never be larger than the value of LICN supplied to F01MAF. Constraint: LICN >= INFORM(1). 5: IRN(LIRN) -- INTEGER array Input On entry: the first LCOL elements, where LCOL is the value supplied in INFORM(2), must contain details of the factorization, as returned by F01MAF. 6: LIRN -- INTEGER Input On entry: the length of the array IRN, as declared in the (sub)program from which F04MAF is called. It need never be larger than the value of LIRN supplied to F01MAF. Constraint: LIRN >= INFORM(2). 7: ICN(LICN) -- INTEGER array Input On entry: the first LROW elements, where LROW is the value supplied in INFORM(1), must contain details of the factorization, as returned by F01MAF. 8: B(N) -- DOUBLE PRECISION array Input/Output On entry: the right-hand side vector b. On exit: B is overwritten by the solution vector x. 9: ACC(2) -- DOUBLE PRECISION array Input/Output On entry: ACC(1) specifies the tolerance for convergence, (eta), in equation (3) of Section 3. If ACC(1) is outside the range [(epsilon),1], where (epsilon) is the machine precision, then the value (epsilon) is used in place of ACC (1). ACC(2) need not be set. On exit: ACC(2) contains the actual value of ||Wr|| at the final point. ACC(1) is 2 unchanged. 10: NOITS(2) -- INTEGER array Input/Output On entry: NOITS(1) specifies the maximum permitted number of iterations. If NOITS(1) < 1, then the value 100 is used in its place. NOITS(2) need not be set. On exit: NOITS(2) contains the number of iterations taken to converge. NOITS (1) is unchanged. 11: WKEEP(3*N) -- DOUBLE PRECISION array Input On entry: WKEEP must be unchanged from the previous call of F01MAF. 12: WORK(3*N) -- DOUBLE PRECISION array Output On exit: WORK(1) contains a lower bound for the condition number of A. The rest of the array is used for workspace. 13: IKEEP(2*N) -- INTEGER array Input On entry: IKEEP must be unchanged from the previous call of F01MAF. 14: INFORM(4) -- INTEGER array Input On entry: INFORM must be unchanged from the previous call of F01MAF. 15: IFAIL -- INTEGER Input/Output For this routine, the normal use of IFAIL is extended to control the printing of error and warning messages as well as specifying hard or soft failure (see the Essential Introduction). Before entry, IFAIL must be set to a value with the decimal expansion cba, where each of the decimal digits c, b and a must have a value of 0 or 1. a=0 specifies hard failure, otherwise soft failure; b=0 suppresses error messages, otherwise error messages will be printed (see Section 6); c=0 suppresses warning messages, otherwise warning messages will be printed (see Section 6). The recommended value for inexperienced users is 110 (i.e., hard failure with all messages printed). Unless the routine detects an error (see Section 6), IFAIL contains 0 on exit. 6. Error Indicators and Warnings Errors detected by the routine: For each error, an explanatory error message is output on the current error message unit (as defined by X04AAF), unless suppressed by the value of IFAIL on entry. IFAIL= 1 On entry N < 1, or NZ < N, or LICN < INFORM(1), or LIRN < INFORM(2). IFAIL= 2 Convergence has not taken place within the requested NOITS (1) number of iterations. ACC(2) gives the value ||Wr|| , 2 for the final point. Either too few iterations have been allowed, or the requested convergence criterion cannot be met. IFAIL= 3 The matrix A is singular, or nearly singular. Singularity has been detected during the conjugate gradient iterations, so that the computations are not complete. IFAIL= 4 The matrix A is singular, or nearly singular. The message output on the current error message channel will include an estimate of the condition number of A. In the case of soft failure an approximate solution is returned such that the value ||Wr|| is given by ACC(2) and the estimate (a lower 2 bound) of the condition number is returned in WORK(1). 7. Accuracy On successful return, or on return with IFAIL = 2 or IFAIL = 4 the computed solution will satisfy equation (3) of Section 3, with (eta) = ACC(2). 8. Further Comments The time taken by the routine will depend upon the sparsity of the factorization and the number of iterations required. The number of iterations will be affected by the nature of the factorization supplied by F01MAF. The more incomplete the factorization, the higher the number of iterations required by F04MAF. When the solution of several systems of equations, all with the same matrix of coefficients, A, is required, then F01MAF need be called only once to factorize A. This is illustrated in the context of an eigenvalue problem in the example program for F02FJF. 9. Example The example program illustrates the use of F01MAF in conjunction with F04MAF to solve the 16 linear equations Ax=b, where (1 a a ) (a 1 a a ) ( a 1 a a ) ( a 1 0 a ) (a 0 1 a a ) ( a a 1 a a ) ( a a 1 a a ) ( a a 1 0 a ) A=( a 0 1 a a ) ( a a 1 a a ) ( a a 1 a a ) ( a a 1 0 a) ( a 0 1 a ) ( a a 1 a ) ( a a 1 a) ( a a 1) 1 where a=- -. 4 T ( 1 1 1 1 1 1 1 1 1 1 1 1) b =( - - - - - 0 0 - - 0 0 - - - - -) ( 2 4 4 2 4 4 4 4 2 4 4 2) The n by n matrix A arises in the solution of Laplace's equation in a unit-square, using a five-point formula with a 6 by 6 discretisation, with unity on the boundaries. The drop tolerance, DROPTL, is taken as 0.1 and the density factor, DENSW, is taken as 0.8. The value IFAIL = 111 is used so that advisory and error messages will be printed, but soft failure would occur if IFAIL were returned as non-zero. A relative accuracy of about 0.0001 is requested in the solution from F04MAF, with a maximum of 50 iterations. The example program for F02FJF illustrates the use of routines F01MAF and F04MAF in solving an eigenvalue problem. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04mbf}{NAG On-line Documentation: f04mbf} \beginscroll \begin{verbatim} F04MBF(3NAG) Foundation Library (12/10/92) F04MBF(3NAG) F04 -- Simultaneous Linear Equations F04MBF F04MBF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04MBF solves a system of real sparse symmetric linear equations using a Lanczos algorithm. 2. Specification SUBROUTINE F04MBF (N, B, X, APROD, MSOLVE, PRECON, SHIFT, 1 RTOL, ITNLIM, MSGLVL, ITN, ANORM, 2 ACOND, RNORM, XNORM, WORK, RWORK, 3 LRWORK, IWORK, LIWORK, INFORM, IFAIL) INTEGER N, ITNLIM, MSGLVL, ITN, LRWORK, IWORK 1 (LIWORK), LIWORK, INFORM, IFAIL DOUBLE PRECISION B(N), X(N), SHIFT, RTOL, ANORM, ACOND, 1 RNORM, XNORM, WORK(N,5), RWORK(LRWORK) LOGICAL PRECON EXTERNAL APROD, MSOLVE 3. Description F04MBF solves the system of linear equations (A-(lambda)I)x=b (3.1) where A is an n by n sparse symmetric matrix and (lambda) is a scalar, which is of course zero if the solution of the equations Ax=b is required. It should be noted that neither A nor (A-(lambda)I) need be positive-definite. (lambda) is supplied as the parameter SHIFT, and allows F04MBF to be used for finding eigenvectors of A in methods such as Rayleigh quotient iteration (see for example Lewis [1]), in which case (lambda) will be an approximation to an eigenvalue of A and b an approximation to an eigenvector of A. The routine also provides an option to allow pre-conditioning and this will often reduce the number of iterations required by F04MBF. F04MBF is based upon algorithm SYMMLQ (see Paige and Saunders [2]) and solves the equations by an algorithm based upon the Lanczos process. Details of the method are given in Paige and Saunders [2]. The routine does not require A explicitly, but A is specified via a user-supplied routine APROD which, given an n element vector c, must return the vector z given by z=Ac. The pre-conditioning option is based on the following reasoning. If A can be expressed in the form A=I+B where B is of rank (rho), then the Lanczos process converges (in exact arithmetic) in at most (rho) iterations. If more generally A can be expressed in the form A=M+C where M is symmetric positive-definite and C has rank (rho), then -(1/2) -(1/2) -(1/2) -(1/2) M AM =I+M CM -(1/2) -(1/2) and M AM also has rank (rho), and the Lanczos process -(1/2) -(1/2) applied to M AM would again converge in at most (rho) iterations. On a computer, the number of iterations may be greater than (rho), but the Lanczos process may still be expected -(1/2) -(1/2) to converge rapidly. F04MBF does not require M AM to be formed explicitly, but implicitly solves the equations -(1/2) -(1/2) -(1/2) 1/2 M (A-(lambda)I)M y=M b , y=M x (3.2) with the user being required to supply a routine MSOLVE to solve the equations Mz=c. (3.3) For the pre-conditioning option to be effective, it is desirable that equations (3.3) can be solved efficiently. The example program in Section 9 illustrates the use of this option. If we let r denote the residual vector r=b-(A-(lambda)I)x corresponding to an iterate x, then, when pre-conditioning has not been requested, the iterative procedure is terminated if it is estimated that ||r||<=tol.||A-(lambda)I||.||x||, (3.4) where tol is a user-supplied tolerance, ||r|| denotes the Euclidean length of the vector r and ||A|| denotes the Frobenius (Euclidean) norm of the matrix A. When pre-conditioning has been requested, the iterative procedure is terminated if it is estimated that -(1/2) -(1/2) -(1/2) 1/2 ||M r||<=tol.||M (A-(lambda)I)M ||.||M x||. (3.5) Note that -(1/2) -(1/2) -(1/2) -(1/2) 1/2 M r=(M b)-M (A-(lambda)I)M (M x) -(1/2) so that M r is the residual vector corresponding to equation (3.2). The routine will also terminate if it is estimated that ||A-(lambda)I||.||x||>=||b||/(epsilon), (3.6) where (epsilon) is the machine precision, when pre-conditioning has not been requested; or if it is estimated that -(1/2) -(1/2) 1/2 -(1/2) ||M (A-(lambda)I)M ||.||M x||>=||M b||/(epsilon) (3.7) when pre-conditioning has been requested. If (3.6) is satisfied then x is almost certainly an eigenvector of A corresponding to the eigenvalue (lambda). If (lambda) was set to 0 (for the solution of Ax=b), then this condition simply means that A is effectively singular. 4. References [1] Lewis J G (1977) Algorithms for sparse matrix eigenvalue problems. Technical Report STAN-CS-77-595. Computer Science Department, Stanford University. [2] Paige C C and Saunders M A (1975) Solution of Sparse Indefinite Systems of Linear Equations. SIAM J. Numer. Anal. 12 617--629. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 1. 2: B(N) -- DOUBLE PRECISION array Input On entry: the right-hand side vector b. 3: X(N) -- DOUBLE PRECISION array Output On exit: the solution vector x. 4: APROD -- SUBROUTINE, supplied by the user. External Procedure APROD must return the vector y=Ax for a given vector x. Its specification is: SUBROUTINE APROD (IFLAG, N, X, Y, RWORK, LRWORK, 1 IWORK,LIWORK) INTEGER IFLAG, N, LRWORK, LIWORK, IWORK 1 (LIWORK) DOUBLE PRECISION X(N), Y(N), RWORK(LRWORK) 1: IFLAG -- INTEGER Input/Output On entry: IFLAG is always non-negative. On exit: IFLAG may be used as a flag to indicate a failure in the computation of Ax. If IFLAG is negative on exit from APROD, F04MBF will exit immediately with IFAIL set to IFLAG. 2: N -- INTEGER Input On entry: n, the order of the matrix A. 3: X(N) -- DOUBLE PRECISION array Input On entry: the vector x for which Ax is required. 4: Y(N) -- DOUBLE PRECISION array Output On exit: the vector y=Ax. 5: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace 6: LRWORK -- INTEGER Input 7: IWORK(LIWORK) -- INTEGER array User Workspace 8: LIWORK -- INTEGER Input APROD is called from F04MBF with the parameters RWORK, LRWORK, IWORK and LIWORK as supplied to F04MBF. The user is free to use the arrays RWORK and IWORK to supply information to APROD and MSOLVE as an alternative to using COMMON. APROD must be declared as EXTERNAL in the (sub)program from which F04MBF is called. Parameters denoted as Input must not be changed by this procedure. 5: MSOLVE -- SUBROUTINE, supplied by the user. External Procedure MSOLVE is only referenced when PRECON is supplied as .TRUE.. When PRECON is supplied as .FALSE., then F04MBF may be called with APROD as the actual argument for MSOLVE. When PRECON is supplied as .TRUE., then MSOLVE must return the solution y of the equations My=x for a given vector x, where M must be symmetric positive-definite. Its specification is: SUBROUTINE MSOLVE (IFLAG, N, X, Y, RWORK, 1 LRWORK, IWORK,LIWORK) INTEGER IFLAG, N, LRWORK, LIWORK, IWORK 1 (LIWORK) DOUBLE PRECISION X(N), Y(N), RWORK(LRWORK) 1: IFLAG -- INTEGER Input/Output On entry: IFLAG is always non-negative. On exit: IFLAG may be used as a flag to indicate a failure in the solution of My=x. If IFLAG is negative on exit from MSOLVE, F04MBF will exit immediately with IFAIL set to IFLAG. 2: N -- INTEGER Input On entry: n, the order of the matrix M. 3: X(N) -- DOUBLE PRECISION array Input On entry: the vector x for which the equations My=x are to be solved. 4: Y(N) -- DOUBLE PRECISION array Output On exit: the solution to the equations My=x. 5: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace 6: LRWORK -- INTEGER Input 7: IWORK(LIWORK) -- INTEGER array User Workspace 8: LIWORK -- INTEGER Input MSOLVE is called from F04MBF with the parameters RWORK, LRWORK, IWORK and LIWORK as supplied to F04MBF. The user is free to use the arrays RWORK and IWORK to supply information to APROD and MSOLVE as an alternative to using COMMON. MSOLVE must be declared as EXTERNAL in the (sub)program from which F04MBF is called. Parameters denoted as Input must not be changed by this procedure. 6: PRECON -- LOGICAL Input On entry: PRECON specifies whether or not pre-conditioning is required. If PRECON = .TRUE., then pre-conditioning will be invoked and MSOLVE will be referenced by F04MBF; if PRECON = .FALSE., then MSOLVE is not referenced. 7: SHIFT -- DOUBLE PRECISION Input On entry: the value of (lambda). If the equations Ax=b are to be solved, then SHIFT must be supplied as zero. 8: RTOL -- DOUBLE PRECISION Input On entry: the tolerance for convergence, tol, of equation (3.4). RTOL should not normally be less than (epsilon), where (epsilon) is the machine precision. 9: ITNLIM -- INTEGER Input On entry: an upper limit on the number of iterations. If ITNLIM <= 0, then the value N is used in place of ITNLIM. 10: MSGLVL -- INTEGER Input On entry: the level of printing from F04MBF. If MSGLVL <= 0, then no printing occurs, but otherwise messages will be output on the advisory message channel (see X04ABF). A description of the printed output is given in Section 5.1 below. The level of printing is determined as follows: MSGLVL <= 0 No printing. MSGLVL = 1 A brief summary is printed just prior to return from F04MBF. MSGLVL >= 2 A summary line is printed periodically to monitor the progress of F04MBF, together with a brief summary just prior to return from F04MBF. 11: ITN -- INTEGER Output On exit: the number of iterations performed. 12: ANORM -- DOUBLE PRECISION Output On exit: an estimate of ||A-(lambda)I|| when PRECON = -(1/2) -(1/2) .FALSE., and ||M (A-(lambda)I)M || when PRECON = .TRUE.. 13: ACOND -- DOUBLE PRECISION Output On exit: an estimate of the condition number of (A- (lambda)I) when PRECON = .FALSE., and of -(1/2) -(1/2) M (A-(lambda)I)M when PRECON = .TRUE.. This will usually be a substantial under-estimate. 14: RNORM -- DOUBLE PRECISION Output On exit: ||r||, where r=b-(A-(lambda)I)x and x is the solution returned in X. 15: XNORM -- DOUBLE PRECISION Output On exit: ||x||, where x is the solution returned in X. 16: WORK(5*N) -- DOUBLE PRECISION array Workspace 17: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace RWORK is not used by F04MBF, but is passed directly to routines APROD and MSOLVE and may be used to pass information to these routines. 18: LRWORK -- INTEGER Input On entry: the length of the array RWORK as declared in the (sub)program from which F04MBF is called. Constraint: LRWORK >= 1. 19: IWORK(LIWORK) -- INTEGER array User Workspace IWORK is not used by F04MBF, but is passed directly to routines APROD and MSOLVE and may be used to pass information to these routines. 20: LIWORK -- INTEGER Input On entry: the length of the array IWORK as declared in the (sub)program from which F04MBF is called. Constraint: LIWORK >= 1. 21: INFORM -- INTEGER Output On exit: the reason for termination of F04MBF as follows: INFORM = 0 The right-hand side vector b=0 so that the exact solution is x=0. No iterations are performed in this case. INFORM = 1 The termination criterion of equation (3.4) has been satisfied with tol as the value supplied in RTOL. INFORM = 2 The termination criterion of equation (3.4) has been satisfied with tol equal to (epsilon), where (epsilon) is the machine precision. The value supplied in RTOL must have been less than (epsilon) and was too small for the machine. INFORM = 3 The termination criterion of equation (3.5) has been satisfied so that X is almost certainly an eigenvector of A corresponding to the eigenvalue SHIFT. The values INFORM = 4 and INFORM = 5 correspond to failure with IFAIL = 3 or IFAIL = 2 respectively (see Section 6) and when IFAIL is negative, INFORM will be set to the same negative value. 22: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 5.1. Description of the Printed Output When MSGLVL > 0, then F04MBF will produce output (except in the case where the routine fails with IFAIL = 1) on the advisory message channel (see X04ABF ). The following notation is used in the output. Output Meaning -(1/2) RBAR M (b-(A-(lambda)I)x)=r -(1/2) -(1/2) ABAR M (A-(lambda)I)M =A 1/2 Y M x R b-(A-(lambda)I)x NORM(A) ||A|| Of course, when pre-conditioning has not been requested then the first three reduce to (b-(A-(lambda)I)x), (A-(lambda)I) and x respectively. When MSGLVL >= 2 then some initial information is printed and the following notation is used. Output Meaning T -1 1/2 BETA1 (b M b) ==(beta) 1 2 -(1/2) T -(1/2) -(1/2) -(1/2) ALFA1 (1/(beta) ) (M b) (M AM )(M b) 1 ==(alpha) 1 and a summary line is printed periodically giving the following information: Output Meaning ITN Iteration number, k. L L X1(LQ) The first element of the vector x , where x is the k k current iterate. See Paige and Saunders [2] for details. C C X1(CG) The first element of the vector x , where x is the k k vector that would be obtained by conjugate gradients. See Paige and Saunders [2] for details. NORM(RBAR) ||r||, where r is as defined above and x is either L C x or x depending upon which is the best current k k approximation to the solution. (See LQ/CG below). NORM(T) The value ||T ||, where T is the tridiagonal k k matrix of the Lanczos process. This increases monotonically and is a lower bound on ||A||. COND(L) A monotonically increasing lower bound on the -1 condition number of A, ||A||||(A) ||. L LQ/CG L is printed if x is the best current k approximation to the solution and C is printed otherwise. 6. Error Indicators and Warnings Errors detected by the routine: IFAIL< 0 A negative value of IFAIL indicates an exit from F04MBF because the user has set IFLAG negative in APROD or MSOLVE. The value of IFAIL will be the same as the user's setting of IFLAG. IFAIL= 1 On entry N < 1, or LRWORK < 1, or LIWORK < 1. IFAIL= 2 The pre-conditioning matrix M does not appear to be positive-definite. The user should check that MSOLVE is working correctly. IFAIL= 3 The limit on the number of iterations has been reached. If IFAIL = 1 on entry then the latest approximation to the solution is returned in X and the values ANORM, ACOND, RNORM and XNORM are also returned. The value of INFORM contains additional information about the termination of the routine and users must examine INFORM to judge whether the routine has performed successfully for the problem in hand. In particular INFORM = 3 denotes that the matrix A- (lambda)I is effectively singular: if the purpose of calling F04MBF is to solve a system of equations Ax=b, then this condition must be regarded as a failure, but if the purpose is to compute an eigenvector, this result would be very satisfactory. 7. Accuracy The computed solution x will satisfy the equation r=b-(A-(lambda)I)x where the value ||r|| is as returned in the parameter RNORM. 8. Further Comments The time taken by the routine is likely to be principally determined by the time taken in APROD and, when pre-conditioning has been requested, in MSOLVE. Each of these routines is called once every iteration. The time taken by the remaining operations in F04MBF is approximately proportional to n. 9. Example To solve the 10 equations Ax=b given by (2 1 0 0 0 0 0 0 0 3) (6) (1 2 1 0 0 0 0 0 0 0) (4) (0 1 2 1 0 0 0 0 0 0) (4) (0 0 1 2 1 0 0 0 0 0) (4) (0 0 0 1 2 1 0 0 0 0) (4) A=(0 0 0 0 1 2 1 0 0 0), b=(4). (0 0 0 0 0 1 2 1 0 0) (4) (0 0 0 0 0 0 1 2 1 0) (4) (0 0 0 0 0 0 0 1 2 1) (4) (3 0 0 0 0 0 0 0 1 2) (6) The tridiagonal part of A is positive-definite and such tridiagonal equations can be solved efficiently by F04FAF. The form of A suggests that this tridiagonal part is a good candidate for the pre-conditioning matrix M and so we illustrate the use of F04MBF by pre-conditioning with the 10 by 10 matrix (2 1 0 ... 0) (1 2 1 ... 0) (0 1 2 ... 0) M=(. . . . ). (. . . . ) (. . . . ) (0 0 0 ... 2) Since A-M has only 2 non-zero elements and is obviously of rank 2, we can expect F04MBF to converge very quickly in this example. Of course, in practical problems we shall not usually be able to make such a good choice of M. -5 The example sets the tolerance RTOL = 10 . The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04mcf}{NAG On-line Documentation: f04mcf} \beginscroll \begin{verbatim} F04MCF(3NAG) Foundation Library (12/10/92) F04MCF(3NAG) F04 -- Simultaneous Linear Equations F04MCF F04MCF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04MCF computes the approximate solution of a system of real linear equations with multiple right-hand sides, AX=B, where A is a symmetric positive-definite variable-bandwidth matrix, which has previously been factorized by F01MCF. Related systems may also be solved. 2. Specification SUBROUTINE F04MCF (N, AL, LAL, D, NROW, IR, B, NRB, 1 ISELCT, X, NRX, IFAIL) INTEGER N, LAL, NROW(N), IR, NRB, ISELCT, NRX, 1 IFAIL DOUBLE PRECISION AL(LAL), D(N), B(NRB,IR), X(NRX,IR) 3. Description The normal use of this routine is the solution of the systems AX=B, following a call of F01MCF to determine the Cholesky T factorization A=LDL of the symmetric positive-definite variable- bandwidth matrix A. However, the routine may be used to solve any one of the following systems of linear algebraic equations: T (1) LDL X = B (usual system), (2) LDX = B (lower triangular system), T (3) DL X = B (upper triangular system), T (4) LL X = B (5) LX = B (unit lower triangular system), T (6) L X = B (unit upper triangular system). L denotes a unit lower triangular variable-bandwidth matrix of order n, D a diagonal matrix of order n, and B a set of right- hand sides. The matrix L is represented by the elements lying within its envelope i.e., between the first non-zero of each row and the diagonal (see Section 9 for an example). The width NROW(i) of the ith row is the number of elements between the first non-zero element and the element on the diagonal inclusive. 4. References [1] Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra. Springer-Verlag. 5. Parameters 1: N -- INTEGER Input On entry: n, the order of the matrix L. Constraint: N >= 1. 2: AL(LAL) -- DOUBLE PRECISION array Input On entry: the elements within the envelope of the lower triangular matrix L, taken in row by row order, as returned by F01MCF. The unit diagonal elements of L must be stored explicitly. 3: LAL -- INTEGER Input On entry: the dimension of the array AL as declared in the (sub)program from which F04MCF is called. Constraint: LAL >= NROW(1) + NROW(2) +... + NROW(n). 4: D(N) -- DOUBLE PRECISION array Input On entry: the diagonal elements of the diagonal matrix D. D is not referenced if ISELCT >= 4. 5: NROW(N) -- INTEGER array Input On entry: NROW(i) must contain the width of row i of L, i.e.,the number of elements between the first (leftmost) non-zero element and the element on the diagonal, inclusive. Constraint: 1 <= NROW(i)<=i. 6: IR -- INTEGER Input On entry: r, the number of right-hand sides. Constraint: IR >= 1. 7: B(NRB,IR) -- DOUBLE PRECISION array Input On entry: the n by r right-hand side matrix B. See also Section 8. 8: NRB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F04MCF is called. Constraint: NRB >= N. 9: ISELCT -- INTEGER Input On entry: ISELCT must specify the type of system to be solved, as follows: T ISELCT = 1: solve LDL X = B, ISELCT = 2: solve LDX = B, T ISELCT = 3: solve DL X = B, T ISELCT = 4: solve LL X = B, ISELCT = 5: solve LX = B, T ISELCT = 6: solve L X = B. 10: X(NRX,IR) -- DOUBLE PRECISION array Output On exit: the n by r solution matrix X. See also Section 8. 11: NRX -- INTEGER Input On entry: the first dimension of the array X as declared in the (sub)program from which F04MCF is called. Constraint: NRX >= N. 12: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL= 1 On entry N < 1, or for some i, NROW(i)<1 or NROW(i) > i, or LAL < NROW(1) + NROW(2) +... + NROW(N). IFAIL= 2 On entry IR < 1, or NRB < N, or NRX < N. IFAIL= 3 On entry ISELCT < 1, or ISELCT > 6. IFAIL= 4 The diagonal matrix D is singular, i.e., at least one of the elements of D is zero. This can only occur if ISELCT <= 3. IFAIL= 5 At least one of the diagonal elements of L is not equal to unity. 7. Accuracy The usual backward error analysis of the solution of triangular system applies: each computed solution vector is exact for slightly perturbed matrices L and D, as appropriate (cf. Wilkinson and Reinsch [1] pp 25--27, 54--55). 8. Further Comments The time taken by the routine is approximately proportional to pr, where p=NROW(1)+NROW(2)+...+NROW(n). Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same actual array supplied for the parameters B and X, in which case the solution matrix will overwrite the right-hand side matrix. However this is not standard Fortran 77 and may not work in all implementations. 9. Example To solve the system of equations AX=B, where (1 2 0 0 5 0) (2 5 3 0 14 0) (0 3 13 0 18 0) A=(0 0 0 16 8 24) (5 14 18 8 55 17) (0 0 0 24 17 77) and ( 6 -10) (15 -21) (11 -3) B=( 0 24) (51 -39) (46 67) Here A is symmetric and positive-definite and must first be factorized by F01MCF. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf04qaf}{NAG On-line Documentation: f04qaf} \beginscroll \begin{verbatim} F04QAF(3NAG) Foundation Library (12/10/92) F04QAF(3NAG) F04 -- Simultaneous Linear Equations F04QAF F04QAF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F04QAF solves sparse unsymmetric equations, sparse linear least- squares problems and sparse damped linear least-squares problems, using a Lanczos algorithm. 2. Specification SUBROUTINE F04QAF (M, N, B, X, SE, APROD, DAMP, ATOL, 1 BTOL, CONLIM, ITNLIM, MSGLVL, ITN, 2 ANORM, ACOND, RNORM, ARNORM, XNORM, 3 WORK, RWORK, LRWORK, IWORK, LIWORK, 4 INFORM, IFAIL) INTEGER M, N, ITNLIM, MSGLVL, ITN, LRWORK, IWORK 1 (LIWORK), LIWORK, INFORM, IFAIL DOUBLE PRECISION B(M), X(N), SE(N), DAMP, ATOL, BTOL, 1 CONLIM, ANORM, ACOND, RNORM, ARNORM, 2 XNORM, WORK(N,2), RWORK(LRWORK) EXTERNAL APROD 3. Description F04QAF can be used to solve a system of linear equations Ax=b (3.1) where A is an n by n sparse unsymmetric matrix, or can be used to solve linear least-squares problems, so that F04QAF minimizes the value (rho) given by (rho)=||r||, r=b-Ax (3.2) where A is an m by n sparse matrix and ||r|| denotes the 2 T Euclidean length of r so that ||r|| =r r. A damping parameter, (lambda), may be included in the least-squares problem in which case F04QAF minimizes the value (rho) given by 2 2 2 2 (rho) =||r|| +(lambda) ||x|| (3.3) (lambda) is supplied as the parameter DAMP and should of course be zero if the solution to problems (3.1) or (3.2) is required. Minimizing (rho) in (3.3) is often called ridge regression. F04QAF is based upon algorithm LSQR (see Paige and Saunders [1] and [2]) and solves the problems by an algorithm based upon the Lanczos process. Details of the method are given in [1]. The routine does not require A explicitly, but A is specified via a user-supplied routine APROD which must perform the operations ( T y+Ax) and (x+A y) for a given n element vector x and m element vector y. A parameter to APROD specifies which of the two operations is required on a given entry. The routine also returns estimates of the standard errors of the sample regression coefficients (x , for i=1,2,...,n) given by the i diagonal elements of the estimated variance-covariance matrix V. When problem (3.2) is being solved and A is of full rank, then V is given by 2 T -1 2 2 V=s (A A) , s =(rho) /(m-n), m>n and when problem (3.3) is being solved then V is given by 2 T 2 -1 2 2 V=s (A A+(lambda) I) , s =(rho) /m, (lambda)/=0. Let A denote the matrix (A ) A=A, (lambda)=0 ; A=((lambda)I), (lambda)/=0, (3.4) let r denote the residual vector (b) r=r, (lambda)=0 ; r=(0)-Ax, (lambda)/=0 (3.5) corresponding to an iterate x, so that (rho)=||r|| is the function being minimized, and let ||A|| denote the Frobenius (Euclidean) norm of A. Then the routine accepts x as a solution if it is estimated that one of the following two conditions is satisfied: (rho)<=tol ||A||.||x||+tol ||b|| (3.6) 1 2 T ||A r||<=tol ||A||(rho) (3.7) 1 where tol and tol are user-supplied tolerances which estimate 1 2 the relative errors in A and b respectively. Condition (3.6) is appropriate for compatible problems where, in theory, we expect the residual to be zero and will be satisfied by an acceptable solution x to a compatible problem. Condition (3.7) is appropriate for incompatible systems where we do not expect the residual to be zero and is based upon the observation that, in theory, T A r=0 when x is a solution to the least-squares problem, and so (3.7) will be satisfied by an acceptable solution x to a linear least- squares problem. The routine also includes a test to prevent convergence to solutions, x, with unacceptably large elements. This can happen if A is nearly singular or is nearly rank deficient. If we let the singular values of A be (sigma) >=(sigma) >=...>=(sigma) >=0 1 2 n then the condition number of A is defined as cond(A)=(sigma) /(sigma) 1 k where (sigma) is the smallest non-zero singular value of A and k hence k is the rank of A. When k=c (3.8) lim where c is a user-supplied limit on the condition number of A. lim For problem (3.1) termination with this condition indicates that A is nearly singular and for problem (3.2) indicates that A is nearly rank deficient and so has near linear dependencies in its T columns. In this case inspection of ||r||, ||A r|| and ||x||, which are all returned by the routine, will indicate whether or not an acceptable solution has been found. Condition (3.8), perhaps in conjunction with (lambda)/=0, can be used to try and ' regularise' least-squares solutions. A full discussion of the stopping criteria is given in Section 6 of reference Paige and Saunders [1]. Introduction of a non-zero damping parameter (lambda) tends to reduce the size of the computed solution and to make its components less sensitive to changes in the data, and F04QAF is applicable when a value of (lambda) is known a priori. To have an effect, (lambda) should normally be at least \/(epsilon)||A|| where (epsilon) is the machine precision. For further discussion see Paige and Saunders [2] and the references given there. Whenever possible the matrix A should be scaled so that the relative errors in the elements of A are all of comparable size. Such a scaling helps to prevent the least-squares problem from being unnecessarily sensitive to data errors and will normally reduce the number of iterations required. At the very least, in the absence of better information, the columns of A should be scaled to have roughly equal column length. 4. References [1] Paige C C and Saunders M A (1982) LSQR: An Algorithm for Sparse Linear Equations and Sparse Least-squares. ACM Trans. Math. Softw. 8 43--71. [2] Paige C C and Saunders M A (1982) ALGORITHM 583 LSQR: Sparse Linear Equations and Least-squares Problems. ACM Trans. Math. Softw. 8 195--209. 5. Parameters 1: M -- INTEGER Input On entry: m, the number of rows of the matrix A. Constraint: M >= 1. 2: N -- INTEGER Input On entry: n, the number of columns of the matrix A. Constraint: N >= 1. 3: B(M) -- DOUBLE PRECISION array Input/Output On entry: the right-hand side vector b. On exit: the array is overwritten. 4: X(N) -- DOUBLE PRECISION array Output On exit: the solution vector x. 5: SE(N) -- DOUBLE PRECISION array Output On exit: the estimates of the standard errors of the components of x. Thus SE(i) contains an estimate of the element v of the estimated variance-covariance matrix V. ii The estimates returned in SE will be the lower bounds on the actual estimated standard errors, but will usually have at least one correct figure. 6: APROD -- SUBROUTINE, supplied by the user. External Procedure T APROD must perform the operations y:=y+Ax and x:=x+A y for given vectors x and y. Its specification is: SUBROUTINE APROD (MODE, M, N, X, Y, RWORK, 1 LRWORK, IWORK, LIWORK) INTEGER MODE, M, N, LRWORK, LIWORK, 1 IWORK(LIWORK) DOUBLE PRECISION X(N), Y(M), RWORK(LRWORK) 1: MODE -- INTEGER Input/Output On entry: MODE specifies which operation is to be performed: If MODE = 1, then APROD must compute y+Ax. T If MODE = 2, then APROD must compute x+A y. On exit: MODE may be used as a flag to indicate a T failure in the computation of y+Ax or x+A y. If MODE is negative on exit from APROD, F04QAF will exit immediately with IFAIL set to MODE. 2: M -- INTEGER Input On entry: m, the number of rows of A. 3: N -- INTEGER Input On entry: n, the number of columns of A. 4: X(N) -- DOUBLE PRECISION array Input/Output On entry: the vector x. On exit: if MODE = 1, X must be unchanged; T If MODE = 2, X must contain x+A y. 5: Y(M) -- DOUBLE PRECISION array Input/Output On entry: the vector y. On exit: if MODE = 1, Y must contain y+Ax; If MODE = 2, Y must be unchanged. 6: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace 7: LRWORK -- INTEGER Input 8: IWORK(LIWORK) -- INTEGER array User Workspace 9: LIWORK -- INTEGER Input APROD is called from F04QAF with the parameters RWORK, LRWORK, IWORK and LIWORK as supplied to F04QAF. The user is free to use the arrays RWORK and IWORK to supply information to APROD as an alternative to using COMMON. APROD must be declared as EXTERNAL in the (sub)program from which F04QAF is called. Parameters denoted as Input must not be changed by this procedure. 7: DAMP -- DOUBLE PRECISION Input On entry: the value (lambda). If either problem (3.1) or problem (3.2) is to be solved, then DAMP must be supplied as zero. 8: ATOL -- DOUBLE PRECISION Input On entry: the tolerance, tol , of the convergence criteria 1 (3.6) and (3.7); it should be an estimate of the largest relative error in the elements of A. For example, if the elements of A are correct to about 4 significant figures, -4 then ATOL should be set to about 5*10 . If ATOL is supplied as less than (epsilon), where (epsilon) is the machine precision, then the value (epsilon) is used in place of ATOL. 9: BTOL -- DOUBLE PRECISION Input On entry: the tolerance, tol , of the convergence criterion 2 (3.6); it should be an estimate of the largest relative error in the elements of B. For example, if the elements of B are correct to about 4 significant figures, then BTOL -4 should be set to about 5*10 . If BTOL is supplied as less than (epsilon), where (epsilon) is the machine precision, then the value (epsilon) is used in place of BTOL. 10: CONLIM -- DOUBLE PRECISION Input On entry: the value c of equation (3.8); it should be an lim upper limit on the condition number of A. CONLIM should not normally be chosen much larger than 1.0/ATOL. If CONLIM is supplied as zero then the value 1.0/(epsilon), where (epsilon) is the machine precision, is used in place of CONLIM. 11: ITNLIM -- INTEGER Input On entry: an upper limit on the number of iterations. If ITNLIM <= 0, then the value N is used in place of ITNLIM, but for ill-conditioned problems a higher value of ITNLIM is likely to be necessary. 12: MSGLVL -- INTEGER Input On entry: the level of printing from F04QAF. If MSGLVL <= 0, then no printing occurs, but otherwise messages will be output on the advisory message channel (see X04ABF). A description of the printed output is given in Section 5.2 below. The level of printing is determined as follows: MSGLVL <= 0 No printing. MSGLVL = 1 A brief summary is printed just prior to return from F04QAF. MSGLVL >= 2 A summary line is printed periodically to monitor the progress of F04QAF, together with a brief summary just prior to return from F04QAF. 13: ITN -- INTEGER Output On exit: the number of iterations performed. 14: ANORM -- DOUBLE PRECISION Output On exit: an estimate of ||A|| for the matrix A of equation (3.4). 15: ACOND -- DOUBLE PRECISION Output On exit: an estimate of cond(A) which is a lower bound. 16: RNORM -- DOUBLE PRECISION Output On exit: an estimate of ||r|| for the residual, r, of equation (3.5) corresponding to the solution x returned in X. Note that ||r|| is the function being minimized. 17: ARNORM -- DOUBLE PRECISION Output T On exit: an estimate of the ||A r|| corresponding to the solution x returned in X. 18: XNORM -- DOUBLE PRECISION Output On exit: an estimate of ||x|| for the solution x returned in X. 19: WORK(2*N) -- DOUBLE PRECISION array Workspace 20: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace RWORK is not used by F04QAF, but is passed directly to routine APROD and may be used to pass information to that routine. 21: LRWORK -- INTEGER Input On entry: the length of the array RWORK as declared in the (sub)program from which F04QAF is called. Constraint: LRWORK >= 1. 22: IWORK(LIWORK) -- INTEGER array User Workspace IWORK is not used by F04QAF, but is passed directly to routine APROD and may be used to pass information to that routine. 23: LIWORK -- INTEGER Input On entry: the length of the array IWORK as declared in the (sub)program from which F04QAF is called. Constraint: LIWORK >= 1. 24: INFORM -- INTEGER Output On exit: the reason for termination of F04QAF as follows: INFORM = 0 The exact solution is x=0. No iterations are performed in this case. INFORM = 1 The termination criterion of equation (3.6) has been satisfied with tol and tol as the values supplied in 1 2 ATOL and BTOL respectively. INFORM = 2 The termination criterion of equation (3.7) has been satisfied with tol as the value supplied in ATOL. 1 INFORM = 3 The termination criterion of equation (3.6) has been satisfied with tol and/or tol as the value (epsilon) 1 2 , where (epsilon) is the machine precision. One or both of the values supplied in ATOL and BTOL must have been less than (epsilon) and was too small for this machine. INFORM = 4 The termination criterion of equation (3.7) has been satisfied with tol as the value (epsilon), where 1 (epsilon) is the machine precision. The value supplied in ATOL must have been less than (epsilon) and was too small for this machine. The values INFORM = 5, INFORM = 6 and INFORM = 7 correspond to failure with IFAIL = 2, IFAIL = 3 and IFAIL = 4 respectively (see Section 6) and when IFAIL is negative INFORM will be set to the same negative value. 25: IFAIL -- INTEGER Input/Output On entry: IFAIL must be set to 0, -1 or 1. For users not familiar with this parameter (described in the Essential Introduction) the recommended value is 0. On exit: IFAIL = 0 unless the routine detects an error (see Section 6). 5.1. Description of the printed output When MSGLVL > 0, then F04QAF will produce output (except in the case where the routine fails with IFAIL = 1) on the advisory message channel (see X04ABF ). When MSGLVL >= 2 then a summary line is printed periodically giving the following information: Output Meaning ITN Iteration number, k. X(1) The first element of the current iterate x . k FUNCTION The current value of the function, (rho), being minimized. COMPAT An estimate of ||r ||/||b||, where r is the k k residual corresponding to x . This value should k converge to zero (in theory) if and only if the problem is compatible. COMPAT decreases monotonically. T INCOMPAT An estimate of ||A r ||/(||A||||r ||) which k k should converge to zero if and only if at the solution (rho) is non-zero. INCOMPAT is not usually monotonic. NRM(ABAR) A monotonically increasing estimate of ||A||. COND(ABAR) A monotonically increasing estimate of the condition number cond(A). 6. Error Indicators and Warnings Errors detected by the routine: IFAIL< 0 A negative value of IFAIL indicates an exit from F04QAF because the user has set MODE negative in APROD. The value of IFAIL will be the same as the user's setting of MODE. IFAIL= 1 On entry M < 1, or N < 1, or LRWORK < 1, or LIWORK < 1. IFAIL= 2 The condition of equation (3.8) has been satisfied for the value of c supplied in CONLIM. If this failure is lim unexpected the user should check that APROD is working correctly. Although conditions (3.6) or (3.7) have not been satisfied, the values returned in RNORM, ARNORM and XNORM may nevertheless indicate that an acceptable solution has been reached. IFAIL= 3 The conditions of equation (3.8) has been satisified for the value c =1.0/(epsilon), where (epsilon) is the machine lim precision. The matrix A is nearly singular or rank deficient and the problem is too ill-conditioned for this machine. If this failure is unexpected, the user should check that APROD is working correctly. IFAIL= 4 The limit on the number of iterations has been reached. The number of iterations required by F04QAF and the condition of the matrix A can depend strongly on the scaling of the problem. Poor scaling of the rows and columns of A should be avoided whenever possible. 7. Accuracy When the problem is compatible, the computed solution x will satisfy the equation r=b-Ax, where an estimate of ||r|| is returned in the parameter RNORM. When the problem is incompatible, the computed solution x will satisfy the equation T A r=e, where an estimate of ||e|| is returned in the parameter ARNORM. See also Section 6.2 of Paige and Saunders [1]. 8. Further Comments The time taken by the routine is likely to be principally determined by the time taken in APROD, which is called twice on each iteration, once with MODE = 1 and once with MODE = 2. The time taken per iteration by the remaining operations in F04QAF is approximately proportional to max(m,n). The Lanczos process will usually converge more quickly if A is pre-conditioned by a non-singular matrix M that approximates A in some sense and is also chosen so that equations of the form My=c can efficiently be solved for y. Some discussion of pre- conditioning in the context of symmetric matrices is given in Section 3 of the document for F04MBF. In the context of F04QAF, problem (3.1) is equivalent to -1 (AM )y=b, Mx=y and problem (3.2) is equivalent to minimizing -1 (rho)=||r||, r=b-(AM )y, Mx=y. -1 T -1 -T T -1 Note that the normal matrix (AM ) (AM )=M (A A)M so that the -1 pre-conditioning AM is equivalent to the pre-conditioning -T T -1 T M (A A)M of the normal matrix A A. Pre-conditioning can be incorporated into F04QAF simply by coding -1 -T T the routine APROD to compute y+AM x and x+M A y in place of T y+Ax and x+A y respectively, and then solving the equations Mx=y -1 for x on return from F04QAF. y+AM x should be computed by -T T solving Mz=x for z and then computing y+Az, and x+M A y should T T be computed by solving M z=A y for z and then forming x+z. 9. Example To solve the linear least-squares problem minimize (rho)=||r||, r=b-Ax where A is the 13 by 12 matrix and b is the 13 element vector given by ( 1 0 0 -1 0 0 0 0 0 0 0 0) ( 0 1 0 0 -1 0 0 0 0 0 0 0) ( 0 0 1 -1 0 0 0 0 0 0 0 0) (-1 0 -1 4 -1 0 0 -1 0 0 0 0) ( 0 -1 0 -1 4 -1 0 0 -1 0 0 0) ( 0 0 0 0 -1 1 0 0 0 0 0 0) A=( 0 0 0 0 0 0 1 -1 0 0 0 0), ( 0 0 0 -1 0 0 -1 4 -1 0 -1 0) ( 0 0 0 0 -1 0 0 -1 4 -1 0 -1) ( 0 0 0 0 0 0 0 0 -1 1 0 0) ( 0 0 0 0 0 0 0 -1 0 0 1 0) ( 0 0 0 0 0 0 0 0 -1 0 0 1) ( 1 1 1 0 0 1 1 0 0 1 1 1) ( 0 ) ( 0 ) ( 0 ) ( 1 ) ( 1 ) 2( 0 ) b=-h ( 0 ) ( 1 ) ( 1 ) ( 0 ) ( 0 ) ( 0 ) ( -3) (-h ) with h=0.1. Such a problem can arise by considering the Neumann problem on a rectangle (delta)u --------=0 (delta)n (delta)u 2 (delta)u / --------=0 (nabla) u=g(x,y) --------=0 |u=1 (delta)n (delta)n / c (delta)u --------=0 (delta)n where C is the boundary of the rectangle, and discretising as illustrated below with the square mesh Please see figure in printed Reference Manual The 12 by 12 symmetric part of A represents the difference equations and the final row comes from the normalising condition. The example program has g(x,y)=1 at all the internal mesh points, but apart from this is written in a general manner so that the number of rows (NROWS) and columns (NCOLS) in the grid can readily be altered. The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf06}{NAG On-line Documentation: f06} \beginscroll \begin{verbatim} F06(3NAG) Foundation Library (12/10/92) F06(3NAG) F06 -- Linear Algebra Support Routines Introduction -- F06 Chapter F06 Linear Algebra Support Routines Contents of this Introduction: 1. Scope of the Chapter 2. Background to the Problems 2.1. The Use of BLAS Names 2.2. Background Information 2.2.1. Real plane rotations 2.3. References 3. Recommendations on Choice and Use of Routines 3.1. The Level-0 Scalar Routines 3.2. The Level-1 Vector Routines 3.3. The Level-2 Matrix-vector Routines 3.4. The Level-3 Matrix-matrix Routines 4. Description of the F06 Routines 4.1. The Level-0 Scalar Routines 4.2. The Level-1 Vector Routines 4.3. The Level-2 Matrix-vector Routines 4.4. The Level-3 Matrix-matrix Routines 1. Scope of the Chapter This Chapter is concerned with basic linear algebra routines which perform elementary algebraic operations involving scalars, vectors and matrices. 2. Background to the Problems All the routines in this Chapter meet the specification of the Basic Linear Algebra Subprograms (BLAS) as described in Lawson et al [6], Dongarra et al [3] and [4]. The first reference describes a set of routines concerned with operations on scalars and vectors: these will be referred to here as the Level-0 and the Level-1 BLAS; the second reference describes a set of routines concerned with matrix-vector operations: these will be referred to here as the Level-2 BLAS; and the third reference describes a set of routines concerned with matrix-matrix operations: these will be referred to here as the Level-3 BLAS. The terminology reflects the number of operations involved. For 2 example, a Level-2 routine involves 0(n ) operations for an n by n matrix. Table 1.1 indicates the naming scheme for the routines in this Chapter. The heading 'mixed type' is for routines where a mixture of data types is involved, such as a routine that returns the real Euclidean length of a complex vector. Level-0 Level-1 Level-2 Level-3 'real' BLAS routine F06A F F06E F F06P F F06Y F 'complex' BLAS routine - F06G F F06S F F06Z F Table 1.1 The routines in this chapter do not have full routine documents, but instead are covered by some relevant background material, in Section 2.2, together with general descriptions, in Section 4, sufficient to enable their use. As this chapter is concerned only with basic linear algebra operations, the routines will not normally be required by the general user. The functionality of each routine is indicated in Section 3 so that those users requiring these routines to build specialist linear algebra modules can determine which routines are of interest. 2.1. The Use of BLAS Names Many of the routines in other chapters of the Library call the BLAS in this chapter. These routines are usually called by the BLAS name and so, for correct operation of the Library, it is essential that users do not attempt to link their own versions of these routines. If users are in any doubt about how to avoid this, please consult your local support staff or the NAG Response Centre. The BLAS names are used in order to make use of efficient implementations of the routines when these exist. Such implementations are stringently tested before being used, to ensure that they correctly meet the specification of the BLAS, and that they return the desired accuracy (see, for example, Dongarra et al. [3] and [4]). 2.2. Background Information Most of the routines in this chapter implement straightforward scalar, vector and matrix operations that need no further explanation beyond a statement of the purpose of the routine. In this section we give some additional background information for those few cases where additional explanation may be necessary. 2.2.1. Real plane rotations Two routines in the chapter are concerned with setting up and applying plane rotations. For further background information see Golub and Van Loan [5]. A plane rotation matrix for the (i,j) plane, R , is an ij orthogonal matrix that is different from the unit matrix only in the elements r , r , r and r . If we put ii jj ij ji (r r ) ( ii ij) R=(r r ), ( ji jj) then, in the real case, it is usual to choose R so that ij ( c s) R=(-s c), c=cos(theta), s=sin(theta). (2.1) The application of plane rotations is straightforward and needs no further elaboration, so further comment is made only on the construction of plane rotations. The most common use of plane rotations is to choose c and s so that for given a and b, ( c s)(a) (d) (-s c)(b)=(0) (2.2) In such an application the matrix R is often termed a Givens rotation matrix. The BLAS routine F06AAF(*) (DROTG), see Lawson et al [6] and Dodson and Grimes [1, 2], computes c, s and d as 2 2 1/2 d=(sigma)(a +b ) , {a/d, d/=0 {b/d, d/=0 c={1, d=0 , s={0, d=0 (2.3) {sign a,|a|>|b| where (sigma)={sign b,|a|<=|b|. The value z defined as {s, |s|1, { 2 {(1-c ), |z|>1. 2.3. References [1] Dodson D S and Grimes R G (1982) Remark on Algorithm 539. ACM Trans Math Softw. 8 403--404. [2] Dodson D S and Grimes R G (1982) Remark on Algorithm 539. ACM Trans. Math. Softw. 9 140. [3] Dongarra J J, Du Croz J J, Hammarling S and Hanson R J (1988) An Extended Set of FORTRAN Basic Linear Algebra Subprograms. ACM Trans. Math. Softw. 14 1--32. [4] Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990) A Set of Level 3 Basic Linear Algebra Subprograms. ACM Trans. Math. Softw. 16 1--28. [5] Golub G H and Van Loan C F (1989) Matrix Computations (2nd Edition). Johns Hopkins University Press, Baltimore, Maryland. [6] Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic Linear Algebra Subprograms for Fortran Usage. ACM Trans. Math. Softw. 5 308--325. 3. Recommendations on Choice and Use of Routines This section lists the routines in each of the categories Level-0 (scalar), Level-1 (vector), Level-2 (matrix-vector and matrix) and Level-3 (matrix-matrix). The corresponding double precision BLAS name is indicated in brackets. Within each section routines are listed in alphabetic order of the fifth character in the routine name, so that corresponding real and complex routines may have adjacent entries. 3.1. The Level-0 Scalar Routine The Level-0 routine performs the scalar operation of generating a plane rotation. F06AAF (DROTG) generates a real plane rotation. 3.2. The Level-1 Vector Routines The Level-1 routines perform operations on or between vectors, such as computing dot products and Euclidean lengths. F06EAF (DDOT) computes the dot product of two real vectors F06GAF (ZDOTU) computes the dot product of two complex vectors (unconjugated) F06GBF (ZDOTC) computes the dot product of two complex vectors (conjugated) F06ECF (DAXPY) adds a scalar times a vector to another real vector F06GCF (ZAXPY) adds a scalar times a vector to another complex vector F06EDF (DSCAL) multiplies a real vector by a scalar F06GDF (ZSCAL) multiplies a complex vector by a scalar F06JDF (ZDSCAL) multiplies a complex vector by a real scalar F06EFF (DCOPY) copies a real vector F06GFF (ZCOPY) copies a complex vector F06EGF (DSWAP) swaps two real vectors F06GGF (ZSWAP) swaps two complex vectors F06EJF (DNRM2) computes the Euclidean length of a real vector F06JJF (DZNRM2) computes the Euclidean length of a complex vector F06EKF (DASUM) sums the absolute values of the elements of a real vector F06JKF (DZASUM) sums the absolute values of the elements of a complex vector F06JLF (IDAMAX) finds the index of the element of largest absolute value of a real vector F06JMF (IZAMAX) finds the index of the element of largest absolute value of a complex vector F06EPF (DROT) applies a real plane rotation 3.3. The Level-2 Matrix-vector Routines The Level-2 routines perform matrix-vector operations, such as forming the product between a matrix and a vector. F06PAF (DGEMV) computes a matrix-vector product; real general matrix F06SAF (ZGEMV) computes a matrix-vector product; complex general matrix F06PBF (DGBMV) computes a matrix-vector product; real general band matrix F06SBF (ZGBMV) computes a matrix-vector product; complex general band matrix F06PCF (DSYMV) computes a matrix-vector product; real symmetric matrix F06SCF (ZHEMV) computes a matrix-vector product; complex Hermitian matrix F06PDF (DSBMV) computes a matrix-vector product; real symmetric band matrix F06SDF (ZHBMV) computes a matrix-vector product; complex Hermitian band matrix F06PEF (DSPMV) computes a matrix-vector product; real symmetric packed matrix F06SEF (ZHPMV) computes a matrix-vector product; complex Hermitian packed matrix F06PFF (DTRMV) computes a matrix-vector product; real triangular matrix F06SFF (ZTRMV) computes a matrix-vector product; complex triangular matrix F06PGF (DTBMV) computes a matrix-vector product; real triangular band matrix F06SGF (ZTBMV) computes a matrix-vector product; complex triangular band matrix F06PHF (DTPMV) computes a matrix-vector product; real triangular packed matrix F06SHF (ZTPMV) computes a matrix-vector product; complex triangular packed matrix F06PJF (DTRSV) solves a system of equations; real triangular coefficient matrix F06SJF (ZTRSV) solves a system of equations; complex triangular coefficient matrix F06PKF (DTBSV) solves a system of equations; real triangular band coefficient matrix F06SKF (ZTBSV) solves a system of equations; complex triangular band coefficient matrix F06PLF (DTPSV) solves a system of equations; real triangular packed coefficient matrix F06SLF (ZTPSV) solves a system of equations; complex triangular packed coefficient matrix F06PMF (DGER) performs a rank-one update; real general matrix F06SMF (ZGERU) performs a rank-one update; complex general matrix (unconjugated vector) F06SNF (ZGERC) performs a rank-one update; complex general matrix (conjugated vector) F06PPF (DSYR) performs a rank-one update; real symmetric matrix F06SPF (ZHER) performs a rank-one update; complex Hermitian matrix F06PQF (DSPR) performs a rank-one update; real symmetric packed matrix F06SQF (ZHPR) performs a rank-one update; complex Hermitian packed matrix F06PRF (DSYR2) performs a rank-two update; real symmetric matrix F06SRF (ZHER2) performs a rank-two update; complex Hermitian matrix F06PSF (DSPR2) performs a rank-two update; real symmetric packed matrix F06SSF (ZHPR2) performs a rank-two update; complex Hermitian packed matrix 3.4. The Level-3 Matrix-matrix Routines The Level-3 routines perform matrix-matrix operations, such as forming the product of two matrices. F06YAF (DGEMM) computes a matrix-matrix product; two real rectangular matrices F06ZAF (ZGEMM) computes a matrix-matrix product; two complex rectangular matrices F06YCF (DSYMM) computes a matrix-matrix product; one real symmetric matrix, one real rectangular matrix F06ZCF (ZHEMM) computes a matrix-matrix product; one complex Hermitian matrix, one complex rectangular matrix F06YFF (DTRMM) computes a matrix-matrix product; one real triangular matrix, one real rectangular matrix F06ZFF (ZTRMM) computes a matrix-matrix product; one complex triangular matrix, one complex rectangular matrix F06YJF (DTRSM) solves a system of equations with multiple right- hand sides, real triangular coefficient matrix F06ZJF (ZTRSM) solves a system of equations with multiple right- hand sides, complex triangular coefficient matrix F06YPF (DSYRK) performs a rank-k update of a real symmetric matrix F06ZPF (ZHERK) performs a rank-k update of a complex hermitian matrix F06YRF (DSYR2K) performs a rank-2k update of a real symmetric matrix F06ZRF (ZHER2K) performs a rank-2k update of a complex Hermitian matrix F06ZTF (ZSYMM) computes a matrix-matrix product: one complex symmetric matrix, one complex rectangular matrix F06ZUF (ZSYRK) performs a rank-k update of a complex symmetric matrix F06ZWF (ZSYR2K) performs a rank-2k update of a complex symmetric matrix 4. Description of the F06 Routines In this section we describe the purpose of each routine and give information on the parameter lists, where appropriate indicating their general nature. Usually the association between the routine arguments and the mathematical variables is obvious and in such cases a description of the argument is omitted. Within each section, the parameter lists for all routines are presented, followed by the purpose of the routines and information on the parameter lists. The double precision BLAS names are given in ENTRY statements. Within each section routines are listed in alphabetic order of the fifth character in the routine name, so that corresponding real and complex routines may have adjacent entries. 4.1. The Level-0 Scalar Routines The scalar routines have no array arguments. SUBROUTINE F06AAF( A,B,C,S ) ENTRY DROTG ( A,B,C,S ) DOUBLE PRECISION A,B,C,S F06AAF(*) generates the parameters c and s of a Givens rotation as defined by equations (2.3) and (2.4), from given a and b. On exit, A is overwritten by d and B is overwritten by z. 4.2. The Level-1 Vector Routines The vector routines all have one or more one-dimensional arrays as arguments, each representing a vector. The length of each vector, n, is represented by the argument N, and the routines may be called with non-positive values of N, in which case the routine returns immediately except for the functions, which set the function value to zero before returning. In addition to the argument N, each array argument is also associated with an increment argument that immediately follows the array argument, and whose name consists of the three characters INC, followed by the name of the array. For example, a vector x will be represented by the two arguments X, INCX. The increment argument is the spacing (stride) in the array for which the elements of the vector occur. For instance, if INCX = 2, then the elements of x are in locations X(1),X(3),...,X(2*N-1) of the array X and the intermediate locations X(2),X(4),...,X(2*N-2) are not referenced. Thus when INCX > 0, the vector element x is in the array element i X(1+(i-1)*INCX). When INCX <= 0 the elements are stored in the reverse order so that the vector element x is in the array i element X(1-(n-i)*INCX) and hence, in particular, the element x n is in X(1). The declared length of the array X in the calling (sub)program must be at least (1+(N-1)*|INCX|). Non-positive increments are permitted only for those routines that have more than one array argument. While zero increments are formally permitted for such routines, their use in Chapter F06 is strongly discouraged since the effect may be implementation dependent. DOUBLE PRECISION FUNCTION F06EAF ( N, X,INCX,Y,INCY ) DOUBLE PRECISION DDOT ENTRY DDOT ( N, X,INCX,Y,INCY ) INTEGER N, INCX, INCY DOUBLE PRECISION X(*), Y(*) COMPLEX(KIND(1.0D0)) FUNCTION F06GAF ( N, X,INCX,Y,INCY ) COMPLEX(KIND(1.0D0)) ZDOTU ENTRY ZDOTU ( N, X,INCX,Y,INCY ) INTEGER N, INCX, INCY COMPLEX(KIND(1.0D0)) X(*), Y(*) COMPLEX(KIND(1.0D0)) FUNCTION F06GBF ( N, X,INCX,Y,INCY ) COMPLEX(KIND(1.0D0)) ZDOTC ENTRY ZDOTC ( N, X,INCX,Y,INCY ) INTEGER N, INCX, INCY COMPLEX(KIND(1.0D0)) X(*), Y(*) SUBROUTINE F06ECF ( N,ALPHA,X,INCX,Y,INCY ) ENTRY DAXPY ( N,ALPHA,X,INCX,Y,INCY ) INTEGER N, INCX, INCY DOUBLE PRECISION ALPHA,X(*), Y(*) SUBROUTINE F06GCF ( N,ALPHA,X,INCX,Y,INCY ) ENTRY ZAXPY ( N,ALPHA,X,INCX,Y,INCY ) INTEGER N, INCX, INCY COMPLEX(KIND(1.0D0)) ALPHA,X(*), Y(*) SUBROUTINE F06EDF ( N,ALPHA,X,INCX ) ENTRY DSCAL ( N,ALPHA,X,INCX ) INTEGER N, INCX DOUBLE PRECISION ALPHA,X(*) SUBROUTINE F06GDF ( N,ALPHA,X,INCX ) ENTRY ZSCAL ( N,ALPHA,X,INCX ) INTEGER N, INCX COMPLEX(KIND(1.0D0)) ALPHA,X(*) SUBROUTINE F06JDF ( N,ALPHA,X,INCX ) ENTRY ZDSCAL ( N,ALPHA,X,INCX ) INTEGER N, INCX DOUBLE PRECISION ALPHA COMPLEX(KIND(1.0D0)) X(*) SUBROUTINE F06EFF ( N, X,INCX,Y,INCY ) ENTRY DCOPY ( N, X,INCX,Y,INCY ) INTEGER N, INCX, INCY DOUBLE PRECISION X(*), Y(*) SUBROUTINE F06GFF ( N, X,INCX,Y,INCY ) ENTRY ZCOPY ( N, X,INCX,Y,INCY ) INTEGER N, INCX, INCY COMPLEX(KIND(1.0D0)) X(*), Y(*) SUBROUTINE F06EGF ( N, X,INCX,Y,INCY ) ENTRY DSWAP ( N, X,INCX,Y,INCY ) INTEGER N, INCX, INCY DOUBLE PRECISION X(*), Y(*) SUBROUTINE F06GGF ( N, X,INCX,Y,INCY ) ENTRY ZSWAP ( N, X,INCX,Y,INCY ) INTEGER N, INCX, INCY COMPLEX(KIND(1.0D0)) X(*), Y(*) DOUBLE PRECISION FUNCTION F06EJF ( N, X,INCX ) DOUBLE PRECISION DNRM2 ENTRY DNRM2 ( N, X,INCX ) INTEGER N, INCX DOUBLE PRECISION X(*) DOUBLE PRECISION FUNCTION F06JJF ( N, X,INCX ) DOUBLE PRECISION DZNRM2 ENTRY DZNRM2 ( N, X,INCX ) INTEGER N, INCX COMPLEX(KIND(1.0D0)) X(*) DOUBLE PRECISION FUNCTION F06EKF ( N, X,INCX ) DOUBLE PRECISION DASUM ENTRY DASUM ( N, X,INCX ) INTEGER N, INCX DOUBLE PRECISION X(*) DOUBLE PRECISION FUNCTION F06JKF ( N, X,INCX ) DOUBLE PRECISION DZASUM ENTRY DZASUM ( N, X,INCX ) INTEGER N, INCX COMPLEX(KIND(1.0D0)) X(*) INTEGER FUNCTION F06JLF ( N, X,INCX ) INTEGER IDAMAX ENTRY IDAMAX ( N, X,INCX ) INTEGER N, INCX DOUBLE PRECISION X(*) INTEGER FUNCTION F06JMF ( N, X,INCX ) INTEGER IZAMAX ENTRY IZAMAX ( N, X,INCX ) INTEGER N, INCX COMPLEX(KIND(1.0D0)) X(*) SUBROUTINE F06EPF ( N, X,INCX,Y,INCY,C,S ) ENTRY DROT ( N, X,INCX,Y,INCY,C,S ) INTEGER N, INCX, INCY DOUBLE PRECISION X(*), Y(*), C,S F06EAF(*) and F06GAF(*) T return the dot product x y. F06GBF(*) H H returns the dot product x y, where x denotes the complex T conjugate of x . F06ECF(*) and F06GCF(*) perform the operation y<-(alpha)x+y, often called an axpy operation. F06EDF(*), F06GDF(*) and F06JDF(*) perform the operation x<-(alpha)x. F06EFF(*) and F06GFF(*) perform the operation y<-x. F06EGF(*) and F06GGF(*) perform the operation x<=>y, that is x and y are swapped. F06EJF(*) and F06JJF(*) ( n )1/2 ( -- 2) return the value ||x|| defined by ||x|| = ( > |x | ) . 2 2 ( -- i ) ( i=1 ) F06EKF(*) n -- returns the value ||x|| defined by ||x|| = > |x |. 1 1 -- i i=1 F06JKF(*) n -- returns the value asum defined by asum= > (|(Re(x )|+|Im(x )|). -- i i i=1 F06JLF(*) returns the first index j such that |x |=max |x |. j i i F06JMF(*) returns the first index j such that |Re(x )|+|Im(x )|=max (|(Re(x )|+|Im(x )|). j j i i i F06EPF(*) ( T) ( T) (x ) (x ) ( T) ( c s)( T) performs the plane rotation (y ) <- (-s c)(y ). 4.3. The Level-2 Matrix-vector Routines The matrix-vector routines all have one array argument representing a matrix; usually this is a two-dimensional array but in some cases the matrix is represented by a one-dimensional array. The size of the matrix is determined by the arguments M and N for an m by n rectangular matrix; and by the argument N for an n by n symmetric, Hermitian, or triangular matrix. Note that it is permissible to call the routines with M or N = 0, in which case the routines exit immediately without referencing their array arguments. For band matrices, the bandwidth is determined by the arguments KL and KU for a rectangular matrix with kl sub- diagonals and ku super-diagonals; and by the argument K for a symmetric, Hermitian, or triangular matrix with k sub-diagonals and/or super-diagonals. The description of the matrix consists either of the array name (A) followed by the first dimension of the array as declared in the calling (sub)program (LDA), when the matrix is being stored in a two-dimensional array; or the array name (AP) alone when the matrix is being stored as a (packed) vector. In the former case the actual array must contain at least ((n-1)d+l) elements, where d is the first dimension of the array, d>=l , and l=m for arrays representing general matrices, l=n for arrays representing symmetric, Hermitian and triangular matrices, l=kl+ku+1 for arrays representing general band matrices and l=k+1 for symmetric, Hermitian and triangular band matrices. For one- dimensional arrays representing matrices (packed storage) the 1 actual array must contain at least -n(n+1) elements. 2 As with the vector routines, vectors are represented by one- dimensional arrays together with a corresponding increment argument (see Section 4.2). The only difference is that for these routines a zero increment is not permitted. When the vector x consists of k elements then the declared length of the array X in the calling (sub)program must be at least (1+(k-1)|INCX|). The arguments that specify options are character arguments with the names TRANS, UPLO and DIAG. TRANS is used by the matrix- vector product routines as follows: Value Meaning 'N' or 'n' Operate with the matrix 'T' or 't' Operate with the transpose of the matrix 'C' or 'c' Operate with the conjugate transpose of the matrix In the real case the values 'T', 't', 'C' and 'c' have the same meaning. UPLO is used by the Hermitian, symmetric, and triangular matrix routines to specify whether the upper or lower triangle is being referenced as follows: Value Meaning 'U' or 'u' Upper triangle 'L' or 'l' Lower triangle DIAG is used by the triangular matrix routines to specify whether or not the matrix is unit triangular, as follows: Value Meaning 'U' or 'u' Unit triangular 'N' or 'n' Non-unit triangular When DIAG is supplied as 'U' or 'u' the diagonal elements are not referenced. It is worth noting that actual character arguments in Fortran may be longer than the corresponding dummy arguments. So that, for example, the value 'T' for TRANS may be passed as 'TRANSPOSE'. The routines for real symmetric and complex Hermitian matrices allow for the matrix to be stored in either the upper (UPLO = 'U to be packed in a one-dimensional array. In the latter case the upper triangle may be packed sequentially column by column (UPLO = 'U'), or the lower triangle may be packed sequentially column by column (UPLO = 'L'). Note that for real symmetric matrices packing the upper triangle by column is equivalent to packing the lower triangle by rows, and packing the lower triangle by columns is equivalent to packing the upper triangle by rows. (For complex Hermitian matrices the only difference is that the off-diagonal elements are conjugated.) For triangular matrices the argument UPLO serves to define whether the matrix is upper (UPLO = 'U') or lower (UPLO = 'L') triangular. In packed storage the triangle has to be packed by column. The band matrix routines allow storage so that the jth column of the matrix is stored in the jth column of the Fortran array. For a general band matrix the diagonal of the matrix is stored in the (ku+1)th row of the array. For a Hermitian or symmetric matrix either the upper triangle (UPLO = 'U') may be stored in which case the leading diagonal is in the (k+1)th row of the array, or the lower triangle (UPLO = 'L') may be stored in which case the leading diagonal is in the first row of the array. For an upper triangular band matrix (UPLO = 'U') the leading diagonal is in the (k+1)th row of the array and for a lower triangular band matrix (UPLO = 'L') the leading diagonal is in the first row. For a Hermitian matrix the imaginary parts of the diagonal elements are of course zero and thus the imaginary parts of the corresponding Fortran array elements need not be set, but are assumed to be zero. For packed triangular matrices the same storage layout is used whether or not DIAG = 'U', i.e., space is left for the diagonal elements even if those array elements are not referenced. H Throughout the following sections A denotes the complex T conjugate of A . SUBROUTINE F06PAF( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY DGEMV ( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 TRANS INTEGER M,N,LDA,INCX,INCY DOUBLE PRECISION ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06SAF( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY ZGEMV ( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 TRANS INTEGER M,N,LDA,INCX,INCY COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06PBF( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY DGBMV ( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 TRANS INTEGER M,N,KL,KU,LDA,INCX,INCY DOUBLE PRECISION ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06SBF( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY ZGBMV ( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 TRANS INTEGER M,N,KL,KU,LDA,INCX,INCY COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06PCF( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY DSYMV ( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 UPLO INTEGER N,LDA,INCX,INCY DOUBLE PRECISION ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06SCF( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY ZHEMV ( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 UPLO INTEGER N,LDA,INCX,INCY COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06PDF( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY DSBMV ( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 UPLO INTEGER N,K,LDA,INCX,INCY DOUBLE PRECISION ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06SDF( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) ENTRY ZHBMV ( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY ) CHARACTER*1 UPLO INTEGER N,K,LDA,INCX,INCY COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*) SUBROUTINE F06PEF( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY ) ENTRY DSPMV ( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY ) CHARACTER*1 UPLO INTEGER N,INCX,INCY DOUBLE PRECISION ALPHA,AP(*),X(*),BETA,Y(*) SUBROUTINE F06SEF( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY ) ENTRY ZHPMV ( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY ) CHARACTER*1 UPLO INTEGER N,INCX,INCY COMPLEX(KIND(1.0D0)) ALPHA,AP(*),X(*),BETA,Y(*) SUBROUTINE F06PFF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) ENTRY DTRMV ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,LDA,INCX DOUBLE PRECISION A(LDA,*),X(*) SUBROUTINE F06SFF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) ENTRY ZTRMV ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,LDA,INCX COMPLEX(KIND(1.0D0)) A(LDA,*),X(*) SUBROUTINE F06PGF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) ENTRY DTBMV ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,K,LDA,INCX DOUBLE PRECISION A(LDA,*),X(*) SUBROUTINE F06SGF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) ENTRY ZTBMV ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,K,LDA,INCX COMPLEX(KIND(1.0D0)) A(LDA,*),X(*) SUBROUTINE F06PHF( UPLO,TRANS,DIAG,N,AP,X,INCX ) ENTRY DTPMV ( UPLO,TRANS,DIAG,N,AP,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,INCX DOUBLE PRECISION AP(*),X(*) SUBROUTINE F06SHF( UPLO,TRANS,DIAG,N,AP,X,INCX ) ENTRY ZTPMV ( UPLO,TRANS,DIAG,N,AP,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,INCX COMPLEX(KIND(1.0D0)) AP(*),X(*) SUBROUTINE F06PJF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) ENTRY DTRSV ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,LDA,INCX DOUBLE PRECISION A(LDA,*),X(*) SUBROUTINE F06SJF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) ENTRY ZTRSV ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,LDA,INCX COMPLEX(KIND(1.0D0)) A(LDA,*),X(*) SUBROUTINE F06PKF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) ENTRY DTBSV ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,K,LDA,INCX DOUBLE PRECISION A(LDA,*),X(*) SUBROUTINE F06SKF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) ENTRY ZTBSV ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,K,LDA,INCX COMPLEX(KIND(1.0D0)) A(LDA,*),X(*) SUBROUTINE F06PLF( UPLO,TRANS,DIAG,N,AP,X,INCX ) ENTRY DTPSV ( UPLO,TRANS,DIAG,N,AP,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,INCX DOUBLE PRECISION AP(*),X(*) SUBROUTINE F06SLF( UPLO,TRANS,DIAG,N,AP,X,INCX ) ENTRY ZTPSV ( UPLO,TRANS,DIAG,N,AP,X,INCX ) CHARACTER*1 UPLO,TRANS,DIAG INTEGER N,INCX COMPLEX(KIND(1.0D0)) AP(*),X(*) SUBROUTINE F06PMF( M,N,ALPHA,X,INCX,Y,INCY,A,LDA ) ENTRY DGER ( M,N,ALPHA,X,INCX,Y,INCY,A,LDA ) INTEGER M,N,INCX,INCY,LDA DOUBLE PRECISION ALPHA,X(*),Y(*),A(LDA,*) SUBROUTINE F06SMF( M,N,ALPHA,X,INCX,Y,INCY,A,LDA ) ENTRY ZGERU ( M,N,ALPHA,X,INCX,Y,INCY,A,LDA ) INTEGER M,N,INCX,INCY,LDA COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),A(LDA,*) SUBROUTINE F06SNF( M,N,ALPHA,X,INCX,Y,INCY,A,LDA ) ENTRY ZGERC ( M,N,ALPHA,X,INCX,Y,INCY,A,LDA ) INTEGER M,N,INCX,INCY,LDA COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),A(LDA,*) SUBROUTINE F06PPF( UPLO,N,ALPHA,X,INCX,A,LDA ) ENTRY DSYR ( UPLO,N,ALPHA,X,INCX,A,LDA ) CHARACTER*1 UPLO INTEGER N,INCX,LDA DOUBLE PRECISION ALPHA,X(*),A(LDA,*) SUBROUTINE F06SPF( UPLO,N,ALPHA,X,INCX,A,LDA ) ENTRY ZHER ( UPLO,N,ALPHA,X,INCX,A,LDA ) CHARACTER*1 UPLO INTEGER N,INCX,LDA DOUBLE PRECISION ALPHA COMPLEX(KIND(1.0D0)) X(*),A(LDA,*) SUBROUTINE F06PQF( UPLO,N,ALPHA,X,INCX,AP ) ENTRY DSPR ( UPLO,N,ALPHA,X,INCX,AP ) CHARACTER*1 UPLO INTEGER N,INCX DOUBLE PRECISION ALPHA,X(*),AP(*) SUBROUTINE F06SQF( UPLO,N,ALPHA,X,INCX,AP ) ENTRY ZHPR ( UPLO,N,ALPHA,X,INCX,AP ) CHARACTER*1 UPLO INTEGER N,INCX DOUBLE PRECISION ALPHA COMPLEX(KIND(1.0D0)) X(*),AP(*) SUBROUTINE F06PRF( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA ) ENTRY DSYR2 ( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA ) CHARACTER*1 UPLO INTEGER N,INCX,INCY,LDA DOUBLE PRECISION ALPHA,X(*),Y(*),A(LDA,*) SUBROUTINE F06SRF( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA ) ENTRY ZHER2 ( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA ) CHARACTER*1 UPLO INTEGER N,INCX,INCY,LDA COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),A(LDA,*) SUBROUTINE F06PSF( UPLO,N,ALPHA,X,INCX,Y,INCY,AP ) ENTRY DSPR2 ( UPLO,N,ALPHA,X,INCX,Y,INCY,AP ) CHARACTER*1 UPLO INTEGER N,INCX,INCY DOUBLE PRECISION ALPHA,X(*),Y(*),AP(*) SUBROUTINE F06SSF( UPLO,N,ALPHA,X,INCX,Y,INCY,AP ) ENTRY ZHPR2 ( UPLO,N,ALPHA,X,INCX,Y,INCY,AP ) CHARACTER*1 UPLO INTEGER N,INCX,INCY COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),AP(*) F06PAF(*), F06SAF(*), F06PBF(*) and F06SBF(*) perform the operation y<-(alpha)Ax+(beta)y, when TRANS = 'N', T y<-(alpha)A x+(beta)y, when TRANS = 'T', H y<-(alpha)A x+(beta)y, when TRANS = 'C', where A is a general matrix for F06PAF(*) and F06SAF(*), and is a general band matrix for F06PBF(*) and F06SBF(*). F06PCF(*), F06SCF(*), F06PEF(*), F06SEF(*), F06PDF(*) and F06SDF(*) perform the operation y<-(alpha)Ax+(beta)y where A is symmetric and Hermitian for F06PCF(*) and F06SCF(*) respectively, is symmetric and Hermitian stored in packed form for F06PEF(*) and F06SEF(*) respectively, and is symmetric and Hermitian band for F06PDF(*) and F06SDF(*). F06PFF(*), F06SFF(*), F06PHF(*), F06SHF(*), F06PGF(*) and F06SGF(*) perform the operation x<-Ax, when TRANS = 'N', T x<-A x, when TRANS = 'T', H x<-A x, when TRANS = 'C', where A is a triangular matrix for F06PFF(*) and F06SFF(*), is a triangular matrix stored in packed form for F06PHF(*) and F06SHF(*), and is a triangular band matrix for F06PGF(*) and F06SGF(*). F06PJF(*), F06SJF(*), F06PLF(*), F06SLF(*), F06PKF(*) and F06SKF(*) solve the equations Ax=b, when TRANS = 'N', T A x=b, when TRANS = 'T', H A x=b, when TRANS = 'C', where A is a triangular matrix for F06PJF(*) and F06SJF(*), is a triangular matrix stored in packed form for F06PLF(*) and F06SLF(*), and is a triangular band matrix for F06PKF(*) and F06SKF(*). The vector b must be supplied in the array X and is overwritten by the solution. It is important to note that no test for singularity is included in these routines. F06PMF(*) and F06SMF(*) T perform the operation A<-(alpha)xy +A, where A is a general matrix. F06SNF(*) H performs the operation A<-(alpha)xy +A, where A is a general complex matrix. F06PPF(*) and F06PQF(*) T perform the operation A<-(alpha)xx +A, where A is a symmetric matrix for F06PPF(*) and is a symmetric matrix stored in packed form for F06PQF(*). F06SPF(*) and F06SQF(*) H perform the operation A<-(alpha)xx +A, where A is an Hermitian matrix for F06SPF(*) and is an Hermitian matrix stored in packed form for F06SQF(*). F06PRF(*) and F06PSF(*) T T perform the operation A<-(alpha)xy +(alpha)yx +A, where A is a symmetric matrix for F06PRF(*) and is a symmetric matrix stored in packed form for F06PSF(*). F06SRF(*) and F06SSF(*) H H perform the operation A<-(alpha)xy +(alpha)yx +A, where A is an Hermitian matrix for F06SRF(*) and is an Hermitian matrix stored in packed form for F06SSF(*). The following argument values are invalid: Any value of the character arguments DIAG, TRANS, or UPLO whose meaning is not specified. M < 0 N < 0 KL < 0 KU < 0 K < 0 LDA < M LDA < KL + KU + 1 LDA < N for the routines involving full Hermitian, symmetric or triangular matrices LDA < K + 1 for the routines involving band Hermitian, symmetric or triangular matrices INCX = 0 INCY = 0 If a routine is called with an invalid value then an error message is output, on the error message unit (see X04AAF), giving the name of the routine and the number of the first invalid argument, and execution is terminated. 4.4. The Level-3 Matrix-matrix Routines The matrix-matrix routines all have either two or three arguments representing a matrix, one of which is an input-output argument, and in each case the arguments are two-dimensional arrays. The sizes of the matrices are determined by one or more of the arguments M, N and K. The size of the input-output array is always determined by the arguments M and N for a rectangular m by n matrix, and by the argument N for a square n by n matrix. It is permissible to call the routines with M or N = 0, in which case the routines exit immediately without referencing their array arguments. Many of the routines perform an operation of the form C<-P+(beta)C, where P is the product of two matrices, or the sum of two such products. When the inner dimension of the matrix product is different from m or n it is denoted by K. Again it is permissible to call the routines with K = 0 and if M > 0, but K = 0, then the routines perform the operation C<-(beta)C. As with the Level-2 routines (see Section 4.3) the description of the matrix consists of the array name (A or B or C) followed by the first dimension (LDA or LDB or LDC). The arguments that specify options are character arguments with the names SIDE, TRANSA, TRANSB, TRANS, UPLO and DIAG. UPLO and DIAG have the same values and meanings as for the Level-2 routines (see Section 4.3); TRANSA, TRANSB and TRANS have the same values and meanings as TRANS in the Level-2 routines, where TRANSA and TRANSB apply to the matrices A and B respectively. SIDE is used by the routines as follows: Value Meaning 'L' Multiply general matrix by symmetric, Hermitian or triangular matrix on the left 'R' Multiply general matrix by symmetric, Hermitian or triangular matrix on the right The storage conventions for matrices are as for the Level-2 routines (see Section 4.3). SUBROUTINE F06YAF( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY DGEMM ( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER TRANSA,TRANSB INTEGER M,N,K,LDA,LDB,LDC DOUBLE PRECISION ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*) SUBROUTINE F06ZAF( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY ZGEMM ( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER TRANSA,TRANSB INTEGER M,N,K,LDA,LDB,LDC COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*) SUBROUTINE F06YCF( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY DSYMM ( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER SIDE,UPLO INTEGER M,N,LDA,LDB,LDC DOUBLE PRECISION ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*) SUBROUTINE F06ZCF( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY ZHEMM ( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER SIDE,UPLO INTEGER M,N,LDA,LDB,LDC COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*) SUBROUTINE F06ZTF( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY ZSYMM ( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER SIDE,UPLO INTEGER M,N,LDA,LDB,LDC COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*) SUBROUTINE F06YFF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) ENTRY DTRMM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) CHARACTER SIDE,UPLO,TRANSA,DIAG INTEGER M,N,LDA,LDB DOUBLE PRECISION ALPHA,A(LDA,*),B(LDB,*) SUBROUTINE F06ZFF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) ENTRY ZTRMM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) CHARACTER SIDE,UPLO,TRANSA,DIAG INTEGER M,N,LDA,LDB COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*) SUBROUTINE F06YJF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) ENTRY DTRSM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) CHARACTER SIDE,UPLO,TRANSA,DIAG INTEGER M,N,LDA,LDB DOUBLE PRECISION ALPHA,A(LDA,*),B(LDB,*) SUBROUTINE F06ZJF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) ENTRY ZTRSM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB ) CHARACTER SIDE,UPLO,TRANSA,DIAG INTEGER M,N,LDA,LDB COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*) SUBROUTINE F06YPF( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC ) ENTRY DSYRK ( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC ) CHARACTER UPLO,TRANS INTEGER N,K,LDA,LDC DOUBLE PRECISION ALPHA,A(LDA,*),BETA,C(LDC,*) SUBROUTINE F06ZPF( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC ) ENTRY ZHERK ( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC ) CHARACTER UPLO,TRANS INTEGER N,K,LDA,LDC DOUBLE PRECISION ALPHA,BETA COMPLEX(KIND(1.0D0)) A(LDA,*),C(LDC,*) SUBROUTINE F06ZUF( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC ) ENTRY ZSYRK ( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC ) CHARACTER UPLO,TRANS INTEGER N,K,LDA,LDC COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),BETA,C(LDC,*) SUBROUTINE F06YRF( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY DSYR2K( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER UPLO,TRANS INTEGER N,K,LDA,LDB,LDC DOUBLE PRECISION ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*) SUBROUTINE F06ZRF( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY ZHER2K( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER UPLO,TRANS INTEGER N,K,LDA,LDB,LDC DOUBLE PRECISION BETA COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),C(LDC,*) SUBROUTINE F06ZWF( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) ENTRY ZSYR2K( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC ) CHARACTER UPLO,TRANS INTEGER N,K,LDA,LDB,LDC COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*) F06YAF(*) and F06ZAF(*) perform the operation indicated in the following table: TRANSA = 'N' TRANSA = 'T' TRANSA = 'C' T H TRANSB='N' C <- (alpha)AB C <- (alpha)A B C <- (alpha)A B +(beta)C +(beta)C +(beta)C A is m*k, A is k*m, A is k*m, B is k*n B is k*n B is k*n T T T H T TRANSB='T' C <- (alpha)AB C <- (alpha)A B C <- (alpha)A B +(beta)C +(beta)C +(beta)C A is m*k, A is k*m, A is k*m, B is n*k B is n*k B is n*k H T H H H TRANSB='C' C <- (alpha)AB C <- (alpha)A B C <- (alpha)A B +(beta)C +(beta)C +(beta)C A is m*k, A is k*m, A is k*m, B is n*k B is n*k B is n*k where A and B are general matrices and C is a general m by n matrix. F06YCF(*), F06ZCF(*) and F06ZTF(*) perform the operation indicated in the following table: SIDE = 'L' SIDE = 'R' C<-(alpha)AB+(beta)C C<-(alpha)BA+(beta)C A is m*m B is m*n B is m*n A is n*n where A is symmetric for F06YCF(*) and F06ZTF(*) and is Hermitian for F06ZCF(*), B is a general matrix and C is a general m by n matrix. F06YFF(*) and F06ZFF(*) perform the operation indicated in the following table: TRANSA = 'N' TRANSA = 'T' TRANSA = 'C' T H SIDE='L' B <- (alpha)AB B <- (alpha)A B B <- (alpha)A B A is A is A is triangular triangular triangular m*m m*m m*m T H SIDE='R' B <- (alpha)BA B <- (alpha)BA B <- (alpha)BA A is A is A is triangular triangular triangular n*n n*n n*n where B is a general m by n matrix. F06YJF(*) and F06ZJF(*) solve the equations, indicated in the following table, for X: TRANSA = 'N' TRANSA = 'T' TRANSA = 'C' T H SIDE='L' AX=(alpha)B A X=(alpha)B A X=(alpha)B A is A is A is triangular triangular triangular m*m m*m m*m T H SIDE='R' XA=(alpha)B XA =(alpha)B XA =(alpha)B A is A is A is triangular triangular triangular n*n n*n n*n where B is a general m by n matrix. The m by n solution matrix X is overwritten on the array B. It is important to note that no test for singularity is included in these routines. F06YPF(*), F06ZPF(*) and F06ZUF(*) perform the operation indicated in the following table: TRANS = 'N' TRANS = 'T' TRANS = 'C' T T T F06YPF C <- (alpha)AA C <- (alpha)A A C <- (alpha)A A +(beta)C +(beta)C +(beta)C T T F06ZUF C <- (alpha)AA C <- (alpha)A A -- +(beta)C +(beta)C H H F06ZPF C <- (alpha)AA -- C <- (alpha)A A +(beta)C +(beta)C A is n*k A is k*n A is k*n where A is a general matrix and C is an n by n symmetric matrix for F06YPF(*) and F06ZUF(*), and is an n by n Hermitian matrix for F06ZPF(*). F06YRF(*), F06ZRF(*) and F06ZWF(*) perform the operation indicated in the following table: TRANS = 'N' TRANS = 'T' TRANS = 'C' T T T F06YRF C <- (alpha)AB C <- (alpha)A B C <- (alpha)A B T T T +(alpha)BA +(alpha)B A +(alpha)B A +(beta)C +(beta)C +(beta)C T T F06ZWF C <- (alpha)AB C <- (alpha)A B -- T T +(alpha)BA +(alpha)B A +(beta)C +(beta)C H H F06ZRF C <- (alpha)AB -- C <- (alpha)A B H H +(alpha)BA +(alpha)B A +(beta)C +(beta)C A and B are n*k A and B are k*n A and B are k*n where A and B are general matrices and C is an n by n symmetric matrix for F06YRF(*) and F06ZWF(*), and is an n by n Hermitian matrix for F06ZPF(*). The following values of arguments are invalid: Any value of the character arguments SIDE, TRANSA, TRANSB, TRANS, UPLO or DIAG, whose meaning is not specified. M < 0 N < 0 K < 0 LDA < the number of rows in the matrix A. LDB < the number of rows in the matrix B. LDC < the number of rows in the matrix C. If a routine is called with an invalid value then an error message is output, on the error message unit (see X04AAF), giving the name of the routine and the number of the first invalid argument, and execution is terminated. F06 -- Linear Algebra Support Routines Contents -- F06 Chapter F06 Linear Algebra Support Routines F06AAF (DROTG) Generate real plane rotation F06EAF (DDOT) Dot product of two real vectors F06ECF (DAXPY) Add scalar times real vector to real vector F06EDF (DSCAL) Multiply real vector by scalar F06EFF (DCOPY) Copy real vector F06EGF (DSWAP) Swap two real vectors F06EJF (DNRM2) Compute Euclidean norm of real vector F06EKF (DASUM) Sum the absolute values of real vector elements F06EPF (DROT) Apply real plane rotation F06GAF (ZDOTU) Dot product of two complex vectors, unconjugated F06GBF (ZDOTC) Dot product of two complex vectors, conjugated F06GCF (ZAXPY) Add scalar times complex vector to complex vector F06GDF (ZSCAL) Multiply complex vector by complex scalar F06GFF (ZCOPY) Copy complex vector F06GGF (ZSWAP) Swap two complex vectors F06JDF (ZDSCAL) Multiply complex vector by real scalar F06JJF (DZNRM2) Compute Euclidean norm of complex vector F06JKF (DZASUM) Sum the absolute values of complex vector elements F06JLF (IDAMAX) Index, real vector element with largest absolute value F06JMF (IZAMAX) Index, complex vector element with largest absolute value F06PAF (DGEMV) Matrix-vector product, real rectangular matrix F06PBF (DGBMV) Matrix-vector product, real rectangular band matrix F06PCF (DSYMV) Matrix-vector product, real symmetric matrix F06PDF (DSBMV) Matrix-vector product, real symmetric band matrix F06PEF (DSPMV) Matrix-vector product, real symmetric packed matrix F06PFF (DTRMV) Matrix-vector product, real triangular matrix F06PGF (DTBMV) Matrix-vector product, real triangular band matrix F06PHF (DTPMV) Matrix-vector product, real triangular packed matrix F06PJF (DTRSV) System of equations, real triangular matrix F06PKF (DTBSV) System of equations, real triangular band matrix F06PLF (DTPSV) System of equations, real triangular packed matrix F06PMF (DGER) Rank-1 update, real rectangular matrix F06PPF (DSYR) Rank-1 update, real symmetric matrix F06PQF (DSPR) Rank-1 update, real symmetric packed matrix F06PRF (DSYR2) Rank-2 update, real symmetric matrix F06PSF (DSPR2) Rank-2 update, real symmetric packed matrix F06SAF (ZGEMV) Matrix-vector product, complex rectangular matrix F06SBF (ZGBMV) Matrix-vector product, complex rectangular band matrix F06SCF (ZHEMV) Matrix-vector product, complex Hermitian matrix F06SDF (ZHBMV) Matrix-vector product, complex Hermitian band matrix F06SEF (ZHPMV) Matrix-vector product, complex Hermitian packed matrix F06SFF (ZTRMV) Matrix-vector product, complex triangular matrix F06SGF (ZTBMV) Matrix-vector product, complex triangular band matrix F06SHF (ZTPMV) Matrix-vector product, complex triangular packed matrix F06SJF (ZTRSV) System of equations, complex triangular matrix F06SKF (ZTBSV) System of equations, complex triangular band matrix F06SLF (ZTPSV) System of equations, complex triangular packed matrix F06SMF (ZGERU) Rank-1 update, complex rectangular matrix, unconjugated vector F06SNF (ZGERC) Rank-1 update, complex rectangular matrix, conjugated vector F06SPF (ZHER) Rank-1 update, complex Hermitian matrix F06SQF (ZHPR) Rank-1 update, complex Hermitian packed matrix F06SRF (ZHER2) Rank-2 update, complex Hermitian matrix F06SSF (ZHPR2) Rank-2 update, complex Hermitian packed matrix F06YAF (DGEMM) Matrix-matrix product, two real rectangular matrices F06YCF (DSYMM) Matrix-matrix product, one real symmetric matrix, one real rectangular matrix F06YFF (DTRMM) Matrix-matrix product, one real triangular matrix, one real rectangular matrix F06YJF (DTRSM) Solves a system of equations with multiple right- hand sides, real triangular coefficient matrix F06YPF (DSYRK) Rank-k update of a real symmetric matrix F06YRF (DSYR2K) Rank-2k update of a real symmetric matrix F06ZAF (ZGEMM) Matrix-matrix product, two complex rectangular matrices F06ZCF (ZHEMM) Matrix-matrix product, one complex Hermitian matrix, one complex rectangular matrix F06ZFF (ZTRMM) Matrix-matrix product, one complex triangular matrix, one complex rectangular matrix F06ZJF (ZTRSM) Solves system of equations with multiple right- hand sides, complex triangular coefficient matrix F06ZPF (ZHERK) Rank-k update of a complex Hermitian matrix F06ZRF (ZHER2K) Rank-2k update of a complex Hermitian matrix F06ZTF (ZSYMM) Matrix-matrix product, one complex symmetric matrix, one complex rectangular matrix F06ZUF (ZSYRK) Rank-k update of a complex symmetric matrix F06ZWF (ZSYR2K) Rank-2k update of a complex symmetric matrix \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf07}{NAG On-line Documentation: f07} \beginscroll \begin{verbatim} F07(3NAG) Foundation Library (12/10/92) F07(3NAG) F07 -- Linear Equations (LAPACK) Introduction -- F07 Chapter F07 Linear Equations (LAPACK) 1. Scope of the Chapter This chapter provides four routines concerned with matrix factorization, and the solution of systems of linear equations following the matrix factorizations. 2. Background to the Problems Background material, together with pointers to the routines in this chapter, are to be found in the F01 and F04 Chapter Introductions. 3. Recommendations on Choice and Use of Routines The routines in this chapter are derived from the LAPACK project and may also be called using the LAPACK name, which is given in brackets following the F07 name in the following descriptions. Routine F07ADF (DGETRF) performs an LU factorization of a real m by n matrix A. Following the use of this routine, F07AEF (DGETRS) may be used to solve a system of n non-singular linear equations, with one or more right-hand sides. Routine F07FDF (DPOTRF) performs the Cholesky factorization of a real symmetric positive-definite matrix A. Following the use of this routine, F07FEF (DPOTRS) may be used to solve a system of symmetric positive-definite linear equations, with one or more right-hand sides. F07 -- Linear Equations (LAPACK) Contents -- F07 Chapter F07 Linear Equations (LAPACK) F07ADF (DGETRF) LU factorization of real m by n matrix F07AEF (DGETRS) Solution of real system of linear equations, multiple right-hand sides, matrix already factorized by F07ADF F07FDF (DPOTRF) Cholesky factorization of real symmetric positive-definite matrix F07FEF (DPOTRS) Solution of real symmetric positive-definite system of linear equations, multiple right-hand sides, matrix already factorized by F07FDF \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf07adf}{NAG On-line Documentation: f07adf} \beginscroll \begin{verbatim} F07ADF(3NAG) Foundation Library (12/10/92) F07ADF(3NAG) F07 -- Linear Equations (LAPACK) F07ADF F07ADF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F07ADF (DGETRF) computes the LU factorization of a real m by n matrix. 2. Specification SUBROUTINE F07ADF (M, N, A, LDA, IPIV, INFO) ENTRY M, N, A, LDA, IPIV, INFO INTEGER M, N, LDA, IPIV(*), INFO DOUBLE PRECISION A(LDA,*) The ENTRY statement enables the routine to be called by its LAPACK name. 3. Description This routine forms the LU factorization of a real m by n matrix A as A=PLU, where P is a permutation matrix, L is lower triangular with unit diagonal elements (lower trapezoidal if m>n) and U is upper triangular (upper trapezoidal if m= 0. 2: N -- INTEGER Input On entry: n, the number of columns of the matrix A. Constraint: N >= 0. 3: A(LDA,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the m by n matrix A. On exit: A is overwritten by the factors L and U; the unit diagonal elements of L are not stored. 4: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F07ADF is called. Constraint: LDA >= max(1,M). 5: IPIV(*) -- INTEGER array Output Note: the dimension of the array IPIV must be at least max(1,min(M,N)). On exit: the pivot indices. Row i of the matrix A was interchanged with row IPIV(i) for i=1,2,...,min(m,n). 6: INFO -- INTEGER Output On exit: INFO = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings INFO < 0 If INFO = -i, the ith parameter has an illegal value. An explanatory message is output, and execution of the program is terminated. INFO > 0 If INFO = i, u is exactly zero. The factorization has been ii completed but the factor U is exactly singular, and division by zero will occur if it is subsequently used to solve a -1 system of linear equations or to compute A . 7. Accuracy The computed factors L and U are the exact factors of a perturbed matrix A+E, where |E|<=c(min(m,n))(epsilon)P|L||U|, c(n) is a modest linear function of n, and (epsilon) is the machine precision. 8. Further Comments The total number of floating-point operations is approximately 2 3 1 2 1 2 -n if m=n (the usual case), -n (3m-n) if m>n and -m (3n-m) if 3 3 3 m= 0. 3: NRHS -- INTEGER Input On entry: r, the number of right-hand sides. Constraint: NRHS >= 0. 4: A(LDA,*) -- DOUBLE PRECISION array Input Note: the second dimension of the array A must be at least max(1,N). On entry: the LU factorization of A, as returned by F07ADF (DGETRF). 5: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F07AEF is called. Constraint: LDA >= max(1,N). 6: IPIV(*) -- INTEGER array Input Note: the dimension of the array IPIV must be at least max(1,N). On entry: the pivot indices, as returned by F07ADF (DGETRF). 7: B(LDB,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array B must be at least max(1,NRHS). On entry: the n by r right-hand side matrix B. On exit: the n by r solution matrix X. 8: LDB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F07AEF is called. Constraint: LDB >= max(1,N). 9: INFO -- INTEGER Output On exit: INFO = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings INFO < 0 If INFO = -i, the ith parameter has an illegal value. An explanatory message is output, and execution of the program is terminated. 7. Accuracy For each right-hand side vector b, the computed solution x is the exact solution of a perturbed system of equations (A+E)x=b, where |E|<=c(n)(epsilon)P|L||U|, c(n) is a modest linear function of n, and (epsilon) is the machine precision. ^ If x is the true solution, then the computed solution x satisfies a forward error bound of the form ^ ||x-x|| infty ------------ <= c(n)cond(A,x)(epsilon) ||x|| infty -1 where cond(A,x)=|||A ||A||x||| /||x|| <= infty infty -1 cond(A)=|||A ||A||| <=(kappa) (A). Note that cond(A,x) infty infty T can be much smaller than cond(A), and cond(A ) can be much larger (or smaller) than cond(A). Forward and backward error bounds can be computed by calling F07AHF (DGERFS)(*), and an estimate for (kappa) (A) can be infty obtained by calling F07AGF (DGECON)(*) with NORM ='I'. 8. Further Comments The total number of floating-point operations is approximately 2 2n r. This routine may be followed by a call to F07AHF (DGERFS)(*) to refine the solution and return an error estimate. The complex analogue of this routine is F07ASF (ZGETRS)(*). 9. Example To solve the system of equations AX=B, where ( 1.80 2.88 2.05 -0.89) ( 5.25 -2.95 -0.95 -3.80) A=( 1.58 -2.69 -2.90 -1.04) (-1.11 -0.66 -0.59 0.80) and ( 9.52 18.47) (24.35 2.25) B=( 0.77 -13.28). (-6.22 -6.21) Here A is unsymmetric and must first be factorized by F07ADF (DGETRF)). The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf07fdf}{NAG On-line Documentation: f07fdf} \beginscroll \begin{verbatim} F07FDF(3NAG) Foundation Library (12/10/92) F07FDF(3NAG) F07 -- Linear Equations (LAPACK) F07FDF F07FDF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F07FDF (DPOTRF) computes the Cholesky factorization of a real symmetric positive-definite matrix. 2. Specification SUBROUTINE F07FDF (UPLO, N, A, LDA, INFO) ENTRY UPLO, N, A, LDA, INFO INTEGER N, LDA, INFO DOUBLE PRECISION A(LDA,*) CHARACTER*1 UPLO The ENTRY statement enables the routine to be called by its LAPACK name. 3. Description This routine forms the Cholesky factorization of a real symmetric T T positive-definite matrix A either as A=U U if UPLO = 'U' or A=LL if UPLO = 'L', where U is an upper triangular matrix and L is lower triangular. 4. References [1] Demmel J W (1989) On Floating-point Errors in Cholesky. LAPACK Working Note No. 14. University of Tennessee, Knoxville. [2] Golub G H and Van Loan C F (1989) Matrix Computations (2nd Edition). Johns Hopkins University Press, Baltimore, Maryland. 5. Parameters 1: UPLO -- CHARACTER*1 Input On entry: indicates whether the upper or lower triangular part of A is stored and how A is factorized, as follows: if UPLO = 'U', then the upper triangular part of A is T stored and A is factorized as U U, where U is upper triangular; if UPLO = 'L', then the lower triangular part of A is T stored and A is factorized as LL , where L is lower triangular. Constraint: UPLO = 'U' or 'L'. 2: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 0. 3: A(LDA,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array A must be at least max(1,N). On entry: the n by n symmetric positive-definite matrix A. If UPLO = 'U', the upper triangle of A must be stored and the elements of the array below the diagonal are not referenced; if UPLO = 'L', the lower triangle of A must be stored and the elements of the array above the diagonal are not referenced. On exit: the upper or lower triangle of A is overwritten by the Cholesky factor U or L as specified by UPLO. 4: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F07FDF is called. Constraint: LDA >= max(1,N). 5: INFO -- INTEGER Output On exit: INFO = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings INFO < 0 If INFO = -i, the ith parameter has an illegal value. An explanatory message is output, and execution of the program is terminated. INFO > 0 If INFO = i, the leading minor of order i is not positive- definite and the factorization could not be completed. Hence A itself is not positive-definite. This may indicate an error in forming the matrix A. To factorize a symmetric matrix which is not positive-definite, call F07MDF (DSYTRF)(*) instead. 7. Accuracy If UPLO = 'U', the computed factor U is the exact factor of a perturbed matrix A+E, where T |E|<=c(n)(epsilon)|U ||U|, c(n) is a modest linear function of n, and (epsilon) is the machine precision. If UPLO = 'L', a similar statement holds for the computed factor L. It follows that |e |<=c(n)(epsilon) /a a . ij \/ ii jj 8. Further Comments The total number of floating-point operations is approximately 1 3 -n . 3 A call to this routine may be followed by calls to the routines: F07FEF (DPOTRS) to solve AX=B; F07FGF (DPOCON)(*) to estimate the condition number of A; F07FJF (DPOTRI)(*) to compute the inverse of A. The complex analogue of this routine is F07FRF (ZPOTRF)(*). 9. Example To compute the Cholesky factorization of the matrix A, where ( 4.16 -3.12 0.56 -0.10) (-3.12 5.03 -0.83 1.18) A=( 0.56 -0.83 0.76 0.34). (-0.10 1.18 0.34 1.18) The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page} \begin{page}{manpageXXf07fef}{NAG On-line Documentation: f07fef} \beginscroll \begin{verbatim} F07FEF(3NAG) Foundation Library (12/10/92) F07FEF(3NAG) F07 -- Linear Equations (LAPACK) F07FEF F07FEF -- NAG Foundation Library Routine Document Note: Before using this routine, please read the Users' Note for your implementation to check implementation-dependent details. The symbol (*) after a NAG routine name denotes a routine that is not included in the Foundation Library. 1. Purpose F07FEF (DPOTRS) solves a real symmetric positive-definite system of linear equations with multiple right-hand sides, AX=B, where A has been factorized by F07FDF (DPOTRF). 2. Specification SUBROUTINE F07FEF (UPLO, N, NRHS, A, LDA, B, LDB, INFO) ENTRY UPLO, N, NRHS, A, LDA, B, LDB, INFO INTEGER N, NRHS, LDA, LDB, INFO DOUBLE PRECISION A(LDA,*), B(LDB,*) CHARACTER*1 UPLO The ENTRY statement enables the routine to be called by its LAPACK name. 3. Description To solve a real symmetric positive-definite system of linear equations AX=B, this routine must be preceded by a call to F07FDF (DPOTRF) which computes the Cholesky factorization of A. The solution X is computed by forward and backward substitution. T If UPLO = 'U', A=U U, where U is upper triangular; the solution X T is computed by solving U Y=B and then UX=Y. T If UPLO = 'L', A=LL , where L is lower triangular; the solution X T is computed by solving LY=B and then L X=Y. 4. References [1] Golub G H and Van Loan C F (1989) Matrix Computations (2nd Edition). Johns Hopkins University Press, Baltimore, Maryland. 5. Parameters 1: UPLO -- CHARACTER*1 Input On entry: indicates whether the upper or lower triangular part of A is stored and how A is factorized, as follows: T if UPLO = 'U', then A=U U where U is upper triangular; T if UPLO = 'L', then A=LL where L is lower triangular. Constraint: UPLO = 'U' or 'L'. 2: N -- INTEGER Input On entry: n, the order of the matrix A. Constraint: N >= 0. 3: NRHS -- INTEGER Input On entry: r, the number of right-hand sides. Constraint: NRHS >= 0. 4: A(LDA,*) -- DOUBLE PRECISION array Input Note: the second dimension of the array A must be at least max(1,N). On entry: the Cholesky factor of A, as returned by F07FDF (DPOTRF). 5: LDA -- INTEGER Input On entry: the first dimension of the array A as declared in the (sub)program from which F07FEF is called. Constraint: LDA >=max(1,N). 6: B(LDB,*) -- DOUBLE PRECISION array Input/Output Note: the second dimension of the array B must be at least max(1,NRHS). On entry: the n by r right-hand side matrix B. 7: LDB -- INTEGER Input On entry: the first dimension of the array B as declared in the (sub)program from which F07FEF is called. Constraint: LDB >=max(1,N). 8: INFO -- INTEGER Output On exit: INFO = 0 unless the routine detects an error (see Section 6). 6. Error Indicators and Warnings INFO < 0 If INFO = -i, the ith parameter has an illegal value. An explanatory message is output, and execution of the program is terminated. 7. Accuracy For each right-hand side vector b, the computed solution x is the exact solution of a perturbed system of equations (A+E)x=b, where T |E|<=c(n)(epsilon)|U ||U| if UPLO = 'U', T |E|<=c(n)(epsilon)|L||L | if UPLO = 'L', c(n) is a modest linear function of n, and (epsilon) is the machine precision. ^ If x is the true solution, then the computed solution x satisfies a forward bound of the form ^ ||x-x|| infty ------------<=c(n)cond(A,x)(epsilon) ||x|| infty -1 where cond(A,x)=|||A ||A||x||| /||x|| <= infty infty -1 cond(A)=|||A ||A||| <=(kappa) (A). Note that cond(A,x) infty infty can be much smaller than cond(A). Forward and backward error bounds can be computed by calling F07FHF (DPORFS)(*), and an estimate for (kappa) (A) ( infty =(kappa) (A)) can be obtained by calling F07FGF (DPOCON)(*). 1 8. Further Comments The total number of floating-point operations is approximately 2 2n r. This routine may be followed by a call to F07FHF (DPORFS)(*) to refine the solution and return an error estimate. The complex analogue of this routine is F07FSF (ZPOTRS)(*). 9. Example To compute the Cholesky factorization of the matrix A, where ( 4.16 -3.12 0.56 -0.10) (-3.12 5.03 -0.83 1.18) A=( 0.56 -0.83 0.76 0.34). (-0.10 1.18 0.34 1.18) and ( 8.70 8.30) (-13.35 2.13) B=( 1.89 1.61). ( -4.14 5.00) Here A is symmetric positive-definite and must first be factorized by F07FDF (DPOTRF). The example program is not reproduced here. The source code for all example programs is distributed with the NAG Foundation Library software and should be available on-line. \end{verbatim} \endscroll \end{page}