NAG CL Interface
e04xac (estimate_deriv)
1
Purpose
e04xac computes an approximation to the gradient vector and/or the Hessian matrix for use in conjunction with, or following the use of an optimization function (such as
e04ucc).
2
Specification
void 
e04xac (Integer n,
double x[],
void 
(*objfun)(Integer n,
const double x[],
double *objf,
double g[],
Nag_Comm *comm),


double *objf,
double g[],
double h_forward[],
double h_central[],
double hess[],
Integer tdhess,
Nag_DerivInfo *deriv_info,
Nag_E04_Opt *options,
Nag_Comm *comm,
NagError *fail) 

The function may be called by the names: e04xac or nag_opt_estimate_deriv.
3
Description
e04xac is based on the routine FDCALC described in
Gill et al. (1983a). It computes finite difference approximations to the gradient vector and the Hessian matrix for a given function, and aims to provide sufficiently accurate estimates for use with an optimization algorithm.
The simplest approximation of the gradients involves the forwarddifference formula, in which the derivative of
${f}^{\prime}\left(x\right)$ of a univariate function
$f\left(x\right)$ is approximated by the quantity
for some interval
$h>0$, where the subscript ‘F’ denotes ‘forwarddifference’ (see
Gill et al. (1983b)).
The choice of which gradients are returned by
e04xac is controlled by the optional parameter
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}$ (see
Section 11 for a description of this argument). To summarise the procedure used by
e04xac when
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessFull}$ (default value) (i.e., for the case when the objective function is available and you require estimates of gradient values and the full Hessian matrix) consider a univariate function
$f$ at the point
$x$. (In order to obtain the gradient of a multivariate function
$F\left(x\right)$, where
$x$ is an
$n$vector, the procedure is applied to each component of
$x$, keeping the other components fixed.) Roughly speaking, the method is based on the fact that the bound on the relative truncation error in the forwarddifference approximation tends to be an increasing function of
$h$, while the relative condition error bound is generally a decreasing function of
$h$, hence changes in
$h$ will tend to have opposite effects on these errors (see
Gill et al. (1983b)).
The ‘best’ interval
$h$ is given by
where
$\Phi $ is an estimate of
${f}^{\prime \prime}\left(x\right)$, and
${e}_{R}$ is an estimate of the relative error associated with computing the function (see Chapter 8 of
Gill et al. (1981)). Given an interval
$h$,
$\Phi $ is defined by the secondorder approximation
The decision as to whether a given value of
$\Phi $ is acceptable involves
$\hat{c}\left(\Phi \right)$, the following bound on the relative condition error in
$\Phi $:
(When
$\Phi $ is zero,
$\hat{c}\left(\Phi \right)$ is taken as an arbitrary large number.)
The procedure selects the interval
${h}_{\varphi}$ (to be used in computing
$\Phi $) from a sequence of trial intervals
$\left({h}_{k}\right)$. The initial trial interval is taken as
unless you specify the initial value to be used.
The value of
$\hat{c}\left(\Phi \right)$ for a trial value
${h}_{k}$ is defined as ‘acceptable’ if it lies in the interval
$\left[0.0001,0.01\right]$. In this case
${h}_{\varphi}$ is taken as
${h}_{k}$, and the current value of
$\Phi $ is used to compute
${h}_{F}$ from
(1). If
$\hat{c}\left(\Phi \right)$ is unacceptable, the next trial interval is chosen so that the relative condition error bound will either decrease or increase, as required. If the bound on the relative condition error is too large, a larger interval is used as the next trial value in an attempt to reduce the condition error bound. On the other hand, if the relative condition error bound is too small,
${h}_{k}$ is reduced.
The procedure will fail to produce an acceptable value of $\hat{c}\left(\Phi \right)$ in two situations. Firstly, if ${f}^{\prime \prime}\left(x\right)$ is extremely small, then $\hat{c}\left(\Phi \right)$ may never become small, even for a very large value of the interval. Alternatively, $\hat{c}\left(\Phi \right)$ may never exceed $0.0001$, even for a very small value of the interval. This usually implies that ${f}^{\prime \prime}\left(x\right)$ is extremely large, and occurs most often near a singularity.
As a check on the validity of the estimated first derivative, the procedure provides a comparison of the forwarddifference approximation computed with
${h}_{F}$ (as above) and the centraldifference approximation computed with
${h}_{\varphi}$. Using the centraldifference formula the first derivative can be approximated by
where
$h>0$. If the values
${h}_{F}$ and
${h}_{\varphi}$ do not display some agreement, neither can be considered reliable.
The approximate Hessian matrix
$G$ is defined as in Chapter 2 of
Gill et al. (1981), by
where
${h}_{j}$ is the best forwarddifference interval associated with the
$j$th component of
$f$ and
${e}_{j}$ is the vector with unity in the
$j$th position and zeros elsewhere.
If you require the gradients and only the diagonal of the Hessian matrix (i.e.,
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessDiag}$; see
Section 11.2),
e04xac follows a similar procedure to the default case, except that the initial trial interval is taken as
$10\overline{h}$, where
and the value of
$\hat{c}\left(\Phi \right)$ for a trial value
${h}_{k}$ is defined as acceptable if it lies in the interval
$\left[0.001,0.1\right]$. The elements of the Hessian diagonal which are returned in this case are the values of
$\Phi $ corresponding to the ‘best’ intervals.
When both function and gradients are available and you require the Hessian matrix (i.e.,
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_HessFull}$; see
Section 11.2),
e04xac follows a similar procedure to the case above with the exception that the gradient function
$g\left(x\right)$ is substituted for the objective function and so the forwarddifference interval for the first derivative of
$g\left(x\right)$ with respect to variable
${x}_{j}$ is computed. The
$j$th column of the approximate Hessian matrix is then defined as in Chapter 2 of
Gill et al. (1981), by
where
${h}_{j}$ is the best forwarddifference interval associated with the
$j$th component of
$g$.
4
References
Gill P E, Murray W, Saunders M A and Wright M H (1983a) Documentation for FDCALC and FDCORE Technical Report SOL 83–6 Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1983b) Computing forwarddifference intervals for numerical optimization SIAM J. Sci. Statist. Comput. 4 310–321
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
5
Arguments

