nag_opt_bounds_2nd_deriv (e04lbc) (PDF version)
e04 Chapter Contents
e04 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_opt_bounds_2nd_deriv (e04lbc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_opt_bounds_2nd_deriv (e04lbc) is a comprehensive modified-Newton algorithm for finding:
an unconstrained minimum of a function of several variables
a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.
First and second derivatives are required. nag_opt_bounds_2nd_deriv (e04lbc) is intended for objective functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

2  Specification

#include <nag.h>
#include <nage04.h>
void  nag_opt_bounds_2nd_deriv (Integer n,
void (*objfun)(Integer n, const double x[], double *objf, double g[], Nag_Comm *comm),
void (*hessfun)(Integer n, const double x[], double h[], double hd[], Nag_Comm *comm),
Nag_BoundType bound, double bl[], double bu[], double x[], double *objf, double g[], Nag_E04_Opt *options, Nag_Comm *comm, NagError *fail)

3  Description

nag_opt_bounds_2nd_deriv (e04lbc) is applicable to problems of the form:
Minimize   F x 1 , x 2 , , x n subject to ​ l j x j u j ,   j = 1 , 2 , , n .
Special provision is made for unconstrained minimization (i.e., problems which actually have no bounds on the x j ), problems which have only non-negativity bounds, and problems in which l 1 = l 2 = = l n  and u 1 = u 2 = = u n . It is possible to specify that a particular x j  should be held constant. You must supply a starting point, a function objfun to calculate the value of F x  and its first derivatives F xj  at any point x , and a function hessfun to calculate the second derivatives 2F xi xj .
A typical iteration starts at the current point x  where n z  (say) variables are free from both their bounds. The vector of first derivatives of F x  with respect to the free variables, g z , and the matrix of second derivatives with respect to the free variables, H , are obtained. (These both have dimension n z .) The equations
H+E p z = - g z
are solved to give a search direction p z . (The matrix E  is chosen so that H+E  is positive definite.) p z  is then expanded to an n -vector p  by the insertion of appropriate zero elements; α  is found such that F x + α p  is approximately a minimum (subject to the fixed bounds) with respect to α , and x  is replaced by x + α p . (If a saddle point is found, a special search is carried out so as to move away from the saddle point.) If any variable actually reaches a bound, it is fixed and n z  is reduced for the next iteration.
There are two sets of convergence criteria – a weaker and a stronger. Whenever the weaker criteria are satisfied, the Lagrange-multipliers are estimated for all active constraints. If any Lagrange-multiplier estimate is significantly negative, then one of the variables associated with a negative Lagrange-multiplier estimate is released from its bound and the next search direction is computed in the extended subspace (i.e., n z  is increased). Otherwise, minimization continues in the current subspace until the stronger criteria are satisfied. If at this point there are no negative or near-zero Lagrange-multiplier estimates, the process is terminated.
If you specify that the problem is unconstrained, nag_opt_bounds_2nd_deriv (e04lbc) sets the l j  to - 10 10  and the u j  to 10 10 . Thus, provided that the problem has been sensibly scaled, no bounds will be encountered during the minimization process and nag_opt_bounds_2nd_deriv (e04lbc) will act as an unconstrained minimization algorithm.

4  References

Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory
Gill P E and Murray W (1974) Newton-type methods for unconstrained and linearly constrained optimization Math. Program. 7 311–350
Gill P E and Murray W (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

5  Arguments

1:     nIntegerInput
On entry: the number n  of independent variables.
Constraint: n1 .
2:     objfunfunction, supplied by the userExternal Function
objfun must evaluate the function F x  and its first derivatives F xj  at any point x . (However, if you do not wish to calculate F x  or its first derivatives at a particular x , there is the option of setting an argument to cause nag_opt_bounds_2nd_deriv (e04lbc) to terminate immediately.)
The specification of objfun is:
void  objfun (Integer n, const double x[], double *objf, double g[], Nag_Comm *comm)
1:     nIntegerInput
On entry: n , the number of variables.
2:     x[n]const doubleInput
On entry: the point x  at which the value of F , or F  and F xj , are required.
3:     objfdouble *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 commflag ; nag_opt_bounds_2nd_deriv (e04lbc) will then terminate.
4:     g[n]doubleOutput
On exit: objfun must set g[j-1]  to the value of the first derivative F xj  at the current point x , for j=1,2,,n. If it is not possible to evaluate the first derivatives then objfun should assign a negative value to commflag ; nag_opt_bounds_2nd_deriv (e04lbc) will then terminate.
5:     commNag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to objfun.
flagIntegerOutput
On exit: if objfun resets commflag to some negative number then nag_opt_bounds_2nd_deriv (e04lbc) will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to nag_opt_bounds_2nd_deriv (e04lbc), fail.errnum will be set to your setting of commflag.
firstNag_BooleanInput
On entry: will be set to Nag_TRUE on the first call to objfun and Nag_FALSE for all subsequent calls.
nfIntegerInput
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).
userdouble *
iuserInteger *
pPointer 
The type Pointer will be void * with a C compiler that defines void * and char * otherwise.
Before calling nag_opt_bounds_2nd_deriv (e04lbc) these pointers may be allocated memory and initialized with various quantities for use by objfun when called from nag_opt_bounds_2nd_deriv (e04lbc).
Note: objfun should be tested separately before being used in conjunction with nag_opt_bounds_2nd_deriv (e04lbc). The array x must not be changed by objfun.
3:     hessfunfunction, supplied by the userExternal Function
hessfun must calculate the second derivatives of F x  at any point x . (As with objfun there is the option of causing nag_opt_bounds_2nd_deriv (e04lbc) to terminate immediately.)
The specification of hessfun is:
void  hessfun (Integer n, const double x[], double h[], double hd[], Nag_Comm *comm)
1:     nIntegerInput
On entry: the number n  of variables.
2:     x[n]const doubleInput
On entry: the point x  at which the second derivatives of F  are required.
3:     h[n×n-1/2]doubleOutput
On exit: hessfun must place the strict lower triangle of the second derivative matrix of F  (evaluated at the point x ) in h, stored by rows, i.e., set
  • h[ i-1 i-2 / 2 + j-1 ] = 2F xi xj x ,   for ​ i = 2 , 3 , , n ​ and ​ j = 1 , 2 , , i - 1 .
(The upper triangle is not required because the matrix is symmetric.) If it is not possible to evaluate the elements of h then hessfun should assign a negative value to commflag ; nag_opt_bounds_2nd_deriv (e04lbc) will then terminate.
4:     hd[n]doubleInput/Output
On entry: the value of F xj  at the point x , for j=1,2,,n. These values may be useful in the evaluation of the second derivatives.
On exit: unless commflag  is reset to a negative number hessfun must place the diagonal elements of the second derivative matrix of F  (evaluated at the point x ) in hd, i.e., set
  • hd[j-1] = 2F xj 2 x ,   for   j = 1 , 2 , , n .
If it is not possible to evaluate the elements of hd then hessfun should assign a negative value to commflag ; nag_opt_bounds_2nd_deriv (e04lbc) will then terminate.
5:     commNag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to objfun.
flagIntegerOutput
On exit: if hessfun resets commflag to some negative number then nag_opt_bounds_2nd_deriv (e04lbc) will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to nag_opt_bounds_2nd_deriv (e04lbc) fail.errnum will be set to your setting of commflag.
firstNag_BooleanInput
On entry: will be set to Nag_TRUE on the first call to hessfun and Nag_FALSE for all subsequent calls.
nfIntegerInput
On entry: the number of calculations of the objective function; this value will be equal to the number of calls made to hessfun including the current one.
userdouble *
iuserInteger *
pPointer 
The type Pointer will be void * with a C compiler that defines void * and char * otherwise.
Before calling nag_opt_bounds_2nd_deriv (e04lbc) these pointers may be allocated memory and initialized with various quantities for use by hessfun when called from nag_opt_bounds_2nd_deriv (e04lbc).
Note: hessfun should be tested separately before being used in conjunction with nag_opt_bounds_2nd_deriv (e04lbc). The array x must not be changed by hessfun.
4:     boundNag_BoundTypeInput
On entry: indicates whether the problem is unconstrained or bounded and, if it is bounded, whether the facility for dealing with bounds of special forms is to be used. bound should be set to one of the following values:
bound=Nag_Bounds
If the variables are bounded and you will be supplying all the l j  and u j  individually.
bound=Nag_NoBounds
If the problem is unconstrained.
bound=Nag_BoundsZero
If the variables are bounded, but all the bounds are of the form 0 x j .
bound=Nag_BoundsEqual
If all the variables are bounded, and l 1 = l 2 = = l n  and u 1 = u 2 = = u n .
Constraint: bound=Nag_Bounds, Nag_NoBounds, Nag_BoundsZero or Nag_BoundsEqual.
5:     bl[n]doubleInput/Output
On entry: the lower bounds l j .
If bound=Nag_Bounds, you must set bl[j-1]  to l j , for j=1,2,,n. (If a lower bound is not required for any x j , the corresponding bl[j-1]  should be set to a large negative number, e.g., - 10 10 .)
If bound=Nag_BoundsEqual, you must set bl[0]  to l 1 ; nag_opt_bounds_2nd_deriv (e04lbc) will then set the remaining elements of bl equal to bl[0] .
If bound=Nag_NoBounds or Nag_BoundsZero, bl will be initialized by nag_opt_bounds_2nd_deriv (e04lbc).
On exit: the lower bounds actually used by nag_opt_bounds_2nd_deriv (e04lbc), e.g., if bound=Nag_BoundsZero, bl[0] = bl[1] = = bl[n-1] = 0.0 .
6:     bu[n]doubleInput/Output
On entry: the upper bounds u j .
If bound=Nag_Bounds, you must set bu[j-1]  to u j , for j=1,2,,n. (If an upper bound is not required for any x j , the corresponding bu[j-1]  should be set to a large positive number, e.g., 10 10 .)
If bound=Nag_BoundsEqual, you must set bu[0]  to u 1 ; nag_opt_bounds_2nd_deriv (e04lbc) will then set the remaining elements of bu equal to bu[0] .
If bound=Nag_NoBounds or Nag_BoundsZero, bu will be initialized by nag_opt_bounds_2nd_deriv (e04lbc).
On exit: the upper bounds actually used by nag_opt_bounds_2nd_deriv (e04lbc), e.g., if bound=Nag_BoundsZero, bu[0] = bu[1] = = bu[n-1] = 10 10 .
7:     x[n]doubleInput/Output
On entry: x[j-1]  must be set to a guess at the j th component of the position of the minimum, for j=1,2,,n.
On exit: the final point x * . Thus, if fail.code=NE_NOERROR  on exit, x[j-1]  is the j th component of the estimated position of the minimum.
8:     objfdouble *Output
On exit: the function value at the final point given in x.
9:     g[n]doubleOutput
On exit: the first derivative vector corresponding to the final point in x. The elements of g corresponding to free variables should normally be close to zero.
10:   optionsNag_E04_Opt *Input/Output
On entry/exit: a pointer to a structure of type Nag_E04_Opt whose members are optional arguments for nag_opt_bounds_2nd_deriv (e04lbc). These structure members offer the means of adjusting some of the argument values of the algorithm and on output will supply further details of the results. A description of the members of options is given below in Section 10.
If any of these optional arguments are required then the structure options should be declared and initialized by a call to nag_opt_init (e04xxc) and supplied as an argument to nag_opt_bounds_2nd_deriv (e04lbc). However, if the optional arguments are not required the NAG defined null pointer, E04_DEFAULT, can be used in the function call.
11:   commNag_Comm *Input/Output
Note: comm is a NAG defined type (see Section 3.2.1.1 in the Essential Introduction).
On entry/exit: structure containing pointers for communication to user-supplied functions; see the description of objfun and hessfun 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 nag_opt_bounds_2nd_deriv (e04lbc); comm will then be declared internally for use in calls to user-supplied functions.
12:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

5.1  Description of Printed Output

Intermediate and final results are printed out by default. The level of printed output can be controlled with the structure member options.print_level (see Section 10.2). The default, options.print_level=Nag_Soln_Iter provides a single line of output at each iteration and the final result. This section describes the default printout produced by nag_opt_bounds_2nd_deriv (e04lbc).
The following line of output is produced at each iteration. In all cases the values of the quantities printed are those in effect on completion of the given iteration.
Itn the iteration count, k .
Nfun the cumulative number of calls made to objfun.
Objective the value of the objective function, F x k
Norm g the Euclidean norm of the projected gradient vector, g z x k .
Norm x the Euclidean norm of x k .
Norm(x(k-1)-x(k)) the Euclidean norm of x k-1 - x k .
Step the step α k  taken along the computed search direction p k .
Cond H the ratio of the largest to the smallest element of the diagonal factor D  of the projected Hessian matrix. This quantity is usually a good estimate of the condition number of the projected Hessian matrix. (If no variables are currently free, this value will be zero.)
PosDef indicates whether the second derivative matrix H  for the current subspace is positive definite (Yes) or not (No).
The printout of the final result consists of:
x the final point, x * .
g the final projected gradient vector, g z x * .
Status the final state of the variable with respect to its bound(s).

6  Error Indicators and Warnings

When one of NE_USER_STOP, NE_INT_ARG_LT, NE_BOUND, NE_DERIV_ERRORS, NE_OPT_NOT_INIT, NE_BAD_PARAM, NE_2_REAL_ARG_LT, NE_INVALID_INT_RANGE_1, NE_INVALID_REAL_RANGE_EF, NE_INVALID_REAL_RANGE_FF and NE_ALLOC_FAIL occurs, no values will have been assigned by nag_opt_bounds_2nd_deriv (e04lbc) to objf or to the elements of g, options.state, options.hesl, or options.hesd.
An exit of fail.code=NW_TOO_MANY_ITER, NW_LAGRANGE_MULT_ZERO and NW_COND_MIN may also be caused by mistakes in objfun, by the formulation of the problem or by an awkward function. If there are no such mistakes, it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.
NE_2_REAL_ARG_LT
On entry, options.step_max=value  while options.optim_tol=value . These arguments must satisfy options.step_maxoptions.optim_tol .
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_BAD_PARAM
On entry, argument bound had an illegal value.
On entry, argument options.print_level had an illegal value.
NE_BOUND
The lower bound for variable value (array element bl[value] ) is greater than the upper bound.
NE_DERIV_ERRORS
Large errors were found in the derivatives of the objective function.
NE_INT_ARG_LT
On entry, n must not be less than 1: n=value .
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_INT_RANGE_1
Value value given to options.max_iter is not valid. Correct range is options.max_iter0 .
NE_INVALID_REAL_RANGE_EF
Value value given to options.optim_tol is not valid. Correct range is ε options.optim_tol < 1.0 .
NE_INVALID_REAL_RANGE_FF
Value value given to options.linesearch_tol is not valid. Correct range is 0.0 options.linesearch_tol < 1.0 .
NE_NOT_APPEND_FILE
Cannot open file string  for appending.
NE_NOT_CLOSE_FILE
Cannot close file string .
NE_OPT_NOT_INIT
Options structure not initialized.
NE_USER_STOP
User requested termination, user flag value =value .
This exit occurs if you set commflag  to a negative value in objfun or hessfun. If fail is supplied, the value of fail.errnum will be the same as your setting of commflag .
NE_WRITE_ERROR
Error occurred when writing to file string .
NW_COND_MIN
The conditions for a minimum have not all been satisfied, but a lower point could not be found.
Provided that, on exit, the first derivatives of F x  with respect to the free variables are sufficiently small, and that the estimated condition number of the second derivative matrix is not too large, this error exit may simply mean that, although it has not been possible to satisfy the specified requirements, the algorithm has in fact found the minimum as far as the accuracy of the machine permits. This could be because options.optim_tol has been set so small that rounding error in objfun makes attainment of the convergence conditions impossible.
If the estimated condition number of the second derivative matrix at the final point is large, it could be that the final point is a minimum but that the smallest eigenvalue of the second derivative matrix is so close to zero that it is not possible to recognize the point as a minimum.
NW_LAGRANGE_MULT_ZERO
All the Lagrange-multiplier estimates which are not indisputably positive lie close to zero.
However, it is impossible either to continue minimizing on the current subspace or to find a feasible lower point by releasing and perturbing any of the fixed variables. You should investigate as for NW_COND_MIN.
NW_TOO_MANY_ITER
The maximum number of iterations, value, have been performed.
If steady reductions in F x , were monitored up to the point where this exit occurred, then the exit probably occurred simply because options.max_iter was set too small, so the calculations should be restarted from the final point held in x. This exit may also indicate that F x  has no minimum.

7  Accuracy

A successful exit fail.code=NE_NOERROR  is made from nag_opt_bounds_2nd_deriv (e04lbc) when H k  is positive definite and when (B1, B2 and B3) or B4 hold, where (Quantities with superscript k  are the values at the k th iteration of the quantities mentioned in Section 3; ε  is the machine precision, .  denotes the Euclidean norm and options.optim_tol is described in Section 10.)
If fail.code=NE_NOERROR , then the vector in x on exit, x sol , is almost certainly an estimate of the position of the minimum, x true , to the accuracy specified by options.optim_tol.
If fail.code=NW_COND_MIN  or NW_LAGRANGE_MULT_ZERO, x sol  may still be a good estimate of x true , but the following checks should be made. Let the largest of the first n z  elements of the optional argument options.hesd be options.hesd[b] , let the smallest be options.hesd[s] , and define κ = options.hesd[b] / options.hesd[s] . The scalar κ  is usually a good estimate of the condition number of the projected Hessian matrix at x sol . If
(a) the sequence F x k  converges to F x sol  at a superlinear or fast linear rate,
(b) g z x sol 2 < 10.0 × ε , and
(c) κ < 1.0 / g z x sol ,
then it is almost certain that x sol  is a close approximation to the position of a minimum. When (b) is true, then usually F x sol  is a close approximation to F x true . The quantities needed for these checks are all available in the results printout from nag_opt_bounds_2nd_deriv (e04lbc); in particular the final value of Cond H gives κ .
Further suggestions about confirmation of a computed solution are given in the e04 Chapter Introduction.

8  Further Comments

8.1  Timing

The number of iterations required depends on the number of variables, the behaviour of F x , the accuracy demanded and the distance of the starting point from the solution. The number of multiplications performed in an iteration of nag_opt_bounds_2nd_deriv (e04lbc) is n z 3 / 6 + O n z 2 . In addition, each iteration makes one call of hessfun and at least one call of objfun. So, unless F x  and its derivatives can be evaluated very quickly, the run time will be dominated by the time spent in objfun.

8.2  Scaling

Ideally, the problem should be scaled so that, at the solution, F x  and the corresponding values of the x j  are each in the range -1,+1 , and so that at points one unit away from the solution, F x  differs from its value at the solution by approximately one unit. This will usually imply that the Hessian matrix at the solution is well conditioned. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that nag_opt_bounds_2nd_deriv (e04lbc) will take less computer time.

8.3  Unconstrained Minimization

If a problem is genuinely unconstrained and has been scaled sensibly, the following points apply:
(a) n z  will always be n ,
(b) the optional arguments options.hesl and options.hesd will be factors of the full approximate second derivative matrix with elements stored in the natural order,
(c) the elements of g should all be close to zero at the final point,
(d) the Status values given in the printout from nag_opt_bounds_2nd_deriv (e04lbc), and in the optional argument options.state on exit are unlikely to be of interest (unless they are negative, which would indicate that the modulus of one of the x j  has reached 10 10  for some reason),
(e) Norm g simply gives the norm of the first derivative vector.

9  Example

This example minimizes the function
F = x 1 + 10 x 2 2 + 5 x 3 - x 4 2 + x 2 - 2 x 3 4 + 10 x 1 - x 4 4
subject to the bounds
-1 x 1 3 -2 x 2 0 -1 x 4 3
starting from the initial guess 1.46,-0.82,0.57,1.21T .
The options structure is declared and initialized by nag_opt_init (e04xxc). One option value is read from a data file by use of nag_opt_read (e04xyc). The memory freeing function nag_opt_free (e04xzc) is used to free the memory assigned to the pointers in the option structure. You must not use the standard C function free() for this purpose.

9.1  Program Text

Program Text (e04lbce.c)

9.2  Program Data

Program Options (e04lbce.opt)

9.3  Program Results

Program Results (e04lbce.r)

10  Optional Arguments

A number of optional input and output arguments to nag_opt_bounds_2nd_deriv (e04lbc) 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 arguments you should use the NAG defined null pointer, E04_DEFAULT, in place of options when calling nag_opt_bounds_2nd_deriv (e04lbc); 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 nag_opt_init (e04xxc). Values may then be assigned to the structure members in the normal C manner.
Option settings may also be read from a text file using the function nag_opt_read (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.
If assignment of functions and memory to pointers in the options structure is required, then this must be done directly in the calling program; they cannot be assigned using nag_opt_read (e04xyc).

10.1  Optional Argument Checklist and Default Values

For easy reference, the following list shows the members of options which are valid for nag_opt_bounds_2nd_deriv (e04lbc) together with their default values where relevant. The number ε  is a generic notation for machine precision (see nag_machine_precision (X02AJC)).
Boolean list Nag_TRUE
Nag_PrintType print_level Nag_Soln_Iter
char outfile[80] stdout  
void (*print_fun)() NULL  
Boolean deriv_check Nag_TRUE
Integer max_iter 50n
double optim_tol 10 ε
double linesearch_tol 0.9 (0.0 if n=1 )
double step_max 100000.0
Integer *state size n
double *hesl size max n n-1 / 2 , 1
double *hesd size n
Integer iter  
Integer nf  

10.2  Description of the Optional Arguments

list – Nag_BooleanDefault =Nag_TRUE
On entry: if options.list=Nag_TRUE  the argument settings in the call to nag_opt_bounds_2nd_deriv (e04lbc) will be printed.
print_level – Nag_PrintTypeDefault =Nag_Soln_Iter
On entry: the level of results printout produced by nag_opt_bounds_2nd_deriv (e04lbc). The following values are available:
Nag_NoPrint No output.
Nag_Soln The final solution.
Nag_Iter One line of output for each iteration.
Nag_Soln_Iter The final solution and one line of output for each iteration.
Nag_Soln_Iter_Full The final solution and detailed printout at each iteration.
Details of each level of results printout are described in Section 10.3.
Constraint: options.print_level=Nag_NoPrint, Nag_Soln, Nag_Iter, Nag_Soln_Iter or Nag_Soln_Iter_Full.
outfile – const char[80]Default = stdout
On entry: the name of the file to which results should be printed. If options.outfile[0] = ' \0 '  then the stdout stream is used.
print_fun – pointer to functionDefault =  NULL
On entry: printing function defined by you; the prototype of options.print_fun is
void (*print_fun)(const Nag_Search_State *st, Nag_COmm *comm);
See Section 10.3.1 below for further details.
deriv_check – Nag_BooleanDefault =Nag_TRUE
On entry: if options.deriv_check=Nag_TRUE  a check of the derivatives defined by objfun and hessfun will be made at the starting point x. A starting point of x=0  or x=1  should be avoided if this test is to be meaningful.
max_iter – IntegerDefault = 50 n
On entry: the limit on the number of iterations allowed before termination.
Constraint: options.max_iter0 .
optim_tol – doubleDefault = 10 ε
On entry: the accuracy in x  to which the solution is required. If x true  is the true value of x  at the minimum, then x sol , the estimated position prior to a normal exit, is such that where y = j=1 n y j 2 1/2 . For example, if the elements of x sol  are not much larger than 1.0 in modulus and if options.optim_tol is set to 10 -5 , then x sol  is usually accurate to about five decimal places. (For further details see Section 8.) If the problem is scaled roughly as described in Section 8 and ε  is the machine precision, then ε  is probably the smallest reasonable choice for options.optim_tol. (This is because, normally, to machine accuracy, F x + ε e j = F x  where e j  is any column of the identity matrix.)
Constraint: ε options.optim_tol < 1.0 .
linesearch_tol – doubleDefault =0.9  if n>1 , and 0.0 otherwise
On entry: every iteration of nag_opt_bounds_2nd_deriv (e04lbc) involves a linear minimization (i.e., minimization of F x + α p  with respect to α ). options.linesearch_tol specifies how accurately these linear minimizations are to be performed. The minimum with respect to α  will be located more accurately for small values of options.linesearch_tol (say 0.01) than for large values (say 0.9).
Although accurate linear minimizations will generally reduce the number of iterations performed by nag_opt_bounds_2nd_deriv (e04lbc), they will increase the number of function evaluations required for each iteration. On balance, it is usually more efficient to perform a low accuracy linear minimization.
A smaller value such as 0.01 may be worthwhile:
(a) if objfun takes so little computer time that it is worth using extra calls of objfun to reduce the number of iterations and associated matrix calculations
(b) if calls to hessfun are expensive compared with calls to objfun.
(c) if F x  is a penalty or barrier function arising from a constrained minimization problem (since such problems are very difficult to solve).
If n=1 , the default for options.linesearch_tol=0.0  (if the problem is effectively one-dimensional then options.linesearch_tol should be set to 0.0 even though n>1 ; i.e., if for all except one of the variables the lower and upper bounds are equal).
Constraint: 0.0 options.linesearch_tol < 1.0 .
step_max – doubleDefault =100000.0
On entry: an estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency a slight overestimate is preferable.) nag_opt_bounds_2nd_deriv (e04lbc) will ensure that, for each iteration, where k  is the iteration number. Thus, if the problem has more than one solution, nag_opt_bounds_2nd_deriv (e04lbc) is most likely to find the one nearest the starting point. On difficult problems, a realistic choice can prevent the sequence of x k  entering a region where the problem is ill-behaved and can also help to avoid possible overflow in the evaluation of F x . However, an underestimate of options.step_max can lead to inefficiency.
Constraint: options.step_maxoptions.optim_tol .
state – Integer *Default memory =n
On exit: options.state contains information about which variables are on their bounds and which are free at the final point given in x. If x j  is:
(a) fixed on its upper bound, options.state[j-1]  is -1 ;
(b) fixed on its lower bound, options.state[j-1]  is -2 ;
(c) effectively a constant (i.e., l j = u j ), options.state[j-1]  is -3 ;
(d) free, options.state[j-1]  gives its position in the sequence of free variables.
hesl – double *Default memory = max n n-1 / 2 , 1
hesd – double *Default memory =n
On exit: during the determination of a direction p z  (see Section 3), H+E  is decomposed into the product LDLT , where L  is a unit lower triangular matrix and D is a diagonal matrix. (The matrices H , E , L  and D  are all of dimension n z , where n z  is the number of variables free from their bounds. H  consists of those rows and columns of the full second derivative matrix which relate to free variables. E  is chosen so that H+E  is positive definite.)
options.hesl and options.hesd are used to store the factors L  and D . The elements of the strict lower triangle of L  are stored row by row in the first n z n z - 1 / 2  positions of options.hesl. The diagonal elements of D  are stored in the first n z  positions of options.hesd.
In the last factorization before a normal exit, the matrix E  will be zero, so that options.hesl and options.hesd will contain, on exit, the factors of the final second derivative matrix H . The elements of options.hesd are useful for deciding whether to accept the result produced by nag_opt_bounds_2nd_deriv (e04lbc) (see Section 8).
iter – Integer 
On exit: the number of iterations which have been performed in nag_opt_bounds_2nd_deriv (e04lbc).
nf – Integer 
On exit: the number of times the residuals have been evaluated (i.e., number of calls of objfun).

10.3  Description of Printed Output

The level of printed output can be controlled with the structure members options.list and options.print_level (see Section 10.2). If options.list=Nag_TRUE  then the argument values to nag_opt_bounds_2nd_deriv (e04lbc) are listed, whereas the printout of results is governed by the value of options.print_level. The default of options.print_level=Nag_Soln_Iter provides a single line of output at each iteration and the final result. This section describes all of the possible levels of results printout available from nag_opt_bounds_2nd_deriv (e04lbc).
When options.print_level=Nag_Iter or Nag_Soln_Iter the following line of output is produced on completion of each iteration.
Itn the iteration count, k .
Nfun the cumulative number of calls made to objfun.
Objective the value of the objective function, F x k
Norm g the Euclidean norm of the projected gradient vector, g z x k .
Norm x the Euclidean norm of x k .
Norm(x(k-1)-x(k)) the Euclidean norm of x k-1 - x k .
Step the step α k  taken along the computed search direction p k .
Cond H the ratio of the largest to the smallest element of the diagonal factor D  of the projected Hessian matrix. This quantity is usually a good estimate of the condition number of the projected Hessian matrix. (If no variables are currently free, this value will be zero.)
PosDef indicates whether the second derivative matrix for the current subspace, H , is positive definite (Yes) or not (No).
When options.print_level=Nag_Soln_Iter_Full more detailed results are given at each iteration. Additional values output are
x the current point x k .
g the current projected gradient vector, g z x k .
Status the current state of the variable with respect to its bound(s).
If options.print_level=Nag_Soln, Nag_Soln_Iter or Nag_Soln_Iter_Full the final result is printed out. This consists of:
x the final point, x * .
g the final projected gradient vector, g z x * .
Status the final state of the variable with respect to its bound(s).
If options.print_level=Nag_NoPrint then printout will be suppressed; you can print the final solution when nag_opt_bounds_2nd_deriv (e04lbc) returns to the calling program.

10.3.1  Output of results via a user-defined printing function

You may also specify your own print function for output of iteration results and the final solution by use of the options.print_fun function pointer, which has prototype
void (*print_fun)(const Nag_Search_State *st, Nag_Comm *comm);
The rest of this section can be skipped if the default printing facilities provide the required functionality.
When a user-defined function is assigned to options.print_fun this will be called in preference to the internal print function of nag_opt_bounds_2nd_deriv (e04lbc). Calls to the user-defined function are again controlled by means of the options.print_level member. Information is provided through st and comm, the two structure arguments to options.print_fun.
If commit_prt = Nag_TRUE then the results on completion of an iteration of nag_opt_bounds_2nd_deriv (e04lbc) are contained in the members of st. If commsol_prt = Nag_TRUE then the final results from nag_opt_bounds_2nd_deriv (e04lbc), including details of the final iteration, are contained in the members of st. In both cases, the same members of st are set, as follows:
iterInteger
The current iteration count, k , if commit_prt = Nag_TRUE; the final iteration count, k , if commsol_prt = Nag_TRUE.
nInteger
The number of variables.
xdouble *
The coordinates of the point x k .
fdouble *
The value of the objective function at x k .
gdouble *
The value of F xj  at x k , j = 1 , 2 , , n .
gpj_normdouble
The Euclidean norm of the projected gradient g z  at x k .
stepdouble
The step α k  taken along the search direction p k .
conddouble
The estimate of the condition number of the projected Hessian matrix, see Section 10.3.
xk_normdouble
The Euclidean norm of x k-1 - x k .
stateInteger *
The status of variables x j , for j=1,2,,n, with respect to their bounds. See Section 10.2 for a description of the possible status values.
posdefNag_Boolean
Will be Nag_TRUE if the second derivative matrix H  for the current subspace is positive definite, and Nag_FALSE otherwise.
nfInteger
The cumulative number of calls made to objfun.
The relevant members of the structure comm are:
it_prtNag_Boolean
Will be Nag_TRUE when the print function is called with the results of the current iteration.
sol_prtNag_Boolean
Will be Nag_TRUE when the print function is called with the final result.
userdouble *
iuserInteger *
pPointer 
Pointers for communication of user information. If used they must be allocated memory either before entry to nag_opt_bounds_2nd_deriv (e04lbc) or during a call to objfun or options.print_fun. The type Pointer will be void * with a C compiler that defines void * and char * otherwise.

nag_opt_bounds_2nd_deriv (e04lbc) (PDF version)
e04 Chapter Contents
e04 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012