*********************************************************************** * * * PBEQ - BROYDEN QUASI-NEWTON METHOD FOR SYSTEMS OF * * NONLINEAR EQUATIONS. * * * *********************************************************************** 1. Introduction: ---------------- The double-precision FORTRAN 77 basic subroutine PBEQ is designed to find a close approximation to a local minimum of a sum of squares FA_1(X) = 0, FA_2(X) = 0, ..., FA_N(X) = 0. Here X is a vector of N variables and FA_I(X), 1 <= I <= N, are twice continuously differentiable functions. We assume that the Jacobian matrix, which will be denoted by AG(X) (it has N rows and N columns) is dense. To simplify user's work, an additional easy to use subroutine PBEQU is added. It calls the basic general subroutine PBEQ. All subroutines contain a description of formal parameters and extensive comments. Furthermore, test program TBEQU is included, which contains 30 test problems. This test program serve as an example for using the subroutine PBEQU, verify its correctness and demonstrate its efficiency. In this short guide, we describe all subroutines which can be called from the user's program. In the description of formal parameters, we introduce a type of the argument that specifies whether the argument must have a value defined on entry to the subroutine (I), whether it is a value which will be returned (O), or both (U), or whether it is an auxiliary value (A). Note that the arguments of the type I can be changed on output under some circumstances, especially if improper input values were given. Besides formal parameters, we can use a COMMON /STAT/ block containing statistical information. This block, used in each subroutine has the following form: COMMON /STAT/ NRES,NDEC,NREM,NADD,NIT,NFV,NFG,NFH The arguments have the following meaning: Argument Type Significance ---------------------------------------------------------------------- NRES O Positive INTEGER variable that indicates the number of restarts. NDEC O Positive INTEGER variable that indicates the number of matrix decompositions. NRED O Positive INTEGER variable that indicates the number of reductions. NREM O Positive INTEGER variable that indicates the number of constraint deletions during the QP solutions. NADD O Positive INTEGER variable that indicates the number of constraint additions during the QP solutions. NIT O Positive INTEGER variable that indicates the number of iterations. NFV O Positive INTEGER variable that indicates the number of function evaluations. NFG O Positive INTEGER variable that specifies the number of gradient evaluations. NFH O Positive INTEGER variable that specifies the number of Hessian evaluations. 2. Subroutine PBEQU: -------------------- The calling sequence is CALL PBEQU(N,X,AF,IPAR,RPAR,F,GMAX,IPRNT,ITERM) The arguments have the following meaning. Argument Type Significance ---------------------------------------------------------------------- N I Positive INTEGER variable that specifies the number of variables of the partially separable function. X(N) U On input, DOUBLE PRECISION vector with the initial estimate to the solution. On output, the approximation to the minimum. AF(N) O DOUBLE PRECISION vector which contains values of partial functions. IPAR(2) I INTEGER parameters: IPAR(1)=MIT, IPAR(2)=MFV. Parameters MIT, MFV are described in Section 3 together with other parameters of the subroutine PNEQ. RPAR(7) I DOUBLE PRECISION parameters: RPAR(1)=XMAX, RPAR(2)=TOLX, RPAR(3)=TOLF, RPAR(4)=TOLB, RPAR(5)=TOLG, RPAR(6)-NONE, RPAR(7)=XDEL. Parameters XMAX, TOLX, TOLF, TOLB, TOLG, XDEL, are described in Section 3 together with other parameters of the subroutine PNEQ. F O DOUBLE PRECISION value of the objective function at the solution X. GMAX O DOUBLE PRECISION maximum absolute value of a partial derivative of the objective function. IPRNT I INTEGER variable that specifies print: IPRNT= 0 - print is suppressed, IPRNT= 1 - basic print of final results, IPRNT=-1 - extended print of final results, IPRNT= 2 - basic print of intermediate and final results, IPRNT=-2 - extended print of intermediate and final results. ITERM O INTEGER variable that indicates the cause of termination: ITERM= 1 - if |X - XO| was less than or equal to TOLX in two subsequent iterations, ITERM= 2 - if |F - FO| was less than or equal to TOLF in two subsequent iterations, ITERM= 3 - if F is less than or equal to TOLB, ITERM= 4 - if GMAX is less than or equal to TOLG, ITERM= 6 - if termination criterion was not satisfied, but the solution is probably acceptable, ITERM=11 - if NIT exceeded MIT, ITERM=12 - if NFV exceeded MFV, ITERM< 0 - if the method failed. The subroutines PBEQU requires the user supplied subroutine FUN that define partial functions and its gradients and has the form SUBROUTINE FUN(N,KA,X,FA) The arguments of the user supplied subroutine have the following meaning. Argument Type Significance ---------------------------------------------------------------------- N I Positive INTEGER variable that specifies the number of variables of the objective function. KA I INTEGER index of the partial function. X(NF) I DOUBLE PRECISION an estimate to the solution. FA O DOUBLE PRECISION value of the KA-th partial function at the point X. 3. Subroutine PBEQ: ------------------- This general subroutine is called from all subroutines described in Section 2. The calling sequence is CALL PBEQ(N,X,GA,AG,G,S,XO,GO,H,AF,AFO,XMAX,TOLX,TOLF,TOLB,TOLG, & XDEL,GMAX,F,MIT,MFV,IPRNT,ITERM) The arguments N, X, AF, GMAX, F, IPRNT,ITERM have the same meaning as in Section 2. Other arguments have the following meaning: Argument Type Significance ---------------------------------------------------------------------- GA(N) A DOUBLE PRECISION gradient of the partial function. AG(N*N) A DOUBLE PRECISION elements of the Jacobian matrix. G(N) A DOUBLE PRECISION gradient of the objective function. S(N) A DOUBLE PRECISION direction vector. XO(N) A DOUBLE PRECISION array which contains increments of variables. GO(N) A DOUBLE PRECISION array which contains increments of gradients. H(M) A DOUBLE PRECISION array which contains an upper triangular matrix in the QR decomposition of the matrix AG. Here M=(N+1)*N/2. AFO(N) A DOUBLE PRECISION vector which contains old values of partial functions. XMAX I DOUBLE PRECISION maximum stepsize; the choice XMAX=0 causes that the default value 1.0D+16 will be taken. TOLX I DOUBLE PRECISION tolerance for the change of the coordinate vector X; the choice TOLX=0 causes that the default value TOLX=1.0D-16 will be taken. TOLF I DOUBLE PRECISION tolerance for the change of function values; the choice TOLF=0 causes that the default value TOLF=1.0D-16 will be taken. TOLB I DOUBLE PRECISION minimum acceptable function value; the choice TOLB=0 causes that the default value TOLB=1.0D-16 will be taken. TOLG I DOUBLE PRECISION tolerance for the Lagrangian function gradient; the choice TOLG=0 causes that the default value TOLG=1.0D-16 will be taken. XDEL I DOUBLE PRECISION initial trust-region radius. MIT I INTEGER variable that specifies the maximum number of iterations; the choice MIT=0 causes that the default value 1000 will be taken. MFV I INTEGER variable that specifies the maximum number of function evaluations; the choice |MFV|=0 causes that the default value 3000 will be taken. The choice of parameter XMAX is rather sensitive. If the objective function is badly scalled, then the default value XMAX=1000 can be too small. On the other hand, a lower value (XMAX=1 say) can sometimes prevent divergence of the iterative process. The subroutine PBEQ requires the user supplied subroutines FUN and DFUN, which is described in Section 2. 4. Verification of the subroutines: ----------------------------------- Subroutine PBEQU can be verified and tested using the program TBEQU. This program calls the subroutines TIUD16 (initiation), TAFU16 (function evaluation) and TAGU16 (gradient evaluation) containing 30 unconstrained test problems with at most 100 variables. The results obtained by the program TBEQU on a PC computer with Microsoft Power Station Fortran compiler have the following form. NIT= 215 NFV= 2172 NFG= 0 F = 0.298627144E-16 ITERM= 3 NIT= 6 NFV= 107 NFG= 0 F = 0.258494126E-21 ITERM= 3 NIT= 3 NFV= 206 NFG= 0 F = 0.460166706E-16 ITERM= 3 NIT= 23 NFV= 326 NFG= 0 F = 0.832738048E-18 ITERM= 3 NIT= 7 NFV= 108 NFG= 0 F = 0.411317746E-25 ITERM= 3 NIT= 16 NFV= 117 NFG= 0 F = 0.350419921E-17 ITERM= 3 NIT= 29 NFV= 130 NFG= 0 F = 0.145620665E-16 ITERM= 3 NIT= 9 NFV= 110 NFG= 0 F = 0.319884855E-17 ITERM= 3 NIT= 12 NFV= 214 NFG= 0 F = 0.188713592E-16 ITERM= 3 NIT= 24 NFV= 650 NFG= 0 F = 79.3894238 ITERM= 1 NIT= 1 NFV= 101 NFG= 0 F = 4.22937500 ITERM=-10 NIT= 25 NFV= 126 NFG= 0 F = 0.765197338E-16 ITERM= 3 NIT= 7 NFV= 108 NFG= 0 F = 0.265817165E-17 ITERM= 3 NIT= 19 NFV= 120 NFG= 0 F = 0.951689359E-16 ITERM= 3 NIT= 27 NFV= 329 NFG= 0 F = 0.624606364E-19 ITERM= 3 NIT= 15 NFV= 116 NFG= 0 F = 0.446541494E-16 ITERM= 3 NIT= 4 NFV= 105 NFG= 0 F = 0.113050372E-17 ITERM= 3 NIT= 21 NFV= 324 NFG= 0 F = 0.356952390E-18 ITERM= 3 NIT= 49 NFV= 559 NFG= 0 F = 0.646948388E-21 ITERM= 3 NIT= 12 NFV= 113 NFG= 0 F = 0.894740627E-16 ITERM= 3 NIT= 6 NFV= 107 NFG= 0 F = 0.989715952E-19 ITERM= 3 NIT= 5 NFV= 106 NFG= 0 F = 0.441231213E-16 ITERM= 3 NIT= 19 NFV= 625 NFG= 0 F = 0.624927296E-16 ITERM= 3 NIT= 29 NFV= 332 NFG= 0 F = 0.406213950E-16 ITERM= 3 NIT= 9 NFV= 110 NFG= 0 F = 0.427797827E-19 ITERM= 3 NIT= 7 NFV= 108 NFG= 0 F = 0.175709374E-17 ITERM= 3 NIT= 20 NFV= 524 NFG= 0 F = 0.245263566E-24 ITERM= 3 NIT= 15 NFV= 116 NFG= 0 F = 0.735209354E-21 ITERM= 3 NIT= 7 NFV= 108 NFG= 0 F = 0.346607630E-16 ITERM= 3 NIT= 9 NFV= 110 NFG= 0 F = 0.691712435E-18 ITERM= 3 NITER = 650 NFVAL = 8387 NSUCC = 28 TIME= 0:00:01.52 The rows corresponding to individual test problems contain the number of iterations NIT, the number of function evaluations NFV, the number of gradient evaluations NFG, the final value of the objective function F (sum of squares of the partial functions)and the cause of termination ITERM.