–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 derivatives are required. e04kbc 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>

void

e04kbc (Integer n,

void	(objfun)(Integer n, const double x[], double objf, double g[], 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)

The function may be called by the names: e04kbc or nag_opt_bounds_deriv.

3 Description

e04kbc is applicable to problems of the form:

\begin{array}{l} Minimize & F (x_{1}, x_{2}, \dots, x_{n}) \\ subject to & l_{j} \leq x_{j} \leq u_{j}, j = 1, 2, \dots, n . \end{array}

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} = \dots = l_{n}

and

u_{1} = u_{2} = \dots = u_{n}

. It is possible to specify that a particular

x_{j}

should be held constant. You must supply a starting point and a function objfun to calculate the value of

F (x)

and its first derivatives

\frac{\partial F}{\partial x_{j}}

at any point

x

A typical iteration starts at the current point

x

where

n_{z}

(say) variables are free from both their bounds. The vector

g_{z}

, whose elements are the derivatives of

F (x)

with respect to the free variables, is known. A unit lower triangular matrix

L

and a diagonal matrix

D

(both of dimension

n_{z}

), such that

{L D L}^{T}

is a positive definite approximation to the matrix of second derivatives with respect to the free variables, are also stored. The equations

{L D L}^{T} p_{z} = - g_{z}

are solved to give a search direction

p_{z}

, which is expanded to an

n

-vector

p

by the insertion of appropriate zero elements. Then

α

is found such that

F (x + α p)

is approximately a minimum (subject to the fixed bounds) with respect to

α

;

x

is replaced by

x + α p

, and the matrices

L

and

D

are updated so as to be consistent with the change produced in the gradient by the step

α p

. If any variable actually reaches a bound during the search along

p

, 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 the 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 provided that this is practicable. When it is not, or when the stronger convergence criteria is already satisfied, then, if one or more Lagrange-multiplier estimates are close to zero, a slight perturbation is made in the values of the corresponding variables in turn until a lower function value is obtained. The normal algorithm is then resumed from the perturbed point.

If a saddle point is suspected, a local search is carried out with a view to moving away from the saddle point. In addition, e04kbc gives you the option of specifying that a local search should be performed when a point is found which is thought to be a constrained minimum.

If you specify that the problem is unconstrained, e04kbc sets the

l_{j}

- 10^{10}

and the

u_{j}

10^{10}

. Thus, provided that the problem has been sensibly scaled, no bounds will be encountered during the minimization process and e04kbc will act as an unconstrained minimization algorithm.

4 References

Gill P E and Murray W (1972) Quasi-Newton methods for unconstrained optimization J. Inst. Math. Appl. 9 91–108

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 (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

Gill P E, Murray W and Pitfield R A (1972) The implementation of two revised quasi-Newton algorithms for unconstrained optimization NPL Report NAC 11 National Physical Laboratory

5 Arguments

1: $n$ – Integer Input

On entry: the number

n

of independent variables.

Constraint:

n \geq 1

2: $objfun$ – function, supplied by the user External Function

objfun must evaluate the function

F (x)

and its first derivatives

\frac{\partial F}{\partial x_{j}}

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 e04kbc to terminate immediately.)

The specification of objfun is:

void	objfun (Integer n, const double x[], double objf, double g[], Nag_Comm comm)

1: $n$ – Integer Input

On entry: the number

n

of variables.

2: $x [n]$ – const double Input

On entry: the point

x

at which the value of

F

, or

F

and

\frac{\partial F}{\partial x_{j}}

, are required.

3: $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

comm \to flag

; e04kbc will then terminate.

4: $g [n]$ – double Output

On exit: if

comm \to flag = 2

on entry, then objfun must set

g [j - 1]

to the value of the first derivative

\frac{\partial F}{\partial x_{j}}

at the current point,

x

for

j = 1, 2, \dots, n

. If it is not possible to evaluate the first derivatives then objfun should assign a negative value to

comm \to flag

