NAG Library Routine Document
e04dgf
(uncon_conjgrd_comp_old)
e04dga (uncon_conjgrd_comp)
Note: this routine uses optional parameters to define choices in the problem specification and in the details of the algorithm. If you wish to use default
settings for all of the optional parameters, you need only read Sections 1 to 10 of this document. If, however, you wish to reset some or all of the settings please refer to Section 11 for a detailed description of the algorithm and to Section 12 for a detailed description of the specification of the optional parameters.
1
Purpose
e04dgf/e04dga minimizes an unconstrained nonlinear function of several variables using a preconditioned, limited memory quasiNewton conjugate gradient method. First derivatives (or an ‘acceptable’ finite difference approximation to them) are required. It is intended for use on large scale problems.
e04dga is a version of
e04dgf that has additional arguments in order to make it safe for use in multithreaded applications (see
Section 5). The initialization routine
e04wbf must have been called before calling
e04dga.
2
Specification
2.1
Specification for e04dgf
Fortran Interface
Subroutine e04dgf ( 
n,
objfun,
iter,
objf,
objgrd,
x,
iwork,
work,
iuser,
ruser,
ifail) 
Integer, Intent (In)  :: 
n  Integer, Intent (Inout)  :: 
iuser(*),
ifail  Integer, Intent (Out)  :: 
iter,
iwork(n+1)  Real (Kind=nag_wp), Intent (Inout)  :: 
x(n),
ruser(*)  Real (Kind=nag_wp), Intent (Out)  :: 
objf,
objgrd(n),
work(13*n)  External  :: 
objfun 

C Header Interface
#include nagmk26.h
void 
e04dgf_ (
const Integer *n,
void (NAG_CALL *objfun)(
Integer *mode,
const Integer *n,
const double x[],
double *objf,
double objgrd[],
const Integer *nstate,
Integer iuser[],
double ruser[]),
Integer *iter,
double *objf,
double objgrd[],
double x[],
Integer iwork[],
double work[],
Integer iuser[],
double ruser[],
Integer *ifail) 

2.2
Specification for e04dga
Fortran Interface
Subroutine e04dga ( 
n,
objfun,
iter,
objf,
objgrd,
x,
iwork,
work,
iuser,
ruser,
lwsav,
iwsav,
rwsav,
ifail) 
Integer, Intent (In)  :: 
n  Integer, Intent (Inout)  :: 
iuser(*),
iwsav(610),
ifail  Integer, Intent (Out)  :: 
iter,
iwork(n+1)  Real (Kind=nag_wp), Intent (Inout)  :: 
x(n),
ruser(*),
rwsav(475)  Real (Kind=nag_wp), Intent (Out)  :: 
objf,
objgrd(n),
work(13*n)  Logical, Intent (Inout)  :: 
lwsav(120)  External  :: 
objfun 

C Header Interface
#include nagmk26.h
void 
e04dga_ (
const Integer *n,
void (NAG_CALL *objfun)(
Integer *mode,
const Integer *n,
const double x[],
double *objf,
double objgrd[],
const Integer *nstate,
Integer iuser[],
double ruser[]),
Integer *iter,
double *objf,
double objgrd[],
double x[],
Integer iwork[],
double work[],
Integer iuser[],
double ruser[],
logical lwsav[],
Integer iwsav[],
double rwsav[],
Integer *ifail) 

Before calling
e04dga, or
either of the option setting routines
e04dja or
e04dka,
routine
e04wbf must be called.
The specification for
e04wbf is:
Fortran Interface
Integer, Intent (In)  :: 
lcwsav,
llwsav,
liwsav,
lrwsav  Integer, Intent (Inout)  :: 
ifail  Integer, Intent (Out)  :: 
iwsav(liwsav)  Real (Kind=nag_wp), Intent (Out)  :: 
rwsav(lrwsav)  Logical, Intent (Out)  :: 
lwsav(llwsav)  Character (*), Intent (In)  :: 
rname  Character (80), Intent (Out)  :: 
cwsav(lcwsav) 