1:
$\mathbf{n}$ – Integer
Input

On entry: the number $n$ of variables.
Constraint:
${\mathbf{n}}\ge 1$.

2:
$\mathbf{x}\left[{\mathbf{n}}\right]$ – double
Input

On entry: the point $x$ at which derivatives are required.

3:
$\mathbf{objfun}$ – function, supplied by the user
External Function

objfun must evaluate the objective function
$F\left(x\right)$ and (optionally) its gradient
$g\left(x\right)=\frac{\partial F}{\partial {x}_{j}}$ for a specified
$n$ element vector
$x$.
The specification of
objfun is:
void 
objfun (Integer n,
const double x[],
double *objf,
double g[],
Nag_Comm *comm)



1:
$\mathbf{n}$ – Integer
Input

On entry: the number $n$ of variables.

2:
$\mathbf{x}\left[{\mathbf{n}}\right]$ – const double
Input

On entry: the point $x$ at which the value of $F$ and, if $\mathbf{comm}\mathbf{\to}\mathbf{flag}=2$, the $\frac{\partial F}{\partial {x}_{j}}$, are required.

3:
$\mathbf{objf}$ – double *
Output

On exit:
objfun must set
objf to the value of the objective function
$F$ at the current point
$x$. If it is not possible to evaluate
$F$ then
objfun should assign a negative value to
$\mathbf{comm}\mathbf{\to}\mathbf{flag}$;
e04xac will then terminate.

4:
$\mathbf{g}\left[{\mathbf{n}}\right]$ – double
Output