; e04kbc will then terminate.

(If

comm \to flag = 0

on entry, objfun must not change the elements of g.)

5: $comm$ – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to objfun.

flag – IntegerInput/Output: On entry: $comm \to 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 $comm \to flag$ to some negative number then e04kbc will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to e04kbc, $fail . errnum$ will be set to your setting of $comm \to 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 calculations 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 e04kbc these pointers may be allocated memory and initialized with various quantities for use by objfun when called from e04kbc.

Note: objfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04kbc. If your code inadvertently does return any NaNs or infinities, e04kbc is likely to produce unexpected results.

Note: objfun should be tested separately before being used in conjunction with e04kbc. The array x must not be changed by objfun.

3: $bound$ – Nag_BoundType Input

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 \leq x_{j}$ .
$bound = Nag_BoundsEqual$: If all the variables are bounded, and $l_{1} = l_{2} = \dots = l_{n}$ and $u_{1} = u_{2} = \dots = u_{n}$ .

Constraint:

bound = Nag_Bounds

Nag_NoBounds

Nag_BoundsZero

Nag_BoundsEqual

4: $bl [n]$ – double Input/Output

On entry: the lower bounds

l_{j}

bound = Nag_Bounds

, you must set

bl [j - 1]

l_{j}

, for

j = 1, 2, \dots, 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}

bound = Nag_BoundsEqual

, you must set

bl [0]

l_{1}

; e04kbc will then set the remaining elements of bl equal to

bl [0]

bound = Nag_NoBounds

Nag_BoundsZero

, bl will be initialized by e04kbc.

On exit: the lower bounds actually used by e04kbc, e.g., if

bound = Nag_BoundsZero

bl [0] = bl [1] = \dots = bl [n - 1] = 0.0

5: $bu [n]$ – double Input/Output

On entry: the upper bounds

u_{j}

bound = Nag_Bounds

, you must set

bu [j - 1]

u_{j}

, for

j = 1, 2, \dots, 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}

bound = Nag_BoundsEqual

, you must set

bu [0]

u_{1}

; e04kbc will then set the remaining elements of bu equal to

bu [0]

bound = Nag_NoBounds

Nag_BoundsZero

, bu will be initialized by e04kbc.

On exit: the upper bounds actually used by e04kbc, e.g., if

bound = Nag_BoundsZero

bu [0] = bu [1] = \dots = bu [n - 1] = 10^{10}

6: $x [n]$ – double Input/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, \dots, 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.

7: $objf$ – double * Input/Output

On entry: if

options . init_state = Nag_Init_None

Nag_Init_H_S

, you need not initialize objf.

options . init_state = Nag_Init_F_G_H

Nag_Init_All

, objf must be set on entry to the value of

F (x)

at the initial point supplied in x.

On exit: the function value at the final point given in x.

8: $g [n]$ – double Input/Output

On entry:

$options . init_state = Nag_Init_F_G_H$ or $Nag_Init_All$: g must be set on entry to the first derivative vector at the initial $x$ .
$options . init_state = Nag_Init_None$ or $Nag_Init_H_S$: g need not be set.

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.

9: $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 e04kbc. 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 11. Some of the results returned in options can be used by e04kbc to perform a ‘warm start’ if it is re-entered (see the member

options . init_state

in Section 11.2).

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 e04kbc. However, if the optional parameters are not required the NAG defined null pointer, E04_DEFAULT, can be used in the function call.

10: $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 user-supplied functions; see the above 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 e04kbc; comm will then be declared internally for use in calls to user-supplied functions.

11: $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

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, NE_INIT_MEM, NE_NO_MEM, NE_HESD or NE_ALLOC_FAIL occurs, no values will have been assigned by e04kbc to objf or to the elements of g, $options . hesl$ , or $options . hesd$ .; An exit of $fail . code = NW_TOO_MANY_ITER$ , NW_COND_MIN and NW_LOCAL_SEARCH 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_max \geq options . optim_tol$ .
NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument bound had an illegal value.

