naginterfaces.library.glopt.handle_solve_mcs¶
- naginterfaces.library.glopt.handle_solve_mcs(handle, objfun=None, monit=None, data=None, io_manager=None)[source]¶
handle_solve_mcs
is designed to find the global minimum or maximum of an arbitrary function, subject to simple bound-constraints using a multi-level coordinate search method. Derivatives are not required, but convergence is only guaranteed if the objective function is continuous in a neighbourhood of a global optimum. It is not intended for large problems.Note: this function uses optional algorithmic parameters, see also:
opt.handle_opt_set
,opt.handle_opt_get
.For full information please refer to the NAG Library document for e05kb
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/e05/e05kbf.html
- Parameters
- handleHandle
The handle to the problem. It needs to be initialized (e.g., by
opt.handle_init
) and to hold a problem formulation compatible withhandle_solve_mcs
. It must not be changed between calls to the NAG optimization modelling suite.- 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.
must calculate the value of the nonlinear objective function at a specified point .
If there is no nonlinear objective (e.g.,
opt.handle_set_linobj
oropt.handle_set_quadobj
was called to define a linear or quadratic objective function), will never be called byhandle_solve_mcs
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 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 and, optionally, to terminate the solver early if necessary.
It is invoked at the end of every th step where is given by the ‘MCS Monitor Frequency’ (the default is , is not called).
A step is complete when the procedure in which a sub-box is considered for splitting finishes correctly.
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 .
- statsfloat, ndarray, shape
Solver statistics at the end of the current iteration as described in .
- 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
Error measures and various indicators at the end of the final iteration as given in the table below:
Objective function value .
Number of sweeps.
–
Reserved for future use.
- statsfloat, ndarray, shape
Solver statistics 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 sub-boxes.
Number of splits.
Cumulative number of splits by initialization list.
The current lowest level containing no split boxes.
–
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.
- ‘MCS Initialization Method’str
Default
The solver provides several methods to produce the initial set of sub-boxes. When , , or ,
handle_solve_mcs
will generate the sub-boxes internally. Please refer to Initialization and Sweeps for more details about the differences between the automatic methods.It is also possible to create a custom initialization list by setting . Creating a Custom Initialization List describes how to provide the custom initialization list to the solver.
Constraint: , , , or
- ‘MCS Max Objective Calls’int
Default
This puts an approximate limit on the number of function calls allowed. The total number of calls made is checked at the top of an internal iteration loop, so it is possible that a few calls more than ‘MCS Max Objective Calls’ may be made.
Constraint:
- ‘MCS Monitor Frequency’int
Default
This argument specifies the frequency on which to call the monitor function . If zero, the monitor function will not be called.
Constraint: .
- ‘MCS Print Frequency’int
Default
This argument specifies the frequency with which to print information regarding each sweep to ‘Print File’ and/or ‘Monitoring File’. By default, it will print information of every sweep.
Constraint: .
- ‘MCS Local Searches’str
Default
If you want to try to accelerate convergence of
handle_solve_mcs
by starting local searches from candidate minima, you will require ‘MCS Local Searches’ to be ‘ON’.Constraint: or
- ‘MCS Local Searches Limit’int
Default
This defines the maximal number of iterations to be used in the trust region loop of the local-search procedure.
Constraint:
- ‘MCS Local Searches Tolerance’float
Default
The value of ‘MCS Local Searches Tolerance’ is the multiplier used during local searches as a stopping criterion for when the approximated gradient is small, in the sense described in Local Search.
Constraint:
- ‘MCS Repeatability’str
Default
For use with random initialization lists (). When set to ‘ON’, The initialization list will be consistent for every call of
handle_solve_mcs
.Constraint: or
- ‘MCS Splits Limit’int
Default
Along with the initialization list, this defines a limit on the number of times the root box will be split along any single coordinate direction. If ‘MCS Local Searches’ is ‘OFF’ you may find the default value to be too small.
Constraint:
- ‘MCS Static Limit’int
Default
As the default termination criterion, computation stops when the best function value is static for ‘MCS Static Limit’ sweeps through levels. This argument is ignored if you have specified a target value to reach in ‘MCS Target Objective Value’.
Constraint:
- ‘MCS Target Objective Error’float
Default
If you have given a target objective value to reach in ‘MCS Target Objective Value’, this option sets your desired relative error between F(x) and ‘MCS Target Objective Value’, as described in Accuracy. See also the description of the option ‘MCS Target Objective Safeguard’.
Constraint:
- ‘MCS Target Objective Safeguard’float
Default
If you have given a target objective value to reach in ‘MCS Target Objective Value’ (the value of the option ‘MCS Target Objective Value’), this option sets your desired safeguarded termination tolerance, for when ‘MCS Target Objective Value’ is close to zero.
Constraint:
- ‘MCS Target Objective Value’float
This argument may be set if you wish
handle_solve_mcs
to use a specific value as the target function value to reach during the optimization. Setting ‘MCS Target Objective Value’ overrides the default termination criterion determined by the option ‘MCS Target Objective Value’.- ‘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 .
- ‘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 .
- ‘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 .
- 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 )
A finite initialization list could not be computed internally. Consider reformulating the bounds on the problem, try providing your own initialization list, use the randomization option () or vary the value of ‘Infinite Bound Size’.
- (errno )
The user-supplied initialization list contained infinite values, as determined by the option ‘Infinite Bound Size’.
- (errno )
On entry, , expected .
Constraint: must match the current number of variables of the model in the .
- (errno )
On entry, user-supplied , .
Constraint: if is not fixed then , for .
- (errno )
On entry, user-supplied , and .
Constraint: if is not fixed then , for .
- (errno )
On entry, user-supplied , , , and .
Constraint: if is not fixed then , for , for .
- (errno )
On entry, user-supplied , , , and .
Constraint: if is not fixed then , for , for .
- (errno )
On entry, user-supplied , .
Constraint: if is not fixed then , for .
- (errno )
On entry, user-supplied , and .
Constraint: if is not fixed then , for .
- (errno )
On entry, user-supplied section contained distinct elements, and : , , .
- (errno )
On entry, user-supplied section was not in ascending order: , .
- (errno )
The dimension of the array ‘MCS List’ is not a multiple of .
- (errno )
There were variables and the option ‘MCS Splits Limit’ .
Constraint: .
Use
opt.handle_opt_set
to set compatible option values.- (errno )
Please provide a proper function.
- (errno )
An error occurred during linesearching. It is likely that your objective function is badly scaled: try rescaling it. Also, try relaxing the bounds or use a different initialization method. If the problem persists, please contact NAG quoting error code .
- (errno )
An error occurred during initialization. It is likely that points from the initialization list are very close together. Try relaxing the bounds on the variables or use a different initialization method.
- (errno )
The optional parameter ‘MCS Initialization Method’ was set to CUSTOM but one of the arrays , or was not passed correctly to the handle.
- Warns
- NagAlgorithmicWarning
- (errno )
The function evaluations limit was exceeded.
Approximately ‘MCS Max Objective Calls’ function calls have been made without your chosen termination criterion being satisfied.
- (errno )
The division procedure completed but your target value could not be reached.
Despite every sub-box being processed ‘MCS Splits Limit’ times, the target value you provided in ‘MCS Target Objective Value’ could not be found to the tolerances given in ‘MCS Target Objective Error’ and ‘MCS Target Objective Safeguard’. You could try reducing ‘MCS Splits Limit’ or the objective tolerances.
- NagCallbackTerminateWarning
- (errno )
User-supplied monitoring function requested termination.
- (errno )
User-supplied objective function requested termination.
- Notes
handle_solve_mcs
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_mcs
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 callopt.handle_init
to initialize it followed, optionally, byopt.handle_set_nlnobj
,opt.handle_set_linobj
oropt.handle_set_quadobj
to define the objective function andopt.handle_set_simplebounds
to define bounds on the variables. Ifopt.handle_set_simplebounds
is not called, all the variables will be considered free by the solver. It should be noted thathandle_solve_mcs
always assumes that the gradient of the objective is dense, therefore, defining a sparse structure for the residuals in the call toopt.handle_set_nlnobj
will have no effect. Additionally, the multi-level coordinate search method used by this solver relies on dividing the feasible space in ‘boxes’ (see Algorithmic Details for a more thorough explanation) so it is advisable to define reasonable bounds for the variables usingopt.handle_set_simplebounds
. See the E04 Introduction for more details about the NAG optimization modelling suite.The algorithm behaviour and solver strategy can be modified by various options (see Other Parameters) which can be set by
opt.handle_opt_set
andopt.handle_opt_set_file
at any time between the initialization of the handle byopt.handle_init
and a call to the solver. The options’ names specific for this solver start with the prefix MCS (Multi-level Coordinate Search). The default values for these options are chosen to work well in the general case, but it is recommended that you tune them to your particular problem. In particular, if the objective function is known to be numerically difficult, it could be desirable to define a customized initialization list for the algorithm with the option ‘MCS Initialization Method’. For more details on how to create a custom initialization list, please refer to Creating a Custom Initialization List. Once the solver has finished, options may be modified for the next solve. The solver may be called repeatedly with various initialization lists and/or options.The method used by
handle_solve_mcs
is based on MCS, the Multi-level Coordinate Search method described in Huyer and Neumaier (1999), and the algorithm it uses is described in detail in Algorithmic Details.
- References
Huyer, W and Neumaier, A, 1999, Global optimization by multi-level coordinate search, Journal of Global Optimization (14), 331–355