NAG Toolbox: nag_opt_bounds_mod_deriv2_easy (e04ly)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{ibound}$ – int64int32nag_int scalar

Indicates whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:

$\mathbf{ibound}=0$

If you are supplying all the $l_j$ and $u_j$ individually.

$\mathbf{ibound}=1$

If there are no bounds on any $x_j$.

$\mathbf{ibound}=2$

If all the bounds are of the form $0\le x_j$.

$\mathbf{ibound}=3$

If $l_1=l_2=\cdots =l_n$ and $u_1=u_2=\cdots =u_n$.

Constraint: $0\le \mathbf{ibound}\le 3$.

2:     $\mathrm{funct2}$ – function handle or string containing name of m-file

You must supply this function to calculate the values of the function $F\left(x\right)$ and its first derivatives $\frac{\partial F}{\partial x_j}$ at any point $x$. It should be tested separately before being used in conjunction with nag_opt_bounds_mod_deriv2_easy (e04ly) (see the E04 Chapter Introduction).

[fc, gc, user] = funct2(n, xc, user)

Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

The number $n$ of variables.

2:     $\mathrm{xc}\left(\mathbf{n}\right)$ – double array

The point $x$ at which the function and its derivatives are required.

3:     $\mathrm{user}$ – Any MATLAB object

funct2 is called from nag_opt_bounds_mod_deriv2_easy (e04ly) with the object supplied to nag_opt_bounds_mod_deriv2_easy (e04ly).

Output Parameters

1:     $\mathrm{fc}$ – double scalar

The value of the function $F$ at the current point $x$.

2:     $\mathrm{gc}\left(\mathbf{n}\right)$ – double array

$\mathbf{gc}\left(\mathit{j}\right)$ must be set to the value of the first derivative $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{j}=1,2,\dots ,n$.

3:     $\mathrm{user}$ – Any MATLAB object

3:     $\mathrm{hess2}$ – function handle or string containing name of m-file

You must supply this function to evaluate the elements $H_{ij}=\frac{{\partial }^{2}F}{\partial x_i\partial x_j}$ of the matrix of second derivatives of $F\left(x\right)$ at any point $x$. It should be tested separately before being used in conjunction with nag_opt_bounds_mod_deriv2_easy (e04ly) (see the E04 Chapter Introduction).

[heslc, hesdc, user] = hess2(n, xc, lh, user)

Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

The number $n$ of variables.

2:     $\mathrm{xc}\left(\mathbf{n}\right)$ – double array

The point $x$ at which the derivatives are required.

3:     $\mathrm{lh}$ – int64int32nag_int scalar

The length of the array heslc.

4:     $\mathrm{user}$ – Any MATLAB object

hess2 is called from nag_opt_bounds_mod_deriv2_easy (e04ly) with the object supplied to nag_opt_bounds_mod_deriv2_easy (e04ly).

Output Parameters

1:     $\mathrm{heslc}\left(\mathbf{lh}\right)$ – double array

hess2 must place the strict lower triangle of the second derivative matrix $H$ in heslc, stored by rows, i.e., set $\mathbf{heslc}\left(\left(\mathit{i}-1\right)\left(\mathit{i}-2\right)/2+\mathit{j}\right)=\frac{{\partial }^{2}F}{\partial x_{\mathit{i}}\partial x_{\mathit{j}}}$, for $\mathit{i}=2,3,\dots ,n$ and $\mathit{j}=1,2,\dots ,\mathit{i}-1$. (The upper triangle is not required because the matrix is symmetric.)

2:     $\mathrm{hesdc}\left(\mathbf{n}\right)$ – double array

Must contain the diagonal elements of the second derivative matrix, i.e., set $\mathbf{hesdc}\left(\mathit{j}\right)=\frac{{\partial }^{2}F}{\partial x_{\mathit{j}}^2}$, for $\mathit{j}=1,2,\dots ,n$.

3:     $\mathrm{user}$ – Any MATLAB object