On entry, argument $options . init_state$ 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_CHOLESKY_OVERFLOW: An overflow would have occurred during the updating of the Cholesky factors if the calculations had been allowed to continue. Restart from the current point with $options . init_state = Nag_Init_None$ .
NE_DERIV_ERRORS: Large errors were found in the derivatives of the objective function.
NE_HESD: The initial values of the supplied $options . hesd$ has some value(s) which is negative or too small or the ratio of the largest element of $options . hesd$ to the smallest is too large.
NE_INIT_MEM: Option $options . init_state = ⟨ string ⟩$ but the pointer $⟨ string ⟩$ in the option structure has not been allocated memory.
NE_INT_ARG_LT: On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 1$ .
NE_INVALID_INT_RANGE_1: Value $⟨ value ⟩$ given to $options . max_iter$ is not valid. Correct range is $options . max_iter \geq 0$ .
NE_INVALID_REAL_RANGE_EF: Value $⟨ value ⟩$ given to $options . optim_tol$ not valid. Correct range is $ε \leq options . optim_tol < 1.0$ .
NE_INVALID_REAL_RANGE_FF: Value $⟨ value ⟩$ given to $options . linesearch_tol$ not valid. Correct range is $0.0 \leq options . linesearch_tol < 1.0$ .
NE_NO_MEM: Option $options . init_state = ⟨ string ⟩$ but at least one of the pointers $⟨ string ⟩$ in the option structure has not been allocated memory.
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 $comm \to flag$ to a negative value in objfun. If fail is supplied the value of $fail . errnum$ will be the same as your setting of $comm \to flag$ .
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 approximate Hessian 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_LOCAL_SEARCH: The local search has failed to find a feasible point which gives a significant change of function value.
If the problem is a genuinely unconstrained one, this type of exit indicates that the problem is extremely ill conditioned or that the function has no minimum. If the problem has bounds which may be close to the minimum, it may just indicate that steps in the subspace of free variables happened to meet a bound before they changed the function value.
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 e04kbc when (B1, B2 and B3) or B4 hold, and the local search (if used) confirms a minimum, where

$B 1 \equiv α^{(k)} \times ‖ p^{(k)} ‖ < (options . optim_tol + \sqrt{ε}) \times (1.0 + ‖ x^{(k)} ‖)$
$B 2 \equiv | F^{(k)} - F^{(k - 1)} | < ({options . optim_tol}^{2} + ε) \times (1.0 + | F^{(k)} |)$
$B 3 \equiv ‖ g_{z}^{(k)} ‖ < (ε^{1 / 3} + options . optim_tol) \times (1.0 + | F^{(k)} |)$
$B 4 \equiv ‖ g_{z}^{(k)} ‖ < 0.01 \times \sqrt{ε} .$

(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 11.)

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

fail . code = NW_COND_MIN

or NW_LOCAL_SEARCH,

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

options . hesd

options . hesd [b]

, let the smallest be

options . hesd [s]

, and define

k = options . hesd [b] / options . hesd [s]

. The scalar

k

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 a fast linear rate,
(b) ${‖ g_{z} (x_{sol}) ‖}^{2} < 10.0 \times ε$ , and
(c) $k < 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 e04kbc; in particular the final value of Cond H gives

k

Further suggestions about confirmation of a computed solution are given in the E04 Chapter Introduction.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

e04kbc is not threaded in any implementation.

9 Further Comments

9.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 e04kbc is roughly proportional to

n_{z}^{2}

. In addition, each iteration makes at least one call of objfun with

comm \to flag = 2

options . minlin = Nag_Lin_Deriv

is used or one call of objfun with

comm \to flag = 0

options . minlin = Nag_Lin_NoDeriv

is chosen. So, unless

F (x)

can be evaluated very quickly, the run time will be dominated by the time spent in objfun.

9.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 e04kbc will take less computer time.