On exit: if
$\mathbf{comm}\mathbf{\to}\mathbf{flag}=2$ on entry, then
objfun must set
${\mathbf{g}}\left[j1\right]$ to the value of the first derivative
$\frac{\partial F}{\partial {x}_{\mathit{j}}}$ at the current point
$x$, for
$\mathit{j}=1,2,\dots ,n$. If it is not possible to evaluate the first derivatives then
objfun should assign a negative value to
$\mathbf{comm}\mathbf{\to}\mathbf{flag}$;
e04xac will then terminate.
If
$\mathbf{comm}\mathbf{\to}\mathbf{flag}=0$ on entry, then
g is not referenced.

5:
$\mathbf{comm}$ – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to
objfun.
 flag – IntegerInput/Output

On entry: $\mathbf{comm}\mathbf{\to}\mathbf{flag}$ will be set to 0 or $2$. The value 0 indicates that only $F$ itself needs to be evaluated. The value 2 indicates that both $F$ and its first derivatives must be calculated.
On exit: if
objfun resets
$\mathbf{comm}\mathbf{\to}\mathbf{flag}$ to a negative number then
e04xac will terminate immediately with the error indicator
NE_USER_STOP. If
fail is supplied to
e04xac,
${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ will be set to the user's setting of
$\mathbf{comm}\mathbf{\to}\mathbf{flag}$.
 first – Nag_BooleanInput

On entry: will be set to Nag_TRUE on the first call to
objfun and Nag_FALSE for all subsequent calls.
 nf – IntegerInput

On entry: the number of evaluations of the objective function; this value will be equal to the number of calls made to
objfun (including the current one).
 user – double *
 iuser – Integer *
 p – Pointer

The type Pointer will be void * with a C compiler that defines void * and char * otherwise.
Before calling
e04xac these pointers may be allocated memory and initialized with various quantities for use by
objfun when called from
e04xac.
Note: objfun should not return floatingpoint NaN (Not a Number) or infinity values, since these are not handled by
e04xac. If your code inadvertently
does return any NaNs or infinities,
e04xac is likely to produce unexpected results.
Note: objfun should be thoroughly tested before being used in conjunction with
e04xac. The array
x must
not be changed by
objfun.

4:
$\mathbf{objf}$ – double *
Output

On exit: the value of the objective function evaluated at the input vector in
x.

5:
$\mathbf{g}\left[{\mathbf{n}}\right]$ – double
Output

On exit: if
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessFull}$ (the default; see
Section 11.2) or
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessDiag}$,
${\mathbf{g}}\left[j1\right]$ contains the best estimate of the first partial derivative for the
$j$th variable,
$j=1,2,\dots ,n$. If
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_HessFull}$,
${\mathbf{g}}\left[j1\right]$ contains the first partial derivative for the
$j$th variable as evaluated by
objfun.

6:
$\mathbf{h\_forward}\left[{\mathbf{n}}\right]$ – double
Input/Output

On entry: if the optional parameter
${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}=\mathrm{Nag\_FALSE}$ (the default; see
Section 11.2), the values contained in
h_forward on entry to
e04xac are ignored.
If
${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}=\mathrm{Nag\_TRUE}$,
h_forward is assumed to contain meaningful values on entry: if
${\mathbf{h\_forward}}\left[j1\right]>0$ then it is used as the initial trial interval for computing the appropriate partial derivative to the
$j$th variable,
$j=1,2,\dots ,n$; if
${\mathbf{h\_forward}}\left[j1\right]\le 0.0$, then the initial trial interval for the
$j$th variable is computed by
e04xac (see
Section 11.2).
On exit: ${\mathbf{h\_forward}}\left[j1\right]$ is the best interval found for computing a forwarddifference approximation to the appropriate partial derivative for the $j$th variable. If you do not require this information, a NULL pointer may be provided, and e04xac will allocate memory internally to calculate the difference intervals.
Constraint:
h_forward must not be
NULL if
${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}=\mathrm{Nag\_TRUE}$.