C Header Interface
#include nagmk26.h
void 
e04wbf (
const char *rname,
char cwsav[],
const Integer *lcwsav,
logical lwsav[],
const Integer *llwsav,
Integer iwsav[],
const Integer *liwsav,
double rwsav[],
const Integer *lrwsav,
Integer *ifail,
const Charlen length_rname,
const Charlen length_cwsav) 

e04wbf should be called with
${\mathbf{rname}}=\text{'e04dga'}$.
lcwsav,
llwsav,
liwsav and
lrwsav, the declared lengths of
cwsav,
lwsav,
iwsav and
rwsav respectively, must satisfy:
 ${\mathbf{lcwsav}}\ge 1$
 ${\mathbf{llwsav}}\ge 120$
 ${\mathbf{liwsav}}\ge 610$
 ${\mathbf{lrwsav}}\ge 475$
The contents of the
arrays
cwsav,
lwsav,
iwsav and
rwsav
must not be altered between calling routines
e04dga,
e04dja,
e04dka and
e04wbf.
3
Description
e04dgf/e04dga is designed to solve unconstrained minimization problems of the form
where
$x$ is an
$n$element vector.
You must supply an initial estimate of the solution.
For maximum reliability, it is preferable to provide all first partial derivatives. If all of the derivatives cannot be provided, you are recommended to obtain approximate values (using finite differences) by calling
e04xaf/e04xaa from within
objfun. This is illustrated in
Section 10 in
e04djf/e04dja.
The method used by
e04dgf/e04dga is described in
Section 11.
4
References
Gill P E and Murray W (1979) Conjugategradient methods for largescale nonlinear optimization Technical Report SOL 7915 Department of Operations Research, Stanford University
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
5
Arguments
 1: $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of variables.
Constraint:
${\mathbf{n}}>0$.
 2: $\mathbf{objfun}$ – Subroutine, supplied by the user.External Procedure

objfun must calculate the objective function
$F\left(x\right)$ and possibly its gradient as well for a specified
$n$element vector
$x$.
The specification of
objfun is:
Fortran Interface
Integer, Intent (In)  :: 
n,
nstate  Integer, Intent (Inout)  :: 
mode,
iuser(*)  Real (Kind=nag_wp), Intent (In)  :: 
x(n)  Real (Kind=nag_wp), Intent (Inout)  :: 
ruser(*)  Real (Kind=nag_wp), Intent (Out)  :: 
objf,
objgrd(n) 

 1: $\mathbf{mode}$ – IntegerInput/Output

On entry: indicates which values must be assigned during each call of
objfun. Only the following values need be assigned:
 ${\mathbf{mode}}=0$
 objf.
 ${\mathbf{mode}}=2$
 objf and objgrd.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem, and in this case
e04dgf/e04dga will terminate with
ifail set to
mode.
 2: $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of variables.
 3: $\mathbf{x}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: $x$, the vector of variables at which the objective function and its gradient are to be evaluated.
 4: $\mathbf{objf}$ – Real (Kind=nag_wp)Output

On exit: the value of the objective function at $x$.
 5: $\mathbf{objgrd}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: if ${\mathbf{mode}}=2$,
${\mathbf{objgrd}}\left(\mathit{i}\right)$ must contain the value of $\frac{\partial F}{\partial {x}_{\mathit{i}}}$ evaluated at $x$, for $\mathit{i}=1,2,\dots ,n$.
 6: $\mathbf{nstate}$ – IntegerInput

On entry: will be
$1$ on the first call of
objfun by
e04dgf/e04dga, and
$0$ for all subsequent calls. Thus, you may wish to test,
nstate within
objfun in order to perform certain calculations once only. For example, you may read data or initialize COMMON blocksglobal variables when
${\mathbf{nstate}}=1$.
 7: $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace
 8: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

objfun is called with the arguments
iuser and
ruser as supplied to
e04dgf/e04dga. You should use the arrays
iuser and
ruser to supply information to
objfun.
objfun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
e04dgf/e04dga is called. Arguments denoted as
Input must
not be changed by this procedure.
Note: objfun should not return floatingpoint NaN (Not a Number) or infinity values, since these are not handled by
e04dgf/e04dga. If your code inadvertently
does return any NaNs or infinities,
e04dgf/e04dga is likely to produce unexpected results.
objfun should be tested separately before being used in conjunction with
e04dgf/e04dga. See also the description of the optional parameter
Verify.
 3: $\mathbf{iter}$ – IntegerOutput

