NAG FL Interface
e04jdf (handle_​solve_​dfno)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{handle}$ – Type (c_ptr) Input

On entry: the handle to the problem. It needs to be initialized by e04raf and the objective must be declared as nonlinear least squares by a call to the routine e04rgf. The routine e04rhf can optionally be called to define box bounds. It must not be changed between calls to the NAG optimization modelling suite.

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

objfun calculates the value of the objective function $f\left(x\right)$ at a specified point $x$.

The specification of objfun is:

Fortran Interface

Subroutine objfun ( nvar, x, fx, inform, iuser, ruser, cpuser) Integer, Intent (In) :: nvar Integer, Intent (Inout) :: inform, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(nvar) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Real (Kind=nag_wp), Intent (Out) :: fx Type (c_ptr), Intent (In) :: cpuser

C Header Interface

void  objfun_ (const Integer *nvar, const double x[], double *fx, Integer *inform, Integer iuser[], double ruser[], void **cpuser)

C++ Header Interface

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

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

On entry: $n$, the number of variables in the problem.

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

On entry: $x$, the vector of variable values at which the objective function is to be evaluated.

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

On exit: the value of the objective function at $x$.

4: $\mathbf{inform}$ – Integer Input/Output

On entry: a non-negative value.

On exit: may be used to indicate that the requested objective value could not be computed. Specifically, it can be set to a negative value:

$\mathbf{inform}=-1$

The solver will attempt a rescue procedure and request an alternative point. If the rescue procedure fails, the solver will exit with $\mathbf{ifail}=\mathbf{17}$.

$\mathbf{inform}=-2$

The solver will cleanly exit with $\mathbf{ifail}=\mathbf{20}$ and return the best available point as well as the solve statistics.

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

6: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

7: $\mathbf{cpuser}$ – Type (c_ptr) User Workspace

objfun is called with the arguments iuser, ruser and cpuser as supplied to e04jdf. You should use the arrays iuser and ruser, and the data handle cpuser to supply information to objfun.

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

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

monit is provided to enable you to monitor the progress of the optimization and optionally to terminate the solver early if necessary, using argument inform. It is invoked at the end of every $i$th iteration where $i$ is given by the DFO Monitor Frequency (the default is $0$, monit is not called).

If no monitoring is required, monit may be the dummy subroutine e04jdu supplied in the NAG Library.

The specification of monit is:

Fortran Interface

Subroutine monit ( nvar, x, inform, rinfo, stats, iuser, ruser, cpuser) Integer, Intent (In) :: nvar Integer, Intent (Inout) :: inform, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(nvar), rinfo(100), stats(100) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Type (c_ptr), Intent (In) :: cpuser

C Header Interface

void  monit_ (const Integer *nvar, const double x[], Integer *inform, const double rinfo[], const double stats[], Integer iuser[], double ruser[], void **cpuser)

C++ Header Interface

#include <nag.h> extern "C" { void  monit_ (const Integer &nvar, const double x[], Integer &inform, const double rinfo[], const double stats[], Integer iuser[], double ruser[], void *&cpuser) }

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

On entry: $n$, the number of variables in the problem.

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

On entry: $x$, the vector of decision variables at the current iteration.

3: $\mathbf{inform}$ – Integer Input/Output

On entry: a non-negative value.

On exit: may be used to request the solver to stop immediately. Specifically, if $\mathbf{inform}<0$, then the solver will terminate immediately with $\mathbf{ifail}=\mathbf{20}$. Otherwise, the solver will proceed normally.

4: $\mathbf{rinfo}\left(100\right)$ – Real (Kind=nag_wp) array Input

On entry: error measures and various indicators at the end of the current iteration as described in the main argument rinfo.

5: $\mathbf{stats}\left(100\right)$ – Real (Kind=nag_wp) array Input

On entry: solver statistics at monitoring steps or at the end of the current iteration (the values are as described in the main argument stats).

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

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

8: $\mathbf{cpuser}$ – Type (c_ptr) User Workspace

monit is called with the arguments iuser, ruser and cpuser as supplied to e04jdf. You should use the arrays iuser and ruser, and the data handle cpuser to supply information to monit.

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

4: $\mathbf{nvar}$ – Integer Input