7:
$\mathbf{h\_central}\left[{\mathbf{n}}\right]$ – double
Output

On exit: ${\mathbf{h\_central}}\left[j1\right]$ is the best interval found for computing a centraldifference approximation to the appropriate partial derivative for the $j$th variable. If you do not require this information, a NULL pointer may be provided, and e04xac will allocate memory internally to calculate the difference intervals.

8:
$\mathbf{hess}\left[{\mathbf{n}}\times {\mathbf{tdhess}}\right]$ – double
Output

Note: the $\left(i,j\right)$th element of the matrix is stored in ${\mathbf{hess}}\left[\left(i1\right)\times {\mathbf{tdhess}}+j1\right]$.
On exit: if the optional parameter
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessFull}$ (the default; see
Section 11.2) or
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_HessFull}$, the estimated Hessian matrix is contained in the leading
$n$ by
$n$ part of this array. If
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessDiag}$, the
$n$ elements of the estimated Hessian diagonal are contained in the first row of this array.

9:
$\mathbf{tdhess}$ – Integer
Input

On entry: the stride separating matrix column elements in the array
hess.
Constraint:
${\mathbf{tdhess}}\ge {\mathbf{n}}$.

10:
$\mathbf{deriv\_info}\left[{\mathbf{n}}\right]$ – Nag_DerivInfo *
Output

On exit:
${\mathbf{deriv\_info}}\left[\mathit{j}1\right]$ contains diagnostic information on the
$\mathit{j}$th variable, for
$\mathit{j}=1,2,\dots ,n$.
 ${\mathbf{deriv\_info}}\left[j1\right]=\mathrm{Nag\_Deriv\_OK}$
 No unusual behaviour observed in estimating the appropriate derivative.
 ${\mathbf{deriv\_info}}\left[j1\right]=\mathrm{Nag\_Fun\_Constant}$
 The appropriate function appears to be constant.
 ${\mathbf{deriv\_info}}\left[j1\right]=\mathrm{Nag\_Fun\_LinearOdd}$
 The appropriate function appears to be linear or odd.
 ${\mathbf{deriv\_info}}\left[j1\right]=\mathrm{Nag\_2ndDeriv\_Large}$
 The second derivative of the appropriate function appears to be so large that it cannot be reliably estimated (e.g., near a singularity).
 ${\mathbf{deriv\_info}}\left[j1\right]=\mathrm{Nag\_1stDeriv\_Small}$
 The forwarddifference and centraldifference estimates of the appropriate first derivatives do not agree to half a decimal place; this usually occurs because the first derivative is small.
A more detailed explanation of these warnings is given in
Section 9.1.

11:
$\mathbf{options}$ – Nag_E04_Opt *
Input/Output

On entry/exit: a pointer to a structure of type Nag_E04_Opt whose members are optional parameters for
e04xac. These structure members offer the means of adjusting some of the argument values of the computation and on output will supply further details of the results. A description of the members of
options is given in
Section 11.
If any of these optional parameters are required then the structure
options should be declared and initialized by a call to
e04xxc and supplied as an argument to
e04xac. However, if the optional parameters are not required the NAG defined null pointer,
E04_DEFAULT, can be used in the function call.

12:
$\mathbf{comm}$ – Nag_Comm *
Input/Output

Note: comm is a NAG defined type (see
Section 3.1.1 in the Introduction to the NAG Library CL Interface).
On entry/exit: structure containing pointers for communication with usersupplied functions; see the description of
objfun for details. If you do not need to make use of this communication feature, the null pointer
NAGCOMM_NULL may be used in the call to
e04xac;
comm will then be declared internally for use in calls to usersupplied functions.

13:
$\mathbf{fail}$ – NagError *
Input/Output

The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
 NE_2_INT_ARG_LT

On entry, ${\mathbf{tdhess}}=\u2329\mathit{\text{value}}\u232a$ while ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$. These arguments must satisfy ${\mathbf{tdhess}}\ge {\mathbf{n}}$.
 NE_ALLOC_FAIL

