***********************************************************************
* *
* PNEQ - NEWTON METHOD FOR SYSTEMS OF NONLINEAR EQUATIONS. *
* *
***********************************************************************
1. Introduction:
----------------
The double-precision FORTRAN 77 basic subroutine PNEQ 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
PNEQU is added. It calls the basic general subroutine PNEQ. All
subroutines contain a description of formal parameters and extensive
comments. Furthermore, test program TNEQU is included, which contains
30 test problems. This test program serve as an example for using the
subroutine PNEQU, 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 PNEQU:
--------------------
The calling sequence is
CALL PNEQU(N,X,AF,IPAR,RPAR,F,GMAX,IDER,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.
IDER I INTEGER variable that specifies the degree of the
analytically computed derivatives (0 or 1). If IDER=1,
then the subroutine DFUN has to define gradients of
partial functions. In the other case this subroutine
can be empty.
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 PNEQU requires the user supplied subroutines
FUN and DFUN that define partial functions and its gradients and has
the form
SUBROUTINE FUN(N,KA,X,FA)
SUBROUTINE DFUN(N,KA,X,GA)
The arguments of the user supplied subroutines 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.
GA(NF) O DOUBLE PRECISION gradient of the KA-th partial function
at the point X.
3. Subroutine PNEQ:
-------------------
This general subroutine is called from all subroutines described
in Section 2. The calling sequence is
CALL PNEQ(N,X,GA,AG,G,S,XO,GO,H,AF,AFO,XMAX,TOLX,TOLF,TOLB,TOLG,
& XDEL,GMAX,F,MIT,MFV,IDER,IPRNT,ITERM)
The arguments N, X, AF, GMAX, F, IDER, 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 values 2000 (if IDER=1) or 5000 (if IDER=0)
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 PNEQ requires the user supplied subroutines FUN
and DFUN, which is described in Section 2.
4. Verification of the subroutines:
-----------------------------------
Subroutine PNEQU can be verified and tested using the program
TBEQU. This program calls the subroutines TIUD16 (initiation), TAFU16
(partial function evaluation) and TAGU16 (partial gradient evaluation)
containing 30 unconstrained test problems with at most 100 variables. The
results obtained by the program TNEQU on a PC computer with Microsoft
Power Station Fortran compiler have the following form.
NIT= 69 NFV= 70 NFG= 69 F = 0.129919909E-16 ITERM= 3
NIT= 5 NFV= 6 NFG= 5 F = 0.146936794E-34 ITERM= 3
NIT= 4 NFV= 5 NFG= 4 F = 0.133778396E-18 ITERM= 3
NIT= 19 NFV= 22 NFG= 19 F = 0.00000000 ITERM= 3
NIT= 5 NFV= 6 NFG= 5 F = 0.367099893E-22 ITERM= 3
NIT= 16 NFV= 17 NFG= 16 F = 0.443298282E-23 ITERM= 3
NIT= 9 NFV= 10 NFG= 9 F = 0.680392531E-28 ITERM= 3
NIT= 5 NFV= 6 NFG= 5 F = 0.512143291E-29 ITERM= 3
NIT= 25 NFV= 31 NFG= 25 F = 0.376696761E-24 ITERM= 3
NIT= 1 NFV= 1 NFG= 1 F = 369.452805 ITERM=-10
NIT= 1 NFV= 1 NFG= 1 F = 4.22937500 ITERM=-10
NIT= 5 NFV= 6 NFG= 5 F = 0.198980951E-17 ITERM= 3
NIT= 6 NFV= 7 NFG= 6 F = 0.429838243E-19 ITERM= 3
NIT= 6 NFV= 7 NFG= 6 F = 0.587285374E-27 ITERM= 3
NIT= 12 NFV= 13 NFG= 12 F = 0.250108465E-24 ITERM= 3
NIT= 15 NFV= 16 NFG= 15 F = 0.126241819E-21 ITERM= 3
NIT= 3 NFV= 4 NFG= 3 F = 0.367632503E-19 ITERM= 3
NIT= 742 NFV= 798 NFG= 742 F = 0.406346121E-08 ITERM= 2
NIT= 25 NFV= 26 NFG= 25 F = 0.387179362E-19 ITERM= 3
NIT= 5 NFV= 6 NFG= 5 F = 0.347033200E-24 ITERM= 3
NIT= 4 NFV= 5 NFG= 4 F = 0.783999805E-21 ITERM= 3
NIT= 3 NFV= 4 NFG= 3 F = 0.568768369E-19 ITERM= 3
NIT= 15 NFV= 21 NFG= 15 F = 0.998705588E-24 ITERM= 3
NIT= 13 NFV= 14 NFG= 13 F = 0.128608165E-28 ITERM= 3
NIT= 7 NFV= 8 NFG= 7 F = 0.270729701E-23 ITERM= 3
NIT= 5 NFV= 6 NFG= 5 F = 0.248397707E-27 ITERM= 3
NIT= 12 NFV= 15 NFG= 12 F = 0.831787473E-21 ITERM= 3
NIT= 14 NFV= 15 NFG= 14 F = 0.574631780E-22 ITERM= 3
NIT= 5 NFV= 6 NFG= 5 F = 0.576649626E-17 ITERM= 3
NIT= 5 NFV= 6 NFG= 5 F = 0.549786000E-16 ITERM= 3
NITER = 1061 NFVAL = 1158 NSUCC = 27
TIME= 0:00:05.89
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.