9.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)if $options . init_state = Nag_Init_All$ or $Nag_Init_H_S$ on entry, $options . state [j - 1]$ has simply to be set to $j$ , for $j = 1, 2, \dots, n$ ,
(c) $options . hesl$ and $options . hesd$ will be factors of the full approximate second derivative matrix with elements stored in the natural order,
(d)the elements of g should all be close to zero at the final point,
(e)the Status values given in the printout from e04kbc and in $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),
(f)Norm g simply gives the norm of the first derivative vector.

10 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

\begin{array}{l} 1 \leq x_{1} \leq 3 \\ −2 \leq x_{2} \leq 0 \\ 1 \leq x_{4} \leq 3 \end{array}

starting from the initial guess

{(3.0, - 0.9, 0.13, 1.1)}^{T}

The options structure is declared and initialized by e04xxc. Four option values are read from a data file by use of e04xyc. The memory freeing function 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.

11 Optional Parameters

A number of optional input and output arguments to e04kbc 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 e04kbc; 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 e04kbc, the options structure may only be re-used for future calls of e04kbc if the dimensions of the new problem are the same. Otherwise, the structure must be cleared by a call of e04xzc) and re-initialized 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.

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 e04xyc.

11.1 Optional Parameter Checklist and Default Values

For easy reference, the following list shows the members of options which are valid for e04kbc together with their default values where relevant. The number

ε

is a generic notation for machine precision (see X02AJC).

Boolean list	Nag_TRUE
Nag_PrintType print_level	Nag_Soln_Iter
char outfile[512]	stdout
void (*print_fun)()	NULL
Boolean deriv_check	Nag_TRUE
Nag_InitType init_state	Nag_Init_None
Integer max_iter	$50 n$
double optim_tol	$10 \sqrt{ε}$
Nag_LinFun minlin	Nag_Lin_Deriv
double linesearch_tol	$0.9$ ( $0.0$ if $n = 1$ )
double step_max	100000.0
double f_est
Boolean local_search	Nag_TRUE
Integer *state	size n
double *hesl	size $\max (n [n - 1] / 2, 1)$
double *hesd	size n
Integer iter
Integer nf

11.2 Description of the Optional Parameters

list – Nag_Boolean

Default

= Nag_TRUE

On entry: if

options . list = Nag_TRUE

the argument settings in the call to e04kbc will be printed.

print_level – Nag_PrintType

Default

= Nag_Soln_Iter

On entry: the level of results printout produced by e04kbc. 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 11.3.

Constraint:

options . print_level = Nag_NoPrint

Nag_Soln

Nag_Iter

Nag_Soln_Iter

Nag_Soln_Iter_Full

outfile – const char[512]

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 function

Default

=

NULL

On entry: printing function defined by you; the prototype of

options . print_fun

void (*print_fun)(const Nag_Search_State *st, Nag_Comm *comm);

See Section 11.3.1 below for further details.

deriv_check – Nag_Boolean

Default

= Nag_TRUE

options . init_state \neq Nag_Init_None

then the default of

options . deriv_check

is changed to Nag_FALSE.

On entry: if

options . deriv_check = Nag_TRUE

a check of the derivatives defined by objfun will be made at the starting point x. The derivative check is carried out by a call to e04hcc. If

options . init_state

is set to a value other than its default value (

options . init_state = Nag_Init_None

) then the default of

options . deriv_check

will be Nag_FALSE. A starting point of

x = 0

x = 1

should be avoided if this test is to be meaningful, if either of these starting points is necessary then e04hcc should be used to check objfun at a different point prior to calling e04kbc.

init_state – Nag_InitType

Default

= Nag_Init_None

On entry:

options . init_state

specifies which of the arguments objf, g,

options . hesl

options . hesd

and

options . state

are actually being initialized. Such information will generally reduce the time taken by e04kbc.

