naginterfaces.library.opt.handle_​solve_​dfno

naginterfaces.library.opt.handle_solve_dfno(handle, x, objfun=None, monit=None, data=None, io_manager=None)[source]

handle_solve_dfno is a forward communication Derivative-free Optimization (DFO) solver from the NAG optimization modelling suite (DFNO) for small to medium-scale nonlinear problems with bound constraints.

Note: this function uses optional algorithmic parameters, see also: handle_opt_set(), handle_opt_get().

For full information please refer to the NAG Library document for e04jd

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/e04/e04jdf.html

Parameters
handleHandle

The handle to the problem. It needs to be initialized (e.g., by handle_init()) and to hold a problem formulation compatible with handle_solve_dfno. It must not be changed between calls to the NAG optimization modelling suite.

xfloat, array-like, shape

, the initial estimates of the variables, .

objfunNone or callable (fx, inform) = objfun(x, inform, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

calculates the value of the objective function at a specified point .

If there is no nonlinear objective (e.g., handle_set_linobj() or handle_set_quadobj() was called to define a linear or quadratic objective function), will never be called by handle_solve_dfno and may be None.

Parameters
xfloat, ndarray, shape

, the vector of variable values at which the objective function is to be evaluated.

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
fxfloat

The value of the objective function at .

informint

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

The solver will attempt a rescue procedure and request an alternative point. If the rescue procedure fails, the solver will exit with = 17.

The solver will cleanly exit with = 20 and return the best available point as well as the solve statistics.

monitNone or callable monit(x, rinfo, stats, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

is provided to enable you to monitor the progress of the optimization.

It is invoked at the end of every th iteration where is given by the ‘DFO Monitor Frequency’ (the default is , is not called).

If no monitoring is required, may be None.

Parameters
xfloat, ndarray, shape

, the vector of decision variables at the current iteration.

rinfofloat, ndarray, shape

Error measures and various indicators at the end of the current iteration as described in the main argument .

statsfloat, ndarray, shape

Solver statistics at monitoring steps or at the end of the current iteration (the values are as described in the main argument ).

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns
xfloat, ndarray, shape

The final values of the variables, .

rinfofloat, ndarray, shape

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:

Objective function value .

, the current lower bound of the trust region.

, the current size of the trust region.

The number of interpolation points used by the solver.

Reserved for future use.

statsfloat, ndarray, shape

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

Number of calls to the objective function.

Total time spent in the solver (including time spent evaluating the objective).

Total time spent evaluating the objective function.

Number of steps.

Reserved for future use.

Other Parameters
‘Defaults’valueless

This special keyword may be used to reset all options to their default values. Any value given with this keyword will be ignored.

‘DFNO Detect Unbounded’str

Default

The solver can try to detect whether the problem is unbounded. This option allows you to turn on or off the unboundedness detection heuristic.

Constraint: or .

‘DFNO Objective Limit’float

Default

This option sets an additional convergence criterion. The solver will stop if it finds a point for which the function value is lower than this parameter.

‘DFO Maximum Slow Steps’int

Default

If , this argument defines the maximum number of consecutive slow iterations allowed. Set to deactivate the slow iteration detection. The algorithm can stop in two situations:

  1. and with = 50,

  2. with = 24.

Constraint: .

‘DFO Max Objective Calls’int

Default

A limit on the number of objective function evaluations the solver is allowed to compute. If the limit is reached, the solver stops with = 21.

Constraint: .

‘DFO Max Soft Restarts’int

Default

The maximum total number of soft restarts that can be performed if the objective function is declared as noisy ().

Constraint: .

‘DFO Max Unsucc Soft Restarts’int

Default

The maximum number of consecutive unsuccessful soft restarts that can be performed if the objective function is declared as noisy ().

Constraint: .

‘DFO Monitor Frequency’int

Default

If , will be called at the end of every th step for monitoring purposes.

Constraint: .

‘DFO Noise Level’float

Default

Indicates the noise level expected when evaluating the objective function if .

Constraint: .

‘DFO Noisy Problem’str

Default

Indicates if the function evaluations provided to the solver are noisy. If , some algorithmic features will be activated:

  1. The trust region update becomes slower to reflect the decreased confidence in the objective values.

  2. Soft restarts of the algorithm can be performed to ensure the algorithm did not get stuck because of the noise (see ‘DFO Max Soft Restarts’, ‘DFO Max Unsucc Soft Restarts’, ‘DFO Number Soft Restarts Pts’ to control the restart characteristics).

  3. In addition, if , the solver will trigger a soft restart if all the function values are within the noise level.

‘DFO Number Interp Points’int

Default

The maximum number of interpolation points in (9) used to build the linear models of the residuals. If , the number of points is chosen to be where is the number of non-fixed variables.

Constraint: .

Consistency constraint, the solver stops with = 6 if not met:

.

‘DFO Number Soft Restarts Pts’int

Default

The number of interpolation points that are replaced during a soft restart.

Constraint: .

‘DFO Print Frequency’int

Default

If , the solver prints the iteration log to the appropriate units at the end of every th step.

Constraint: .

‘DFO Random Seed’int

Default

The random seed used to generate the random points used to build the initial model. If , the random seed will be based on values taken from the real-time clock, potentially resulting in the solver taking a different path each time it is run. Set it to a positive value to get fully reproducible runs.

Constraint: .

‘DFO Starting Trust Region’float

Default

, the initial trust region radius. This argument should be set to 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 of length along each coordinate direction. The default value assumes that the variables have an order of magnitude .

Constraint: .

Consistency constraints, the solver stops with = 5 if not met:

.

.

‘DFO Trust Region Slow Tol’float

Default

The minimal acceptable trust region radius for the solution to be declared as acceptable. The solver stops if:

and .

Constraint: .

Consistency constraint, the solver stops with = 5 if not met:

.

‘DFO Trust Region Tolerance’float

Default

, the requested trust region radius. The algorithm declares convergence when the trust region radius reaches this limit. It should indicate the absolute accuracy that is required in the final values of the variables.

Constraint: .

Consistency constraints, the solver stops with = 5 if not met:

.

.

‘Infinite Bound Size’float

Default

This defines the ‘infinite’ bound in the definition of the problem constraints. Any upper bound greater than or equal to will be regarded as (and similarly any lower bound less than or equal to will be regarded as ). Note that a modification of this option does not influence constraints which have already been defined; only the constraints formulated after the change will be affected.

Constraint: .

‘Monitoring File’int

Default

If , the unit number for the secondary (monitoring) output. If , no secondary output is provided. The information output to this unit is controlled by ‘Monitoring Level’.

Constraint: .

‘Monitoring Level’int

Default

This argument sets the amount of information detail that will be printed by the solver to the secondary output. The meaning of the levels is the same as with ‘Print Level’.

Constraint: .

‘Print File’int

Default

If , the unit number for the primary output of the solver. If , the primary output is completely turned off independently of other settings. The default value is the advisory message unit number at the time of the options initialization, e.g., at the initialization of the handle. The information output to this unit is controlled by ‘Print Level’.

Constraint: .

‘Print Level’int

Default

This argument defines how detailed information should be printed by the solver to the primary and secondary output.

Output

No output from the solver.

The Header and Summary.

, , ,

Additionally, the Iteration log.

Constraint: .

‘Print Options’str

Default

If , a listing of options will be printed to the primary output and is always printed to the secondary output.

Constraint: or .

‘Print Solution’str

Default

If , the solution will be printed to the primary and secondary output.

Constraint: or .

‘Task’str

Default

This argument specifies the required direction of the optimization. If , the objective function (if set) is ignored and the algorithm stops as soon as a feasible point is found with respect to the given tolerance.

Constraint: , or .

‘Stats Time’str

Default

This argument turns on timings of various parts of the algorithm to give a better overview of where most of the time is spent. This might be helpful for a choice of different solving approaches. It is possible to choose between CPU and wall clock time. Choice ‘YES’ is equivalent to ‘WALL CLOCK’.

Constraint: , , or .

‘Time Limit’float

Default

A limit to the number of seconds that the solver can use to solve one problem. If during the convergence check this limit is exceeded, the solver will terminate with = 23.

Constraint: .

Raises
NagValueError
(errno )

has not been initialized.

(errno )

does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.

(errno )

has not been initialized properly or is corrupted.

(errno )

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

(errno )

The problem is already being solved.

(errno )

On entry, , expected .

Constraint: must match the current number of variables of the model in the .

(errno )

Inconsistent options ‘DFO Trust Region Tolerance’ and ‘DFO Starting Trust Region’ .

Constraint: .

Use handle_opt_set() to set compatible option values.

(errno )

Inconsistent options ‘DFO Trust Region Tolerance’ and ‘DFO Trust Region Slow Tol’ .

Constraint: .

Use handle_opt_set() to set compatible option values.

(errno )

Option ‘DFO Starting Trust Region’ , , and .

Constraint: if in coordinate , then .

Use handle_opt_set() to set compatible option values.

(errno )

There were unequal bounds and the option ‘DFO Number Interp Points’ .

Constraint: .

Use handle_opt_set() to set compatible option values.

(errno )

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.

(errno )

Please provide a proper function.

Warns
NagAlgorithmicWarning
(errno )

The problem was solved to an acceptable level after consecutive slow iterations.

Use the option ‘DFO Maximum Slow Steps’ to modify the maximum number of slow steps accepted.

NagAlgorithmicMajorWarning
(errno )

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 .

(errno )

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 .

(errno )

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 .

(errno )

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 .

(errno )

User requested termination after a call to the objective function.

(errno )

Maximum number of function evaluations exceeded.

(errno )

The solver terminated after the maximum time allowed was exceeded.

(errno )

No progress, the solver was stopped after consecutive slow steps.

Use the option ‘DFO Maximum Slow Steps’ to modify the maximum number of slow steps accepted.

(errno )

The problem seems to be unbounded.

The unboundedness detection heuristic can be turned off with the option ‘DFNO Detect Unbounded’.

NagCallbackTerminateWarning
(errno )

User requested termination during a monitoring step.

Notes

handle_solve_dfno is aimed at minimizing a nonlinear objective function subject to bound constraints:

Here is a smooth nonlinear function and and are -dimensional vectors defining bounds on the variables.

handle_solve_dfno serves as a solver for compatible problems stored as a handle. The handle points to an internal data structure which defines the problem and serves as a means of communication for functions in the NAG optimization modelling suite. To define a compatible problem handle, you must call handle_init() followed by handle_set_nlnobj() to initialize it and optionally call handle_set_simplebounds() to define bounds on the variables. If handle_set_simplebounds() is not called, all the variables will be considered free by the solver. It should be noted that handle_solve_dfno always assumes that the gradient of the objective is dense, therefore, defining a sparse structure for the residuals in the call to handle_set_nlnobj() will have no effect. See the E04 Introduction for more details about the NAG optimization modelling suite.

The solver allows fixing variables with the definition of the bounds. However, the following constraint must be met in order to be able to call the solver:

for all non-fixed variable , the value of must be at least twice the starting trust region radius (see the consistency constraint of the option ‘DFO Starting Trust Region’).

The solver is based on a derivative-free trust region framework. This type of method is well suited for small to medium-scale problems (around 100 variables) for which the derivatives are unavailable or not easy to compute, and/or for which the function evaluations are expensive or noisy. For a detailed description of the algorithm see Algorithmic Details.

The algorithm behaviour and solver strategy can be modified by various options (see Other Parameters) which can be set by handle_opt_set() and handle_opt_set_file() at any time between the initialization of the handle by handle_init() and a call to the solver. The options’ names specific for this solver start either with the prefix DFO (Derivative-free Optimization) or DFNO (Derivative-free Nonlinear Optimization). The default values for these options are chosen to work well in the general case, but it is recommended you tune them to your particular problem. In particular, if the objective function is known to be noisy, it is highly recommended to set the option ‘DFO Noisy Problem’ to ‘YES’. Once the solver has finished, options may be modified for the next solve. The solver may be called repeatedly with various starting points and/or options.

The underlying algorithm implemented for handle_solve_dfno is the same as the one used by handle_solve_dfno_rcomm(). handle_solve_dfno serves as a forward communication interface to the derivative-free solver for nonlinear objective functions.

References

Cartis, C, Fiala, J, Marteau, B and Roberts, L, 2018, Improving the Flexibility and Robustness of Model-Based Derivative-Free Optimization Solvers, Technical Report, University of Oxford

Conn, A R, Scheinberg, K and Vicente, L N, 2009, Introduction to Derivative-Free Optimization, vol. 8 of MPS-SIAM Series on Optimization, MPS/SIAM, Philadelphia

Powell, M J D, 2009, The BOBYQA algorithm for bound constrained optimization without derivatives, Report DAMTP 2009/NA06, University of Cambridge, https://www.damtp.cam.ac.uk/user/na/NA_papers/NA2009_06.pdf