4:     $\mathrm{bl}\left(\mathbf{n}\right)$ – double array

The lower bounds $l_j$.

If ibound is set to $0$, $\mathbf{bl}\left(\mathit{j}\right)$ must be set to $l_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$. (If a lower bound is not specified for any $x_j$, the corresponding $\mathbf{bl}\left(j\right)$ should be set to $-{10}^6$.)

If ibound is set to $3$, you must set $\mathbf{bl}\left(1\right)$ to $l_1$; nag_opt_bounds_mod_deriv2_easy (e04ly) will then set the remaining elements of bl equal to $\mathbf{bl}\left(1\right)$.

5:     $\mathrm{bu}\left(\mathbf{n}\right)$ – double array

The upper bounds $u_j$.

If ibound is set to $0$, $\mathbf{bu}\left(\mathit{j}\right)$ must be set to $u_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$. (If an upper bound is not specified for any $x_j$ the corresponding $\mathbf{bu}\left(j\right)$ should be set to ${10}^6$.)

If ibound is set to $3$, you must set $\mathbf{bu}\left(1\right)$ to $u_1$; nag_opt_bounds_mod_deriv2_easy (e04ly) will then set the remaining elements of bu equal to $\mathbf{bu}\left(1\right)$.

6:     $\mathrm{x}\left(\mathbf{n}\right)$ – double array

$\mathbf{x}\left(\mathit{j}\right)$ must be set to a guess at the $\mathit{j}$th component of the position of the minimum, for $\mathit{j}=1,2,\dots ,n$. The function checks the gradient and the Hessian matrix at the starting point, and is more likely to detect any error in your programming if the initial $\mathbf{x}\left(j\right)$ are nonzero and mutually distinct.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the arrays bl, bu, x. (An error is raised if these dimensions are not equal.)

The number $n$ of independent variables.

Constraint: $\mathbf{n}\ge 1$.

2:     $\mathrm{user}$ – Any MATLAB object

user is not used by nag_opt_bounds_mod_deriv2_easy (e04ly), but is passed to funct2 and hess2. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

Output Parameters

1:     $\mathrm{bl}\left(\mathbf{n}\right)$ – double array

The lower bounds actually used by nag_opt_bounds_mod_deriv2_easy (e04ly).

2:     $\mathrm{bu}\left(\mathbf{n}\right)$ – double array

The upper bounds actually used by nag_opt_bounds_mod_deriv2_easy (e04ly).

3:     $\mathrm{x}\left(\mathbf{n}\right)$ – double array

The lowest point found during the calculations. Thus, if $\mathbf{ifail}=\mathbf{0}$ on exit, $\mathbf{x}\left(j\right)$ is the $j$th component of the position of the minimum.

4:     $\mathrm{f}$ – double scalar

The value of $F\left(x\right)$ corresponding to the final point stored in x.

5:     $\mathrm{g}\left(\mathbf{n}\right)$ – double array

The value of $\frac{\partial F}{\partial x_{\mathit{j}}}$ corresponding to the final point stored in x, for $\mathit{j}=1,2,\dots ,n$; the value of $\mathbf{g}\left(j\right)$ for variables not on a bound should normally be close to zero.

6:     $\mathrm{user}$ – Any MATLAB object

7:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{ifail}=1$

On entry,	$\mathbf{n}<1$,
or	$\mathbf{ibound}<0$,
or	$\mathbf{ibound}>3$,
or	$\mathbf{ibound}=0$ and $\mathbf{bl}\left(j\right)>\mathbf{bu}\left(j\right)$ for some $j$,
or	$\mathbf{ibound}=3$ and $\mathbf{bl}\left(1\right)>\mathbf{bu}\left(1\right)$,
or	$\mathit{liw}<\mathbf{n}+2$,
or	$\mathit{lw}<\max \left(10,\mathbf{n}\times \left(\mathbf{n}+7\right)\right)$.

   $\mathbf{ifail}=2$