Dynamic memory allocation failed.
 NE_BAD_PARAM

On entry, argument ${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}$ had an illegal value.
On entry, argument ${\mathbf{options}}\mathbf{.}{\mathbf{print\_deriv}}$ had an illegal value.
 NE_H_FORWARD_NULL

${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}=\mathrm{Nag\_TRUE}$ but argument
h_forward is
NULL.
 NE_INT_ARG_LT

On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 1$.
 NE_INVALID_REAL_RANGE_F

Value $\u2329\mathit{\text{value}}\u232a$ given to ${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ is not valid. Correct range is ${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}>0.0$.
 NE_NOT_APPEND_FILE

Cannot open file $\u2329\mathit{string}\u232a$ for appending.
 NE_NOT_CLOSE_FILE

Cannot close file $\u2329\mathit{string}\u232a$.
 NE_OPT_NOT_INIT

Options structure not initialized.
 NE_USER_STOP

User requested termination, user flag value $\text{}=\u2329\mathit{\text{value}}\u232a$.
This exit occurs if you set
$\mathbf{comm}\mathbf{\to}\mathbf{flag}$ to a negative value in
objfun. If
fail is supplied, the value of
${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ will be the same as your setting of
$\mathbf{comm}\mathbf{\to}\mathbf{flag}$.
 NE_WRITE_ERROR

Error occurred when writing to file $\u2329\mathit{string}\u232a$.
 NW_DERIV_INFO

On exit, at least one element of the
deriv_info array does not contain the value
${\mathbf{deriv\_info}}=\mathrm{Nag\_Deriv\_OK}$. This does not necessarily represent an unsuccessful exit.
See
Section 9.1 for information about the possible values which may be returned in
deriv_info.
7
Accuracy
e04xac exits with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=\mathrm{NE\_NOERROR}$ if the algorithm terminated successfully, i.e., the forwarddifference estimates of the appropriate first derivatives (computed with the final estimate of the ‘optimal’ forwarddifference interval ${h}_{F}$) and the centraldifference estimates (computed with the interval ${h}_{\varphi}$ used to compute the final estimate of the second derivative) agree to at least half a decimal place.
8
Parallelism and Performance
e04xac is not threaded in any implementation.
9.1
Diagnostic Information
Diagnostic information is returned via the array argument
deriv_info. If
${\mathbf{fail}}\mathbf{.}\mathbf{code}=\mathrm{NE\_NOERROR}$ on exit then
${\mathbf{deriv\_info}}\left[\mathit{j}1\right]=\mathrm{Nag\_Deriv\_OK}$, for
$\mathit{j}=1,2,\dots ,n$. If
${\mathbf{fail}}\mathbf{.}\mathbf{code}={\mathbf{NW\_DERIV\_INFO}}$ on exit, then, for at least one
$j$,
${\mathbf{deriv\_info}}\left[j1\right]$ contains one of the following values:
 $\mathrm{Nag\_Fun\_Constant}$
 The appropriate function appears to be constant. On exit, ${\mathbf{h\_forward}}\left[j1\right]$ is set to the initial trial interval corresponding to a well scaled problem, and Error est in the printed output is set to zero. This value occurs when the estimated relative condition error in the first derivative approximation is unacceptably large for every value of the finite difference interval. If this happens when the function is not constant the initial interval may be too small; in this case, it may be worthwhile to rerun e04xac with larger initial trial interval values supplied in h_forward and with the optional parameter ${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}$ set to Nag_TRUE. This error may also occur if the function evaluation includes an inordinately large constant term or if optional parameter ${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ is too large.
 $\mathrm{Nag\_Fun\_LinearOdd}$
 The appropriate function appears to be linear or odd. On exit, ${\mathbf{h\_forward}}\left[j1\right]$ is set to the smallest interval with acceptable bounds on the relative condition error in the forward and backwarddifference estimates. In this case, the estimated relative condition error in the second derivative approximation remained large for every trial interval, but the estimated error in the first derivative approximation was acceptable for at least one interval. If the function is not linear or odd the relative condition error in the second derivative may be decreasing very slowly. It may be worthwhile to rerun e04xac with larger initial trial interval values supplied in h_forward and with ${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}$ set to Nag_TRUE.
 $\mathrm{Nag\_2ndDeriv\_Large}$
 The second derivative of the appropriate function appears to be so large that it cannot be reliably estimated (e.g., near a singularity). On exit, ${\mathbf{h\_forward}}\left[j1\right]$ is set to the smallest trial interval.
This value occurs when the relative condition error estimate in the second derivative remained very small for every trial interval.
If the second derivative is not large the relative condition error in the second derivative may be increasing very slowly. It may be worthwhile to rerun
e04xac with smaller initial trial interval values supplied in
h_forward and with
${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}$ set to Nag_TRUE. This error may also occur when the given value of the optional parameter
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ is not a good estimate of a bound on the absolute error in the appropriate function (i.e.,
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ is too small).
 $\mathrm{Nag\_1stDeriv\_Small}$
 The algorithm terminated with an apparently acceptable estimate of the second derivative. However the forwarddifference estimates of the appropriate first derivatives (computed with the final estimate of the ‘optimal’ forwarddifference interval) and the central difference estimates (computed with the interval used to compute the final estimate of the second derivative) do not agree to half a decimal place. The usual reason that the forward and centraldifference estimates fail to agree is that the first derivative is small.
If the first derivative is not small, it may be helpful to run e04xac at a different point.
9.2
Timing
Unless the objective function can be evaluated very quickly, the run time will usually be dominated by the time spent in
objfun.
To evaluate an acceptable set of finite difference intervals for a wellscaled problem e04xac will use around two function evaluations per variable; in a badly scaled problem, six function evaluations per variable may be needed.
In the default case where gradients and the full Hessian matrix are required (i.e., optional parameter ${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessFull}$), e04xac performs a further $3n\left(n+1\right)/2$ function evaluations. If the full Hessian matrix is required, with you supplying both function and gradients (i.e., ${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_HessFull}$), a further $n$ function evaluations are performed.
10
Example
The example program computes the gradient vector and Hessian matrix of the following function:
at the point
${\left(3,1,0,1\right)}^{\mathrm{T}}$.
This example shows the use of some optional parameters which are discussed fully in
Section 11.
The same
objfun is used as in
Section 10 and the derivatives are estimated at the same point. The
options structure is declared and initialized by
e04xxc. Two options are set to suppress all printout from
e04xac:
${\mathbf{options}}\mathbf{.}{\mathbf{list}}$ is set to Nag_FALSE and
${\mathbf{options}}\mathbf{.}{\mathbf{print\_deriv}}=\mathrm{Nag\_D\_NoPrint}$.
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessDiag}$ and
e04xac is called. The returned function value and estimated derivative values are printed out and
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}$ is reset to
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_HessFull}$ before
e04xac is called again. On return, the computed function value and gradient, and estimated Hessian, are printed out.
10.1
Program Text
10.2
Program Data
None.
10.3
Program Results
11
Optional Parameters
A number of optional input and output arguments to
e04xac are available through the structure argument
options, type Nag_E04_Opt. An argument may be selected by assigning an appropriate value to the relevant structure member; those arguments not selected will be assigned default values. If no use is to be made of any of the optional parameters you should use the NAG defined null pointer,
E04_DEFAULT, in place of
options when calling
e04xac; the default settings will then be used for all arguments.
Before assigning values to
options directly the structure
must be initialized by a call to the function
e04xxc. Values may then be assigned to the structure members in the normal C manner.
After return from
e04xac, the
options structure may only be reused for future calls of
e04xac if the dimensions of the new problem are the same. Otherwise, the structure must be cleared by a call of
e04xzc) and reinitialized by a call of
e04xxc before future calls. Failure to do this will result in unpredictable behaviour.
Option settings may also be read from a text file using the function
e04xyc in which case initialization of the
options structure will be performed automatically if not already done. Any subsequent direct assignment to the
options structure must
not be preceded by initialization.
11.1
Optional Parameter Checklist and Default Values
For easy reference, the following list shows the members of
options which are valid for
e04xac together with their default values where relevant. The number
$\epsilon $ is a generic notation for
machine precision (see
X02AJC).
Boolean list 
Nag_TRUE 
Nag_DPrintType print_deriv 
$\mathrm{Nag\_D\_Print}$ 
char outfile[512] 
stdout 
Nag_DWantType deriv_want 
$\mathrm{Nag\_Grad\_HessFull}$ 
Boolean use_hfwd_init 
Nag_FALSE 
double f_prec 
${\epsilon}^{0.9}$ 
double f_prec_used 
Integer nf 
11.2
Description of the Optional Parameters
list – Nag_Boolean   Default $\text{}=\mathrm{Nag\_TRUE}$ 
On entry: if ${\mathbf{options}}\mathbf{.}{\mathbf{list}}=\mathrm{Nag\_TRUE}$ the argument settings in the call to e04xac will be printed.
print_deriv – Nag_DPrintType   Default $\text{}=\mathrm{Nag\_D\_Print}$ 
On entry: controls whether printout is produced by
e04xac. The following values are available:
$\mathrm{Nag\_D\_NoPrint}$ 
No output. 
$\mathrm{Nag\_D\_Print}$ 
Printout for each variable as described in Section 5. 
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{print\_deriv}}=\mathrm{Nag\_D\_NoPrint}$ or $\mathrm{Nag\_D\_Print}$.
outfile – const char[512]   Default $\text{}=\mathtt{stdout}$ 
On entry: the name of the file to which results should be printed. If ${\mathbf{options}}\mathbf{.}{\mathbf{outfile}}\left[0\right]=\text{'}\text{}\text{0}\text{}\text{'}$ then the stdout stream is used.
deriv_want – Nag_DWantType   Default $\text{}=\mathrm{Nag\_Grad\_HessFull}$ 
On entry: specifies which derivatives
e04xac should estimate. The following values are available:
$\mathrm{Nag\_Grad\_HessFull}$ 
Estimate the gradient and full Hessian, with you supplying the objective function via objfun. 
$\mathrm{Nag\_Grad\_HessDiag}$ 
Estimate the gradient and the Hessian diagonal values, with you supplying the objective function via objfun. 
$\mathrm{Nag\_HessFull}$ 
Estimate the full Hessian, with you supplying the objective function and gradients via objfun. 
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{deriv\_want}}=\mathrm{Nag\_Grad\_HessFull}$, $\mathrm{Nag\_Grad\_HessDiag}$ or $\mathrm{Nag\_HessFull}$.
use_hfwd_init – Nag_Boolean   Default $\text{}=\mathrm{Nag\_FALSE}$ 
On entry: if
${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}=\mathrm{Nag\_FALSE}$, then
e04xac ignores any values supplied on entry in
h_forward, and computes the initial trial intervals itself. If
${\mathbf{options}}\mathbf{.}{\mathbf{use\_hfwd\_init}}=\mathrm{Nag\_TRUE}$, then
e04xac uses the forward difference interval provided in
${\mathbf{h\_forward}}\left[j1\right]$ as the initial trial interval for computing the appropriate partial derivative to the
$j$th variable,
$j=1,2,\dots ,n$; however, if
${\mathbf{h\_forward}}\left[j1\right]\le 0.0$ for some
$j$, the initial trial interval for the
$j$th variable is computed by
e04xac.
f_prec – double   Default $\text{}={\epsilon}^{0.9}$ 
On entry: specifies
${e}_{R}$, which is intended to measure the accuracy with which the problem function
$F$ can be computed. The value of
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ should reflect the relative precision of
$1+\leftF\left(x\right)\right$, i.e., acts as a relative precision when
$\leftF\right$ is large, and as an absolute precision when
$\leftF\right$ is small. For example, if
$\leftF\left(x\right)\right$ is typically of order 1000 and the first six significant figures are known to be correct, an appropriate value of
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ would be
${10}^{6}$. The default value of
${\epsilon}^{0.9}$ will be appropriate for most simple functions that are computed with full accuracy
A discussion of
${e}_{R}$ is given in Chapter 8 of
Gill et al. (1981). If you provide a value of
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ which
e04xac determines to be either too small or too large, the default value will be used instead and a warning will be output if optional parameter
${\mathbf{options}}\mathbf{.}{\mathbf{print\_deriv}}=\mathrm{Nag\_D\_Print}$. The value actually used is returned in
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec\_used}}$.
Constraint:
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}>0$.
On exit: if
${\mathbf{fail}}\mathbf{.}\mathbf{code}=\mathrm{NE\_NOERROR}$ or
NW_DERIV_INFO, or if
${\mathbf{options}}\mathbf{.}{\mathbf{nf}}>1$ and
${\mathbf{fail}}\mathbf{.}\mathbf{code}={\mathbf{NE\_USER\_STOP}}$, then
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec\_used}}$ contains the value of
${e}_{R}$ used by
e04xac. If you supply a value for
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec}}$ and
e04xac considers that the value supplied is neither too large nor too small, then this value will be returned in
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec\_used}}$; otherwise
${\mathbf{options}}\mathbf{.}{\mathbf{f\_prec\_used}}$ will contain the default value,
${\epsilon}^{0.9}$.
On exit: the number of times the objective function has been evaluated (i.e., number of calls of
objfun).
11.3
Description of Printed Output
Results from
e04xac are printed out by default. The level of printed output can be controlled with the structure members
${\mathbf{options}}\mathbf{.}{\mathbf{list}}$ and
${\mathbf{options}}\mathbf{.}{\mathbf{print\_deriv}}$ (see
Section 11.2). If
${\mathbf{options}}\mathbf{.}{\mathbf{list}}=\mathrm{Nag\_TRUE}$ then the argument values to
e04xac are listed, whereas printout of results is governed by the value of
${\mathbf{options}}\mathbf{.}{\mathbf{print\_deriv}}$.
The default,
${\mathbf{options}}\mathbf{.}{\mathbf{print\_deriv}}=\mathrm{Nag\_D\_Print}$ provides the following line of output for each variable.
j 
the index of the variable for which the difference interval has been computed. 
X(j) 
the value of ${x}_{j}$ as provided in ${\mathbf{x}}\left[j1\right]$. 
Fwd diff int 
the best interval found for computing a forwarddifference approximation to the appropriate partial derivative with respect to ${x}_{j}$. 
Cent diff int 
the best interval found for computing a centraldifference approximation to the appropriate partial derivative with respect to ${x}_{j}$. 
Error est 
a bound on the estimated error in the final forwarddifference approximation. When ${\mathbf{deriv\_info}}\left[j1\right]=\mathrm{Nag\_Fun\_Constant}$, Error est is set to zero. 
Grad est 
best estimate of the first partial derivative with respect to ${x}_{j}$. 
Hess diag est 
best estimate of the second partial derivative with respect to ${x}_{j}$. 
Nfun 
the number of function evaluations used to compute the final difference intervals for ${x}_{j}$. 
Info 
gives diagnostic information for ${x}_{j}$. Info will be one of OK, Constant?, Linear or odd?, Large 2nd deriv?, or Small 1st deriv?, corresponding to ${\mathbf{deriv\_info}}\left[j1\right]=\mathrm{Nag\_Deriv\_OK}$, $\mathrm{Nag\_Fun\_Constant}$, $\mathrm{Nag\_Fun\_LinearOdd}$, $\mathrm{Nag\_2ndDeriv\_Large}$ or $\mathrm{Nag\_1stDeriv\_Small}$, respectively. 