naginterfaces.library.glopt.bnd_mcs_solve¶
- naginterfaces.library.glopt.bnd_mcs_solve(objfun, ibound, bl, bu, comm, iinit=0, sdlist=3, inlist=None, numpts=None, initpt=None, monit=None, data=None, io_manager=None)[source]¶
bnd_mcs_solve
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.The initialization function
bnd_mcs_init()
must have been called before callingbnd_mcs_solve
.Note: this function uses optional algorithmic parameters, see also:
bnd_mcs_init()
,bnd_mcs_optset_file()
,bnd_mcs_optset_string()
,bnd_mcs_optset_char()
,bnd_mcs_optset_int()
,bnd_mcs_optset_real()
,bnd_mcs_option_check()
,bnd_mcs_optget_char()
,bnd_mcs_optget_int()
,bnd_mcs_optget_real()
.Deprecated since version 28.3.0.0:
bnd_mcs_solve
is deprecated. Please usehandle_solve_mcs()
instead. See also the Replacement Calls document.For full information please refer to the NAG Library document for e05jb
https://www.nag.com/numeric/nl/nagdoc_29/flhtml/e05/e05jbf.html
- Parameters
- objfuncallable f = objfun(x, nstate, data=None)
must evaluate the objective function for a specified -vector .
- Parameters
- xfloat, ndarray, shape
, the vector at which the objective function is to be evaluated.
- nstateint
If then
bnd_mcs_solve
is calling for the first time. This argument setting allows you to save computation time if certain data must be read or calculated only once.- dataarbitrary, optional, modifiable in place
User-communication data for callback functions.
- Returns
- ffloat
Must be set to the value of the objective function at .
- iboundint
Indicates whether the facility for dealing with bounds of special forms is to be used. must be set to one of the following values.
You will supply and individually.
There are no bounds on .
There are semi-infinite bounds .
There are constant bounds and .
Note that it only makes sense to fix any components of when .
- blfloat, array-like, shape
is , the array of lower bounds.
- bufloat, array-like, shape
is , the array of upper bounds.
- commdict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to
bnd_mcs_init()
.- iinitint, optional
Selects which initialization method to use.
Simple initialization (boundary and midpoint), with
, and
, , ,
for .
Simple initialization (off-boundary and midpoint), with
, and
, , ,
for .
Initialization using linesearches.
You are providing your own initialization list.
Generate a random initialization list.
For more information on methods , or see Initialization and Sweeps.
If ‘infinite’ values (as determined by the value of the option ‘Infinite Bound Size’) are detected by
bnd_mcs_solve
when you are using a simple initialization method ( or ), a safeguarded initialization procedure will be attempted, to avoid overflow.- sdlistint, optional
When , this argument is used to determine the maximal number of random initialization points to use in any given dimension. Otherwise a value is inferred internally.
- inlistNone or float, array-like, shape , optional
This argument need not be set on entry if you wish to use one of the preset initialization methods ().
is the ‘initialization list’: whenever a sub-box in the algorithm is split for the first time (either during the initialization procedure or later), for each non-fixed coordinate the split is done at the values , as well as at some adaptively chosen intermediate points.
The array sections , for , must be in ascending order with each entry being distinct.
In this context, ‘distinct’ should be taken to mean relative to the safe-range parameter (see
machine.real_safe
).- numptsNone or int, array-like, shape , optional
This argument need not be set on entry if you wish to use one of the preset initialization methods ().
encodes the number of splitting points in each non-fixed dimension.
- initptNone or int, array-like, shape , optional
This argument need not be set on entry if you wish to use one of the preset initialization methods ().
You must designate a point stored in that you wish
bnd_mcs_solve
to consider as an ‘initial point’ for the purposes of the splitting procedure.Call this initial point .
The coordinates of correspond to a set of indices , for , such that is stored in , for .
You must set , for .
- monitNone or callable monit(ncall, xbest, icount, inlist, numpts, initpt, xbaskt, boxl, boxu, nstate, data=None), optional
Note: if this argument is None then a NAG-supplied facility will be used.
may be used to monitor the optimization process.
It is invoked upon every successful completion of the procedure in which a sub-box is considered for splitting.
It will also be called just before
bnd_mcs_solve
exits if that splitting procedure was not successful.If no monitoring is required, may be None.
- Parameters
- ncallint
The cumulative number of calls to .
- xbestfloat, ndarray, shape
The current best point.
- icountint, ndarray, shape
An array of counters.
, the current number of sub-boxes.
, the cumulative number of calls to made in local searches.
, the cumulative number of points used as start points for local searches.
, the cumulative number of sweeps through levels.
, the cumulative number of splits by initialization list.
, the current lowest level containing non-split boxes.
- inlistfloat, ndarray, shape
The initialization list.
- numptsint, ndarray, shape
The number of points in each coordinate at which to split according to the initialization list .
- initptint, ndarray, shape
A pointer to the ‘initial point’ in . Element is the column index in of the th coordinate of the initial point.
- xbasktfloat, ndarray, shape
Note: the th candidate minimum has its th coordinate stored in , for , for .
The ‘shopping basket’ of candidate minima.
- boxlfloat, ndarray, shape
The array of lower bounds of the current search box.
- boxufloat, ndarray, shape
The array of upper bounds of the current search box.
- nstateint
Is set by
bnd_mcs_solve
to indicate at what stage of the minimization was called.This is the first time that has been called.
This is the last time will be called.
This is the first and last time will be called.
- 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
- blfloat, ndarray, shape
is , the array of lower bounds.
- bufloat, ndarray, shape
is , the array of upper bounds.
- inlistfloat, ndarray, shape
Unless = 1, 2 or
NagMemoryError
on exit, the actual initialization data used bybnd_mcs_solve
. If you wish to monitor the contents of you are advised to do so solely through , not through the output value here.- numptsint, ndarray, shape
Unless = 1, 2 or
NagMemoryError
on exit, the actual initialization data used bybnd_mcs_solve
.- initptint, ndarray, shape
Unless = 1, 2 or
NagMemoryError
on exit, the actual initialization data used bybnd_mcs_solve
.- xfloat, ndarray, shape
If no exception or warning is raised, contains an estimate of the global optimum (see also Accuracy).
- objfloat
If no exception or warning is raised, contains the function value at .
If you request early termination of
bnd_mcs_solve
in or , there is no guarantee that the function value at equals .
- Other Parameters
- ‘Defaults’valueless
This special keyword is used to reset all options to their default values, and any random state stored in the array will be destroyed.
Any option value given with this keyword will be ignored. This option cannot be queried or got.
- ‘Function Evaluations Limit’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 may be made.
- ‘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 ).
- ‘Local Searches’str
Default
If you want to try to accelerate convergence of
bnd_mcs_solve
by starting local searches from candidate minima, you will require to be ‘ON’.- ‘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.
- ‘Local Searches Tolerance’float
Default
The value of 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.
- ‘Minimize’valueless
Default
These keywords specify the required direction of optimization. Any option value given with these keywords will be ignored.
- ‘Maximize’valueless
These keywords specify the required direction of optimization. Any option value given with these keywords will be ignored.
- ‘Nolist’valueless
Default
Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.
- ‘List’valueless
Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.
- ‘Repeatability’str
Default
For use with random initialization lists (). When set to ‘ON’, an internally-initialized random state is stored in the array for use in subsequent calls to
bnd_mcs_solve
.- ‘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 ‘Local Searches’ is ‘OFF’ you may find the default value to be too small.
- ‘Static Limit’int
Default
As the default termination criterion, computation stops when the best function value is static for sweeps through levels. This argument is ignored if you have specified a target value to reach in ‘Target Objective Value’.
- ‘Target Objective Error’float
Default
If you have given a target objective value to reach in (the value of the option ‘Target Objective Value’), sets your desired relative error (from above if ‘Minimize’ is set, from below if ‘Maximize’ is set) between and , as described in Accuracy. See also the description of the option ‘Target Objective Safeguard’.
- ‘Target Objective Safeguard’float
Default
If you have given a target objective value to reach in (the value of the option ‘Target Objective Value’), sets your desired safeguarded termination tolerance, for when is close to zero.
- ‘Target Objective Value’float
This argument may be set if you wish
bnd_mcs_solve
to use a specific value as the target function value to reach during the optimization. Setting overrides the default termination criterion determined by the option ‘Static Limit’.
- Raises
- NagValueError
- (errno )
Initialization function
bnd_mcs_init()
has not been called.- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: , , or .
- (errno )
On entry, or and , and .
Constraint: if then , for ; if then .
- (errno )
On entry, and .
Constraint: if then .
- (errno )
On entry, .
Constraint: , , , or .
- (errno )
On entry, and .
Constraint: if then .
- (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 , .
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 , , , 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 section was not in ascending order: , .
- (errno )
The number of non-fixed variables .
Constraint: .
- (errno )
A value of ‘Splits Limit’ () smaller than was set: , .
- (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 )
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.
- Warns
- NagAlgorithmicWarning
- (errno )
The division procedure completed but your target value could not be reached.
Despite every sub-box being processed ‘Splits Limit’ times, the target value you provided in ‘Target Objective Value’ could not be found to the tolerances given in ‘Target Objective Error’ and ‘Target Objective Safeguard’. You could try reducing ‘Splits Limit’ or the objective tolerances.
- (errno )
The function evaluations limit was exceeded.
Approximately ‘Function Evaluations Limit’ function calls have been made without your chosen termination criterion being satisfied.
- NagCallbackTerminateWarning
- (errno )
User-supplied monitoring function requested termination.
- (errno )
User-supplied objective function requested termination.
- Notes
bnd_mcs_solve
is designed to solve modestly sized global optimization problems having simple bound-constraints only; it finds the global optimum of a nonlinear function subject to a set of bound constraints on the variables. Without loss of generality, the problem is assumed to be stated in the following form:where (the objective function) is a nonlinear scalar function (assumed to be continuous in a neighbourhood of a global minimum), and the bound vectors are elements of , where denotes the extended reals . Relational operators between vectors are interpreted elementwise.
The option ‘Maximize’ should be set if you wish to solve maximization, rather than minimization, problems.
If certain bounds are not present, the associated elements of or can be set to special values that will be treated as or . See the description of the option ‘Infinite Bound Size’. Phrases in this document containing terms like ‘unbounded values’ should be understood to be taken relative to this option.
Fixing variables (that is, setting for some ) is allowed in
bnd_mcs_solve
.The initialization function
bnd_mcs_init()
does not need to be called before each invocation ofbnd_mcs_solve
. You should be aware that a call to the initialization function will reset each option to its default value, and, if you are using repeatable randomized initialization lists (see the description of the argument ), the random state stored in the array will be destroyed.You must supply a function that evaluates ; derivatives are not required.
The method used by
bnd_mcs_solve
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