There have been $50\times \mathbf{n}$ function evaluations, yet the algorithm does not seem to be converging. The calculations can be restarted from the final point held in x. The error may also indicate that $F\left(x\right)$ has no minimum.

W  $\mathbf{ifail}=3$

The conditions for a minimum have not all been met but a lower point could not be found and the algorithm has failed.

   $\mathbf{ifail}=4$

Not used. (This value of the argument is included so as to make the significance of $\mathbf{ifail}=\mathbf{5}$ etc. consistent in the easy-to-use functions.)

W  $\mathbf{ifail}=5$

W  $\mathbf{ifail}=6$

W  $\mathbf{ifail}=7$

W  $\mathbf{ifail}=8$

There is some doubt about whether the point $x$ found by nag_opt_bounds_mod_deriv2_easy (e04ly) is a minimum. The degree of confidence in the result decreases as ifail increases. Thus, when $\mathbf{ifail}=\mathbf{5}$ it is probable that the final $x$ gives a good estimate of the position of a minimum, but when $\mathbf{ifail}=\mathbf{8}$ it is very unlikely that the function has found a minimum.

   $\mathbf{ifail}=9$

In the search for a minimum, the modulus of one of the variables has become very large $\left(\sim {10}^6\right)$. This indicates that there is a mistake in user-supplied functions funct2 or hess2, that your problem has no finite solution, or that the problem needs rescaling (see Further Comments).

   $\mathbf{ifail}=10$

It is very likely that you have made an error in forming the gradient.

   $\mathbf{ifail}=11$

It is very likely that you have made an error in forming the second derivatives.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: e04ly_example

function e04ly_example


fprintf('e04ly example results\n\n');

bl = [ 1; -2; -1000000; 1];
bu = [ 3;  0;  1000000; 3];
x  = [ 3; -1;        0; 1];
ibound = int64(0);
% Catch warnings and assume ifail=3,5 gives a good estimate
wstat = warning();
warning('OFF');
[bl, bu, x, f, g, user, ifail] = e04ly(ibound, @funct2, @hess2, bl, bu, x);
warning(wstat);
if (ifail == 0 || ifail == 5 | ifail == 3)
  fprintf('Minimum found at x: ');
  fprintf(' %9.4f',x);
  fprintf('\nGradients at x,  g: ');
  fprintf(' %9.4f',g);
  fprintf('\nMinimum value     :  %9.4f\n\n',f);
else   
  fprintf('\n Error: e04ly returns ifail = %d\n',ifail);
end



function [fc, gc, user] = funct2(n, xc, user)
  gc = zeros(n, 1);
  fc = 0;
  x1 = xc(1) + 10*xc(2);
  x2 = xc(3) -    xc(4);
  x3 = xc(2) -  2*xc(3);
  x4 = xc(1) -    xc(4);
  fc = x1^2 + 5*x2^2 + x3^4 + 10*x4^4;
  gc(1) =   2*x1 + 40*x4^3;
  gc(2) =  20*x1 +  4*x3^3;
  gc(3) =  10*x2 -  8*x3^3;
  gc(4) = -10*x2 - 40*x4^3;

function [fhesl, fhesd, user] = hess2(n, xc, lh, user)
  fhesl = zeros(lh, 1);
  fhesd = zeros(n, 1);

  x3 = xc(2) -  2*xc(3);
  x4 = xc(1) -    xc(4);
  fhesd(1) =    2 + 120*x4^2;
  fhesd(2) =  200 +  12*x3^2;
  fhesd(3) =   10 +  48*x3^2;
  fhesd(4) =   10 + 120*x4^2;
  fhesl(1) =   20;
  fhesl(2) =    0;
  fhesl(3) =  -24*x3^2;
  fhesl(4) = -120*x4^2;
  fhesl(5) =    0;
  fhesl(6) =  -10;

e04ly example results

Minimum found at x:     1.0000   -0.0852    0.4093    1.0000
Gradients at x,  g:     0.2953   -0.0000    0.0000    5.9070
Minimum value     :     2.4338