NAG C Library Function Document

nag_opt_handle_solve_dfls (e04ffc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{handle}$ – void *Input

On entry: the handle to the problem. It needs to be initialized by nag_opt_handle_init (e04rac) and the objective must be declared as nonlinear least squares by a call to the function nag_opt_handle_set_nlnls (e04rmc). The function nag_opt_handle_set_simplebounds (e04rhc) can optionally be called to define box bounds. It must not be changed between calls to the NAG optimization modelling suite.

2:    $\mathbf{objfun}$ – function, supplied by the userExternal Function

objfun must evaluate the value of the nonlinear residuals $r_i\left(x\right)$ at a specified point $x$.

The specification of objfun is:

void  objfun (Integer nvar, const double x[], Integer nres, double rx[], Integer *inform, Nag_Comm *comm)

1:    $\mathbf{nvar}$ – IntegerInput

On entry: $n$, the number of variables in the problem, as set during the initialization of the handle by nag_opt_handle_init (e04rac).

2:    $\mathbf{x}\left[\mathbf{nvar}\right]$ – const doubleInput

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 nag_opt_handle_set_nlnls (e04rmc).

4:    $\mathbf{rx}\left[\mathbf{nres}\right]$ – doubleOutput

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

5:    $\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 value of rx will be discarded and the solver will terminate immediately with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_USER_STOP otherwise, the solver will proceed normally.

6:    $\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 nag_opt_handle_solve_dfls (e04ffc) you may allocate memory and initialize these pointers with various quantities for use by objfun when called from nag_opt_handle_solve_dfls (e04ffc) (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).

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

3:    $\mathbf{mon}$ – function, supplied by the userExternal Function

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

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

The specification of mon is:

void  mon (Integer nvar, const double x[], Integer *inform, const double rinfo[], const double stats[], Nag_Comm *comm)

1:    $\mathbf{nvar}$ – IntegerInput

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

2:    $\mathbf{x}\left[\mathbf{nvar}\right]$ – const doubleInput

On entry: the current best point.

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 value of rx will be discarded and the solver will terminate immediately with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_USER_STOP otherwise, the solver will proceed normally.

4:    $\mathbf{rinfo}\left[100\right]$ – const doubleInput

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]$ – const doubleInput

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

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

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

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_opt_handle_solve_dfls (e04ffc) you may allocate memory and initialize these pointers with various quantities for use by mon when called from nag_opt_handle_solve_dfls (e04ffc) (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).

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 nag_opt_handle_init (e04rac).

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

5:    $\mathbf{x}\left[\mathbf{nvar}\right]$ – doubleInput/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 nag_opt_handle_set_nlnls (e04rmc).

7:    $\mathbf{rx}\left[\mathbf{nres}\right]$ – doubleOutput

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

8:    $\mathbf{rinfo}\left[100\right]$ – doubleOutput

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

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

9:    $\mathbf{stats}\left[100\right]$ – doubleOutput

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

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

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

The NAG communication argument (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).

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

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_BOUND

Optional argument $\mathbf{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 nag_opt_handle_opt_set (e04zmc) to set compatible option values.

NE_HANDLE

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 nag_opt_handle_init (e04rac) or it has been corrupted.

NE_INT

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 $\mathbf{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 nag_opt_handle_opt_set (e04zmc) to set compatible option values.

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 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_NO_IMPROVEMENT

No progress, the solver was stopped after $〈\mathit{\text{value}}〉$ consecutive slow steps.
Use the optional argument $\mathbf{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 $\mathbf{DFLS\; Trust\; Region\; Slow\; Tol}$.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

NE_PHASE

The problem is already being solved.

NE_REAL_2

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

Inconsistent optional arguments $\mathbf{DFLS\; Trust\; Region\; Tolerance}$ ${\rho }_{\mathrm{end}}$ and $\mathbf{DFLS\; Starting\; Trust\; Region}$ ${\rho }_{\mathrm{beg}}$.
Constraint: ${\rho }_{\mathrm{end}}<{\rho }_{\mathrm{beg}}$.
Use nag_opt_handle_opt_set (e04zmc) to set compatible option values.

NE_REF_MATCH

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

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 progress could be made. Check your specification of objfun and whether the function needs rescaling. Try a different initial x.

NE_SETUP_ERROR

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

NE_TIME_LIMIT

The solver terminated after the maximum time allowed was exceeded.

Maximum number of seconds exceeded. Use option $\mathbf{Time\; Limit}$ to reset the limit.

NE_TOO_MANY_ITER

Maximum number of function evaluations exceeded.

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

NW_NOT_CONVERGED

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

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

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 (e04ffce.c)

10.2

Program Data

10.3

Program Results

Program Results (e04ffce.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 nag_machine_precision (X02AJC)).