NAG Library Routine Document

e04jcf  (bounds_bobyqa_func)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{objfun}$ – Subroutine, supplied by the user.External Procedure

objfun must evaluate the objective function $F$ at a specified vector $\mathbf{x}$.

The specification of objfun is:

Fortran Interface

Subroutine objfun ( n, x, f, iuser, ruser, inform) Integer, Intent (In) :: n Integer, Intent (Inout) :: iuser(*) Integer, Intent (Out) :: inform Real (Kind=nag_wp), Intent (In) :: x(n) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Real (Kind=nag_wp), Intent (Out) :: f

C Header Interface

#include nagmk26.h void  objfun ( const Integer *n, const double x[], double *f, Integer iuser[], double ruser[], Integer *inform)

1:     $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of independent variables.

2:     $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: $\mathbf{x}$, the vector at which the objective function is to be evaluated.

3:     $\mathbf{f}$ – Real (Kind=nag_wp)Output

On exit: must be set to the value of the objective function at $\mathbf{x}$, unless you have specified termination of the current problem using inform.

4:     $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

5:     $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

objfun is called with the arguments iuser and ruser as supplied to e04jcf. You should use the arrays iuser and ruser to supply information to objfun.

6:     $\mathbf{inform}$ – IntegerOutput

On exit: must be set to a value describing the action to be taken by the solver on return from objfun. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

objfun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e04jcf is called. Arguments denoted as Input must not be changed by this procedure.

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

2:     $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of independent variables.

Constraint: $\mathbf{n}\ge 2$ and $n_r\ge 2$, where $n_r$ denotes the number of non-fixed variables.

3:     $\mathbf{npt}$ – IntegerInput

On entry: $m$, the number of interpolation conditions imposed on the quadratic approximation at each iteration.

Suggested value: $\mathbf{npt}=2\times n_r+1$, where $n_r$ denotes the number of non-fixed variables.

Constraint: $n_r+2\le \mathbf{npt}\le \frac{\left(n_r+1\right)\times \left(n_r+2\right)}{2}$, where $n_r$ denotes the number of non-fixed variables.

4:     $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: an estimate of the position of the minimum. If any component is out-of-bounds it is replaced internally by the bound it violates.

On exit: the lowest point found during the calculations. Thus, if $\mathbf{ifail}=\mathbf{0}$ on exit, x is the position of the minimum.

5:     $\mathbf{bl}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

6:     $\mathbf{bu}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the fixed vectors of bounds: the lower bounds $\mathbf{\ell }$ and the upper bounds $\mathbf{u}$, respectively. To signify that a variable is unbounded you should choose a large scalar $r$ appropriate to your problem, then set the lower bound on that variable to $-r$ and the upper bound to $r$. For well-scaled problems $r=r_{\max }^{\frac{1}{4}}$ may be suitable, where $r_{\max }$ denotes the largest positive model number (see x02alf).

Constraints:

• if $\mathbf{x}\left(\mathit{i}\right)$ is to be fixed at $\mathbf{bl}\left(\mathit{i}\right)$, then$\mathbf{bl}\left(\mathit{i}\right)=\mathbf{bu}\left(\mathit{i}\right)$;
• otherwise $\mathbf{bu}\left(\mathit{i}\right)-\mathbf{bl}\left(\mathit{i}\right)\ge 2.0\times \mathbf{rhobeg}$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

7:     $\mathbf{rhobeg}$ – Real (Kind=nag_wp)Input

On entry: an initial lower bound on the value of the trust region radius.

Suggested value: rhobeg should be about one tenth of the greatest expected overall change to a variable: the initial quadratic model will be constructed by taking steps from the initial x of length rhobeg along each coordinate direction.

Constraints:

• $\mathbf{rhobeg}>0.0$;
• $\mathbf{rhobeg}\ge \mathbf{rhoend}$.

8:     $\mathbf{rhoend}$ – Real (Kind=nag_wp)Input

On entry: a final lower bound on the value of the trust region radius.

Suggested value: rhoend should indicate the absolute accuracy that is required in the final values of the variables.

Constraint: $\mathbf{rhoend}\ge \mathit{macheps}$, where $\mathit{macheps}=\mathbf{x02ajf}\left(\right)$, the machine precision..

9:     $\mathbf{monfun}$ – Subroutine, supplied by the NAG Library or the user.External Procedure

monfun may be used to monitor the optimization process. It is invoked every time a new trust region radius is chosen.

