NAG FL Interface
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

void  objfun_ (const Integer *n, const double x[], double *f, Integer iuser[], double ruser[], Integer *inform)

C++ Header Interface

#include <nag.h> extern "C" { void  objfun_ (const Integer &n, const double x[], double &f, Integer iuser[], double ruser[], Integer &inform) }

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

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

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

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}$.

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

5: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User 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}$ – Integer Output

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}$ – Integer Input

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}$ – Integer Input

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) array Input/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) array Input

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

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

void  monfun_ (const Integer *n, const Integer *nf, const double x[], const double *f, const double *rho, Integer iuser[], double ruser[], Integer *inform)

C++ Header Interface

#include <nag.h> extern "C" { 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}$ – Integer Input

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

2: $\mathbf{nf}$ – Integer Input

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

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

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 array User Workspace

7: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User 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}$ – Integer Output

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}$ – Integer Input

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}$ – Integer Output

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 array User Workspace

14: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User 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}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

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

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results