*********************************************************************** * * * PSQP - A SEQUENTIAL QUADRATIC PROGRAMMING ALGORITHM * * FOR GENERAL NONLINEAR PROGRAMMING PROBLEMS. * * * *********************************************************************** 1. Introduction: ---------------- The double-precision FORTRAN 77 basic subroutine PSQP is designed to find a close approximation to a local minimum of a nonlinear objective function F(X) with simple bounds on variables and general nonlinear constraints. Here X is a vector of N variables and F(X), is a smooth function. Simple bounds are assumed in the form X(I) unbounded if IX(I) = 0, XL(I) <= X(I) if IX(I) = 1, X(I) <= XU(I) if IX(I) = 2, XL(I) <= X(I) <= XU(I) if IX(I) = 3, XL(I) = X(I) = XU(I) if IX(I) = 5, where 1 <= I <= N. General nonlinear constraints are assumed in the form C_I(X) unbounded if IC(I) = 0, CL(I) <= C_I(X) if IC(I) = 1, C_I(X) <= CU(I) if IC(I) = 2, CL(I) <= C_I(X) <= CU(I) if IC(I) = 3, CL(I) = C_I(X) = CU(I) if IC(I) = 5, where C_I(X), 1 <= I <= NC, are twice continuously differentiable functions. To simplify user's work, an additional easy to use subroutine PSQPN is added. It calls the basic general subroutine PSQP. All subroutines contain a description of formal parameters and extensive comments. Furthermore, test program TSQPN is included, which contains several test problems. This test programs serve as an example for using the subroutine PSQPN, 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 PSQN: ------------------- The calling sequence is CALL PSQPN(NF,NB,NC,X,IX,XL,XU,CF,IC,CL,CU,IPAR,RPAR,F,GMAX, & CMAX,IPRNT,ITERM) The arguments have the following meaning. Argument Type Significance ---------------------------------------------------------------------- NF I Positive INTEGER variable that specifies the number of variables of the objective function. NB I Nonnegative INTEGER variable that specifies whether the simple bounds are suppressed (NB=0) or accepted (NB>0). NC I Nonnegative INTEGER variable that specifies the number of general nonlinear constraints; if NC=0 the general nonlinear constraints are suppressed. X(NF) U On input, DOUBLE PRECISION vector with the initial estimate to the solution. On output, the approximation to the minimum. IX(NF) I On input (significant only if NB>0) INTEGER vector containing the simple bounds types: IX(I)=0 - the variable X(I) is unbounded, IX(I)=1 - the lower bound X(I) >= XL(I), IX(I)=2 - the upper bound X(I) <= XU(I), IX(I)=3 - the two side bound XL(I) <= X(I) <= XU(I), IX(I)=5 - the variable X(I) is fixed (given by its initial estimate). XL(NF) I DOUBLE PRECISION vector with lower bounds for variables (significant only if NB>0). XU(NF) I DOUBLE PRECISION vector with upper bounds for variables (significant only if NB>0). CF(NC) A DOUBLE PRECISION vector which contains values of constraint functions (only if NC>0). IC(NC) I On input (significant only if NC>0) INTEGER vector which contains constraint types: IC(K)=0 - the constraint CF(K) is not used, IC(K)=1 - the lower constraint CF(K) >= CL(K), IC(K)=2 - the upper constraint CF(K) <= CU(K), IC(K)=3 - the two side constraint CL(K) <= CF(K) <= CU(K), IC(K)=5 - the equality constraint CF(K) = CL(K). CL(NC) I DOUBLE PRECISION vector with lower bounds for constraint functions (significant only if NC>0). CU(NC) I DOUBLE PRECISION vector with upper bounds for constraint functions (significant only if NC>0). IPAR(6) A INTEGER parameters: IPAR(1)=MIT, IPAR(2)=MFV, IPAR(3)-NONE, IPAR(4)-NONE, IPAR(5)=MET, IPAR(5)=MEC. Parameters MIT, MFV, MET, MEC are described in Section 3 together with other parameters of the subroutine PSQP. RPAR(5) A DOUBLE PRECISION parameters: RPAR(1)=XMAX, RPAR(2)=TOLX, RPAR(3)=TOLC, RPAR(4)=TOLG, RPAR(5)=RPF. Parameters XMAX, TOLX, TOLC, TOLG, RPF are described in Section 3 together with other parameters of the subroutine PSQP. 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 Lagrangian function. CMAX O maximum constraint violation. 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 MTESX subsequent iterations, ITERM= 2 - if |F - FO| was less than or equal to TOLF in MTESF 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=11 - if NIT exceeded MIT, ITERM=12 - if NFV exceeded MFV, ITERM< 0 - if the method failed. If ITERM=-6, then the termination criterion has not been satisfied, but the point obtained is usually acceptable. The subroutine PSQPN requires the user supplied subroutines OBJ, DOBJ that define the objective function and its gradient and CON, DCON that define constraint functions and their gradients. These subroutines have the form SUBROUTINE OBJ(NF,X,F) SUBROUTINE DOBJ(NF,X,G) SUBROUTINE CON(NF,KC,X,FC) SUBROUTINE DCON(NF,KC,X,GC) The arguments of the user supplied subroutine have the following meaning. Argument Type Significance ---------------------------------------------------------------------- NF I Positive INTEGER variable that specifies the number of variables of the objective function. X(NF) I DOUBLE PRECISION an estimate to the solution. F O DOUBLE PRECISION value of the objective function at the point X. G(NF) O DOUBLE PRECISION gradient of the objective function at the point X. KC I INTEGER index of the partial function. FC O DOUBLE PRECISION value of the KC-th partial function at the point X. GC(NF) O DOUBLE PRECISION gradient of the KC-th partial function at the point X. 3. Subroutine PSQP: ------------------- This general subroutine is called from all the subroutines described in Section 2. The calling sequence is CALL PSQP(NF,NB,NC,X,IX,XL,XU,CF,IC,CL,CU,CG,CFO,CFD,GC,ICA,CR, & CZ,CP,GF,G,H,S,XO,GO,XMAX,TOLX,TOLC,TOLG,RPF,CMAX,GMAX,F,MIT, & MFV,MEC,IPRNT,ITERM). The arguments NF, NB, NC, X, IX, XL, XU, CF, IC, CL, CU, CMAX, GMAX, F, IPRNT, ITERM, have the same meaning as in Section 2. Other arguments have the following meaning: Argument Type Significance ---------------------------------------------------------------------- CG(NF*NC) A DOUBLE PRECISION elements of the constraint Jacobian matrix. CFO(NC+1) A DOUBLE PRECISION vector which contains old values of constraint functions. CFD(NC) A DOUBLE PRECISION vector of constraint function increments. GC(NF) A DOUBLE PRECISION gradient of the constraint function. ICA(NC) A INTEGER vector containing indices of active constraints. CR(NCR) A DOUBLE PRECISION matrix containing triangular decomposition of the orthogonal projection kernel (NCR is equal to NF*(NF+1)/2). CZ(NF) A DOUBLE PRECISION vector of Lagrange multipliers. of linear manifold defined by active constraints. CP(NF) A DOUBLE PRECISION auxiliary array. GF(NF) A DOUBLE PRECISION gradient of the objective function. G(NF) A DOUBLE PRECISION gradient of the Lagrangian function. H(NH) A DOUBLE PRECISION variable metric approximation of the Hessian matrix of the Lagrangian function. S(NF) A DOUBLE PRECISION direction vector. XO(NF) A DOUBLE PRECISION vector which contains increments of variables. GO(NF) A DOUBLE PRECISION vector which contains increments of gradients. XMAX I DOUBLE PRECISION maximum stepsize; the choice XMAX=0 causes that the default value 1.0D+3 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. TOLC I DOUBLE PRECISION tolerance for the constraint violation; the choice TOLC=0 causes that the default value TOLC=1.0D-6 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-6 will be taken. RPF I DOUBLE PRECISION value of the penalty coefficient; the choice RPF=0 causes that the default value 1.0D-4 will be taken. 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 2000 will be taken. MET I INTEGER variable that specifies the variable metric update. MET=1 - the BFGS update is used. MET=2 - the Hoshino update is used. The choice MET=0 causes that the default value MET=1 will be taken. MEC I INTEGER variable that specifies a correction when the negative curvature is detected: MEC=1 - correction is not used. MEC=2 - the Powell correction is used. The choice MEC=0 causes that the default value MEC=2 will be taken. The default velue RPF=0.0001 is relatively small. Therefore, larger value (RPF=1 say) can sometimes be more suitable. The subroutine PSQP requires the user supplied subroutines OBJ DOBJ, CON, DCON, which are described in Section 2. 4. Subroutine PLQDB1: --------------------- Since the dual range space method for solving quadratic programming subproblems arising in sequential quadratic programming algorithms can be used separately in many applications, we describe the subroutine PLQDB1 in more details. The calling sequence is CALL PLQDB1(NF,NC,X,IX,XL,XU,CF,CFD,IC,ICA,CL,CU,CG,CR,CZ,G,GO, & H,S,MFP,KBF,KBC,IDECF,ETA2,ETA9,EPS7,EPS9,UMAX,GMAX,N,ITERQ) The arguments NF, NC, X, IX, XL, XU, CF, IC, CL, CU, have the same meaning as in Section 2 (only with the difference that the arguments X and CF are of the type (I), i.e. they must have a value defined on entry to ULQDF1 and they are not changed). The arguments CFD, ICA, CG, CR, CZ have the same meaning as in Section 3 (only with the difference that the arguments CFD, ICA, CR, CZ are of the type (O), i.e. their values can be used subsequently). Other arguments have the following meaning: Argument Type Significance ---------------------------------------------------------------------- G(NF) O DOUBLE PRECISION gradient of the Lagrangian function. GO(NF) A DOUBLE PRECISION old gradient of the Lagrangian function. H(NH) U DOUBLE PRECISION Choleski decomposition of the approximate Hessian (NH is equal to NF*(NF+1)/2). S(NF) O DOUBLE PRECISION direction vector. MFP I INTEGER variable that specifies the type of the computed point. MFP=1 - computation is terminated whenever an arbitrary feasible point is found, MFP=2 - computation is terminated whenever an optimum feasible point is found, MFP=3 - computation starts from the previously reached point and is terminated whenever an optimum feasible point is found. KBF I INTEGER variable that specifies simple bounds on variables. KBF=0 - simple bounds are suppressed, KBF=1 - one sided simple bounds, KBF=2 - two sided simple bounds. KBC I INTEGER variable that specifies general linear constraints. KBC=0 - linear constraints are suppressed, KBC=1 - one sided linear constraints, KBC=2 - two sided linear constraints. IDECF U INTEGER variable that specifies the type of matrix decomposition. IDECF= 0 - no decomposition, IDECF= 1 - Choleski decomposition, IDECF= 9 - inversion, IDECF=10 - diagonal matrix. ETA2 I DOUBLE PRECISION tolerance for positive definiteness in the Choleski decomposition. ETA9 I DOUBLE PRECISION maximum floating point number. EPS7 I DOUBLE PRECISION tolerance for linear independence of constraints (the recommended value is 1.0D-10). EPS9 I DOUBLE PRECISION tolerance for the definition of active constraints (the recommended value is 1.0D-8). UMAX O DOUBLE PRECISION maximum absolute value of the negative Lagrange multiplier. GMAX O DOUBLE PRECISION infinity norm of the gradient of the Lagrangian function. N O INTEGER dimension of a manifold defined by active constraints. ITERQ O INTEGER variable that indicates the type of the computed feasible point. ITERQ= 1 - an arbitrary feasible point was found, ITERQ= 2 - the optimum feasible point was found, ITERQ=-1 - an arbitrary feasible point does not exist, ITERQ=-2 - the optimum feasible point does not exist. 5. Verification of the subroutines: ----------------------------------- Subroutine PSQPN can be verified and tested using the program TSQPN. This program calls the subroutines TIND07 (initiation), TFFU07 (objective function evaluation), TFGU07 (objective gradient evaluation), TCFU07 (constraint functions evaluation) and TFGU07 (constraint gradients evaluation) containing 34 equality constrained test problems with at most 20 variables. The results obtained by the program TSQPN on a PC computer with Microsoft Power Station Fortran compiler have the following form. NIT= 7 NFV= 7 NFG= 7 F=-1.41421 C=0.8E-08 G=0.4E-06 ITERM= 4 NIT= 12 NFV= 12 NFG= 12 F=-1.00000 C=0.5E-10 G=0.6E-07 ITERM= 4 NIT= 10 NFV= 11 NFG= 10 F=-30.0000 C=0.3E-10 G=0.8E-08 ITERM= 4 NIT= 6 NFV= 6 NFG= 6 F= 1.28072 C=0.0E+00 G=0.4E-06 ITERM= 4 NIT= 36 NFV= 40 NFG= 36 F=0.284597E-01 C=0.0E+00 G=0.1E-06 ITERM= 4 NIT= 11 NFV= 13 NFG= 11 F= 1.00000 C=0.0E+00 G=0.4E-06 ITERM= 4 NIT= 6 NFV= 6 NFG= 6 F=-6961.81 C=0.7E-08 G=0.1E-06 ITERM= 4 NIT= 4 NFV= 4 NFG= 4 F= 40.1987 C=0.0E+00 G=0.2E-06 ITERM= 4 NIT= 9 NFV= 9 NFG= 9 F= 13.3567 C=0.3E-06 G=0.8E-07 ITERM= 4 NIT= 16 NFV= 23 NFG= 16 F=-22.6274 C=0.9E-11 G=0.3E-06 ITERM= 4 NIT= 14 NFV= 14 NFG= 14 F= 1.00000 C=0.0E+00 G=0.8E-06 ITERM= 4 NIT= 10 NFV= 13 NFG= 10 F= 6.00000 C=0.2E-12 G=0.1E-06 ITERM= 4 NIT= 54 NFV= 71 NFG= 54 F= 6299.84 C=0.4E-15 G=0.2E-07 ITERM= 4 NIT= 8 NFV= 8 NFG= 8 F=-.834032 C=0.3E-07 G=0.3E-08 ITERM= 4 NIT= 30 NFV= 30 NFG= 30 F=-1162.12 C=0.0E+00 G=0.1E-06 ITERM= 4 NIT= 74 NFV= 76 NFG= 74 F= 4.75530 C=0.0E+00 G=0.4E-06 ITERM= 4 NIT= 22 NFV= 22 NFG= 22 F= 727.679 C=0.4E-14 G=0.7E-06 ITERM= 4 NIT= 11 NFV= 14 NFG= 11 F=-44.0000 C=0.9E-12 G=0.8E-07 ITERM= 4 NIT= 29 NFV= 35 NFG= 29 F=-210.408 C=0.2E-13 G=0.1E-06 ITERM= 4 NIT= 4 NFV= 4 NFG= 4 F=-30665.0 C=0.3E-08 G=0.1E-06 ITERM= 4 NIT= 11 NFV= 30 NFG= 11 F=-.528034E+07 C=0.0E+00 G=0.1E-07 ITERM= 4 NIT= 21 NFV= 21 NFG= 21 F=-1.90516 C=0.1E-08 G=0.2E-10 ITERM= 4 NIT= 10 NFV= 12 NFG= 10 F= 5.00000 C=0.2E-11 G=0.8E-07 ITERM= 4 NIT= 45 NFV= 50 NFG= 45 F= 135.076 C=0.3E-14 G=0.3E-07 ITERM= 4 NIT= 10 NFV= 10 NFG= 10 F= 4.07125 C=0.0E+00 G=0.7E-10 ITERM= 4 NIT= 16 NFV= 19 NFG= 16 F= 680.630 C=0.1E-11 G=0.5E-06 ITERM= 4 NIT= 26 NFV= 35 NFG= 26 F= 221.878 C=0.2E-15 G=0.3E-06 ITERM= 4 NIT= 32 NFV= 33 NFG= 32 F= 3.95116 C=0.9E-11 G=0.6E-06 ITERM= 4 NIT= 21 NFV= 21 NFG= 21 F= 7049.25 C=0.4E-07 G=0.1E-06 ITERM= 4 NIT= 16 NFV= 16 NFG= 16 F=-.866025 C=0.2E-08 G=0.2E-09 ITERM= 4 NIT= 22 NFV= 24 NFG= 22 F= 24.3062 C=0.5E-12 G=0.3E-06 ITERM= 4 NIT= 22 NFV= 22 NFG= 22 F= 32.3487 C=0.8E-12 G=0.1E-06 ITERM= 4 NIT= 77 NFV= 77 NFG= 77 F= 174.787 C=0.6E-11 G=0.4E-10 ITERM= 4 NIT= 32 NFV= 35 NFG= 32 F= 133.728 C=0.9E-13 G=0.8E-06 ITERM= 4 NITER = 734 NFVAL = 823 NSUCC = 34 TIME= 0:00:00.03 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, the constraint violation C, the norm of the Lagrangian function gradient G and the cause of termination ITERM.