$options . init_state = Nag_Init_None$: No values are assumed to have been set in any of objf, g, $options . hesl$ , $options . hesd$ or $options . state$ . (e04kbc will use the unit matrix as the initial estimate of the Hessian matrix.)
$options . init_state = Nag_Init_F_G_H$: The arguments objf and g must contain the value of $F (x)$ and its first derivatives at the starting point. The elements $options . hesd [j - 1]$ must have been set to estimates of the derivatives $\frac{\partial^{2} F}{\partial x_{j}^{2}}$ at the starting point. No values are assumed to have been set in $options . hesl$ or $options . state$ .
$options . init_state = Nag_Init_All$: The arguments objf and g must contain the value of $F (x)$ and its first derivatives at the starting point. All $n$ elements of $options . state$ must have been set to indicate which variables are on their bounds and which are free. $options . hesl$ and $options . hesd$ must contain the Cholesky factors of a positive definite approximation to the $n_{z} \times n_{z}$ Hessian matrix for the subspace of free variables. (This option is useful for restarting the minimization process if $options . max_iter$ is reached.)
$options . init_state = Nag_Init_H_S$: No values are assumed to have been set in objf or g, but $options . hesl$ , $options . hesd$ and $options . state$ must have been set as for $options . init_state = Nag_Init_All$ . (This option is useful for starting off a minimization run using second derivative information from a previous, similar, run.)

Constraint:

options . init_state = Nag_Init_None

Nag_Init_F_G_H

Nag_Init_All

Nag_Init_H_S

max_iter – Integer

Default

= 50 n

On entry: the limit on the number of iterations allowed before termination.

Constraint:

options . max_iter \geq 0

optim_tol – double

Default

= 10 \sqrt{ε}

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

‖ x_{sol} - x_{true} ‖ < options . optim_tol \times (1.0 + ‖ x_{true} ‖),

where