If no monitoring is required, monfun may be the dummy monitoring routine e04jcp supplied by the NAG Library.

The specification of monfun is:

Fortran Interface

Subroutine monfun ( n, nf, x, f, rho, iuser, ruser, inform) Integer, Intent (In) :: n, nf Integer, Intent (Inout) :: iuser(*) Integer, Intent (Out) :: inform Real (Kind=nag_wp), Intent (In) :: x(n), f, rho Real (Kind=nag_wp), Intent (Inout) :: ruser(*)

C Header Interface

#include nagmk26.h void  monfun ( const Integer *n, const Integer *nf, const double x[], const double *f, const double *rho, Integer iuser[], double ruser[], Integer *inform)

1:     $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of independent variables.

2:     $\mathbf{nf}$ – IntegerInput

On entry: the cumulative number of calls made to objfun.

3:     $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the current best point.

4:     $\mathbf{f}$ – Real (Kind=nag_wp)Input

On entry: the value of objfun at x.

5:     $\mathbf{rho}$ – Real (Kind=nag_wp)Input

On entry: a lower bound on the current trust region radius.

6:     $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

7:     $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

monfun is called with the arguments iuser and ruser as supplied to e04jcf. You should use the arrays iuser and ruser to supply information to monfun.

8:     $\mathbf{inform}$ – IntegerOutput

On exit: must be set to a value describing the action to be taken by the solver on return from monfun. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

monfun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e04jcf is called. Arguments denoted as Input must not be changed by this procedure.

10:   $\mathbf{maxcal}$ – IntegerInput

On entry: the maximum permitted number of calls to objfun.

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

11:   $\mathbf{f}$ – Real (Kind=nag_wp)Output

On exit: the function value at the lowest point found (x).

12:   $\mathbf{nf}$ – IntegerOutput

On exit: unless $\mathbf{ifail}=\mathbf{1}$ or $-\mathbf{999}$ on exit, the total number of calls made to objfun.

13:   $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

14:   $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

iuser and ruser are not used by e04jcf, but are passed directly to objfun and monfun and may be used to pass information to these routines.

15:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

e04jcf returns with $\mathbf{ifail}=\mathbf{0}$ if the final trust region radius has reached its lower bound rhoend.

6

Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, $\mathbf{maxcal}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{maxcal}\ge 1$.

On entry, $\mathbf{rhobeg}=〈\mathit{\text{value}}〉$, $\mathbf{bl}\left(i\right)=〈\mathit{\text{value}}〉$, $\mathbf{bu}\left(i\right)=〈\mathit{\text{value}}〉$ and $i=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{bl}\left(i\right)\ne \mathbf{bu}\left(i\right)$ in coordinate $i$, $\mathbf{bu}\left(i\right)-\mathbf{bl}\left(i\right)\ge 2\times \mathbf{rhobeg}$.

On entry, $\mathbf{rhobeg}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{rhobeg}>0.0$.

On entry, $\mathbf{rhobeg}=〈\mathit{\text{value}}〉$ and $\mathbf{rhoend}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{rhoend}\le \mathbf{rhobeg}$.

On entry, $\mathbf{rhoend}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{rhoend}\ge \mathit{macheps}$, where $\mathit{macheps}=\mathbf{x02ajf}\left(\right)$, the machine precision.

There were $n_r=〈\mathit{\text{value}}〉$ unequal bounds.
Constraint: $n_r\ge 2$.

There were $n_r=〈\mathit{\text{value}}〉$ unequal bounds and $\mathbf{npt}=〈\mathit{\text{value}}〉$ on entry.
Constraint: $n_r+2\le \mathbf{npt}\le \frac{\left(n_r+1\right)\times \left(n_r+2\right)}{2}$.

$\mathbf{ifail}=2$

The function evaluations limit was reached: objfun has been called maxcal times.

$\mathbf{ifail}=3$

The predicted reduction in a trust region step was non-positive. Check your specification of objfun and whether the function needs rescaling. Try a different initial x.

$\mathbf{ifail}=4$

A rescue procedure has been called in order to correct damage from rounding errors when computing an update to a quadratic approximation of $F$, but no further progess could be made. Check your specification of objfun and whether the function needs rescaling. Try a different initial x.

$\mathbf{ifail}=5$

User-supplied monitoring routine requested termination.

User-supplied objective function requested termination.

$\mathbf{ifail}=-99$

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

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

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

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (e04jcfe.f90)

10.2

Program Data

10.3

Program Results

Program Results (e04jcfe.r)