On entry: $n$, the number of variables in the problem. It must be unchanged from the value set during the initialization of the handle by e04raf.

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

5: $\mathbf{x}\left(\mathbf{nvar}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: $x_0$, the initial estimates of the variables $x$.

On exit: the final values of the variables $x$.

6: $\mathbf{rinfo}\left(100\right)$ – Real (Kind=nag_wp) array Output

On exit: optimal objective value and various indicators at monitoring steps or at the end of the final iteration. The measures are given in the table below:

$1$	Objective function value $f\left(x\right)$.
$2$	$\rho$, the current lower bound of the trust region.
$3$	$\Delta$, the current size of the trust region.
$4$	The number of interpolation points used by the solver.
$5-100$	Reserved for future use.

7: $\mathbf{stats}\left(100\right)$ – Real (Kind=nag_wp) array Output

On exit: solver statistics at monitoring steps or at the end of the final iteration as given in the table below:

$1$	Number of calls to the objective function.
$2$	Total time spent in the solver (including time spent evaluating the objective).
$3$	Total time spent evaluating the objective function.
$4$	Number of steps.
$5-100$	Reserved for future use.

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

9: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

10: $\mathbf{cpuser}$ – Type (c_ptr) User Workspace

iuser, ruser and cpuser are not used by e04jdf, but are passed directly to objfun and monit and may be used to pass information to these routines. If you do not need to reference cpuser, it should be initialized to c_null_ptr.

11: $\mathbf{ifail}$ – Integer Input/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 4 in the Introduction to the NAG Library FL Interface 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, because for this routine the values of the output arguments may be useful even if $\mathbf{ifail}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }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).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

The supplied handle does not define a valid handle to the data structure for the NAG optimization modelling suite. It has not been initialized by e04raf or it has been corrupted.

$\mathbf{ifail}=2$

The problem is already being solved.

This solver does not support the model defined in the handle.

$\mathbf{ifail}=4$

The information supplied does not match with that previously stored.
On entry, $\mathbf{nvar}=〈\mathit{\text{value}}〉$ must match that given during initialization of the handle, i.e., $〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=5$

Inconsistent optional parameters DFO Trust Region Tolerance ${\rho }_{\mathrm{end}}$ and DFO Trust Region Slow Tol ${\rho }_{\mathrm{tol}}$.
Constraint: ${\rho }_{\mathrm{end}}<{\rho }_{\mathrm{tol}}$.
Use e04zmf to set compatible option values.

Inconsistent optional parameters DFO Trust Region Tolerance ${\rho }_{\mathrm{end}}$ and DFO Starting Trust Region ${\rho }_{\mathrm{beg}}$.
Constraint: ${\rho }_{\mathrm{end}}<{\rho }_{\mathrm{beg}}$.
Use e04zmf to set compatible option values.

Optional parameter DFO Starting Trust Region ${\rho }_{\mathrm{beg}}=〈\mathit{\text{value}}〉$, $l_x\left(i\right)=〈\mathit{\text{value}}〉$, $u_x\left(i\right)=〈\mathit{\text{value}}〉$ and $i=〈\mathit{\text{value}}〉$.
Constraint: if $l_x\left(i\right)\ne u_x\left(i\right)$ in coordinate $i$, then $u_x\left(i\right)-l_x\left(i\right)\ge 2\times {\rho }_{\mathrm{beg}}$.
Use e04zmf to set compatible option values.

$\mathbf{ifail}=6$

The number of initial interpolation points is different from the total set by DFO Number Interp Points.
Growing the interpolation set is not supported for this solver.

There were $n_r=〈\mathit{\text{value}}〉$ unequal bounds and the optional parameter DFO Number Interp Points $\mathit{npt}=〈\mathit{\text{value}}〉$.
Constraint: $n_r+1\le \mathit{npt}\le \frac{\left(n_r+1\right)\times \left(n_r+2\right)}{2}$.
Use e04zmf to set compatible option values.

$\mathbf{ifail}=17$

Rescue failed: the trust region could not be reduced further after some function evaluation could not be provided. Check the specification of your objective and whether it needs rescaling. Try a different initial x.