‖ y ‖ = {(\sum_{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 5 decimal places. (For further details see Section 9.) If the problem is scaled roughly as described in Section 9 and

ε

is the machine precision, then

\sqrt{ε}

is probably the smallest reasonable choice for

options . optim_tol

. (This is because, normally, to machine accuracy,

F (x + \sqrt{ε} e_{j}) = F (x)

where

e_{j}

is any column of the identity matrix.)

Constraint:

ε \leq options . optim_tol < 1.0

minlin – Nag_LinFun

Default

= Nag_Lin_Deriv

On entry:

options . minlin

specifies whether the linear minimizations (i.e., minimizations of

F (x + α p)

with respect to

α

) are to be performed by a function which just requires the evaluation of

F (x)

Nag_Lin_NoDeriv

, or by a function which also requires the first derivatives of

F (x)

Nag_Lin_Deriv

It will often be possible to evaluate the first derivatives of

F

in about the same amount of computer time that is required for the evaluation of

F

itself – if this is so then e04kbc should be called with

options . minlin

set to

Nag_Lin_Deriv

. However, if the evaluation of the derivatives takes more than about 4 times as long as the evaluation of

F

, then a setting of

Nag_Lin_NoDeriv

will usually be preferable. If in doubt, use the default setting

Nag_Lin_Deriv

as it is slightly more robust.

Constraint:

options . minlin = Nag_Lin_Deriv

Nag_Lin_NoDeriv

linesearch_tol – double

Default

= 0.9

n > 1

, and

0.0

otherwise

options . minlin = Nag_Lin_NoDeriv

then the default value of

options . linesearch_tol

will be changed from

0.9

0.5

n > 1

On entry: every iteration of e04kbc 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 e04kbc, 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 $F (x)$ is a penalty or barrier function arising from a constrained minimization problem (since such problems are very difficult to solve)
(c)if $options . minlin = Nag_Lin_NoDeriv$ and the calculation of first derivatives takes so much computer time (relative to the time taken to evaluate the function) that it is worth using extra function evaluations to reduce the number of derivative evaluations.

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 \leq options . linesearch_tol < 1.0

step_max – double

Default

= 100000.0

On entry: an estimate of the Euclidean distance between the solution and the starting point supplied. (For maximum efficiency a slight overestimate is preferable.) e04kbc will ensure that, for each iteration,

{(\sum_{j = 1}^{n} {[x_{j}^{(k)} - x_{j}^{(k - 1)}]}^{2})}^{1 / 2} \leq options . step_max,

where

k

is the iteration number. Thus, if the problem has more than one solution, e04kbc 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_max \geq options . optim_tol

f_est – double

On entry: an estimate of the function value at the minimum. This estimate is just used for calculating suitable step lengths for starting linear minimizations off, so the choice is not too critical. However, it is better for

options . f_est

to be set to an underestimate rather than to an overestimate. If no value is supplied then an initial step length of

1.0

, subject to the variable bounds, will be used.

local_search – Nag_Boolean

Default

= Nag_TRUE

On entry:

options . local_search

must specify whether or not you wish a ‘local search’ to be performed when a point is found which is thought to be a constrained minimum.

options . local_search = Nag_TRUE

and either the quasi-Newton direction of search fails to produce a lower function value or the convergence criteria are satisfied, then a local search will be performed. This may move the search away from a saddle point or confirm that the final point is a minimum.

options . local_search = Nag_FALSE

there will be no local search when a point is found which is thought to be a minimum.

The amount of work involved in a local search is comparable to twice that required in a normal iteration to minimize

F (x + α p)

with respect to

α

. For most problems this will be small (relative to the total time required for the minimization).

options . local_search

could be set Nag_FALSE if:

–it is known from the physical properties of a problem that a stationary point will be the required minimum;
–a point which is not a minimum could be easily recognized, for example if the value of $F (x)$ at the minimum is known.

state – Integer *

Default memory

= n

On entry:

options . state

need not be set if the default option of

options . init_state = Nag_Init_None

is used as n values of memory will be automatically allocated by e04kbc.

options . init_state = Nag_Init_All

Nag_Init_H_S

has been chosen,

options . state

must point to a minimum of n elements of memory. This memory will already be available if the calling program has used the options structure in a previous call to e04kbc with

options . init_state = Nag_Init_None

and the same value of n. If a previous call has not been made you must allocate sufficient memory.

When

options . init_state = Nag_Init_All

Nag_Init_H_S

then

options . state

must specify information about which variables are currently on their bounds and which are free. 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.

options . init_state = Nag_Init_None

Nag_Init_F_G_H

options . state

will be initialized by e04kbc.

options . init_state = Nag_Init_All

Nag_Init_H_S

options . state

must be initialized before e04kbc is called.

On exit:

options . state

gives information as above about the final point given in x.

hesl – double *

Default memory

= \max (n [n - 1] / 2, 1)

hesd – double *

Default memory

= n

On entry:

options . hesl

and

options . hesd

need not be set if the default of

options . init_state = Nag_Init_None

is used as sufficient memory will be automatically allocated by e04kbc.

options . init_state = Nag_Init_All

options . init_state = Nag_Init_H_S

has been set then

options . hesl

must point to a minimum of

\max (n [n - 1] / 2, 1)

elements of memory.

options . hesd

must point to at least n elements of memory if

options . init_state = Nag_Init_F_G_H

Nag_Init_All

Nag_Init_H_S

has been chosen.

The appropriate amount of memory will already be available for

options . hesl

and

options . hesd

if the calling program has used the options structure in a previous call to e04kbc with

options . init_state = Nag_Init_None

and the same value of n. If a previous call has not been made, you must allocate sufficient memory.

options . hesl

and

options . hesd

are used to store the factors

L

and

D

of the current approximation to the matrix of second derivatives with respect to the free variables (see Section 3). (The elements of the matrix are assumed to be ordered according to the permutation specified by the positive elements of

options . state

, see above.)

options . hesl

holds the lower triangle of

L

, omitting the unit diagonal, stored by rows.

options . hesd

stores the diagonal elements of

D

. Thus if

n_{z}

elements of

options . state

are positive, the strict lower triangle of

L

will be held in the first

n_{z} (n_{z} - 1) / 2

elements of

options . hesl

and the diagonal elements of

D

in the first

n_{z}

elements of

options . hesd

options . init_state = Nag_Init_None

(the default),

options . hesl

and

options . hesd

will be initialized within e04kbc to the factors of the unit matrix.

If you set

options . init_state = Nag_Init_F_G_H

options . hesd [j - 1]

must contain on entry an approximation to the second derivative with respect to

x_{j}

, for

j = 1, 2, \dots, n

options . hesl

need not be set.

options . init_state = Nag_Init_All

Nag_Init_H_S

options . hesl

and

options . hesd

must contain on entry the Cholesky factors of a positive definite approximation to the

n_{z} \times n_{z}

matrix of second derivatives for the subspace of free variables as specified by your setting of

options . state

On exit:

options . hesl

and

options . hesd

hold the factors

L

and

D

corresponding to the final point given in x. The elements of

options . hesd

are useful for deciding whether to accept the result produced by e04kbc (see Section 9).

iter – Integer

On exit: the number of iterations which have been performed in e04kbc.

nf – Integer

On exit: the number of times the residuals have been evaluated (i.e., number of calls of objfun).

11.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 11.2). If

options . list = Nag_TRUE

then the argument values to e04kbc 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 e04kbc.

When

options . print_level = Nag_Iter

Nag_Soln_Iter

a single line of output is produced on completion of each iteration, this gives the following values:

Itn	the iteration count, $k$ .
Nfun	the cumulative number of calls to objfun.
Objective	the current 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.)

When

options . print_level = Nag_Soln

Nag_Soln_Iter

Nag_Soln_Full

this single line of output is also produced for the final solution.

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).

