diff options
| author | dos-reis <gdr@axiomatics.org> | 2007-08-14 05:14:52 +0000 |
|---|---|---|
| committer | dos-reis <gdr@axiomatics.org> | 2007-08-14 05:14:52 +0000 |
| commit | ab8cc85adde879fb963c94d15675783f2cf4b183 (patch) | |
| tree | c202482327f474583b750b2c45dedfc4e4312b1d /src/hyper/pages/nagf.ht | |
| download | open-axiom-ab8cc85adde879fb963c94d15675783f2cf4b183.tar.gz | |
Initial population.
Diffstat (limited to 'src/hyper/pages/nagf.ht')
| -rw-r--r-- | src/hyper/pages/nagf.ht | 12302 |
1 files changed, 12302 insertions, 0 deletions
diff --git a/src/hyper/pages/nagf.ht b/src/hyper/pages/nagf.ht new file mode 100644 index 00000000..7a3b37d2 --- /dev/null +++ b/src/hyper/pages/nagf.ht @@ -0,0 +1,12302 @@ +\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)<<n), the consequent savings are likely to be greater. + + The time taken to estimate growth (GROW = .TRUE.) is typically + under 2% of the overall time. + + The overall time may be substantially increased if there is + inadequate 'elbow-room' in the arrays A, IRN and ICN. When the + sizes of the arrays are minimal (IDISP(6) and IDISP(7)) it can + execute as much as three times slower. Values of IDISP(3) and + IDISP(4) greater than about 10 indicate that it may be worthwhile + to increase array sizes. + + 8.2. Scaling + + The use of a relative pivot tolerance PIVOT essentially + presupposes that the matrix is well-scaled, i.e., that the matrix + elements are broadly comparable in size. Practical problems are + often naturally well-scaled but particular care is needed for + problems containing mixed types of variables (for example + millimetres and neutron fluxes). + + 8.3. Singular and Rectangular Systems + + It is envisaged that this routine will almost always be called + for square non-singular matrices and that singularity indicates + an error condition. However, even if the matrix is singular it is + possible to complete the factorization. It is even possible for + F04AXF to solve a set of equations whose matrix is singular + provided the set is consistent. + + Two forms of singularity are possible. If the matrix would be + singular for any values of the non-zeros (e.g. if it has a whole + row of zeros), then we say it is structurally singular, and + continue only if ABORT(1) = .FALSE.. If the matrix is non- + singular by virtue of the particular values of the non-zeros, + then we say that it is numerically singular and continue only if + ABORT(2) = .FALSE.. + + Rectangular matrices may be treated by setting N to the larger of + the number of rows and numbers of columns and setting ABORT(1) = + + Note: the soft failure option should be used (last digit of IFAIL + = 1) if the user wishes to factorize singular matrices with ABORT + (1) or ABORT(2) set to .FALSE.. + + 8.4. Duplicated Non-zeros + + The matrix A may consist of a sum of contributions from different + sub-systems (for example finite elements). In such cases the user + may rely on this routine to perform assembly, since duplicated + elements are summed. + + 9. Example + + To factorize the real sparse matrix: + + ( 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) + + This example program simply prints out some information about the + factorization as returned by F01BRF in W(1) and IDISP. Normally + the call of F01BRF would be followed by a call of F04AXF (see + Example for 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}{manpageXXf01bsf}{NAG On-line Documentation: f01bsf} +\beginscroll +\begin{verbatim} + + + + F01BSF(3NAG) Foundation Library (12/10/92) F01BSF(3NAG) + + + + F01 -- Matrix Factorizations F01BSF + F01BSF -- 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 + + F01BSF factorizes a real sparse matrix using the pivotal sequence + previously obtained by F01BRF when a matrix of the same sparsity + pattern was factorized. + + 2. Specification + + SUBROUTINE F01BSF (N, NZ, A, LICN, IVECT, JVECT, ICN, + 1 IKEEP, IW, W, GROW, ETA, RPMIN, ABORT, + 2 IDISP, IFAIL) + INTEGER N, NZ, LICN, IVECT(NZ), JVECT(NZ), ICN + 1 (LICN), IKEEP(5*N), IW(8*N), IDISP(2), + 2 IFAIL + DOUBLE PRECISION A(LICN), W(N), ETA, RPMIN + LOGICAL GROW, ABORT + + 3. Description + + This routine accepts as input a real sparse matrix of the same + sparsity pattern as a matrix previously factorized by a call of + F01BRF. It first applies to the matrix the same permutations as + were used by F01BRF, both for permutation to block triangular + form and for pivoting, and then performs Gaussian elimination to + obtain the LU factorization of the diagonal blocks. + + 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. + + F01BSF is much faster than F01BRF and in some applications it is + expected that there will be many calls of F01BSF for each call of + F01BRF. + + 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. Constraint: N > 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 )<TOL, where f is the + i i i k i + normalised residual of the current approximation to the + eigenvector (see Section 8 for further information). The + values of the f and d can be printed from routine MONIT. + i i + If TOL is supplied outside the range ((epsilon), 1.0), where + (epsilon) is the machine precision, then the value (epsilon) + is used in place of TOL. + + 6: DOT -- DOUBLE PRECISION FUNCTION, supplied by the user. + External Procedure + T + DOT must return the value w Bz for given vectors w and z. + For the standard eigenvalue problem, where B=I, DOT must + T + return the dot product w z. + + Its specification is: + + DOUBLE PRECISION FUNCTION DOT (IFLAG, N, Z, W, + 1 RWORK, LRWORK, + 2 IWORK, LIWORK) + INTEGER IFLAG, N, LRWORK, IWORK(LIWORK), + 1 LIWORK + DOUBLE PRECISION Z(N), W(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 + T + computation of w Bz. If IFLAG is negative on exit from + DOT, then F02FJF will exit immediately with IFAIL set + to IFLAG. Note that in this case DOT must still be + assigned a value. + + 2: N -- INTEGER Input + On entry: the number of elements in the vectors z and w + and the order of the matrix B. + + 3: Z(N) -- DOUBLE PRECISION array Input + T + On entry: the vector z for which w Bz is required. + + 4: W(N) -- DOUBLE PRECISION array Input + T + On entry: the vector w for which w Bz is required. + + 5: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace + + + 6: LRWORK -- INTEGER Input + + + 7: IWORK(LIWORK) -- INTEGER array User Workspace + + + 8: LIWORK -- INTEGER Input + DOT is called from F02FJF with the parameters RWORK, + LRWORK, IWORK and LIWORK as supplied to F02FJF. The + user is free to use the arrays RWORK and IWORK to + supply information to DOT and to IMAGE as an + alternative to using COMMON. + DOT must be declared as EXTERNAL in the (sub)program + from which F02FJF is called. Parameters denoted as + Input must not be changed by this procedure. + + 7: IMAGE -- SUBROUTINE, supplied by the user. + External Procedure + IMAGE must return the vector w=Cz for a given vector z. + + Its specification is: + + SUBROUTINE IMAGE (IFLAG, N, Z, W, RWORK, LRWORK, + 1 IWORK, LIWORK) + INTEGER IFLAG, N, LRWORK, IWORK(LIWORK), + 1 LIWORK + DOUBLE PRECISION Z(N), W(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 w. If IFLAG is negative on exit from + IMAGE, then F02FJF will exit immediately with IFAIL set + to IFLAG. + + 2: N -- INTEGER Input + On entry: n, the number of elements in the vectors w + and z, and the order of the matrix C. + + 3: Z(N) -- DOUBLE PRECISION array Input + On entry: the vector z for which Cz is required. + + 4: W(N) -- DOUBLE PRECISION array Output + On exit: the vector w=Cz. + + 5: RWORK(LRWORK) -- DOUBLE PRECISION array User Workspace + + 6: LRWORK -- INTEGER Input + + 7: IWORK(LIWORK) -- INTEGER array User Workspace + + 8: LIWORK -- INTEGER Input + IMAGE is called from F02FJF with the parameters RWORK, + LRWORK, IWORK and LIWORK as supplied to F02FJF. The + user is free to use the arrays RWORK and IWORK to + supply information to IMAGE and DOT as an alternative + to using COMMON. + IMAGE must be declared as EXTERNAL in the (sub)program + from which F02FJF is called. Parameters denoted as + Input must not be changed by this procedure. + + 8: MONIT -- SUBROUTINE, supplied by the user. + External Procedure + MONIT is used to monitor the progress of F02FJF. MONIT may + be the dummy subroutine F02FJZ if no monitoring is actually + required. (F02FJZ is included in the NAG Foundation Library + and so need not be supplied by the user. The routine name + F02FJZ may be implementation dependent: see the Users' Note + for your implementation for details.) MONIT is called after + the solution of each eigenvalue sub-problem and also just + prior to return from F02FJF. The parameters ISTATE and + NEXTIT allow selective printing by MONIT. + + Its specification is: + + SUBROUTINE MONIT (ISTATE, NEXTIT, NEVALS, + 1 NEVECS, K, F, D) + INTEGER ISTATE, NEXTIT, NEVALS, NEVECS, + 1 K + DOUBLE PRECISION F(K), D(K) + + 1: ISTATE -- INTEGER Input + On entry: ISTATE specifies the state of F02FJF and will + have values as follows: + ISTATE = 0 + No eigenvalue or eigenvector has just been + accepted. + + ISTATE = 1 + One or more eigenvalues have been accepted since + the last call to MONIT. + + ISTATE = 2 + One or more eigenvectors have been accepted since + the last call to MONIT. + + ISTATE = 3 + One or more eigenvalues and eigenvectors have + been accepted since the last call to MONIT. + + ISTATE = 4 + Return from F02FJF is about to occur. + + 2: NEXTIT -- INTEGER Input + On entry: the number of the next iteration. + + 3: NEVALS -- INTEGER Input + On entry: the number of eigenvalues accepted so far. + + 4: NEVECS -- INTEGER Input + On entry: the number of eigenvectors accepted so far. + + 5: K -- INTEGER Input + On entry: k, the number of simultaneous iteration + vectors. + + 6: F(K) -- DOUBLE PRECISION array Input + On entry: a vector of error quantities measuring the + state of convergence of the simultaneous iteration + vectors. See the parameter TOL of F02FJF above and + Section 8 for further details. Each element of F is + initially set to the value 4.0 and an element remains + at 4.0 until the corresponding vector is tested. + + 7: D(K) -- DOUBLE PRECISION array Input + On entry: D(i) contains the latest approximation to the + absolute value of the ith eigenvalue of C. + MONIT must be declared as EXTERNAL in the (sub)program + from which F02FJF is called. Parameters denoted as + Input must not be changed by this procedure. + + 9: NOVECS -- INTEGER Input + On entry: the number of approximate vectors that are being + supplied in X. If NOVECS is outside the range (0,K), then + the value 0 is used in place of NOVECS. + + 10: X(NRX,K) -- DOUBLE PRECISION array Input/Output + On entry: if 0 < NOVECS <= K, the first NOVECS columns of X + must contain approximations to the eigenvectors + corresponding to the NOVECS eigenvalues of largest absolute + value of C. Supplying approximate eigenvectors can be useful + when reasonable approximations are known, or when the + routine is being restarted with a larger value of K. + Otherwise it is not necessary to supply approximate vectors, + as simultaneous iteration vectors will be generated randomly + by the routine. On exit: if IFAIL = 0, 2, 3 or 4, the first + m' columns contain the eigenvectors corresponding to the + eigenvalues returned in the first m' elements of D (see + below); and the next k-m'-1 columns contain approximations + to the eigenvectors corresponding to the approximate + eigenvalues returned in the next k-m'-1 elements of D. Here + m' is the value returned in M (see above), the number of + eigenvalues actually found. The kth column is used as + workspace. + + 11: NRX -- INTEGER Input + On entry: + the first dimension of the array X as declared in the + (sub)program from which F02FJF is called. + Constraint: NRX >= 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)<TOL + r r r + + ~ + where e is the current approximation to |d |. The values of the + k + f are systematically increased if the convergence criteria + i + appear to be too strict. See Rutishauser [4] for further details. + + The algorithm implemented by F02FJF differs slightly from SIMITZ + (Nikolai [1]) in that the eigenvalue sub-problem is solved using + the singular value decomposition of the upper triangular matrix R + T + of the Gram-Schmidt factorization of Cx , rather than forming R R + r + + 9. Example + + To find the four eigenvalues of smallest absolute value and + corresponding eigenvectors for the generalized symmetric + eigenvalue problem Ax=(lambda)Bx, where A and B are the 16 by 16 + matrices + + (1 a a ) + (a 1 a a ) + ( a 1 a a ) + ( a 1 a a ) + (a a 1 a a ) + ( a a 1 a a ) + ( a a 1 a a ) + ( a a 1 a a ) + A=( a a 1 a a ) + ( a a 1 a a ) + ( a a 1 a a ) + ( a a 1 a a) + ( a a 1 a ) + ( a a 1 a ) + ( a a 1 a) + ( a a 1) + + 1 + where a=- - + 4 + + (1 b ) + (b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b ) + B=( b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b ) + ( b 1 b) + + 1 + where b=- - + 2 + + TOL is taken as 0.0001 and 6 iteration vectors are used. F01MAF + is used to factorize the matrix A, prior to calling F02FJF, and + F04MAF is used within IMAGE to solve the equations Aw=Bz for w. + Details of the factorization of A are passed from F01MAF to + F04MAF by means of the COMMON block BLOCK1. + + Output from MONIT occurs each time ISTATE is non-zero. Note that + the required eigenvalues are the reciprocals of the eigenvalues + returned by F02FJF. + + 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}{manpageXXf02wef}{NAG On-line Documentation: f02wef} +\beginscroll +\begin{verbatim} + + + + F02WEF(3NAG) Foundation Library (12/10/92) F02WEF(3NAG) + + + + F02 -- Eigenvalue and Eigenvectors F02WEF + F02WEF -- 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 + + F02WEF returns all, or part, of the singular value decomposition + of a general real matrix. + + 2. Specification + + SUBROUTINE F02WEF (M, N, A, LDA, NCOLB, B, LDB, WANTQ, Q, + 1 LDQ, SV, WANTP, PT, LDPT, WORK, IFAIL) + INTEGER M, N, LDA, NCOLB, LDB, LDQ, LDPT, IFAIL + DOUBLE PRECISION A(LDA,*), B(LDB,*), Q(LDQ,*), SV(*), PT + 1 (LDPT,*), WORK(*) + LOGICAL WANTQ, WANTP + + 3. Description + + The m by n matrix A is factorized as + + T + A=QDP , + + where + + (S) + D=(0), m>n, + + D=S, m=n, + + D=(S 0), m<n, + + Q is an m by m orthogonal matrix, P is an n by n orthogonal + matrix and S is a min(m,n) by min(m,n) diagonal matrix with non- + negative diagonal elements, sv ,sv ,...,sv , ordered such + 1 2 min(m,n) + that + + sv >=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<n. The upper triangular form is then reduced to bidiagonal form + by Givens plane rotations and finally the QR algorithm is used to + obtain the singular value decomposition of the bidiagonal form. + + Good background descriptions to the singular value decomposition + are given in Dongarra et al [1], Hammarling [2] and Wilkinson [3] + DSVDC. + + Note that if K is any orthogonal diagonal matrix so that + + T + KK =I, + + (so that K has elements +1 or -1 on the diagonal) + + then + + T + A=(QK)D(PK) + + is also a singular value decomposition of A. + + 4. References + + [1] Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) + LINPACK Users' Guide. SIAM, Philadelphia. + + [2] Hammarling S (1985) The Singular Value Decomposition in + Multivariate Statistics. ACM Signum Newsletter. 20, 3 2--25. + + [3] Wilkinson J H (1978) Singular Value Decomposition -- Basic + Aspects. Numerical Software -- Needs and Availability. (ed D + A H Jacobs) Academic Press. + + 5. Parameters + + 1: M -- INTEGER Input + On entry: the number of rows, m, of the matrix A. + Constraint: 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)<tol*SV(1), where tol is the tolerance supplied in + TOL, so that IRANK is an estimate of the rank of S and thus also + of A. If TOL is supplied as negative then the machine precision + is used in place of TOL. + + 9. Example + + 9.1. Example 1 + + To find the singular value decomposition 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) + + T + together with the vector Q b for the vector + + ( 1.1) + ( 0.9) + b=( 0.6) + ( 0.0) + (-0.8) + + 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. + + 9.2. Example 2 + + To find the singular value decomposition of the 3 by 5 matrix + + (2.0 2.0 1.6 2.0 1.2) + A=(2.5 2.5 -0.4 -0.5 -0.3) + (2.5 2.5 2.8 0.5 -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}{manpageXXf02xef}{NAG On-line Documentation: f02xef} +\beginscroll +\begin{verbatim} + + + + F02XEF(3NAG) Foundation Library (12/10/92) F02XEF(3NAG) + + + + F02 -- Eigenvalue and Eigenvectors F02XEF + F02XEF -- 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 + + F02XEF returns all, or part, of the singular value decomposition + of a general complex matrix. + + 2. Specification + + SUBROUTINE F02XEF (M, N, A, LDA, NCOLB, B, LDB, WANTQ, Q, + 1 LDQ, SV, WANTP, PH, LDPH, RWORK, CWORK, + 2 IFAIL) + INTEGER M, N, LDA, NCOLB, LDB, LDQ, LDPH, + 1 IFAIL + DOUBLE PRECISION SV(*), RWORK(*) + COMPLEX(KIND=KIND(1.0D0)) A(LDA,*), B(LDB,*), Q(LDQ,*), + 1 PH(LDPH,*), CWORK(*) + LOGICAL WANTQ, WANTP + + 3. Description + + The m by n matrix A is factorized as + + H + A=QDP , + + where + + (S) + D=(0) m>n, + + D=S, m=n, + + D=(S 0), m<n, + + Q is an m by m unitary matrix, P is an n by n unitary matrix and + S is a min(m,n) by min(m,n) diagonal matrix with real non- + negative diagonal elements, sv ,sv ,...,sv , ordered such + 1 2 min(m,n) + that + + sv >=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<n. The upper triangular form is then reduced to bidiagonal form + by Givens plane rotations and finally the QR algorithm is used to + obtain the singular value decomposition of the bidiagonal form. + + Good background descriptions to the singular value decomposition + are given in Dongarra et al [1], Hammarling [2] and Wilkinson [3] + ZSVDC. + + Note that if K is any unitary diagonal matrix so that + + H + KK =I, + + then + + H + A=(QK)D(PK) + + is also a singular value decomposition of A. + + 4. References + + [1] Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) + LINPACK Users' Guide. SIAM, Philadelphia. + + [2] Hammarling S (1985) The Singular Value Decomposition in + Multivariate Statistics. ACM Signum Newsletter. 20, 3 2--25. + + [3] Wilkinson J H (1978) Singular Value Decomposition -- Basic + Aspects. Numerical Software -- Needs and Availability. (ed D + A H Jacobs) Academic Press. + + 5. Parameters + + 1: M -- INTEGER Input + On entry: the number of rows, m, of the matrix A. + Constraint: 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)<tol*SV(1), where tol is the tolerance supplied in + TOL, so that IRANK is an estimate of the rank of S and thus also + of A. If TOL is supplied as negative then the machine precision + is used in place of TOL. + + 9. Example + + 9.1. Example 1 + + To find the singular value decomposition 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) + + H + together with the vector Q b for the vector + + (-0.55+1.05i) + ( 0.49+0.93i) + b=( 0.56-0.16i) + ( 0.39+0.23i) + ( 1.13+0.83i) + + 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. + + 9.2. Example 2 + + To find the singular value decompostition of the 3 by 5 matrix + + ( 0.5i 0.4-0.3i 0.4 0.3+0.4i 0.3i) + A=(-0.5-1.5i 0.9-1.3i -0.4-0.4i 0.1-0.7i 0.3-0.3i) + (-1.0-1.0i 0.2-1.4i 1.8 0.0 -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}{manpageXXf04}{NAG On-line Documentation: f04} +\beginscroll +\begin{verbatim} + + + + F04(3NAG) Foundation Library (12/10/92) F04(3NAG) + + + + F04 -- Simultaneous Linear Equations Introduction -- F04 + Chapter F04 + Simultaneous Linear Equations + + 1. Scope of the Chapter + + This chapter, together with two routines in Chapter F07, is + concerned with the solution of the matrix equation AX=B, where B + may be a single vector or a matrix of multiple right-hand sides. + The matrix A may be real, complex, symmetric, Hermitian positive- + definite, or sparse. It may also be rectangular, in which case a + least-squares solution is obtained. + + 2. Background to the Problems + + A set of linear equations may be written in the form + + Ax=b + + where the known matrix A, with real or complex coefficients, is + of size m by n, (m rows and n columns), the known right-hand + vector b has m components (m rows and one column), and the + required solution vector x has n components (n rows and one + column). There may sometimes be p vectors b , i=1,2,...,p on the + i + right-hand side and the equations may then be written as + + AX=B + + the required matrix X having as its p columns the solutions of + Ax =b , i=1,2,...,p. Some routines deal with the latter case, but + i i + for clarity only the case p=1 is discussed here. + + The most common problem, the determination of the unique solution + of Ax=b, occurs when m=n and A is non-singular, that is rank(A)=n + problem, discussed in Section 2.2 below, is the determination of + the least-squares solution of Ax~=b, i.e., the determination of a + vector x which minimizes the Euclidean length (two norm) of the + residual vector r=b-Ax. The usual case has m>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) solution of m real equations in n unknowns, rank + <=n, m>=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<n, then A is rank deficient, the + least-squares solution is not unique and F04QAF will normally + + + converge to the minimal length solution. In practice A will not + have exactly zero singular values, but may instead have small + singular values that we wish to regard as zero. + + The routine provides for this possibility by terminating if + + + + cond(A)>=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|<c or c=0 + z={1/c, 0<|c|<=s (2.4) + + is also computed and this enables c and s to be reconstructed + from the single value z as + + + {0, z=1 + { 2 1/2 {1, z=1 + c={(1-z ) , |z|<1 s={z, |z|<1 + {1/z, |z|>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<n). Usually A is square + (m=n), and both L and U are triangular. The routine uses partial + pivoting, with row interchanges. + + 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: M -- INTEGER Input + On entry: m, the number of rows of the matrix A. + Constraint: 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<n. + + A call to this routine with m=n may be followed by calls to the + routines: + + T + F07AEF (DGETRS) to solve AX=B or A X=B; + + F07AGF (DGECON)(*) to estimate the condition number of A; + + F07AJF (DGETRI)(*) to compute the inverse of A. + + The complex analogue of this routine is F07ARF (ZGETRF)(*). + + 9. Example + + To compute the LU factorization of the matrix A, 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) + + 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}{manpageXXf07aef}{NAG On-line Documentation: f07aef} +\beginscroll +\begin{verbatim} + + + + F07AEF(3NAG) Foundation Library (12/10/92) F07AEF(3NAG) + + + + F07 -- Linear Equations (LAPACK) F07AEF + F07AEF -- 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 + + F07AEF (DGETRS) solves a real system of linear equations with + T + multiple right-hand sides, AX=B or A X=B, where A has been + factorized by F07ADF (DGETRF). + + 2. Specification + + SUBROUTINE F07AEF (TRANS, N, NRHS, A, LDA, IPIV, B, LDB, + 1 INFO) + ENTRY TRANS, N, NRHS, A, LDA, IPIV, B, LDB, INFO + INTEGER N, NRHS, LDA, IPIV(*), LDB, INFO + DOUBLE PRECISION A(LDA,*), B(LDB,*) + CHARACTER*1 TRANS + + The ENTRY statement enables the routine to be called by its + LAPACK name. + + 3. Description + + T + To solve a real system of linear equations AX=B or A X=B, this + routine must be preceded by a call to F07ADF (DGETRF)which + computes the LU factorization of A as A=PLU. The solution is + computed by forward and backward substitution. + + If TRANS = 'N', the solution is computed by solving PLY=B and + then UX=Y. + + T + If TRANS = 'T' or 'C', the solution is computed by solving U Y=B + T T + and then L P 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: TRANS -- CHARACTER*1 Input + On entry: indicates the form of the equations as follows: + if TRANS = 'N', then AX=B is solved for X; + + T + if TRANS = 'T' or 'C', then A X=B is solved for X. + Constraint: TRANS = 'N', 'T' or 'C'. + + 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 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} |