On exit: the total number of iterations performed.
 4: $\mathbf{objf}$ – Real (Kind=nag_wp)Output

On exit: the value of the objective function at the final iterate.
 5: $\mathbf{objgrd}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the gradient of the objective function at the final iterate (or its finite difference approximation).
 6: $\mathbf{x}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: an initial estimate of the solution.
On exit: the final estimate of the solution.
 7: $\mathbf{iwork}\left({\mathbf{n}}+1\right)$ – Integer arrayWorkspace
 8: $\mathbf{work}\left(13\times {\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayWorkspace

 9: $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace
 10: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

iuser and
ruser are not used by
e04dgf/e04dga, but are passed directly to
objfun and may be used to pass information to this routine.
 11: $\mathbf{ifail}$ – IntegerInput/Output

Note: for e04dga, ifail does not occur in this position in the argument list. See the additional arguments described below.
On entry:
ifail must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit, the recommended value is
$1$.
When the value $\mathbf{1}\text{ or}1$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
e04dgf/e04dga returns with
${\mathbf{ifail}}={\mathbf{0}}$ if the following three conditions are satisfied:
(i) 
${F}_{k1}{F}_{k}<{\tau}_{F}\left(1+\left{F}_{k}\right\right)$ 
(ii) 
$\Vert {x}_{k1}{x}_{k}\Vert <\sqrt{{\tau}_{F}}\left(1+\Vert {x}_{k}\Vert \right)$ 
(iii) 
$\Vert {g}_{k}\Vert \le \sqrt[3]{{\tau}_{F}}\left(1+\left{F}_{k}\right\right)$ or $\Vert {g}_{k}\Vert <{\epsilon}_{A}$ 
where
${\tau}_{F}$ is the value of the optional parameter
Optimality Tolerance (
$\text{default value}={\epsilon}^{0.8}$) and
${\epsilon}_{A}$ is the absolute error associated with computing the objective function.
For a full discussion on termination criteria see Chapter 8 of
Gill et al. (1981).
 Note: the following are additional arguments for specific use with e04dga. Users of e04dgf therefore need not read the remainder of this description.
 11: $\mathbf{lwsav}\left(120\right)$ – Logical arrayCommunication Array
 12: $\mathbf{iwsav}\left(610\right)$ – Integer arrayCommunication Array
 13: $\mathbf{rwsav}\left(475\right)$ – Real (Kind=nag_wp) arrayCommunication Array

The arrays
lwsav,
iwsav and
rwsav must not be altered between calls to any of the routines
e04dga,
e04dja,
e04dka or
e04wbf.
 14: $\mathbf{ifail}$ – IntegerInput/Output

Note: see the argument description for
ifail above.
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Note: e04dgf/e04dga may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}<0$

A negative value of
ifail indicates an exit from
e04dgf/e04dga because you set
${\mathbf{mode}}<0$ in
objfun. The value of
ifail will be the same as your setting of
mode.
 ${\mathbf{ifail}}=1$
Not used by this routine.
 ${\mathbf{ifail}}=2$
Not used by this routine.
 ${\mathbf{ifail}}=3$

The limiting number of iterations (as determined by the optional parameter
Iteration Limit (
$\text{default value}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(50,5n\right)$) has been reached.
If the algorithm appears to be making satisfactory progress, optional parameter
Iteration Limit may be too small. If so, increase its value and rerun
e04dgf/e04dga. If the algorithm seems to be making little or no progress, then you should check for incorrect gradients as described under
${\mathbf{ifail}}={\mathbf{7}}$.
 ${\mathbf{ifail}}=4$

The computed upper bound on the step length taken during the linesearch was too small. A rerun with an increased value of the optional parameter
Maximum Step Length (
$\rho $ say) may be successful unless
$\rho \ge {10}^{20}$ (the default value), in which case the current point cannot be improved upon.
 ${\mathbf{ifail}}=5$
Not used by this routine.
 ${\mathbf{ifail}}=6$

The conditions for an acceptable solution (see argument
ifail in
Section 5) have not all been met, but a lower point could not be found.
If
objfun computes the objective function and its gradient correctly, then this may occur because an overly stringent accuracy has been requested, i.e., the value of the optional parameter
Optimality Tolerance (
$\text{default value}={\epsilon}^{0.8}$) is too small or if
${\alpha}_{k}\simeq 0$. In this case you should apply the three tests described under
${\mathbf{ifail}}={\mathbf{0}}$ to determine whether or not the final solution is acceptable. For a discussion of attainable accuracy see
Gill et al. (1981).
If many iterations have occurred in which essentially no progress has been made or
e04dgf/e04dga has failed to move from the initial point,
objfun may be incorrect. You should refer to the comments below under
${\mathbf{ifail}}={\mathbf{7}}$ and check the gradients using the optional parameter
Verify (
$\text{default value}=0$). Unfortunately, there may be small errors in the objective gradients that cannot be detected by the verification process. Finite difference approximations to first derivatives are catastrophically affected by even small inaccuracies.
 ${\mathbf{ifail}}=7$

The usersupplied derivatives of the objective function appear to be incorrect.
Large errors were found in the derivatives of the objective function. This value of
ifail will occur if the verification process indicated that at least one gradient element had no correct figures. You should refer to the printed output to determine which elements are suspected to be in error.
As a first step, you should check that the code for the objective values is correct – for example, by computing the function at a point where the correct value is known. However, care should be taken that the chosen point fully tests the evaluation of the function. It is remarkable how often the values $x=0$ or $x=1$ are used to test function evaluation procedures, and how often the special properties of these numbers make the test meaningless.
Special care should be used in this test if computation of the objective function involves subsidiary data communicated in COMMON storage. Although the first evaluation of the function may be correct, subsequent calculations may be in error because some of the subsidiary data has accidentally been overwritten.
Errors in programming the function may be quite subtle in that the function value is almost correct. For example, the function may not be accurate to full precision because of the inaccurate calculation of a subsidiary quantity, or the limited accuracy of data upon which the function depends. A common error on machines where numerical calculations are usually performed in double precision is to include even one single precision constant in the calculation of the function; since some compilers do not convert such constants to double precision, half the correct figures may be lost by such a seemingly trivial error.
 ${\mathbf{ifail}}=8$

The gradient
$\left(g=\frac{\partial F}{\partial x}\right)$ at the starting point
${x}_{0}$ is ‘too small’. More precisely, the value of
$g{\left({x}_{0}\right)}^{\mathrm{T}}g\left({x}_{0}\right)$ is less than
${\epsilon}_{r}\left1+F\left({x}_{0}\right)\right$, where
${\epsilon}_{r}$ is the value of the optional parameter
Function Precision (
$\text{default value}={\epsilon}^{0.9}$).
The problem should be rerun from a different starting point.
 ${\mathbf{ifail}}=9$

An input argument is invalid.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
On successful exit (
${\mathbf{ifail}}={\mathbf{0}}$) the accuracy of the solution will be as defined by the optional parameter
Optimality Tolerance (
$\text{default value}={\epsilon}^{0.8}$).
8
Parallelism and Performance
e04dgf/e04dga makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
To evaluate an ‘acceptable’ set of finite difference intervals using
e04xaf/e04xaa requires
$2$ function evaluations per variable for a wellscaled problem and up to
$6$ function evaluations per variable for a badly scaled problem.
10
Example
This example finds a minimum of the function
The initial point is
and
$F\left({x}_{0}\right)=1.8394$ (to five figures).
The optimal solution is
and
$F\left({x}^{*}\right)=0$.
The document for
e04djf/e04dja includes an example program to solve the same problem using some of the optional parameters described in
Section 12.
10.1
Program Text
Note: the following programs illustrate the use of e04dgf and e04dga.
Program Text (e04dgfe.f90)
Program Text (e04dgae.f90)
10.2
Program Data
Program Data (e04dgfe.d)
Program Data (e04dgae.d)
10.3
Program Results
Program Results (e04dgfe.r)
Program Results (e04dgae.r)
Note: the remainder of this document is intended for more advanced users. Section 11 contains a detailed description of the algorithm which may be needed in order to understand Section 12. Section 12 describes the optional parameters which may be set by calls to e04djf/e04dja and/or e04dkf/e04dka.
11
Algorithmic Details
This section contains a description of the method used by e04dgf/e04dga.
e04dgf/e04dga uses a preconditioned conjugate gradient method and is based upon algorithm PLMA as described in Section 4.8.3 of
Gill and Murray (1979) and
Gill et al. (1981).
The algorithm proceeds as follows:
Let
${x}_{0}$ be a given starting point and let
$k$ denote the current iteration, starting with
$k=0$. The iteration requires
${g}_{k}$, the gradient vector evaluated at
${x}_{k}$, the
$k$th estimate of the minimum. At each iteration a vector
${p}_{k}$ (known as the direction of search) is computed and the new estimate
${x}_{k+1}$ is given by
${x}_{k}+{\alpha}_{k}{p}_{k}$ where
${\alpha}_{k}$ (the step length) minimizes the function
$F\left({x}_{k}+{\alpha}_{k}{p}_{k}\right)$ with respect to the scalar
${\alpha}_{k}$. A choice of initial step
${\alpha}_{0}$ is taken as
where
${F}_{\mathrm{est}}$ is a usersupplied estimate of the function value at the solution. If
${F}_{\mathrm{est}}$ is not specified, the software always chooses the unit step length for
${\alpha}_{0}$. Subsequent step length estimates are computed using cubic interpolation with safeguards.
A quasiNewton method can be used to compute the search direction
${p}_{k}$ by updating the inverse of the approximate Hessian
$\left({H}_{k}\right)$ and computing
The updating formula for the approximate inverse is given by
where
${y}_{k}={g}_{k1}{g}_{k}$ and
${s}_{k}={x}_{k+1}{x}_{k}={\alpha}_{k}{p}_{k}$.
The method used to obtain the search direction is based upon computing
${p}_{k+1}$ as
${H}_{k+1}{g}_{k+1}$ where
${H}_{k+1}$ is a matrix obtained by updating the identity matrix with a limited number of quasiNewton corrections. The storage of an
$n$ by
$n$ matrix is avoided by storing only the vectors that define the rank two corrections – hence the term ‘limitedmemory’ quasiNewton method. The precise method depends upon the number of updating vectors stored. For example, the direction obtained with the ‘onestep’ limited memory update is given by
(1) using
(2) with
${H}_{k}$ equal to the identity matrix, viz.
Using a limitedmemory quasiNewton formula, such as the one above, guarantees
${p}_{k+1}$ to be a descent direction if all the inner products
${y}_{k}^{\mathrm{T}}{s}_{k}$ are positive for all vectors
${y}_{k}$ and
${s}_{k}$ used in the updating formula.
12
Optional Parameters
Several optional parameters in e04dgf/e04dga define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of e04dgf/e04dga these optional parameters have associated default values that are appropriate for most problems. Therefore, you need only specify those optional parameters whose values are to be different from their default values.
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in
Section 12.1.
Optional parameters may be specified by calling one, or both, of the routines
e04djf/e04dja and
e04dkf/e04dka before a call to
e04dgf/e04dga.
e04djf/e04dja reads options from an external options file, with
Begin and
End as the first and last lines respectively and each intermediate line defining a single optional parameter. For example,
Begin
Print Level = 1
End
The call
Call e04djf/e04dja (ioptns, inform)
can then be used to read the file on unit
ioptns.
inform will be zero on successful exit.
e04djf/e04dja should be consulted for a full description of this method of supplying optional parameters.
e04dkf/e04dka can be called to supply options directly, one call being necessary for each optional parameter. For example,
Call e04dkf/e04dka ('Print Level = 1')
e04dkf/e04dka should be consulted for a full description of this method of supplying optional parameters.
All optional parameters not specified by you are set to their default values. Optional parameters specified by you are unaltered by e04dgf/e04dga (unless they define invalid values) and so remain in effect for subsequent calls unless altered by you.
12.1
Description of the Optional Parameters
For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
 the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
 a parameter value,
where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
 the default value, where the symbol $\epsilon $ is a generic notation for machine precision (see x02ajf), and ${\epsilon}_{r}$ denotes the relative precision of the objective function Function Precision.
Keywords and character values are case and white space insensitive.
This special keyword may be used to reset all optional parameters to their default values.
Estimated Optimal Function Value  $r$  
This value of
$r$ specifies the usersupplied guess of the optimum objective function value
${F}_{\mathrm{est}}$. This value is used to calculate an initial step length
${\alpha}_{0}$ (see
Section 11). If the value of
$r$ is not specified (the default), then this has the effect of setting
${\alpha}_{0}$ to unity. It should be noted that for badly scaled functions a unit step along the steepest descent direction will often compute the objective function at very large values of
$x$.
Function Precision  $r$  Default $\text{}={\epsilon}^{0.9}$ 
The parameter defines ${\epsilon}_{r}$, which is intended to be a measure of the accuracy with which the problem function $F\left(x\right)$ can be computed. If $r<\epsilon $ or $r\ge 1$, the default value is used.
The value of
${\epsilon}_{r}$ should reflect the relative precision of
$1+\leftF\left(x\right)\right$; i.e.,
${\epsilon}_{r}$ acts as a relative precision when
$\leftF\right$ is large, and as an absolute precision when
$\leftF\right$ is small. For example, if
$F\left(x\right)$ is typically of order
$1000$ and the first six significant digits are known to be correct, an appropriate value for
${\epsilon}_{r}$ would be
${10}^{6}$. In contrast, if
$F\left(x\right)$ is typically of order
${10}^{4}$ and the first six significant digits are known to be correct, an appropriate value for
${\epsilon}_{r}$ would be
${10}^{10}$. The choice of
${\epsilon}_{r}$ can be quite complicated for badly scaled problems; see Chapter 8 of
Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy. However when the accuracy of the computed function values is known to be significantly worse than full precision, the value of
${\epsilon}_{r}$ should be large enough so that no attempt will be made to distinguish between function values that differ by less than the error inherent in the calculation.
Iteration Limit  $i$  Default $\text{}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(50,5n\right)$ 
The value of $i$ specifies the maximum number of iterations allowed before termination. If $i<0$, the default value is used.
Problems whose Hessian matrices at the solution contain sets of clustered eigenvalues are likely to be minimized in significantly fewer than $n$ iterations. Problems without this property may require anything between $n$ and $5n$ iterations, with approximately $2n$ iterations being a common figure for moderately difficult problems.
Linesearch Tolerance  $r$  Default $\text{}=0.9$ 
The value $r$ controls the accuracy with which the step $\alpha $ taken during each iteration approximates a minimum of the function along the search direction (the smaller the value of $r$, the more accurate the linesearch). The default value $r=0.9$ requests an inaccurate search, and is appropriate for most problems. A more accurate search may be appropriate when it is desirable to reduce the number of iterations – for example, if the objective function is cheap to evaluate. If $r<0$ or $r\ge 1$, the default value is used.
List   Default for e04dgf $\text{}={\mathbf{List}}$ 
Nolist   Default for e04dga $\text{}={\mathbf{Nolist}}$ 
Normally each optional parameter specification is printed as it is supplied. Optional parameter
Nolist may be used to suppress the printing and optional parameter
List may be used to restore printing.
Maximum Step Length  $r$  Default $\text{}={10}^{20}$ 
If $r>0$, the maximum allowable step length for the linesearch is taken as $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(\frac{1}{{\mathbf{x02amf}}\left(\right)},\frac{r}{\Vert {p}_{k}\Vert}\right)$. If $r\le 0$, the default value is used.
Optimality Tolerance  $r$  Default $\text{}={\epsilon}_{R}^{0.8}$ 
The parameter
$r$ specifies the accuracy to which you wish the final iterate to approximate a solution of the problem. Broadly speaking,
$r$ indicates the number of correct figures desired in the objective function at the solution. For example, if
$r$ is
${10}^{6}$ and termination occurs with
${\mathbf{ifail}}={\mathbf{0}}$ (see
Section 5), then the final point satisfies the termination criteria, where
${\tau}_{F}$ represents
Optimality Tolerance. If
$r<{\epsilon}_{r}$ or
$r\ge 1$, the default value is used. If
Optimality Tolerance is chosen below a certain threshold, it will automatically be reset to another value.
Print Level  $i$  Default for e04dgf
$\text{}=10$
Default for e04dga
$\text{}=0$ 
The value
$i$ controls the amount of printout produced by
e04dgf/e04dga, as indicated below. A detailed description of the printout is given in
Section 12.2 (summary output at each iteration and the final solution).
$i$ 
Output 
$\phantom{0}0$ 
No output. 
$\phantom{0}1$ 
The final solution only. 
$\phantom{0}5$ 
One line of summary output ($\text{}<80$ characters; see Section 12.2) for each iteration (no printout of the final solution). 
$10$ 
The final solution and one line of summary output for each iteration. 
Start Objective Check at Variable  ${i}_{1}$  Default $\text{}=1$ 
Stop Objective Check at Variable  ${i}_{2}$  Default $\text{}=n$ 
These keywords take effect only if
${\mathbf{Verify\; Level}}>0$. They may be used to control the verification of gradient elements computed by
objfun. For example, if the first
$30$ elements of the objective gradient appeared to be correct in an earlier run, so that only element
$31$ remains questionable, it is reasonable to specify
${\mathbf{Start\; Objective\; Check\; at\; Variable}}=31$. If the first
$30$ variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If ${i}_{1}\le 0$ or ${i}_{1}>\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,{i}_{2}\right)\right)$, the default value is used. If ${i}_{2}\le 0$ or ${i}_{2}>n$, the default value is used.
Verify Level  $i$  Default $\text{}=0$ 
Verify Objective Gradients   
These keywords refer to finite difference checks on the gradient elements computed by
objfun. Gradients are verified at the usersupplied initial estimate of the solution. The possible choices for
$i$ are as follows:
$i$ 
Meaning 
$1$ 
No checks are performed. 
$\phantom{}0$ 
Only a ‘cheap’ test will be performed, requiring one call to objfun. 
$\phantom{}1$ 
In addition to the ‘cheap’ test, individual gradient elements will also be checked using a reliable (but more expensive) test. 
For example, the objective gradient will be verified if
Verify,
${\mathbf{Verify}}=\mathrm{YES}$,
Verify Gradients,
Verify Objective Gradients or
${\mathbf{Verify\; Level}}=1$ is specified.
This section describes the intermediate printout and final printout produced by
e04dgf/e04dga. You can control the level of printed output (see the description of the optional parameter
Print Level). Note that the intermediate printout and final printout are produced only if
${\mathbf{Print\; Level}}\ge 10$ (the default
for
e04dgf, by default no output is produced by
e04dga).
The following line of summary output (
$\text{}<80$ characters) is produced at every iteration. In all cases, the values of the quantities are those in effect
on completion of the given iteration.
Itn 
is the iteration count.

Step 
is the step ${\alpha}_{k}$ taken along the computed search direction. On reasonably wellbehaved problems, the unit step (i.e., ${\alpha}_{k}=1$) will be taken as the solution is approached.

Nfun 
is the cumulated number of evaluations of the objective function needed for the linesearch. Evaluations needed for the verification of the gradients by finite differences are not included. Nfun is printed as a guide to the amount of work required for the linesearch. e04dgf/e04dga will perform at most $11$ function evaluations per iteration.

Objective 
is the value of the objective function at ${x}_{k}$.

Norm G 
is the Euclidean norm of the gradient of the objective function at ${x}_{k}$.

Norm X 
is the Euclidean norm of ${x}_{k}$.

Norm (X(k1)X(k)) 
is the Euclidean norm of ${x}_{k1}{x}_{k}$.

The following describes the printout for each variable.
Variable 
gives the name (Varbl) and index $\mathit{j}$, for $\mathit{j}=1,2,\dots ,n$ of the variable.

Value 
is the value of the variable at the final iteration.

Gradient Value 
is the value of the gradient of the objective function with respect to the $j$th variable at the final iteration.

Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.