Some initial interpolation points could not be provided. Rescue cannot be attempted at this stage.
Check the specification of your objective and whether it needs rescaling. Try a different initial x.

$\mathbf{ifail}=18$

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

$\mathbf{ifail}=19$

The solver failed at the model building phase and the maximum number of restarts was reached. Check the specification of your objective and whether it needs rescaling. Try a different initial x.

$\mathbf{ifail}=20$

User requested termination after a call to the objective function. inform was set to a value lower than $-1$ within the user-supplied function objfun.

User requested termination during a monitoring step. inform was set to a value lower than $0$ within the user-supplied function monit.

$\mathbf{ifail}=21$

Maximum number of function evaluations exceeded.

$\mathbf{ifail}=23$

The solver terminated after the maximum time allowed was exceeded.

Maximum number of seconds exceeded. Use optional parameter Time Limit to reset the limit.

$\mathbf{ifail}=24$

No progress, the solver was stopped after $〈\mathit{\text{value}}〉$ consecutive slow steps.
Use the optional parameter DFO Maximum Slow Steps to modify the maximum number of slow steps accepted.

The solver stopped after $5\times \mathbf{DFO\; Maximum\; Slow\; Steps}$ consecutive slow steps and a trust region above the tolerance set by DFO Trust Region Slow Tol.

$\mathbf{ifail}=50$

The problem was solved to an acceptable level after $〈\mathit{\text{value}}〉$ consecutive slow iterations.
Use the optional parameter DFO Maximum Slow Steps to modify the maximum number of slow steps accepted.

The solver stopped after DFO Maximum Slow Steps consecutive slow steps and a trust region below the tolerance set by DFO Trust Region Slow Tol.

$\mathbf{ifail}=54$

The problem seems to be unbounded.
The unboundedness detection heuristic can be turned off with the option DFNO Detect Unbounded.

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

9.1 Description of the Printed Output

--------------------------------------------------------
E04J(D|E)), Derivative-free solver for bound constrained
            nonlinear functions
--------------------------------------------------------

Problem statistics
  Number of variables                  2
  Number of unconstrained variables    1
  Number of fixed variables            0
  Total interpolation points           5

Stats Time                    =                  No     * d
Dfo Trust Region Tolerance    =         5.00000E-07     * U
Dfo Max Objective Calls       =                 500     * d
Dfo Starting Trust Region     =         1.00000E-01     * d

----------------------------------------
 step |    obj        rho    |    nf   |
----------------------------------------
    1 |  4.32E+00  1.00E-01  |     6   |
    2 |  4.18E+00  1.00E-02  |    12   |
    3 |  4.11E+00  1.00E-02  |    13   |
    4 |  3.85E+00  1.00E-02  |    14   |

Status: Converged, small trust region size

Value of the objective                    1.17772E-15
Number of objective function evaluations          205
Number of steps                                   116

Timings
      Total time spent in the solver            0.056
      Time spent in the objective evaluation    0.012

Primal variables:
  idx   Lower bound        Value      Upper bound
    1       -inf       1.00000E+00         inf
    2  -2.00000E+00    1.00000E+00         inf

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

11 Algorithmic Details

11.1 Derivative-free Trust Region Algorithm

11.2 Bounds on the Variables

11.3 Dealing with Noisy Problems

12 Optional Parameters

• Defaults
• DFNO Detect Unbounded
• DFNO Objective Limit
• DFO Maximum Slow Steps
• DFO Max Objective Calls
• DFO Max Soft Restarts
• DFO Max Unsucc Soft Restarts
• DFO Monitor Frequency
• DFO Noise Level
• DFO Noisy Problem
• DFO Number Interp Points
• DFO Number Soft Restarts Pts
• DFO Print Frequency
• DFO Random Seed
• DFO Starting Trust Region
• DFO Trust Region Slow Tol
• DFO Trust Region Tolerance
• Infinite Bound Size
• Monitoring File
• Monitoring Level
• Print File
• Print Level
• Print Options
• Print Solution
• Stats Time
• Task
• Time Limit

12.1 Description of the Optional Parameters

• the keywords, where the minimum abbreviation of each keyword is underlined;
• a parameter value, where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
• the default value, where the symbol $\epsilon$ is a generic notation for machine precision (see x02ajf).