NAG Library Routine Document

e04fff (handle_solve_dfls)

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 e04rmf. 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 must evaluate the value of the nonlinear residuals $r_i\left(x\right)$ at a specified point $x$.

The specification of objfun is:

Fortran Interface

Subroutine objfun ( nvar, x, nres, rx, inform, iuser, ruser, cpuser) Integer, Intent (In) :: nvar, nres 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) :: rx(nres) Type (c_ptr), Intent (In) :: cpuser

C Header Interface

#include <nagmk26.h> void  objfun (const Integer *nvar, const double x[], const Integer *nres, double rx[], Integer *inform, Integer iuser[], double ruser[], void **cpuser)

1:     $\mathbf{nvar}$ – IntegerInput

On entry: $n$, the number of variables in the problem, as set during the initialization of the handle by e04raf.

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

On entry: $x$, the vector of variable values at which the residuals $r_i$ are to be evaluated.

3:     $\mathbf{nres}$ – IntegerInput

On entry: $m_r$, the number of residuals in the problem, as set during the initialization of the handle by e04rmf.

4:     $\mathbf{rx}\left(\mathbf{nres}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the value of the residuals $r_i\left(x\right)$ at $x$.

5:     $\mathbf{inform}$ – IntegerInput/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 value of rx will be discarded and the solver will terminate immediately with $\mathbf{ifail}=\mathbf{20}$ otherwise, the solver will proceed normally.

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

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

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

objfun is called with the arguments iuser, ruser and cpuser as supplied to e04fff. 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 e04fff 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 e04fff. If your code inadvertently does return any NaNs or infinities, e04fff is likely to produce unexpected results.

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

mon is provided to enable you to monitor the progress of the optimization and, if necessary, to halt the optimization process using argument inform.

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

mon is called at the end of every $i^{\mathrm{th}}$ step where $i$ is controlled by the optional parameter DFLS Monitor Frequency (default value $0$, mon is never called).

The specification of mon is:

Fortran Interface

Subroutine mon ( 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

#include <nagmk26.h> void  mon (const Integer *nvar, const double x[], Integer *inform, const double rinfo[], const double stats[], Integer iuser[], double ruser[], void **cpuser)

1:     $\mathbf{nvar}$ – IntegerInput

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

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

On entry: the current best point.

3:     $\mathbf{inform}$ – IntegerInput/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 value of rx will be discarded and 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) arrayInput

On entry: best objective value computed and various indicators (the values are as described in the main argument rinfo).

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

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

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

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

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

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

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

4:     $\mathbf{nvar}$ – IntegerInput

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

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

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

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

6:     $\mathbf{nres}$ – IntegerInput

On entry: $m_r$, the number of residuals in the problem. It must be unchanged from the value set during the definition of the objective structure by e04rmf.

7:     $\mathbf{rx}\left(\mathbf{nres}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the values of the residuals at the final point given in x.

8:     $\mathbf{rinfo}\left(100\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: optimal objective value and various indicators at the end of the final iteration as given in the table below:

$1$	objective function value $f\left(x\right)$ (sum of the squared residuals);
$2$	$\rho$, the size of trust region at the end of the algorithm;
$3$	the number of interpolation points used by the solver.
$4-100$	reserved for future use.

9:     $\mathbf{stats}\left(100\right)$ – Real (Kind=nag_wp) arrayOutput

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

$1$	number of calls to the objective function;
$2$	if Stats Time is activated, total time spent in the solver (including time spent evaluating the objective);
$3$	if Stats Time is activated, total time spent evaluating the objective function;
$4$	number of steps.
$5-100$	reserved for future use.

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

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

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

iuser, ruser and cpuser are not used by e04fff, but are passed directly to objfun and mon 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.

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

The solver does not support the model defined in the handle.
It supports only nonlinear least squares problems with bound constraints.

$\mathbf{ifail}=4$

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

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 arguments DFLS Trust Region Tolerance ${\rho }_{\mathrm{end}}$ and DFLS Starting Trust Region ${\rho }_{\mathrm{beg}}$.
Constraint: ${\rho }_{\mathrm{end}}<{\rho }_{\mathrm{beg}}$.
Use e04zmf to set compatible option values.

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

Optional argument DFLS 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$

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

There were $n_r=〈\mathit{\text{value}}〉$ unequal bounds and the optional argument DFLS Number Interp Points $\mathit{npt}=〈\mathit{\text{value}}〉$
Constraint: $n_r+2\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}=18$

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}=19$

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 progress could be made. Check your specification of objfun and whether the function 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 negative value within the user-supplied function objfun.

User requested termination during a monitoring step. inform was set to a negative value within the user-supplied function mon

$\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 option 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 argument DFLS Maximum Slow Steps to modify the maximum number of slow steps accepted.

The solver stopped after $5\times \mathbf{DFLS\; Maximum\; Slow\; Steps}$ consecutive slow steps and a trust region above the tolerance set by DFLS 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 argument DFLS Maximum Slow Steps to modify the maximum number of slow steps accepted.

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

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

9.1

Description of the Printed Output

  ----------------------------------------------
  E04FF, Derivative-free solver for data fitting
         (nonlinear least squares problems)
  ----------------------------------------------
  Problem statistics
    Number of variables                 10
    Number of unconstrained variables   10
    Number of fixed variables            0
    Number of residuals                 10

     Stats Time                    =                 Yes     * U
     Dfls Trust Region Tolerance   =         1.00000E-07     * U
     Dfls Max Objective Calls      =                 500     * d
     Dfls Starting Trust Region    =         1.10000E-01     * U
     Dfls Number Interp Points     =                   0     * d

  ----------------------------------------
   step |    obj       rho     |    nf   |
  ----------------------------------------
      1 |  3.82E+01  1.10E-01  |    13   |
      2 |  3.55E+01  1.10E-01  |    14   |
      3 |  3.05E+01  1.10E-01  |    15   |
      4 |  2.15E+01  1.10E-01  |    18   |

  Status: Converged, small trust region size.
 
  Value of the objective                    2.23746E-06
  Number of objective function evaluations          107
  Number of steps                                    51

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

  Computed Solution:
    idx   Lower bound        Value      Upper bound
      1       -inf       -1.00000E+00        inf
      2       -inf       -1.00000E+00        inf
      3       -inf       -1.00000E+00        inf
      4       -inf       -1.00000E+00        inf

10

Example

10.1

Program Text

Program Text (e04fffe.f90)

10.2

Program Data

10.3

Program Results

Program Results (e04fffe.r)

11

Algorithmic Details

11.1

Derivative-free trust region algorithm

11.2

Bounds on the variables

11.3

Adaptation to nonlinear least squares problems

12

Optional Parameters

• Defaults
• DFLS Maximum Slow Steps
• DFLS Max Objective Calls
• DFLS Monitor Frequency
• DFLS Number Interp Points
• DFLS Print Frequency
• DFLS Small Residuals Tol
• DFLS Starting Trust Region
• DFLS Trust Region Slow Tol
• DFLS Trust Region Tolerance
• DFLS Trust Region Update
• Infinite Bound Size
• Monitoring File
• Monitoring Level
• Print File
• Print Level
• Print Options
• Print Solution
• Stats Time
• 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).