NAG CL Interface
e04jcc (bounds_​bobyqa_​func)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{objfun}$ – function, supplied by the user External Function

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

The specification of objfun is:

copy

void  objfun (Integer n, const double x[], double *f, Nag_Comm *comm, Integer *inform)

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

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

2: $\mathbf{x}\left[\mathbf{n}\right]$ – const double Input

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

3: $\mathbf{f}$ – double * Output

On exit: must be set to the value of the objective function at $\mathbf{x}$.

4: $\mathbf{comm}$ – Nag_Comm *

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

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling e04jcc you may allocate memory and initialize these pointers with various quantities for use by objfun when called from e04jcc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

5: $\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.

Note: objfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04jcc. If your code inadvertently does return any NaNs or infinities, e04jcc 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{(n_r+1)\times (n_r+2)}{2}$, where $n_r$ denotes the number of non-fixed variables.

4: $\mathbf{x}\left[\mathbf{n}\right]$ – double 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{fail}\mathbf{.}\mathbf{code}=$ NE_NOERROR on exit, x is the position of the minimum.

5: $\mathbf{bl}\left[\mathbf{n}\right]$ – const double Input

6: $\mathbf{bu}\left[\mathbf{n}\right]$ – const double 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 X02ALC).

Constraints:

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

7: $\mathbf{rhobeg}$ – double 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}$ – double 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{nag\_machine\_precision}$, the machine precision.

9: $\mathbf{monfun}$ – function, supplied by the user External Function

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 specified as NULLFN.

The specification of monfun is:

copy

void  monfun (Integer n, Integer nf, const double x[], double f, double rho, Nag_Comm *comm, 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]$ – const double Input

On entry: the current best point.

4: $\mathbf{f}$ – double Input

On entry: the value of objfun at x.

5: $\mathbf{rho}$ – double Input

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

6: $\mathbf{comm}$ – Nag_Comm *

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

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling e04jcc you may allocate memory and initialize these pointers with various quantities for use by monfun when called from e04jcc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

7: $\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.

10: $\mathbf{maxcal}$ – Integer Input

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

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

11: $\mathbf{f}$ – double * Output

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

12: $\mathbf{nf}$ – Integer * Output

On exit: unless $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_RESCUE_FAILED, NE_TOO_MANY_FEVALS, NE_TR_STEP_FAILED or NE_USER_STOP on exit, the total number of calls made to objfun.

13: $\mathbf{comm}$ – Nag_Comm *

The NAG communication argument (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

14: $\mathbf{fail}$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

e04jcc returns with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_NOERROR if the final trust region radius has reached its lower bound rhoend.

6 Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_BOUND

On entry, $\mathbf{rhobeg}=⟨\mathit{\text{value}}⟩$, $\mathbf{bl}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, $\mathbf{bu}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and $i=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{bl}\left[i-1\right]\ne \mathbf{bu}\left[i-1\right]$ in coordinate $i$, $\mathbf{bu}\left[i-1\right]-\mathbf{bl}\left[i-1\right]\ge 2\times \mathbf{rhobeg}$.

NE_INT

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

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{(n_r+1)\times (n_r+2)}{2}$.

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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

NE_REAL

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

On entry, $\mathbf{rhoend}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{rhoend}\ge \mathit{macheps}$, where $\mathit{macheps}=\mathbf{nag\_machine\_precision}$, the machine precision.

NE_REAL_2

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

NE_RESCUE_FAILED

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.

NE_TOO_MANY_FEVALS

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

NE_TR_STEP_FAILED

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.

NE_USER_STOP

User-supplied monitoring function requested termination.

User-supplied objective function requested termination.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results