options . print_level = Nag_Soln

Nag_Soln_Iter

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).

options . print_level = Nag_NoPrint

then printout will be suppressed; you can print the final solution when e04kbc returns to the calling program.

11.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

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 e04kbc. 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

The results contained in the members of st are those on completion of the last iteration or those after a local search. (An iteration may be followed by a local search (see

options . local_search

, Section 11.2) in which case

options . print_fun

is called with the results of the last iteration (

st \to local_search = Nag_FALSE

) and then again when the local search has been completed (

st \to local_search = Nag_TRUE

).)

comm \to it_prt = Nag_TRUE

then the results on completion of an iteration of e04kbc are contained in the members of st. If

comm \to sol_prt = Nag_TRUE

then the final results from e04kbc, 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:

iter – Integer: The current iteration count, $k$ , if $comm \to it_prt = Nag_TRUE$ ; the final iteration count, $k$ , if $comm \to sol_prt = Nag_TRUE$ .

n – Integer: The number of variables.

x – double *: The coordinates of the point $x^{(k)}$ .

f – double *: The value of the current objective function.

g – double *: Points to the n memory locations holding the first derivatives of $F$ at the current point $x^{(k)}$ .

gpj_norm – double *: The Euclidean norm of the current projected gradient $g_{z}$ .

step – double *: The step $α^{(k)}$ taken along the search direction $p^{(k)}$ .

cond – double *: The estimate of the condition number of the Hessian matrix.

xk_norm – double *: The Euclidean norm of $x^{(k - 1)} - x^{(k)}$ .

state – Integer: The status of variables $x_{j}$ , $j = 1, 2, \dots, n$ , with respect to their bounds. See Section 3 for a description of the possible status values.

local_search – Nag_Boolean: Nag_TRUE if a local search has been performed.

nf – Integer: The cumulative number of calls made to objfun.

The relevant members of the structure comm are:

it_prt – Nag_Boolean: Will be Nag_TRUE when the print function is called with the results of the current iteration.

sol_prt – Nag_Boolean: Will be Nag_TRUE when the print function is called with the final result.

user – double *
iuser – Integer *
p – Pointer: Pointers for communication of user information. If used they must be allocated memory either before entry to e04kbc 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.