# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.3 `glopt` Chapter.
``glopt`` - Global Optimization of a Function
Global optimization involves finding the absolute maximum or minimum value of a function (the `objective function`) of several variables, possibly subject to restrictions (defined by a set of bounds or `constraint functions`) on the values of the variables.
Where submodule :mod:`~naginterfaces.library.opt` treats local nonlinear optimization problems as well as convex optimization problems (for which local optima are by definition also global), this module tries to handle finding global optima of non-convex nonlinear optimization problems.
Such problems can be much harder to solve than local optimization problems because it is difficult to determine whether a potential optimum found is global, and because of the nonlocal methods required to avoid becoming trapped near local optima.
This introduction is a brief guide to the subject of global optimization, designed for the casual user.
For further details you may find it beneficial to consult a more detailed text, see Neumaier (2004).
Furthermore, much of the material in `the E04 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e04/e04intro.html>`__ is also relevant in this context and it is strongly recommended that you read `the E04 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e04/e04intro.html#background5>`__.
Some solvers in this module have been integrated in to the NAG optimization modelling suite, which provides an easy-to-use and flexible way of defining optimization problems among numerous solvers of the NAG library.
All utility routines from the suite can be used to define a compatible problem to be solved by the integrated solvers; see `the E04 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e04/e04intro.html#optsuite>`__ for more details.
See Also
--------
``naginterfaces.library.examples.glopt`` :
This subpackage contains examples for the ``glopt`` module.
See also the :ref:`library_glopt_ex` subsection.
Functionality Index
-------------------
**Nonlinear programming (NLP) -- global optimization**
bound constrained
branching algorithm, multi-level coordinate search: :meth:`handle_solve_mcs`
branching algorithm, multi-level coordinate search (D): :meth:`bnd_mcs_solve`
heuristic algorithm, particle swarm optimization (PSO): :meth:`bnd_pso`
generic, including nonlinearly constrained
heuristic algorithm, particle swarm optimization (PSO): :meth:`nlp_pso`
multi-start: :meth:`nlp_multistart_sqp`
**Nonlinear least squares, data fitting -- global optimization**
generic, including nonlinearly constrained
multi-start: :meth:`nlp_multistart_sqp_lsq`
**Service functions**
option setting functions
:meth:`bnd_mcs_solve`
initialization: :meth:`bnd_mcs_init`
check whether option has been set: :meth:`bnd_mcs_option_check`
retrieve character option values: :meth:`bnd_mcs_optget_char`
retrieve integer option values: :meth:`bnd_mcs_optget_int`
retrieve real option values: :meth:`bnd_mcs_optget_real`
supply character option values: :meth:`bnd_mcs_optset_char`
supply integer option values: :meth:`bnd_mcs_optset_int`
supply option values from character string: :meth:`bnd_mcs_optset_string`
supply option values from external file: :meth:`bnd_mcs_optset_file`
supply real option values: :meth:`bnd_mcs_optset_real`
:meth:`bnd_pso`, :meth:`nlp_pso`, :meth:`nlp_multistart_sqp` and :meth:`nlp_multistart_sqp_lsq`
supply option values from a character string: :meth:`optset`
retrieve option values: :meth:`optget`
For full information please refer to the NAG Library document
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05intro.html
"""
# NAG Copyright 2017-2023.
[docs]def bnd_mcs_init():
r"""
``bnd_mcs_init`` is used to initialize communication data for the suite of multi-level coordinate search functions: :meth:`bnd_mcs_solve`, :meth:`bnd_mcs_optset_file`, :meth:`bnd_mcs_optset_string`, :meth:`bnd_mcs_optset_char`, :meth:`bnd_mcs_optset_int`, :meth:`bnd_mcs_optset_real`, :meth:`bnd_mcs_option_check`, :meth:`bnd_mcs_optget_char`, :meth:`bnd_mcs_optget_int` and :meth:`bnd_mcs_optget_real`.
.. deprecated:: 28.3.0.0
``bnd_mcs_init`` is deprecated.
There is no suggested replacement for this routine.
.. _e05ja-py2-py-doc:
For full information please refer to the NAG Library document for e05ja
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jaf.html
**Returns**
**comm** : dict, communication object
Communication structure.
.. _e05ja-py2-py-notes:
**Notes**
``bnd_mcs_init`` initializes the communication array :math:`\mathrm{comm}`\ ['comm'] for the solver :meth:`bnd_mcs_solve` and the optional-argument handlers :meth:`bnd_mcs_optset_file`, :meth:`bnd_mcs_optset_string`, :meth:`bnd_mcs_optset_char`, :meth:`bnd_mcs_optset_int`, :meth:`bnd_mcs_optset_real`, :meth:`bnd_mcs_option_check`, :meth:`bnd_mcs_optget_char`, :meth:`bnd_mcs_optget_int` and :meth:`bnd_mcs_optget_real`.
"""
raise NotImplementedError
[docs]def 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):
r"""
``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 :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_solve``.
Note: this function uses optional algorithmic parameters, see also: :meth:`bnd_mcs_init`, :meth:`bnd_mcs_optset_file`, :meth:`bnd_mcs_optset_string`, :meth:`bnd_mcs_optset_char`, :meth:`bnd_mcs_optset_int`, :meth:`bnd_mcs_optset_real`, :meth:`bnd_mcs_option_check`, :meth:`bnd_mcs_optget_char`, :meth:`bnd_mcs_optget_int`, :meth:`bnd_mcs_optget_real`.
.. deprecated:: 28.3.0.0
``bnd_mcs_solve`` is deprecated.
Please use :meth:`handle_solve_mcs` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _e05jb-py2-py-doc:
For full information please refer to the NAG Library document for e05jb
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jbf.html
.. _e05jb-py2-py-parameters:
**Parameters**
**objfun** : callable f = objfun(x, nstate, data=None)
:math:`\mathrm{objfun}` must evaluate the objective function :math:`F\left(\mathbf{x}\right)` for a specified :math:`n`-vector :math:`\mathbf{x}`.
**Parameters**
**x** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathbf{x}`, the vector at which the objective function is to be evaluated.
**nstate** : int
If :math:`\mathrm{nstate} = 1` then ``bnd_mcs_solve`` is calling :math:`\mathrm{objfun}` for the first time. This argument setting allows you to save computation time if certain data must be read or calculated only once.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**f** : float
Must be set to the value of the objective function at :math:`\mathbf{x}`.
**ibound** : int
Indicates whether the facility for dealing with bounds of special forms is to be used. :math:`\mathrm{ibound}` must be set to one of the following values.
:math:`\mathrm{ibound} = 0`
You will supply :math:`\ell` and :math:`\mathbf{u}` individually.
:math:`\mathrm{ibound} = 1`
There are no bounds on :math:`\mathbf{x}`.
:math:`\mathrm{ibound} = 2`
There are semi-infinite bounds :math:`0\leq \mathbf{x}`.
:math:`\mathrm{ibound} = 3`
There are constant bounds :math:`\ell = \ell_1` and :math:`\mathbf{u} = u_1`.
Note that it only makes sense to fix any components of :math:`\mathbf{x}` when :math:`\mathrm{ibound} = 0`.
**bl** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{bl}` is :math:`\ell`, the array of lower bounds.
**bu** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{bu}` is :math:`\mathbf{u}`, the array of upper bounds.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**iinit** : int, optional
Selects which initialization method to use.
:math:`\mathrm{iinit} = 0`
Simple initialization (boundary and midpoint), with
:math:`\mathrm{numpts}[i-1] = 3`, :math:`\mathrm{initpt}[i-1] = 2` and
:math:`\mathrm{inlist}[i-1,0] = \mathrm{bl}[i-1]`, :math:`\mathrm{inlist}[i-1,1] = \left(\mathrm{bl}[i-1]+\mathrm{bu}[i-1]\right)/2`, :math:`\mathrm{inlist}[i-1,2] = \mathrm{bu}[i-1]`,
for :math:`i = 1,2,\ldots,n`.
:math:`\mathrm{iinit} = 1`
Simple initialization (off-boundary and midpoint), with
:math:`\mathrm{numpts}[i-1] = 3`, :math:`\mathrm{initpt}[i-1] = 2` and
:math:`\mathrm{inlist}[i-1,0] = \left(5\mathrm{bl}[i-1]+\mathrm{bu}[i-1]\right)/6`, :math:`\mathrm{inlist}[i-1,1] = \left(\mathrm{bl}[i-1]+\mathrm{bu}[i-1]\right)/2`, :math:`\mathrm{inlist}[i-1,2] = \left(\mathrm{bl}[i-1]+5\mathrm{bu}[i-1]\right)/6`,
for :math:`i = 1,2,\ldots,n`.
:math:`\mathrm{iinit} = 2`
Initialization using linesearches.
:math:`\mathrm{iinit} = 3`
You are providing your own initialization list.
:math:`\mathrm{iinit} = 4`
Generate a random initialization list.
For more information on methods :math:`\mathrm{iinit} = 2`, :math:`3` or :math:`4` see `Initialization and Sweeps <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jbf.html#ad-initializationandsweeps>`__.
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 (:math:`\mathrm{iinit} = 0` or :math:`1`), a safeguarded initialization procedure will be attempted, to avoid overflow.
**sdlist** : int, optional
When :math:`\mathrm{iinit} = 4`, 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.
**inlist** : None or float, array-like, shape :math:`\left(n, \mathrm{sdlist}\right)`, optional
This argument need not be set on entry if you wish to use one of the preset initialization methods (:math:`\mathrm{iinit} \neq 3`).
:math:`\mathrm{inlist}` 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 :math:`i` the split is done at the values :math:`\mathrm{inlist}[i-1,0:\mathrm{numpts}[i-1]]`, as well as at some adaptively chosen intermediate points.
The array sections :math:`\mathrm{inlist}[\textit{i}-1,0:\mathrm{numpts}[\textit{i}-1]]`, for :math:`\textit{i} = 1,2,\ldots,n`, 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 :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`).
**numpts** : None or int, array-like, shape :math:`\left(n\right)`, optional
This argument need not be set on entry if you wish to use one of the preset initialization methods (:math:`\mathrm{iinit} \neq 3`).
:math:`\mathrm{numpts}` encodes the number of splitting points in each non-fixed dimension.
**initpt** : None or int, array-like, shape :math:`\left(n\right)`, optional
This argument need not be set on entry if you wish to use one of the preset initialization methods (:math:`\mathrm{iinit} \neq 3`).
You must designate a point stored in :math:`\mathrm{inlist}` that you wish ``bnd_mcs_solve`` to consider as an 'initial point' for the purposes of the splitting procedure.
Call this initial point :math:`\mathbf{x}^*`.
The coordinates of :math:`\mathbf{x}^*` correspond to a set of indices :math:`J_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, such that :math:`\mathbf{x}_{\textit{i}}^*` is stored in :math:`\mathrm{inlist}[\textit{i}-1,J_{\textit{i}}-1]`, for :math:`\textit{i} = 1,2,\ldots,n`.
You must set :math:`\mathrm{initpt}[\textit{i}-1] = J_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**monit** : None 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.
:math:`\mathrm{monit}` 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, :math:`\mathrm{monit}` may be **None**.
**Parameters**
**ncall** : int
The cumulative number of calls to :math:`\mathrm{objfun}`.
**xbest** : float, ndarray, shape :math:`\left(n\right)`
The current best point.
**icount** : int, ndarray, shape :math:`\left(6\right)`
An array of counters.
:math:`\mathrm{icount}[0]`
:math:`\textit{nboxes}`, the current number of sub-boxes.
:math:`\mathrm{icount}[1]`
:math:`\textit{ncloc}`, the cumulative number of calls to :math:`\mathrm{objfun}` made in local searches.
:math:`\mathrm{icount}[2]`
:math:`\textit{nloc}`, the cumulative number of points used as start points for local searches.
:math:`\mathrm{icount}[3]`
:math:`\textit{nsweep}`, the cumulative number of sweeps through levels.
:math:`\mathrm{icount}[4]`
:math:`\textit{m}`, the cumulative number of splits by initialization list.
:math:`\mathrm{icount}[5]`
:math:`\textit{s}`, the current lowest level containing non-split boxes.
**inlist** : float, ndarray, shape :math:`\left(n, \textit{ninit}\right)`
The initialization list.
**numpts** : int, ndarray, shape :math:`\left(n\right)`
The number of points in each coordinate at which to split according to the initialization list :math:`\mathrm{inlist}`.
**initpt** : int, ndarray, shape :math:`\left(n\right)`
A pointer to the 'initial point' in :math:`\mathrm{inlist}`. Element :math:`\mathrm{initpt}[i-1]` is the column index in :math:`\mathrm{inlist}` of the :math:`i`\ th coordinate of the initial point.
**xbaskt** : float, ndarray, shape :math:`\left(n, \textit{nbaskt}\right)`
Note: the :math:`j`\ th candidate minimum has its :math:`i`\ th coordinate stored in :math:`\mathrm{xbaskt}[\textit{j}-1,\textit{i}-1]`, for :math:`\textit{j} = 1,2,\ldots,\textit{nbaskt}`, for :math:`\textit{i} = 1,2,\ldots,n`.
The 'shopping basket' of candidate minima.
**boxl** : float, ndarray, shape :math:`\left(n\right)`
The array of lower bounds of the current search box.
**boxu** : float, ndarray, shape :math:`\left(n\right)`
The array of upper bounds of the current search box.
**nstate** : int
Is set by ``bnd_mcs_solve`` to indicate at what stage of the minimization :math:`\mathrm{monit}` was called.
:math:`\mathrm{nstate} = 1`
This is the first time that :math:`\mathrm{monit}` has been called.
:math:`\mathrm{nstate} = -1`
This is the last time :math:`\mathrm{monit}` will be called.
:math:`\mathrm{nstate} = 0`
This is the first `and` last time :math:`\mathrm{monit}` will be called.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**data** : arbitrary, optional
User-communication data for callback functions.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**Returns**
**bl** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{bl}` is :math:`\ell`, the array of lower bounds.
**bu** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{bu}` is :math:`\mathbf{u}`, the array of upper bounds.
**inlist** : float, ndarray, shape :math:`\left(n, \mathrm{sdlist}\right)`
Unless :math:`\mathrm{errno}` = 1, 2 or ``NagMemoryError`` on exit, the actual initialization data used by ``bnd_mcs_solve``. If you wish to monitor the contents of :math:`\mathrm{inlist}` you are advised to do so solely through :math:`\mathrm{monit}`, not through the output value here.
**numpts** : int, ndarray, shape :math:`\left(n\right)`
Unless :math:`\mathrm{errno}` = 1, 2 or ``NagMemoryError`` on exit, the actual initialization data used by ``bnd_mcs_solve``.
**initpt** : int, ndarray, shape :math:`\left(n\right)`
Unless :math:`\mathrm{errno}` = 1, 2 or ``NagMemoryError`` on exit, the actual initialization data used by ``bnd_mcs_solve``.
**x** : float, ndarray, shape :math:`\left(n\right)`
If no exception or warning is raised, contains an estimate of the global optimum (see also `Accuracy <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jbf.html#accuracy>`__).
**obj** : float
If no exception or warning is raised, contains the function value at :math:`\mathrm{x}`.
If you request early termination of ``bnd_mcs_solve`` in :math:`\mathrm{objfun}` or :math:`\mathrm{monit}`, there is no guarantee that the function value at :math:`\mathrm{x}` equals :math:`\mathrm{obj}`.
.. _e05jb-py2-py-other_params:
**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 :math:`\textit{comm}` 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 :math:`\text{} = 100n_r^2`
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 :math:`\textit{nf}` may be made.
**'Infinite Bound Size'** : float
Default :math:`\text{} = r_{\mathrm{max}}^{\frac{1}{4}}`
This defines the 'infinite' bound :math:`\textit{infbnd}` in the definition of the problem constraints.
Any upper bound greater than or equal to :math:`\textit{infbnd}` will be regarded as :math:`\infty` (and similarly any lower bound less than or equal to :math:`{-\textit{infbnd}}` will be regarded as :math:`-\infty`).
**'Local Searches'** : str
Default :math:`\text{} = \texttt{'ON'}`
If you want to try to accelerate convergence of ``bnd_mcs_solve`` by starting local searches from candidate minima, you will require :math:`\textit{lcsrch}` to be 'ON'.
**'Local Searches Limit'** : int
Default :math:`\text{} = 50`
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 :math:`\text{} = 2\epsilon`
The value of :math:`\textit{loctol}` 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 <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jbf.html#ad-localsearch>`__.
**'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 :math:`\text{} = \texttt{'OFF'}`
For use with random initialization lists (:math:`\mathrm{iinit} = 4`).
When set to 'ON', an internally-initialized random state is stored in the array :math:`\textit{comm}` for use in subsequent calls to ``bnd_mcs_solve``.
**'Splits Limit'** : int
Default :math:`\text{} = \left\lfloor d\left(n_r+2\right)/3\right\rfloor`
Along with the initialization list :math:`\mathrm{inlist}`, 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 :math:`\text{} = 3n_r`
As the default termination criterion, computation stops when the best function value is static for :math:`\textit{stclim}` 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 :math:`\text{} = \epsilon^{\frac{1}{4}}`
If you have given a target objective value to reach in :math:`\textit{objval}` (the value of the option 'Target Objective Value'), :math:`\textit{objerr}` sets your desired relative error (from above if 'Minimize' is set, from below if 'Maximize' is set) between :math:`\mathrm{obj}` and :math:`\textit{objval}`, as described in `Accuracy <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jbf.html#accuracy>`__.
See also the description of the option 'Target Objective Safeguard'.
**'Target Objective Safeguard'** : float
Default :math:`\text{} = \epsilon^{\frac{1}{2}}`
If you have given a target objective value to reach in :math:`\textit{objval}` (the value of the option 'Target Objective Value'), :math:`\textit{objsfg}` sets your desired safeguarded termination tolerance, for when :math:`\textit{objval}` 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 :math:`\textit{objval}` overrides the default termination criterion determined by the option 'Static Limit'.
.. _e05jb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{ibound} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ibound} = 0`, :math:`1`, :math:`2` or :math:`3`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{ibound} = 0` or :math:`3` and :math:`\mathrm{bl}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{bu}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{ibound} = 0` then :math:`\mathrm{bl}[\textit{i}-1]\leq \mathrm{bu}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n`; if :math:`\mathrm{ibound} = 3` then :math:`\mathrm{bl}[0] < \mathrm{bu}[0]`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{ibound} = 3` and :math:`\mathrm{bl}[0] = \mathrm{bu}[0] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{ibound} = 3` then :math:`\mathrm{bl}[0] < \mathrm{bu}[0]`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{iinit} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{iinit} = 0`, :math:`1`, :math:`2`, :math:`3` or :math:`4`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{iinit} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{sdlist} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{iinit} \neq 2` then :math:`\mathrm{sdlist}\geq 3`.
(`errno` :math:`2`)
On entry, user-supplied :math:`\mathrm{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\mathrm{numpts}[\textit{i}-1]\geq 3`, for :math:`\textit{i} = 1,2,\ldots,n`.
(`errno` :math:`2`)
On entry, user-supplied :math:`\mathrm{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{sdlist} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\mathrm{numpts}[\textit{i}-1]\leq \mathrm{sdlist}`, for :math:`\textit{i} = 1,2,\ldots,n`.
(`errno` :math:`2`)
On entry, user-supplied :math:`\mathrm{initpt}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\mathrm{initpt}[\textit{i}-1]\geq 1`, for :math:`\textit{i} = 1,2,\ldots,n`.
(`errno` :math:`2`)
On entry, user-supplied :math:`\mathrm{initpt}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{sdlist} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\mathrm{initpt}[\textit{i}-1]\leq \mathrm{sdlist}`, for :math:`\textit{i} = 1,2,\ldots,n`.
(`errno` :math:`2`)
On entry, user-supplied section :math:`\mathrm{inlist}[i,1:\mathrm{numpts}[i-1]]` contained :math:`\textit{ndist}` distinct elements, and :math:`\textit{ndist} < \mathrm{numpts}[i-1]`: :math:`\textit{ndist} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, user-supplied :math:`\mathrm{inlist}[i-1,j-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`j = \langle\mathit{\boldsymbol{value}}\rangle`, and :math:`\mathrm{bl}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\mathrm{inlist}[\textit{i}-1,\textit{j}-1]\geq \mathrm{bl}[\textit{i}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{numpts}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n`.
(`errno` :math:`2`)
On entry, user-supplied :math:`\mathrm{inlist}[i-1,j-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`j = \langle\mathit{\boldsymbol{value}}\rangle`, and :math:`\mathrm{bu}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\mathrm{inlist}[\textit{i}-1,\textit{j}-1]\leq \mathrm{bu}[\textit{i}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{numpts}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n`.
(`errno` :math:`2`)
On entry, user-supplied section :math:`\mathrm{inlist}[i,1:\mathrm{numpts}[i-1]]` was not in ascending order: :math:`\mathrm{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
The number of non-fixed variables :math:`n_r = 0`.
Constraint: :math:`n_r > 0`.
(`errno` :math:`2`)
A value of 'Splits Limit' (:math:`\textit{smax}`) smaller than :math:`n_r+3` was set: :math:`\textit{smax} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n_r = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
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 (:math:`\mathrm{iinit} = 4`) or vary the value of 'Infinite Bound Size'.
(`errno` :math:`3`)
The user-supplied initialization list contained infinite values, as determined by the option 'Infinite Bound Size'.
(`errno` :math:`7`)
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 <https://www.nag.com>`__ quoting error code :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`7`)
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` :math:`4`)
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` :math:`5`)
The function evaluations limit was exceeded.
Approximately 'Function Evaluations Limit' function calls have been made without your chosen termination criterion being satisfied.
**NagCallbackTerminateWarning**
(`errno` :math:`6`)
User-supplied monitoring function requested termination.
(`errno` :math:`6`)
User-supplied objective function requested termination.
.. _e05jb-py2-py-notes:
**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:
.. math::
\textit{minimize}_{{\mathbf{x} \in R^n}}F\left(\mathbf{x}\right)\quad \text{ subject to }\quad \ell \leq \mathbf{x}\leq \mathbf{u}\quad \text{ and }\quad \ell \leq \mathbf{u}\text{,}
where :math:`F\left(\mathbf{x}\right)` (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 :math:`\bar{R}^n`, where :math:`\bar{R}` denotes the extended reals :math:`R∪\left\{{-\infty }, \infty \right\}`.
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 :math:`\ell` or :math:`\mathbf{u}` can be set to special values that will be treated as :math:`{-\infty }` or :math:`{+\infty }`.
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 :math:`l_i = u_i` for some :math:`i`) is allowed in ``bnd_mcs_solve``.
The initialization function :meth:`bnd_mcs_init` does not need to be called before each invocation of ``bnd_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 :math:`\mathrm{iinit}`), the random state stored in the array :math:`\textit{comm}` will be destroyed.
You must supply a function that evaluates :math:`F\left(\mathbf{x}\right)`; 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 <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jbf.html#algdetails>`__.
.. _e05jb-py2-py-references:
**References**
Huyer, W and Neumaier, A, 1999, `Global optimization by multi-level coordinate search`, Journal of Global Optimization (14), 331--355
"""
raise NotImplementedError
[docs]def bnd_mcs_optset_file(iopts, comm, io_manager=None):
r"""
``bnd_mcs_optset_file`` may be used to supply options to :meth:`bnd_mcs_solve` from an external file.
The initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optset_file``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optset_file`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jc-py2-py-doc:
For full information please refer to the NAG Library document for e05jc
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jcf.html
.. _e05jc-py2-py-parameters:
**Parameters**
**iopts** : int
The unit number (see :meth:`~naginterfaces.base.utils.FileObjManager.unit_from_fileobj`) of the option file to be read.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
.. _e05jc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
Could not read options file.
(`errno` :math:`2`)
At least one option from the options file could not be recognized.
(`errno` :math:`2`)
End-of-file found before BEGIN.
(`errno` :math:`2`)
BEGIN found, but end-of-file found before END.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Function Evaluations Limit' (:math:`\textit{nf}`): :math:`\textit{nf} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign an out-of-bounds value of 'Infinite Bound Size' (:math:`\textit{infbnd}`): :math:`\textit{infbnd} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Static Limit' (:math:`\textit{stclim}`): :math:`\textit{stclim} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Target Objective Error' (:math:`\textit{objerr}`): :math:`\textit{objerr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Target Objective Safeguard' (:math:`\textit{objsfg}`): :math:`\textit{objsfg} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Local Searches Limit' (:math:`\textit{loclim}`): :math:`\textit{loclim} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Local Searches Tolerance' (:math:`\textit{loctol}`): :math:`\textit{loctol} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign an illegal value of 'Local Searches' (:math:`\textit{lcsrch}`): :math:`\textit{lcsrch} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign an illegal value of 'Repeatability' (:math:`\textit{repeat}`): :math:`\textit{repeat} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
One of the numeric values to be set could not be parsed. Check that all such strings specify valid integer or real values.
.. _e05jc-py2-py-notes:
**Notes**
``bnd_mcs_optset_file`` may be used to supply values for options to :meth:`bnd_mcs_solve`. ``bnd_mcs_optset_file`` reads an external file and each line of the file defines a single option.
It is only necessary to supply values for those arguments whose values are to be different from their default values.
Each option is defined by a single character string, of up to :math:`72` characters, consisting of one or more items.
The items associated with a given option must be separated by spaces, or equals signs :math:`\left[ = \right]`.
Alphabetic characters may be upper or lower case.
The string
::
Static Limit = 100
is an example of a string used to set an option.
For each option the string contains one or more of the following items:
- a mandatory keyword;
- a phrase that qualifies the keyword;
- a number that specifies an integer or real value. Such numbers may be up to :math:`40` contiguous characters.
Blank strings and comments are ignored.
A comment begins with an asterisk (*) and all subsequent characters in the string are regarded as part of the comment.
The implied data type (character, integer or real) of each value to set **must** match that expected by the corresponding option.
The file containing the options must start with ``Begin`` and must finish with ``End``.
An example of a valid options file is:
::
Begin * Example options file
Static Limit = 500
End
Option settings are preserved following a call to :meth:`bnd_mcs_solve` and so the keyword 'Defaults' is provided to allow you to reset all the options to their default values before a subsequent call to :meth:`bnd_mcs_solve`.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_optset_string(optstr, comm, io_manager=None):
r"""
``bnd_mcs_optset_string`` may be used to supply individual options to :meth:`bnd_mcs_solve`.
The initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optset_string``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optset_string`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jd-py2-py-doc:
For full information please refer to the NAG Library document for e05jd
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jdf.html
.. _e05jd-py2-py-parameters:
**Parameters**
**optstr** : str
A string defining a single option (as described in :ref:`Notes <e05jd-py2-py-notes>` and in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`). The implied data type (character, integer or real) of each value to set **must** match that expected by the option.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
.. _e05jd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Function Evaluations Limit' (:math:`\textit{nf}`): :math:`\textit{nf} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign an out-of-bounds value of 'Infinite Bound Size' (:math:`\textit{infbnd}`): :math:`\textit{infbnd} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Static Limit' (:math:`\textit{stclim}`): :math:`\textit{stclim} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Target Objective Error' (:math:`\textit{objerr}`): :math:`\textit{objerr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Target Objective Safeguard' (:math:`\textit{objsfg}`): :math:`\textit{objsfg} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Local Searches Limit' (:math:`\textit{loclim}`): :math:`\textit{loclim} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Local Searches Tolerance' (:math:`\textit{loctol}`): :math:`\textit{loctol} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign an illegal value of 'Local Searches' (:math:`\textit{lcsrch}`): :math:`\textit{lcsrch} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign an illegal value of 'Repeatability' (:math:`\textit{repeat}`): :math:`\textit{repeat} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
The value to be set could not be parsed. Check that it specifies a valid integer or real value.
.. _e05jd-py2-py-notes:
**Notes**
``bnd_mcs_optset_string`` may be used to supply values for options to :meth:`bnd_mcs_solve`.
It is only necessary to call ``bnd_mcs_optset_string`` for those arguments whose values are to be different from their default values.
One call to ``bnd_mcs_optset_string`` sets one argument value.
Each option is defined by a single character string, of up to :math:`72` characters, consisting of one or more items.
The items associated with a given option must be separated by spaces, or equals signs :math:`\left[ = \right]`.
Alphabetic characters may be upper or lower case.
The string
::
Static Limit = 100
is an example of a string used to set an option.
For each option the string contains one or more of the following items:
- a mandatory keyword;
- a phrase that qualifies the keyword;
- a number that specifies an integer or real value. Such numbers may be up to :math:`40` contiguous characters.
Printing of user-specified options is turned off by default.
It may be turned on at any time using the keyword 'List'.
Option settings are preserved following a call to :meth:`bnd_mcs_solve` and so the keyword 'Defaults' is provided to allow you to reset all the options to their default values before a subsequent call to :meth:`bnd_mcs_solve`.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_optset_char(optstr, cvalue, comm, io_manager=None):
r"""
``bnd_mcs_optset_char`` may be used to supply individual 'ON'/'OFF'-valued character options to :meth:`bnd_mcs_solve`.
The initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optset_char``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optset_char`` is deprecated.
There is no suggested replacement for this routine.
.. _e05je-py2-py-doc:
For full information please refer to the NAG Library document for e05je
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jef.html
.. _e05je-py2-py-parameters:
**Parameters**
**optstr** : str
A string defining a single 'ON'/'OFF'-valued character option (as described in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`).
**cvalue** : str
The 'ON'/'OFF' value associated with the keyword in :math:`\mathrm{optstr}`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
.. _e05je-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
(`errno` :math:`3`)
Attempt to assign an illegal value of 'Local Searches' (:math:`\textit{lcsrch}`): :math:`\textit{lcsrch} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign an illegal value of 'Repeatability' (:math:`\textit{repeat}`): :math:`\textit{repeat} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e05je-py2-py-notes:
**Notes**
``bnd_mcs_optset_char`` may be used to supply values for 'ON'/'OFF'-valued character options to :meth:`bnd_mcs_solve`.
It is only necessary to call ``bnd_mcs_optset_char`` for those arguments whose values are to be different from their default values.
One call to ``bnd_mcs_optset_char`` sets one argument value.
Each 'ON'/'OFF'-valued character option is defined by a single character string in :math:`\mathrm{optstr}` and the corresponding value in :math:`\mathrm{cvalue}`.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_optset_int(optstr, ivalue, comm, io_manager=None):
r"""
``bnd_mcs_optset_int`` may be used to supply individual integer options to :meth:`bnd_mcs_solve`.
The initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optset_int``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optset_int`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jf-py2-py-doc:
For full information please refer to the NAG Library document for e05jf
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jff.html
.. _e05jf-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying an integer-valued option (as described in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`).
**ivalue** : int
An integer value associated with the option in :math:`\mathrm{optstr}`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
.. _e05jf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Function Evaluations Limit' (:math:`\textit{nf}`): :math:`\textit{nf} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Static Limit' (:math:`\textit{stclim}`): :math:`\textit{stclim} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign a non-positive value of 'Local Searches Limit' (:math:`\textit{loclim}`): :math:`\textit{loclim} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e05jf-py2-py-notes:
**Notes**
``bnd_mcs_optset_int`` may be used to supply values for integer options to :meth:`bnd_mcs_solve`.
It is only necessary to call ``bnd_mcs_optset_int`` for those arguments whose values are to be different from their default values.
One call to ``bnd_mcs_optset_int`` sets one argument value.
Each integer option is defined by a single character string in :math:`\mathrm{optstr}` and the corresponding value in :math:`\mathrm{ivalue}`.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_optset_real(optstr, rvalue, comm, io_manager=None):
r"""
``bnd_mcs_optset_real`` may be used to supply individual real options to :meth:`bnd_mcs_solve`.
The initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optset_real``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optset_real`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jg-py2-py-doc:
For full information please refer to the NAG Library document for e05jg
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jgf.html
.. _e05jg-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying a real-valued option (as described in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`).
**rvalue** : float
The value associated with the option in :math:`\mathrm{optstr}`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
.. _e05jg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
(`errno` :math:`3`)
Attempt to assign an out-of-bounds value of 'Infinite Bound Size' (:math:`\textit{infbnd}`): :math:`\textit{infbnd} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Target Objective Error' (:math:`\textit{objerr}`): :math:`\textit{objerr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Target Objective Safeguard' (:math:`\textit{objsfg}`): :math:`\textit{objsfg} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Attempt to assign too small a value of 'Local Searches Tolerance' (:math:`\textit{loctol}`): :math:`\textit{loctol} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e05jg-py2-py-notes:
**Notes**
``bnd_mcs_optset_real`` may be used to supply values for real options to :meth:`bnd_mcs_solve`.
It is only necessary to call ``bnd_mcs_optset_real`` for those arguments whose values are to be different from their default values.
One call to ``bnd_mcs_optset_real`` sets one argument value.
Each real option is defined by a single character string in :math:`\mathrm{optstr}` and the corresponding value in :math:`\mathrm{rvalue}`.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_option_check(optstr, comm):
r"""
``bnd_mcs_option_check`` is used to check if you have set an option of :meth:`bnd_mcs_solve`.
The initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_option_check``.
.. deprecated:: 28.3.0.0
``bnd_mcs_option_check`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jh-py2-py-doc:
For full information please refer to the NAG Library document for e05jh
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jhf.html
.. _e05jh-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying an option (as described in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`).
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**Returns**
**ichkopt** : bool
:math:`\mathbf{True}` if and only if you have set the option of :meth:`bnd_mcs_solve`.
.. _e05jh-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
.. _e05jh-py2-py-notes:
**Notes**
``bnd_mcs_option_check`` returns :math:`\mathbf{True}` if you have previously set the option contained in :math:`\mathrm{optstr}`, otherwise it returns :math:`\mathbf{False}`.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_optget_char(optstr, comm):
r"""
``bnd_mcs_optget_char`` is used to get the value of an 'ON'/'OFF'-valued character :meth:`bnd_mcs_solve` option. ``bnd_mcs_optget_char`` can be used before or after calling :meth:`bnd_mcs_solve`, but the initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optget_char``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optget_char`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jj-py2-py-doc:
For full information please refer to the NAG Library document for e05jj
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jjf.html
.. _e05jj-py2-py-parameters:
**Parameters**
**optstr** : str
A string defining a single 'ON'/'OFF'-valued character option (as described in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`).
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**Returns**
**cvalue** : str
If no exception or warning is raised on exit, :math:`\mathrm{cvalue}` contains the 'ON'/'OFF' value associated with the keyword in :math:`\mathrm{optstr}`.
.. _e05jj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
.. _e05jj-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``bnd_mcs_optget_char`` obtains the current value of an 'ON'/'OFF'-valued character option.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_optget_int(optstr, comm):
r"""
``bnd_mcs_optget_int`` is used to get the value of an integer :meth:`bnd_mcs_solve` option. ``bnd_mcs_optget_int`` can be used before or after calling :meth:`bnd_mcs_solve`, but the initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optget_int``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optget_int`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jk-py2-py-doc:
For full information please refer to the NAG Library document for e05jk
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jkf.html
.. _e05jk-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying an integer-valued option (as described in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`).
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**Returns**
**ivalue** : int
If no exception or warning is raised on exit, :math:`\mathrm{ivalue}` contains the integer value associated with the option in :math:`\mathrm{optstr}`.
.. _e05jk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
.. _e05jk-py2-py-notes:
**Notes**
``bnd_mcs_optget_int`` obtains the current value of an integer-valued option.
The default values of the options 'Function Evaluations Limit', 'Splits Limit', 'Static Limit' depend on the problem parameter :math:`n_r` (the number of non-fixed variables).
A default value for each of these options will be set in the first call to the solver :meth:`bnd_mcs_solve`: before that time, getting the value of any of these options using ``bnd_mcs_optget_int`` will not return a meaningful result.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def bnd_mcs_optget_real(optstr, comm):
r"""
``bnd_mcs_optget_real`` is used to get the value of a real :meth:`bnd_mcs_solve` option. ``bnd_mcs_optget_real`` can be used before or after calling :meth:`bnd_mcs_solve`, but the initialization function :meth:`bnd_mcs_init` **must** have been called before calling ``bnd_mcs_optget_real``.
.. deprecated:: 28.3.0.0
``bnd_mcs_optget_real`` is deprecated.
There is no suggested replacement for this routine.
.. _e05jl-py2-py-doc:
For full information please refer to the NAG Library document for e05jl
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05jlf.html
.. _e05jl-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying a real-valued option (as described in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`).
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`bnd_mcs_init`.
**Returns**
**rvalue** : float
If no exception or warning is raised on exit, :math:`\mathrm{rvalue}` contains the real value associated with the option in :math:`\mathrm{optstr}`.
.. _e05jl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Initialization function :meth:`bnd_mcs_init` has not been called.
(`errno` :math:`2`)
The supplied option is invalid. A keyword or keyword combination was not recognized.
.. _e05jl-py2-py-notes:
**Notes**
``bnd_mcs_optget_real`` obtains the current value of a real-valued option.
A complete list of options, their symbolic names and default values is given in :ref:`Other Parameters for bnd_mcs_solve <e05jb-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def handle_solve_mcs(handle, objfun=None, monit=None, data=None, io_manager=None):
r"""
``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: :meth:`opt.handle_opt_set <naginterfaces.library.opt.handle_opt_set>`, :meth:`opt.handle_opt_get <naginterfaces.library.opt.handle_opt_get>`.
.. _e05kb-py2-py-doc:
For full information please refer to the NAG Library document for e05kb
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html
.. _e05kb-py2-py-parameters:
**Parameters**
**handle** : Handle
The handle to the problem. It needs to be initialized (e.g., by :meth:`opt.handle_init <naginterfaces.library.opt.handle_init>`) and to hold a problem formulation compatible with ``handle_solve_mcs``. It **must not** be changed between calls to the NAG optimization modelling suite.
**objfun** : None or callable (fx, inform) = objfun(x, inform, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
:math:`\mathrm{objfun}` must calculate the value of the nonlinear objective function :math:`f\left(x\right)` at a specified point :math:`x`.
If there is no nonlinear objective (e.g., :meth:`opt.handle_set_linobj <naginterfaces.library.opt.handle_set_linobj>` or :meth:`opt.handle_set_quadobj <naginterfaces.library.opt.handle_set_quadobj>` was called to define a linear or quadratic objective function), :math:`\mathrm{objfun}` will never be called by ``handle_solve_mcs`` and may be **None**.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nvar}\right)`
The vector :math:`x` of variable values at which the objective function is to be evaluated.
**inform** : int
A non-negative value.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fx** : float
The value of the objective function at :math:`x`.
**inform** : int
May be used to indicate that the requested objective value could not be computed. Specifically, it can be set to a negative value:
:math:`\mathrm{inform} < 0`
The solver will cleanly exit with :math:`\mathrm{errno}` = 20 and return the best available point as well as the solve statistics.
**monit** : None or callable monit(x, rinfo, stats, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
:math:`\mathrm{monit}` 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 :math:`i`\ th step where :math:`i` is given by the 'MCS Monitor Frequency' (the default is :math:`0`, :math:`\mathrm{monit}` is not called).
A step is complete when the procedure in which a sub-box is considered for splitting finishes correctly.
:math:`\mathrm{monit}` may be **None**.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nvar}\right)`
The vector :math:`x` of decision variables at the current iteration.
**rinfo** : float, ndarray, shape :math:`\left(100\right)`
Error measures and various indicators at the end of the current iteration as described in :math:`\mathrm{rinfo}`.
**stats** : float, ndarray, shape :math:`\left(100\right)`
Solver statistics at the end of the current iteration as described in :math:`\mathrm{stats}`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**data** : arbitrary, optional
User-communication data for callback functions.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**Returns**
**x** : float, ndarray, shape :math:`\left(:\right)`
The final values of the variables, :math:`x`.
**rinfo** : float, ndarray, shape :math:`\left(100\right)`
Error measures and various indicators at the end of the final iteration as given in the table below:
.. rst-class:: nag-rules-none nag-align-left
+---------------------+----------------------------------------------------------+
|:math:`0` |Objective function value :math:`\mathrm{f}\left(x\right)`.|
+---------------------+----------------------------------------------------------+
|:math:`1` |Number of sweeps. |
+---------------------+----------------------------------------------------------+
|:math:`2`--:math:`99`|Reserved for future use. |
+---------------------+----------------------------------------------------------+
**stats** : float, ndarray, shape :math:`\left(100\right)`
Solver statistics at the end of the final iteration as given in the table below:
.. rst-class:: nag-rules-none nag-align-left
+---------------------+-------------------------------------------------------------------------------+
|:math:`0` |Number of calls to the objective function. |
+---------------------+-------------------------------------------------------------------------------+
|:math:`1` |Total time spent in the solver (including time spent evaluating the objective).|
+---------------------+-------------------------------------------------------------------------------+
|:math:`2` |Total time spent evaluating the objective function. |
+---------------------+-------------------------------------------------------------------------------+
|:math:`3` |Number of sub-boxes. |
+---------------------+-------------------------------------------------------------------------------+
|:math:`4` |Number of splits. |
+---------------------+-------------------------------------------------------------------------------+
|:math:`5` |Cumulative number of splits by initialization list. |
+---------------------+-------------------------------------------------------------------------------+
|:math:`6` |The current lowest level containing no split boxes. |
+---------------------+-------------------------------------------------------------------------------+
|:math:`7`--:math:`99`|Reserved for future use. |
+---------------------+-------------------------------------------------------------------------------+
.. _e05kb-py2-py-other_params:
**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 :math:`\text{} = \textit{SIMPLE BOUNDS}`
The solver provides several methods to produce the initial set of sub-boxes.
When :math:`\text{‘MCS Initialization Method'} = \texttt{'SIMPLE BOUNDS'}`, :math:`\texttt{'SIMPLE OFF-BOUNDS'}`, :math:`\texttt{'LINESEARCH'}` or :math:`\texttt{'RANDOM'}`, ``handle_solve_mcs`` will generate the sub-boxes internally.
Please refer to `Initialization and Sweeps <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html#ad-initializationandsweeps>`__ for more details about the differences between the automatic methods.
It is also possible to create a custom initialization list by setting :math:`\text{‘MCS Initialization Method'} = \texttt{'CUSTOM'}`. `Creating a Custom Initialization List <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html#creatingcustominit>`__ describes how to provide the custom initialization list to the solver.
Constraint: :math:`\text{‘MCS Initialization Method'} = \texttt{'SIMPLE BOUNDS'}`, :math:`\texttt{'SIMPLE OFF-BOUNDS'}`, :math:`\texttt{'LINESEARCH'}`, :math:`\texttt{'RANDOM'}` or :math:`\texttt{'CUSTOM'}`
**'MCS Max Objective Calls'** : int
Default :math:`\text{} = 100n_r^2`
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: :math:`\text{‘MCS Max Objective Calls'} \geq 1`
**'MCS Monitor Frequency'** : int
Default :math:`\text{} = 0`
This argument specifies the frequency on which to call the monitor function :math:`\mathrm{monit}`.
If zero, the monitor function will not be called.
Constraint: :math:`\text{‘MCS Monitor Frequency'} \geq 0`.
**'MCS Print Frequency'** : int
Default :math:`\text{} = 1`
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: :math:`\text{‘MCS Print Frequency'} \geq 1`.
**'MCS Local Searches'** : str
Default :math:`\text{} = \texttt{'ON'}`
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: :math:`\text{‘MCS Local Searches'} = \texttt{'ON'}` or :math:`\texttt{'OFF'}`
**'MCS Local Searches Limit'** : int
Default :math:`\text{} = 50`
This defines the maximal number of iterations to be used in the trust region loop of the local-search procedure.
Constraint: :math:`\text{‘MCS Local Searches Limit'} > 0`
**'MCS Local Searches Tolerance'** : float
Default :math:`\text{} = 2\epsilon`
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 <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html#ad-localsearch>`__.
Constraint: :math:`\text{‘MCS Local Searches Tolerance'}\geq {2\epsilon }`
**'MCS Repeatability'** : str
Default :math:`\text{} = \texttt{'OFF'}`
For use with random initialization lists (:math:`\text{‘MCS Initialization Method'} = RANDOM`).
When set to 'ON', The initialization list will be consistent for every call of ``handle_solve_mcs``.
Constraint: :math:`\text{‘MCS Repeatability'} = \texttt{'ON'}` or :math:`\texttt{'OFF'}`
**'MCS Splits Limit'** : int
Default :math:`\text{} = \left\lfloor d\left(n_r+2\right)/3\right\rfloor`
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: :math:`\text{‘MCS Splits Limit'} > n_r+2`
**'MCS Static Limit'** : int
Default :math:`\text{} = 3n_r`
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: :math:`\text{‘MCS Static Limit'} > 0`
**'MCS Target Objective Error'** : float
Default :math:`\text{} = \epsilon^{\frac{1}{4}}`
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 <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html#accuracy>`__.
See also the description of the option 'MCS Target Objective Safeguard'.
Constraint: :math:`\text{‘MCS Target Objective Error'}\geq 2\epsilon`
**'MCS Target Objective Safeguard'** : float
Default :math:`\text{} = \epsilon^{\frac{1}{2}}`
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: :math:`\text{‘MCS Target Objective Safeguard'}\geq 2\epsilon`
**'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 :math:`\text{} = r_{\mathrm{max}}^{\frac{1}{4}}`
This defines the 'infinite' bound :math:`\textit{bigbnd}` in the definition of the problem constraints.
Any upper bound greater than or equal to :math:`\textit{bigbnd}` will be regarded as :math:`{+\infty }` (and similarly any lower bound less than or equal to :math:`{-\textit{bigbnd}}` will be regarded as :math:`{-\infty }`).
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: :math:`\text{‘Infinite Bound Size'} \geq 1000`.
**'Monitoring File'** : int
Default :math:`\text{} = -1`
If :math:`i\geq 0`, the unit number for the secondary (monitoring) output.
If :math:`\text{‘Monitoring File'} = -1`, no secondary output is provided.
The information output to this unit is controlled by 'Monitoring Level'.
Constraint: :math:`\text{‘Monitoring File'} \geq -1`.
**'Monitoring Level'** : int
Default :math:`= 4`
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: :math:`0\leq \text{‘Monitoring Level'}\leq 5`.
**'Print File'** : int
Default :math:`= \text{advisory message unit number}`
If :math:`i\geq 0`, the unit number for the primary output of the solver.
If :math:`\text{‘Print File'} = -1`, 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: :math:`\text{‘Print File'} \geq -1`.
**'Print Level'** : int
Default :math:`= 2`
This argument defines how detailed information should be printed by the solver to the primary and secondary output.
.. rst-class:: nag-rules-none nag-align-left
+------------------------------------------+--------------------------------+
|:math:`i` |Output |
+==========================================+================================+
|:math:`0` |No output from the solver. |
+------------------------------------------+--------------------------------+
|:math:`1` |The Header and Summary. |
+------------------------------------------+--------------------------------+
|:math:`2`, :math:`3`, :math:`4`, :math:`5`|Additionally, the Iteration log.|
+------------------------------------------+--------------------------------+
Constraint: :math:`0\leq \text{‘Print Level'}\leq 5`.
**'Print Options'** : str
Default :math:`= \texttt{'YES'}`
If :math:`\text{‘Print Options'} = \texttt{'YES'}`, a listing of options will be printed to the primary output and is always printed to the secondary output.
Constraint: :math:`\text{‘Print Options'} = \texttt{'YES'}` or :math:`\texttt{'NO'}`.
**'Print Solution'** : str
Default :math:`= \texttt{'NO'}`
If :math:`\text{‘Print Solution'} = \texttt{'YES'}`, the solution will be printed to the primary and secondary output.
Constraint: :math:`\text{‘Print Solution'} = \texttt{'YES'}` or :math:`\texttt{'NO'}`.
**'Stats Time'** : str
Default :math:`= \texttt{'NO'}`
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: :math:`\text{‘Stats Time'} = \texttt{'YES'}`, :math:`\texttt{'NO'}`, :math:`\texttt{'CPU'}` or :math:`\texttt{'WALL CLOCK'}`.
**'Task'** : str
Default :math:`= \texttt{'MINIMIZE'}`
This argument specifies the required direction of the optimization.
If :math:`\text{‘Task'} = \texttt{'FEASIBLE POINT'}`, 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: :math:`\text{‘Task'} = \texttt{'MINIMIZE'}`, :math:`\texttt{'MAXIMIZE'}` or :math:`\texttt{'FEASIBLE POINT'}`.
.. _e05kb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
:math:`\mathrm{handle}` has not been initialized.
(`errno` :math:`1`)
:math:`\mathrm{handle}` does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.
(`errno` :math:`1`)
:math:`\mathrm{handle}` has not been initialized properly or is corrupted.
(`errno` :math:`2`)
This solver does not support the model defined in the handle.
(`errno` :math:`2`)
The problem is already being solved.
(`errno` :math:`3`)
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 (:math:`\text{‘MCS Initialization Method'} = \texttt{'CUSTOM'}`) or vary the value of 'Infinite Bound Size'.
(`errno` :math:`3`)
The user-supplied initialization list contained infinite values, as determined by the option 'Infinite Bound Size'.
(`errno` :math:`4`)
On entry, :math:`\textit{nvar} = \langle\mathit{\boldsymbol{value}}\rangle`, expected :math:`\mathrm{value} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{nvar}` must match the current number of variables of the model in the :math:`\mathrm{handle}`.
(`errno` :math:`5`)
On entry, user-supplied :math:`\textit{initpt}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\textit{initpt}[\textit{i}-1]\geq 1`, for :math:`\textit{i} = 1,2,\ldots,\textit{nvar}`.
(`errno` :math:`5`)
On entry, user-supplied :math:`\textit{initpt}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{sdlist} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\textit{initpt}[\textit{i}-1]\leq \textit{sdlist}`, for :math:`\textit{i} = 1,2,\ldots,\textit{nvar}`.
(`errno` :math:`5`)
On entry, user-supplied :math:`\textit{list}[i,\textit{j}] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{j} = \langle\mathit{\boldsymbol{value}}\rangle`, and :math:`\textit{bl}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\textit{list}[\textit{i},\textit{j}]\geq \textit{bl}[\textit{i}-1]`, for :math:`\textit{j} = 1,2,\ldots,\textit{numpts}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\textit{nvar}`.
(`errno` :math:`5`)
On entry, user-supplied :math:`\textit{list}[i,\textit{j}] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{j} = \langle\mathit{\boldsymbol{value}}\rangle`, and :math:`\textit{bu}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\textit{list}[i,\textit{j}]\leq \textit{bu}[\textit{i}-1]`, for :math:`\textit{j} = 1,2,\ldots,\textit{numpts}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\textit{nvar}`.
(`errno` :math:`5`)
On entry, user-supplied :math:`\textit{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\textit{numpts}[\textit{i}-1]\geq 3`, for :math:`\textit{i} = 1,2,\ldots,\textit{nvar}`.
(`errno` :math:`5`)
On entry, user-supplied :math:`\textit{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{sdlist} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{x}[i-1]` is not fixed then :math:`\textit{numpts}[\textit{i}-1]\leq \textit{sdlist}`, for :math:`\textit{i} = 1,2,\ldots,\textit{nvar}`.
(`errno` :math:`5`)
On entry, user-supplied section :math:`\textit{list}[i,1:\textit{numpts}[i-1]]` contained :math:`\textit{ndist}` distinct elements, and :math:`\textit{ndist} < \textit{numpts}[i-1]`: :math:`\textit{ndist} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
On entry, user-supplied section :math:`\textit{list}[i,1:\textit{numpts}[i-1]]` was not in ascending order: :math:`\textit{numpts}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
The dimension of the array 'MCS List' is not a multiple of :math:`\textit{nvar}`.
(`errno` :math:`6`)
There were :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` variables and the option 'MCS Splits Limit' :math:`\textit{smax} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{smax} > n+2`.
Use :meth:`opt.handle_opt_set <naginterfaces.library.opt.handle_opt_set>` to set compatible option values.
(`errno` :math:`7`)
Please provide a proper :math:`\mathrm{objfun}` function.
(`errno` :math:`8`)
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 <https://www.nag.com>`__ quoting error code :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`8`)
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` :math:`11`)
The optional parameter 'MCS Initialization Method' was set to CUSTOM but one of the arrays :math:`\textit{list}`, :math:`\textit{initpt}` or :math:`\textit{numpts}` was not passed correctly to the handle.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`21`)
The function evaluations limit was exceeded.
Approximately 'MCS Max Objective Calls' function calls have been made without your chosen termination criterion being satisfied.
(`errno` :math:`24`)
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` :math:`20`)
User-supplied monitoring function requested termination.
(`errno` :math:`20`)
User-supplied objective function requested termination.
.. _e05kb-py2-py-notes:
**Notes**
``handle_solve_mcs`` is aimed at minimizing a nonlinear objective function subject to bound constraints:
.. math::
\begin{array}{ll} \mathrm{minimize}_{{x \in ℝ^n}} & {f\left(x\right)} \\\text{subject to}& l_x \leq x \leq u_x \text{.} \end{array}
Here :math:`f` is a smooth nonlinear function and :math:`l_x` and :math:`u_x` are :math:`n`-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 call :meth:`opt.handle_init <naginterfaces.library.opt.handle_init>` to initialize it followed, optionally, by :meth:`opt.handle_set_nlnobj <naginterfaces.library.opt.handle_set_nlnobj>`, :meth:`opt.handle_set_linobj <naginterfaces.library.opt.handle_set_linobj>` or :meth:`opt.handle_set_quadobj <naginterfaces.library.opt.handle_set_quadobj>` to define the objective function and :meth:`opt.handle_set_simplebounds <naginterfaces.library.opt.handle_set_simplebounds>` to define bounds on the variables.
If :meth:`opt.handle_set_simplebounds <naginterfaces.library.opt.handle_set_simplebounds>` is not called, all the variables will be considered free by the solver.
It should be noted that ``handle_solve_mcs`` always assumes that the gradient of the objective is dense, therefore, defining a sparse structure for the residuals in the call to :meth:`opt.handle_set_nlnobj <naginterfaces.library.opt.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 <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html#algdetails>`__ for a more thorough explanation) so it is advisable to define reasonable bounds for the variables using :meth:`opt.handle_set_simplebounds <naginterfaces.library.opt.handle_set_simplebounds>`.
See `the E04 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e04/e04intro.html#optsuite>`__ for more details about the NAG optimization modelling suite.
The algorithm behaviour and solver strategy can be modified by various options (see :ref:`Other Parameters <e05kb-py2-py-other_params>`) which can be set by :meth:`opt.handle_opt_set <naginterfaces.library.opt.handle_opt_set>` and :meth:`opt.handle_opt_set_file <naginterfaces.library.opt.handle_opt_set_file>` at any time between the initialization of the handle by :meth:`opt.handle_init <naginterfaces.library.opt.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 <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html#creatingcustominit>`__.
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 <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05kbf.html#algdetails>`__.
.. _e05kb-py2-py-references:
**References**
Huyer, W and Neumaier, A, 1999, `Global optimization by multi-level coordinate search`, Journal of Global Optimization (14), 331--355
See Also
--------
:meth:`naginterfaces.library.examples.glopt.handle_solve_mcs_ex.main`
"""
raise NotImplementedError
[docs]def bnd_pso(bl, bu, objfun, comm, npar=None, monmod=None, data=None, io_manager=None, spiked_sorder='C'):
r"""
``bnd_pso`` is designed to search for the global minimum or maximum of an arbitrary function, using Particle Swarm Optimization (PSO).
Derivatives are not required, although these may be used by an accompanying local minimization function if desired. ``bnd_pso`` is essentially identical to :meth:`nlp_pso`, but with a simpler interface and with various options removed; otherwise most arguments are identical.
In particular, ``bnd_pso`` does not handle general constraints.
Note: this function uses optional algorithmic parameters, see also: :meth:`optset`.
.. _e05sa-py2-py-doc:
For full information please refer to the NAG Library document for e05sa
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05saf.html
.. _e05sa-py2-py-parameters:
**Parameters**
**bl** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathrm{bl}` is :math:`\ell`, the array of lower bounds.
**bu** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathrm{bu}` is :math:`\mathbf{u}`, the array of upper bounds.
**objfun** : callable (objf, vecout) = objfun(mode, x, objf, vecout, nstate, data=None)
:math:`\mathrm{objfun}` must, depending on the value of :math:`\mathrm{mode}`, calculate the objective function `and/or` calculate the gradient of the objective function for a :math:`\textit{ndim}`-variable vector :math:`\mathbf{x}`.
Gradients are only required if a local minimizer has been chosen which requires gradients.
See the option 'Local Minimizer' for more information.
**Parameters**
**mode** : int
Indicates which functionality is required.
:math:`\mathrm{mode} = 0`
:math:`F\left(\mathbf{x}\right)` should be returned in :math:`\mathrm{objf}`. The value of :math:`\mathrm{objf}` on entry may be used as an upper bound for the calculation. Any expected value of :math:`F\left(\mathbf{x}\right)` that is greater than :math:`\mathrm{objf}` may be approximated by this upper bound; that is :math:`\mathrm{objf}` can remain unaltered.
:math:`\mathrm{mode} = 1`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}` only
First derivatives can be evaluated and returned in :math:`\mathrm{vecout}`. Any unaltered elements of :math:`\mathrm{vecout}` will be approximated using finite differences.
:math:`\mathrm{mode} = 2`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}` only
:math:`F\left(\mathbf{x}\right)` `must` be calculated and returned in :math:`\mathrm{objf}`, and available first derivatives can be evaluated and returned in :math:`\mathrm{vecout}`. Any unaltered elements of :math:`\mathrm{vecout}` will be approximated using finite differences.
:math:`\mathrm{mode} = 5`
:math:`F\left(\mathbf{x}\right)` `must` be calculated and returned in :math:`\mathrm{objf}`. The value of :math:`\mathrm{objf}` on entry may not be used as an upper bound.
:math:`\mathrm{mode} = 6`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_conjgrd_comp'}` or :math:`\texttt{'opt.bounds_mod_deriv_easy'}` only
`All` first derivatives `must` be evaluated and returned in :math:`\mathrm{vecout}`.
:math:`\mathrm{mode} = 7`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_conjgrd_comp'}` or :math:`\texttt{'opt.bounds_mod_deriv_easy'}` only
:math:`F\left(\mathbf{x}\right)` `must` be calculated and returned in :math:`\mathrm{objf}`, and `all` first derivatives `must` be evaluated and returned in :math:`\mathrm{vecout}`.
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathbf{x}`, the point at which the objective function and/or its gradient are to be evaluated.
**objf** : float
The value of :math:`\mathrm{objf}` passed to :math:`\mathrm{objfun}` varies with the argument :math:`\mathrm{mode}`.
:math:`\mathrm{mode} = 0`
:math:`\mathrm{objf}` is an upper bound for the value of :math:`F\left(\mathbf{x}\right)`, often equal to the best value of :math:`F\left(\mathbf{x}\right)` found so far by a given particle. Only objective function values less than the value of :math:`\mathrm{objf}` on entry will be used further. As such this upper bound may be used to stop further evaluation when this will only increase the objective function value above the upper bound.
:math:`\mathrm{mode} = 1`, :math:`2`, :math:`5`, :math:`6` or :math:`7`
:math:`\mathrm{objf}` is meaningless on entry.
**vecout** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
If :math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}`, the values of :math:`\mathrm{vecout}` are used internally to indicate whether a finite difference approximation is required. See :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>`.
**nstate** : int
:math:`\mathrm{nstate}` indicates various stages of initialization throughout the function. This allows for permanent global arguments to be initialized the least number of times. For example, you may initialize a random number generator seed.
:math:`\mathrm{nstate} = 2`
:math:`\mathrm{objfun}` is called for the very first time. You may save computational time if certain data must be read or calculated only once.
:math:`\mathrm{nstate} = 1`
:math:`\mathrm{objfun}` is called for the first time by a NAG local minimization function. You may save computational time if certain data required for the local minimizer need only be calculated at the initial point of the local minimization.
:math:`\mathrm{nstate} = 0`
Used in all other cases.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**objf** : float
The value of :math:`\mathrm{objf}` returned varies with the argument :math:`\mathrm{mode}`.
:math:`\mathrm{mode} = 0`
:math:`\mathrm{objf}` must be the value of :math:`F\left(\mathbf{x}\right)`. Only values of :math:`F\left(\mathbf{x}\right)` strictly less than :math:`\mathrm{objf}` on entry need be accurate.
:math:`\mathrm{mode} = 1` or :math:`6`
Need not be set.
:math:`\mathrm{mode} = 2`, :math:`5` or :math:`7`
:math:`F\left(\mathbf{x}\right)` must be calculated and returned in :math:`\mathrm{objf}`. The entry value of :math:`\mathrm{objf}` may not be used as an upper bound.
**vecout** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The required values of :math:`\mathrm{vecout}` returned to the calling function depend on the value of :math:`\mathrm{mode}`.
:math:`\mathrm{mode} = 0` or :math:`5`
The value of :math:`\mathrm{vecout}` need not be set.
:math:`\mathrm{mode} = 1` or :math:`2`
:math:`\mathrm{vecout}` can contain components of the gradient of the objective function :math:`\frac{{\partial F}}{{\partial x_i}}` for some :math:`i = 1,2,\ldots \mathrm{ndim}`, or acceptable approximations. Any unaltered elements of :math:`\mathrm{vecout}` will be approximated using finite differences.
:math:`\mathrm{mode} = 6` or :math:`7`
:math:`\mathrm{vecout}` must contain the gradient of the objective function :math:`\frac{{\partial F}}{{\partial x_i}}` for all :math:`i = 1,2,\ldots \mathrm{ndim}`. Approximation of the gradient is strongly discouraged, and no finite difference approximations will be performed internally (see :meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>` and :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>`).
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`optset`.
**npar** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`10\times \textit{ndim}`.
:math:`\textit{npar}`, the number of particles to be used in the swarm. Assuming all particles remain within bounds, each complete iteration will perform at least :math:`\mathrm{npar}` function evaluations. Otherwise, significantly fewer objective function evaluations may be performed.
**monmod** : None or callable x = monmod(x, xb, fb, xbest, fbest, itt, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
A user-specified monitoring and modification function. :math:`\mathrm{monmod}` is called once every complete iteration after a finalization check.
It may be used to modify the particle locations that will be evaluated at the next iteration.
This permits the incorporation of algorithmic modifications such as including additional advection heuristics and genetic mutations. :math:`\mathrm{monmod}` is only called during the main loop of the algorithm, and as such will be unaware of any further improvement from the final local minimization.
If no monitoring and/or modification is required, :math:`\mathrm{monmod}` may be **None**.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
Note: the :math:`i`\ th component of the :math:`j`\ th particle, :math:`x_j\left(i\right)`, is stored in :math:`\mathrm{x}[i-1,j-1]`.
The :math:`\mathrm{npar}` particle locations, :math:`\mathbf{x}_j`, which will currently be used during the next iteration unless altered in :math:`\mathrm{monmod}`.
**xb** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The location, :math:`\tilde{\mathbf{x}}`, of the best solution yet found.
**fb** : float
The objective value, :math:`\tilde{f} = {F\left(\tilde{\mathbf{x}}\right)}`, of the best solution yet found.
**xbest** : float, ndarray, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
Note: the :math:`i`\ th component of the position of the :math:`j`\ th particle's cognitive memory, :math:`\hat{x}_j\left(i\right)`, is stored in :math:`\mathrm{xbest}[i-1,j-1]`.
The locations currently in the cognitive memory, :math:`\hat{\mathbf{x}}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{npar}` (see `Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05saf.html#algdetails>`__).
**fbest** : float, ndarray, shape :math:`\left(\textit{npar}\right)`
The objective values currently in the cognitive memory, :math:`F\left(\hat{\mathbf{x}}_{\textit{j}}\right)`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{npar}`.
**itt** : int, ndarray, shape :math:`\left(6\right)`
Iteration and function evaluation counters (see description of :math:`\mathrm{itt}` below).
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**x** : float, array-like, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
The particle locations to be used during the next iteration.
**data** : arbitrary, optional
User-communication data for callback functions.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**spiked_sorder** : str, optional
If :math:`\mathrm{x}` in :math:`\mathrm{monmod}` is spiked (i.e., has unit extent in all but one dimension, or has size :math:`1`), :math:`\mathrm{spiked\_sorder}` selects the storage order to associate with it in the NAG Engine:
spiked_sorder = :math:`\texttt{'C'}`
row-major storage will be used;
spiked_sorder = :math:`\texttt{'F'}`
column-major storage will be used.
**Returns**
**xb** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The location of the best solution found, :math:`\tilde{\mathbf{x}}`, in :math:`R^{\textit{ndim}}`.
**fb** : float
The objective value of the best solution, :math:`\tilde{f} = {F\left(\tilde{\mathbf{x}}\right)}`.
**itt** : int, ndarray, shape :math:`\left(6\right)`
Integer iteration counters for ``bnd_pso``.
:math:`\mathrm{itt}[0]`
Number of complete iterations.
:math:`\mathrm{itt}[1]`
Number of complete iterations without improvement to the current optimum.
:math:`\mathrm{itt}[2]`
Number of particles converged to the current optimum.
:math:`\mathrm{itt}[3]`
Number of improvements to the optimum.
:math:`\mathrm{itt}[4]`
Number of function evaluations performed.
:math:`\mathrm{itt}[5]`
Number of particles reset.
**inform** : int
Indicates which finalization criterion was reached. The possible values of :math:`\mathrm{inform}` are:
.. rst-class:: nag-rules-none nag-align-left
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\mathrm{inform}`|Meaning |
+=======================+====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`< 0` |Exit from a user-supplied function. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|0 |``bnd_pso`` has detected an error and terminated. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|1 |The provided objective target has been achieved. ('Target Objective Value'). |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|2 |The standard deviation of the location of all the particles is below the set threshold ('Swarm Standard Deviation'). If the solution returned is not satisfactory, you may try setting a smaller value of 'Swarm Standard Deviation', or try adjusting the options governing the repulsive phase ('Repulsion Initialize', 'Repulsion Finalize'). |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|3 |The total number of particles converged ('Maximum Particles Converged') to the current global optimum has reached the set limit. This is the number of particles which have moved to a distance less than 'Distance Tolerance' from the optimum with regard to the :math:`L^2` norm. If the solution is not satisfactory, you may consider lowering the 'Distance Tolerance'. However, this may hinder the global search capability of the algorithm. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|4 |The maximum number of iterations without improvement ('Maximum Iterations Static') has been reached, and the required number of particles ('Maximum Iterations Static Particles') have converged to the current optimum. Increasing either of these options will allow the algorithm to continue searching for longer. Alternatively if the solution is not satisfactory, re-starting the application several times with :math:`\text{‘Repeatability'} = \texttt{'OFF'}` may lead to an improved solution. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|5 |The maximum number of iterations ('Maximum Iterations Completed') has been reached. If the number of iterations since improvement is small, then a better solution may be found by increasing this limit, or by using the option 'Local Minimizer' with corresponding exterior options. Otherwise if the solution is not satisfactory, you may try re-running the application several times with :math:`\text{‘Repeatability'} = \texttt{'OFF'}` and a lower iteration limit, or adjusting the options governing the repulsive phase ('Repulsion Initialize', 'Repulsion Finalize').|
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|6 |The maximum allowed number of function evaluations ('Maximum Function Evaluations') has been reached. As with :math:`\mathrm{inform} = 5`, increasing this limit if the number of iterations without improvement is small, or decreasing this limit and running the algorithm multiple times with :math:`\text{‘Repeatability'} = \texttt{'OFF'}`, may provide a superior result. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. _e05sa-py2-py-other_params:
**Other Parameters**
**'Advance Cognitive'** : float
Default :math:`\text{} = 2.0`
The cognitive advance coefficient, :math:`C_s`.
When larger than the global advance coefficient, this will cause particles to be attracted toward their previous best positions.
Setting :math:`r = 0.0` will cause ``bnd_pso`` to act predominantly as a local optimizer.
Setting :math:`r > 2.0` may cause the swarm to diverge, and is generally inadvisable.
At least one of the global and cognitive coefficients must be nonzero.
**'Advance Global'** : float
Default :math:`\text{} = 2.0`
The global advance coefficient, :math:`C_g`.
When larger than the cognitive coefficient this will encourage convergence toward the best solution yet found.
Values :math:`r \in \left(0, 1\right)` will inhibit particles overshooting the optimum.
Values :math:`r \in \left[1, 2\right)` cause particles to fly over the optimum some of the time.
Larger values can prohibit convergence.
Setting :math:`r = 0.0` will remove any attraction to the current optimum, effectively generating a Monte Carlo multi-start optimization algorithm.
At least one of the global and cognitive coefficients must be nonzero.
**'Boundary'** : str
Default :math:`\text{} = \texttt{'FLOATING'}`
Determines the behaviour if particles leave the domain described by the box bounds.
This only affects the general PSO algorithm, and will not pass down to any NAG local minimizers chosen.
This option is only effective in those dimensions for which :math:`\mathrm{bl}[i-1]\neq \mathrm{bu}[i-1]`, :math:`i = 1,2,\ldots,\textit{ndim}`.
IGNORE
The box bounds are ignored. The objective function is still evaluated at the new particle position.
RESET
The particle is re-initialized inside the domain. :math:`\hat{\mathbf{x}}_j` and :math:`\hat{f}_j` are not affected.
FLOATING
The particle position remains the same, however the objective function will not be evaluated at the next iteration. The particle will probably be advected back into the domain at the next advance due to attraction by the cognitive and global memory.
HYPERSPHERICAL
The box bounds are wrapped around an :math:`\textit{ndim}`-dimensional hypersphere. As such a particle leaving through a lower bound will immediately re-enter through the corresponding upper bound and vice versa. The standard distance between particles is also modified accordingly.
FIXED
The particle rests on the boundary, with the corresponding dimensional velocity set to :math:`0.0`.
**'Distance Scaling'** : str
Default :math:`\text{} = \texttt{'ON'}`
Determines whether distances should be scaled by box widths.
ON
When a distance is calculated between :math:`\mathbf{x}` and :math:`\mathbf{y}`, a scaled :math:`L^2` norm is used.
.. math::
L^2\left(\mathbf{x}, \mathbf{y}\right) = \left(\sum_{\left\{i|\mathbf{u}_i\neq \ell_i,i\leq \textit{ndim}\right\}}\left(\frac{{x_i-y_i}}{{\mathbf{u}_i-\ell_i}}\right)^2\right)^{\frac{1}{2}}\text{.}
OFF
Distances are calculated as the standard :math:`L^2` norm without any rescaling.
.. math::
L^2\left(\mathbf{x}, \mathbf{y}\right) = \left(\sum_{{i = 1}}^{\textit{ndim}}\left(x_i-y_i\right)^2\right)^{\frac{1}{2}}\text{.}
**'Distance Tolerance'** : float
Default :math:`\text{} = 10^{-4}`
This is the distance, :math:`\textit{dtol}` between particles and the global optimum which must be reached for the particle to be considered converged, i.e., that any subsequent movement of such a particle cannot significantly alter the global optimum.
Once achieved the particle is reset into the box bounds to continue searching.
**'Function Precision'** : float
Default :math:`\text{} = \epsilon^{0.9}`
The argument defines :math:`\epsilon_r`, which is intended to be a measure of the accuracy with which the problem function :math:`F\left(\mathbf{x}\right)` can be computed.
If :math:`r < \epsilon` or :math:`r\geq 1`, the default value is used.
The value of :math:`\epsilon_r` should reflect the relative precision of :math:`1+\left\lvert F\left(\mathbf{x}\right)\right\rvert`; i.e., :math:`\epsilon_r` acts as a relative precision when :math:`\left\lvert F\right\rvert` is large, and as an absolute precision when :math:`\left\lvert F\right\rvert` is small.
For example, if :math:`F\left(\mathbf{x}\right)` is typically of order :math:`1000` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-6}`.
In contrast, if :math:`F\left(\mathbf{x}\right)` is typically of order :math:`10^{-4}` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-10}`.
The choice of :math:`\epsilon_r` can be quite complicated for badly scaled problems; see Module 8 of Gill `et al.` (1981) for a discussion of scaling techniques.
The default value is appropriate for most simple functions that are computed with full accuracy.
However when the accuracy of the computed function values is known to be significantly worse than full precision, the value of :math:`\epsilon_r` should be large enough so that no attempt will be made to distinguish between function values that differ by less than the error inherent in the calculation.
**'Local Boundary Restriction'** : float
Default :math:`\text{} = 0.5`
Contracts the box boundaries used by a box constrained local minimizer to, :math:`\left[\beta_l, \beta_u\right]`, containing the start point :math:`x`, where
.. math::
\begin{array}{c} \partial_i = r \times \left(\mathbf{u}_i-\ell_i\right) \\ \beta_l^i = \mathrm{max}\left(\ell_i, {x_i-\frac{\partial_i}{2}}\right) \\ \beta_u^i = \mathrm{min}\left(\mathbf{u}_i, {x_i+\frac{\partial_i}{2}}\right) \text{, }\quad i = 1,\ldots,\textit{ndim} \text{.} \end{array}
Smaller values of :math:`r` thereby restrict the size of the domain exposed to the local minimizer, possibly reducing the amount of work done by the local minimizer.
**'Local Interior Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``bnd_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Interior Major Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``bnd_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Exterior Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``bnd_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Exterior Major Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``bnd_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Interior Tolerance'** : float
Default :math:`\text{} = 10^{-4}`
This is the tolerance provided to a local minimizer in the interior (exterior) of the main loop of the algorithm.
**'Local Exterior Tolerance'** : float
Default :math:`\text{} = 10^{-4}`
This is the tolerance provided to a local minimizer in the interior (exterior) of the main loop of the algorithm.
**'Local Interior Minor Iterations'** : int
Where applicable, the secondary number of iterations the chosen local minimizer will use inside (outside) the main loop.
Currently the relevant default values are:
.. rst-class:: nag-rules-none
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================+=======================+============================================================+============================================================+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>`|'Minor Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
**'Local Exterior Minor Iterations'** : int
Where applicable, the secondary number of iterations the chosen local minimizer will use inside (outside) the main loop.
Currently the relevant default values are:
.. rst-class:: nag-rules-none
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================+=======================+============================================================+============================================================+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>`|'Minor Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
**'Local Minimizer'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Allows for a choice of submodule :mod:`~naginterfaces.library.opt` functions to be used as a coupled, dedicated local minimizer.
:math:`\text{‘Local Minimizer'} = \texttt{'OFF'}`
No local minimization will be performed in either the INTERIOR or EXTERIOR sections of the algorithm.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_simplex'}`
Use :meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` as the local minimizer. This does not require the calculation of derivatives.
On a call to :math:`\mathrm{objfun}` during a local minimization, :math:`\mathrm{mode} = 5`.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.bounds_mod_deriv_easy'}`
Use :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` as the local minimizer. This requires the calculation of derivatives in :math:`\mathrm{objfun}`, as indicated by :math:`\mathrm{mode}`.
The box bounds forwarded to this function from ``bnd_pso`` will have been acted upon by 'Local Boundary Restriction'.
As such, the domain exposed may be greatly smaller than that provided to ``bnd_pso``.
Accurate derivatives must be provided to this function, and will not be approximated internally.
Each iteration of this local minimizer also requires the calculation of both the objective function and its derivative.
Hence on a call to :math:`\mathrm{objfun}` during a local minimization, :math:`\mathrm{mode} = 7`.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.bounds_quasi_func_easy'}`
Use :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` as the local minimizer. This does not require the calculation of derivatives.
On a call to :math:`\mathrm{objfun}` during a local minimization, :math:`\mathrm{mode} = 5`.
The box bounds forwarded to this function from ``bnd_pso`` will have been acted upon by 'Local Boundary Restriction'.
As such, the domain exposed may be greatly smaller than that provided to ``bnd_pso``.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_conjgrd_comp'}`
Use :meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>` as the local minimizer.
Accurate derivatives must be provided, and will not be approximated internally.
Additionally, each call to :math:`\mathrm{objfun}` during a local minimization will require either the objective to be evaluated alone, or both the objective and its gradient to be evaluated.
Hence on a call to :math:`\mathrm{objfun}`, :math:`\mathrm{mode} = 5` or :math:`7`.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}`
Use :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` as the local minimizer. This operates such that any derivatives of the objective function that you cannot supply, will be approximated internally using finite differences.
Either, the objective, objective gradient, or both may be requested during a local minimization, and as such on a call to :math:`\mathrm{objfun}`, :math:`\mathrm{mode} = 1`, :math:`2` or :math:`5`.
The box bounds forwarded to this function from ``bnd_pso`` will have been acted upon by 'Local Boundary Restriction'.
As such, the domain exposed may be greatly smaller than that provided to ``bnd_pso``.
**'Maximum Function Evaluations'** : int
Default :math:`= \textit{Imax}`
The maximum number of evaluations of the objective function.
When reached this will return :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 6`.
**'Maximum Iterations Completed'** : int
Default :math:`\text{} = 1000\times \textit{ndim}`
The maximum number of complete iterations that may be performed.
Once exceeded ``bnd_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 5`.
Unless set, this adapts to the parameters passed to ``bnd_pso``.
**'Maximum Iterations Static'** : int
Default :math:`\text{} = 100`
The maximum number of iterations without any improvement to the current global optimum.
If exceeded ``bnd_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 4`.
This exit will be hindered by setting 'Maximum Iterations Static Particles' to larger values.
**'Maximum Iterations Static Particles'** : int
Default :math:`\text{} = 0`
The minimum number of particles that must have converged to the current optimum before the function may exit due to 'Maximum Iterations Static' with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 4`.
**'Maximum Particles Converged'** : int
Default :math:`= \textit{Imax}`
The maximum number of particles that may converge to the current optimum.
When achieved, ``bnd_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 3`.
This exit will be hindered by setting '**Repulsion**' options, as these cause the swarm to re-expand.
**'Maximum Particles Reset'** : int
Default :math:`= \textit{Imax}`
The maximum number of particles that may be reset after converging to the current optimum.
Once achieved no further particles will be reset, and any particles within 'Distance Tolerance' of the global optimum will continue to evolve as normal.
**'Maximum Variable Velocity'** : float
Default :math:`\text{} = 0.25`
Along any dimension :math:`j`, the absolute velocity is bounded above by :math:`\left\lvert \mathbf{v}_j\right\rvert \leq r\times \left(\mathbf{u}_j-\ell_j\right) = \mathbf{V}_{\textit{max}}`.
Very low values will greatly increase convergence time.
There is no upper limit, although larger values will allow more particles to be advected out of the box bounds, and values greater than :math:`4.0` may cause significant and potentially unrecoverable swarm divergence.
**'Optimize'** : str
Default :math:`\text{} = \mathrm{MINIMIZE}`
Determines whether to maximize or minimize the objective function.
MINIMIZE
The objective function will be minimized.
MAXIMIZE
The objective function will be maximized. This is accomplished by minimizing the negative of the objective.
**'Repeatability'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Allows for the same random number generator seed to be used for every call to ``bnd_pso``. :math:`\text{‘Repeatability'} = \texttt{'OFF'}` is recommended in general.
OFF
The internal generation of random numbers will be nonrepeatable.
ON
The same seed will be used.
**'Repulsion Finalize'** : int
Default :math:`= \textit{Imax}`
The number of iterations performed in a repulsive phase before re-contraction.
This allows a re-diversified swarm to contract back toward the current optimum, allowing for a finer search of the near optimum space.
**'Repulsion Initialize'** : int
Default :math:`= \textit{Imax}`
The number of iterations without any improvement to the global optimum before the algorithm begins a repulsive phase.
This phase allows the particle swarm to re-expand away from the current optimum, allowing more of the domain to be investigated.
The repulsive phase is automatically ended if a superior optimum is found.
**'Repulsion Particles'** : int
Default :math:`\text{} = 0`
The number of particles required to have converged to the current optimum before any repulsive phase may be initialized.
This will prevent repulsion before a satisfactory search of the near optimum area has been performed, which may happen for large dimensional problems.
**'Seed'** : int
Default :math:`\text{} = 0`
Sets the random number generator seed to be used when :math:`\text{‘Repeatability'} = \texttt{'ON'}`.
If set to 0, the default seed will be used.
If not, the absolute value of 'Seed' will be used to generate the random number generator seed.
**'Swarm Standard Deviation'** : float
Default :math:`\text{} = 0.1`
The target standard deviation of the particle distances from the current optimum. Once the standard deviation is below this level, ``bnd_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 2`.
This criterion will be penalized by the use of '**Repulsion**' options, as these cause the swarm to re-expand, increasing the standard deviation of the particle distances from the best point.
**'Target Objective'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Activate or deactivate the use of a target value as a finalization criterion.
If active, then once the supplied target value for the objective function is found (beyond the first iteration if 'Target Warning' is active) ``bnd_pso`` will exit with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
Other than checking for feasibility only (:math:`\text{‘Optimize'} = \textit{CONSTRAINTS}`), this is the only finalization criterion that guarantees that the algorithm has been successful.
If the target value was achieved at the initialization phase or first iteration and 'Target Warning' is active, ``bnd_pso`` will exit with :math:`\mathrm{errno}` = 2.
This option may take any real value :math:`r`, or the character ON/OFF as well as DEFAULT.
If this option is queried using :meth:`optget`, the current value of :math:`r` will be returned in :math:`\textit{rvalue}`, and :math:`\textit{cvalue}` will indicate whether this option is ON or OFF.
The behaviour of the option is as follows:
:math:`r`
Once a point is found with an objective value within the 'Target Objective Tolerance' of :math:`r`, ``bnd_pso`` will exit successfully with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
OFF
The current value of :math:`r` will remain stored, however it will not be used as a finalization criterion.
ON
The current value of :math:`r` stored will be used as a finalization criterion.
DEFAULT
The stored value of :math:`r` will be reset to its default value (:math:`0.0`), and this finalization criterion will be deactivated.
**'Target Objective Value'** : float
Default :math:`\text{} = 0.0`
Activate or deactivate the use of a target value as a finalization criterion.
If active, then once the supplied target value for the objective function is found (beyond the first iteration if 'Target Warning' is active) ``bnd_pso`` will exit with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
Other than checking for feasibility only (:math:`\text{‘Optimize'} = \textit{CONSTRAINTS}`), this is the only finalization criterion that guarantees that the algorithm has been successful.
If the target value was achieved at the initialization phase or first iteration and 'Target Warning' is active, ``bnd_pso`` will exit with :math:`\mathrm{errno}` = 2.
This option may take any real value :math:`r`, or the character ON/OFF as well as DEFAULT.
If this option is queried using :meth:`optget`, the current value of :math:`r` will be returned in :math:`\textit{rvalue}`, and :math:`\textit{cvalue}` will indicate whether this option is ON or OFF.
The behaviour of the option is as follows:
:math:`r`
Once a point is found with an objective value within the 'Target Objective Tolerance' of :math:`r`, ``bnd_pso`` will exit successfully with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
OFF
The current value of :math:`r` will remain stored, however it will not be used as a finalization criterion.
ON
The current value of :math:`r` stored will be used as a finalization criterion.
DEFAULT
The stored value of :math:`r` will be reset to its default value (:math:`0.0`), and this finalization criterion will be deactivated.
**'Target Objective Safeguard'** : float
Default :math:`\text{} = 100.0\epsilon`
If you have given a target objective value to reach in :math:`\textit{objval}` (the value of the option 'Target Objective Value'), :math:`\textit{objsfg}` sets your desired safeguarded termination tolerance, for when :math:`\textit{objval}` is close to zero.
**'Target Objective Tolerance'** : float
Default :math:`\text{} = 0.0`
The optional tolerance to a user-specified target value.
**'Target Warning'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Activates or deactivates the error exit associated with the target value being achieved before entry into the main loop of the algorithm, :math:`\mathrm{errno}` = 2.
OFF
No error will be returned, and the function will exit normally.
ON
An error will be returned if the target objective is reached prematurely, and the function will exit with :math:`\mathrm{errno}` = 2.
**'Verify Gradients'** : str
Default :math:`\text{} = \texttt{'ON'}`
Adjusts the level of gradient checking performed when gradients are required.
Gradient checks are only performed on the first call to the chosen local minimizer if it requires gradients.
There is no guarantee that the gradient check will be correct, as the finite differences used in the gradient check are themselves subject to inaccuracies.
OFF
No gradient checking will be performed.
ON
A cheap gradient check will be performed on both the gradients corresponding to the objective through :math:`\mathrm{objfun}`.
OBJECTIVE FULL
A more expensive gradient check will be performed on the gradients corresponding to the objective :math:`\mathrm{objfun}`.
**'Weight Decrease'** : str
Default :math:`\text{} = \mathrm{INTEREST}`
Determines how particle weights decrease.
OFF
Weights do not decrease.
INTEREST
Weights decrease through compound interest as :math:`w_{{\textit{IT}+1}} = w_{\textit{IT}}\left(1-W_{\textit{val}}\right)`, where :math:`W_{\textit{val}}` is the 'Weight Value' and :math:`\textit{IT}` is the current number of iterations.
LINEAR
Weights decrease linearly following :math:`w_{{\textit{IT}+1}} = w_{\textit{IT}}-\textit{IT}\times \left(W_{\textit{max}}-W_{\textit{min}}\right)/\textit{IT}_{\textit{max}}`, where :math:`\textit{IT}` is the iteration number and :math:`\textit{IT}_{\textit{max}}` is the maximum number of iterations as set by 'Maximum Iterations Completed'.
**'Weight Initial'** : float
Default :math:`\text{} = W_{\textit{max}}`
The initial value of any particle's inertial weight, :math:`W_{\textit{ini}}`, or the minimum possible initial value if initial weights are randomized.
When set, this will override :math:`\text{‘Weight Initialize'} = \texttt{'RANDOMIZED'}` or :math:`\texttt{'MAXIMUM'}`, and as such these must be set afterwards if so desired.
**'Weight Initialize'** : str
Default :math:`\text{} = \mathrm{MAXIMUM}`
Determines how the initial weights are distributed.
INITIAL
All weights are initialized at the initial weight, :math:`W_{\textit{ini}}`, if set. If 'Weight Initial' has not been set, this will be the maximum weight, :math:`W_{\textit{max}}`.
MAXIMUM
All weights are initialized at the maximum weight, :math:`W_{\textit{max}}`.
RANDOMIZED
Weights are uniformly distributed in :math:`\left(W_{\textit{min}}, W_{\textit{max}}\right)` or :math:`\left(W_{\textit{ini}}, W_{\textit{max}}\right)` if 'Weight Initial' has been set.
**'Weight Maximum'** : float
Default :math:`\text{} = 1.0`
The maximum particle weight, :math:`W_{\textit{max}}`.
**'Weight Minimum'** : float
Default :math:`\text{} = 0.1`
The minimum achievable weight of any particle, :math:`W_{\textit{min}}`.
Once achieved, no further weight reduction is possible.
**'Weight Reset'** : str
Default :math:`\text{} = \mathrm{MAXIMUM}`
Determines how particle weights are re-initialized.
INITIAL
Weights are re-initialized at the initial weight if set. If 'Weight Initial' has not been set, this will be the maximum weight.
MAXIMUM
Weights are re-initialized at the maximum weight.
RANDOMIZED
Weights are uniformly distributed in :math:`\left(W_{\textit{min}}, W_{\textit{max}}\right)` or :math:`\left(W_{\textit{ini}}, W_{\textit{max}}\right)` if 'Weight Initial' has been set.
**'Weight Value'** : float
Default :math:`\text{} = 0.01`
The constant :math:`W_{\textit{val}}` used with :math:`\text{‘Weight Decrease'} = \texttt{'INTEREST'}`.
**'SMP Callback Thread Safe'** : str
Default :math:`\text{} = \mathrm{WARNING}`
Declare that the callback functions you provide are or are not thread safe.
In particular, this indicates that access to the shared memory arrays :math:`\mathrm{iuser}` and :math:`\mathrm{ruser}` from within your provided callbacks is done in a thread safe manner. If these arrays are just used to pass constant data, then you may assume they are thread safe. If these are also used for workspace, or passing variable data such as random number generator seeds, then you must ensure these are accessed and updated safely. Whilst this can be done using OpenMP critical sections, we suggest their use is minimized to prevent unnecessary bottlenecks, and that instead individual threads have access to independent subsections of the provided arrays where possible.
YES
The callback functions have been programmed in a thread safe way. The algorithm will use ``OMP_NUM_THREADS`` threads.
NO
The callback functions are not thread safe. Setting this option will force the algorithm to run on a single thread only, and is advisable only for debugging purposes, or if you wish to parallelize your callback functions.
WARNING
This will cause an immediate exit from ``bnd_pso`` with :math:`\mathrm{errno}` = 51 if multiple threads are detected. This is to inform you that you have not declared the callback functions either to be thread safe, or that they are thread unsafe and you wish the algorithm to run in serial.
**'SMP Local Minimizer External'** : str
Default :math:`\text{} = \mathrm{ALL}`
Determines how many threads will attempt to locally minimize the best found solution after the function has exited the main loop.
MASTER
Only the master thread will attempt to find any improvement. The local minimization will be launched from the best known solution. All other threads will remain effectively idle.
ALL
The master thread will perform a local minimization from the best known solution, while all other threads will perform a local minimization from randomly generated perturbations of the best known solution, increasing the chance of an improvement. Assuming all local minimizations will take approximately the same amount of computation, this will be effectively free in terms of real time. It will however increase the number of function evaluations performed.
**'SMP Monitor'** : str
Default :math:`\text{} = \mathrm{SINGLE}`
Determines whether the user-supplied function :math:`\mathrm{monmod}` is invoked once every sub-iteration each thread performs, or only once by a single thread after all threads have completed at least one sub-iteration.
SINGLE
Only one thread will invoke :math:`\mathrm{monmod}`, after all threads have performed at least one sub-iteration.
ALL
Each thread will invoke :math:`\mathrm{monmod}` each time it completes a sub-iteration. If you wish to alter :math:`\mathrm{x}` using :math:`\mathrm{monmod}` you should use this option, as :math:`\mathrm{monmod}` will only receive the arrays :math:`\mathrm{x}`, :math:`\mathrm{xbest}` and :math:`\mathrm{fbest}` private to the calling thread.
**'SMP Monmod'** : str
Default :math:`\text{} = \mathrm{SINGLE}`
Determines whether the user-supplied function :math:`\mathrm{monmod}` is invoked once every sub-iteration each thread performs, or only once by a single thread after all threads have completed at least one sub-iteration.
SINGLE
Only one thread will invoke :math:`\mathrm{monmod}`, after all threads have performed at least one sub-iteration.
ALL
Each thread will invoke :math:`\mathrm{monmod}` each time it completes a sub-iteration. If you wish to alter :math:`\mathrm{x}` using :math:`\mathrm{monmod}` you should use this option, as :math:`\mathrm{monmod}` will only receive the arrays :math:`\mathrm{x}`, :math:`\mathrm{xbest}` and :math:`\mathrm{fbest}` private to the calling thread.
**'SMP Subswarm'** : int
Default :math:`\text{} = 1`
Determines how many threads support a particle subswarm.
This is an extra collection of particles constrained to search only within a hypercube of edge length :math:`10.0\times \text{‘Distance Tolerance'}` of the best point known to an individual thread.
This may improve the number of iterations required to find a provided target, particularly if no local minimizer is in use.
If :math:`i\leq 0`, then this will be disabled on all the threads.
If :math:`i\geq \texttt{OMP_NUM_THREADS}`, then all the threads will support a particle subswarm.
**'SMP Thread Overrun'** : int
Default :math:`\text{} = \textit{Imax}`
This option provides control over the level of asynchronicity present in a simulation.
In particular, a barrier synchronization between all threads is performed if any thread completes :math:`i` sub-iterations more than the slowest thread, causing all threads to be exposed to the current best solution.
Allowing asynchronous behaviour does however allow individual threads to focus on different global optimum candidates some of the time, which can inhibit convergence to unwanted sub-optima.
It also allows for threads to continue searching when other threads are completing sub-iterations at a slower rate.
If :math:`i < 1`, the algorithm will force a synchronization between threads at the end of each iteration.
.. _e05sa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\geq 1`.
(`errno` :math:`12`)
On entry, :math:`\mathrm{npar} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{npar}\geq 5\times \mathbf{num\_threads}`, where **num_threads** is the value returned by the OpenMP environment variable ``OMP_NUM_THREADS``, or **num_threads** is :math:`1` for a serial version of this function.
(`errno` :math:`14`)
On entry, :math:`\mathrm{bl}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{bu}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{bu}[i]\geq \mathrm{bl}[i]` for all :math:`i`.
(`errno` :math:`14`)
On entry, :math:`\mathrm{bl}[i] = \mathrm{bu}[i]` for all :math:`i`.
Constraint: :math:`\mathrm{bu}[i] > \mathrm{bl}[i]` for at least one :math:`i`.
(`errno` :math:`19`)
Error :math:`\langle\mathit{\boldsymbol{value}}\rangle` occurred whilst adjusting to interior local minimizer options.
(`errno` :math:`19`)
Error :math:`\langle\mathit{\boldsymbol{value}}\rangle` occurred whilst adjusting to exterior local minimizer options.
(`errno` :math:`21`)
Either the option arrays have not been initialized for ``bnd_pso``, or they have become corrupted.
(`errno` :math:`51`)
Multiple SMP threads have been detected; however, the option 'SMP Callback Thread Safe' has not been set.
Set :math:`\text{‘SMP Callback Thread Safe'} = \texttt{'YES'}` if the provided callbacks are thread safe.
Set :math:`\text{‘SMP Callback Thread Safe'} = \texttt{'NO'}` if the provided callbacks are not thread safe, to force serial execution.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
A finalization criterion was reached that cannot guarantee success.
On exit, :math:`\mathrm{inform} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Target :math:`\langle\mathit{\boldsymbol{value}}\rangle` achieved after the first iteration.
:math:`\mathrm{fb} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`32`)
Derivative checks indicate possible errors in the supplied derivatives.
**NagCallbackTerminateWarning**
(`errno` :math:`3`)
User requested exit :math:`\langle\mathit{\boldsymbol{value}}\rangle` during call to :math:`\mathrm{objfun}`.
(`errno` :math:`3`)
User requested exit :math:`\langle\mathit{\boldsymbol{value}}\rangle` during call to :math:`\mathrm{monmod}`.
.. _e05sa-py2-py-notes:
**Notes**
``bnd_pso`` uses a stochastic method based on Particle Swarm Optimization (PSO) to search for the global optimum of a nonlinear function :math:`F`, subject to a set of bound constraints on the variables.
In the PSO algorithm (see `Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05saf.html#algdetails>`__), a set of particles is generated in the search space, and advances each iteration to (hopefully) better positions using a heuristic velocity based upon `inertia`, `cognitive memory` and `global memory`.
The inertia is provided by a decreasingly weighted contribution from a particles current velocity, the cognitive memory refers to the best candidate found by an individual particle and the global memory refers to the best candidate found by all the particles.
This allows for a global search of the domain in question.
Further, this may be coupled with a selection of local minimization functions, which may be called during the iterations of the heuristic algorithm, the `interior` phase, to hasten the discovery of locally optimal points, and after the heuristic phase has completed to attempt to refine the final solution, the `exterior` phase.
Different options may be set for the local optimizer in each phase.
Without loss of generality, the problem is assumed to be stated in the following form:
.. math::
\textit{minimize}_{{\mathbf{x} \in R^{\textit{ndim}}}} F\left(\mathbf{x}\right)\quad \text{ subject to }\quad \ell \leq \mathbf{x}\leq \mathbf{u}\text{,}
where the objective :math:`F\left(\mathbf{x}\right)` is a scalar function, :math:`\mathbf{x}` is a vector in :math:`R^{\textit{ndim}}` and the vectors :math:`\ell \leq \mathbf{u}` are lower and upper bounds respectively for the :math:`\textit{ndim}` variables.
The objective function may be nonlinear.
Continuity of :math:`F` is not essential.
For functions which are smooth and primarily unimodal, faster solutions will almost certainly be achieved by using submodule :mod:`~naginterfaces.library.opt` functions directly.
For functions which are smooth and multi-modal, gradient dependent local minimization functions may be coupled with ``bnd_pso``.
For multi-modal functions for which derivatives cannot be provided, particularly functions with a significant level of noise in their evaluation, ``bnd_pso`` should be used either alone, or coupled with :meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>`.
The :math:`\textit{ndim}` lower and upper box bounds on the variable :math:`\mathbf{x}` are included to initialize the particle swarm into a finite hypervolume, although their subsequent influence on the algorithm is user determinable (see the option 'Boundary' in :ref:`Other Parameters <e05sa-py2-py-other_params>`).
It is strongly recommended that sensible bounds are provided for all variables.
``bnd_pso`` may also be used to maximize the objective function (see the option 'Optimize').
Due to the nature of global optimization, unless a predefined target is provided, there is no definitive way of knowing when to end a computation.
As such several stopping heuristics have been implemented into the algorithm.
If any of these is achieved, ``bnd_pso`` will exit with :math:`\mathrm{errno}` = 1, and the parameter :math:`\mathrm{inform}` will indicate which criteria was reached.
See :math:`\mathrm{inform}` for more information.
In addition, you may provide your own stopping criteria through :math:`\mathrm{monmod}` and :math:`\mathrm{objfun}`.
:meth:`nlp_pso` provides a comprehensive interface, allowing for the inclusion of general nonlinear constraints.
.. _e05sa-py2-py-references:
**References**
Gill, P E, Murray, W and Wright, M H, 1981, `Practical Optimization`, Academic Press
Kennedy, J and Eberhart, R C, 1995, `Particle Swarm Optimization`, Proceedings of the 1995 IEEE International Conference on Neural Networks, 1942--1948
Koh, B, George, A D, Haftka, R T and Fregly, B J, 2006, `Parallel Asynchronous Particle Swarm Optimization`, International Journal for Numerical Methods in Engineering (67(4)), 578--595
Vaz, A I and Vicente, L N, 2007, `A Particle Swarm Pattern Search Method for Bound Constrained Global Optimization`, Journal of Global Optimization (39(2)), 197--219, Kluwer Academic Publishers
"""
raise NotImplementedError
[docs]def nlp_pso(bl, bu, xbest, fbest, cbest, objfun, comm, confun=None, monmod=None, data=None, io_manager=None, spiked_sorder='C'):
r"""
``nlp_pso`` is designed to search for the global minimum or maximum of an arbitrary function, subject to general nonlinear constraints, using Particle Swarm Optimization (PSO).
Derivatives are not required, although these may be used by an accompanying local minimization function if desired. ``nlp_pso`` is essentially identical to :meth:`bnd_pso`, with an expert interface and various additional arguments added; otherwise most arguments are identical.
In particular, :meth:`bnd_pso` does not handle general constraints.
Note: this function uses optional algorithmic parameters, see also: :meth:`optset`.
.. _e05sb-py2-py-doc:
For full information please refer to the NAG Library document for e05sb
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05sbf.html
.. _e05sb-py2-py-parameters:
**Parameters**
**bl** : float, array-like, shape :math:`\left(\textit{ndim}+\textit{ncon}\right)`
:math:`\mathrm{bl}` is :math:`\ell`, the array of lower bounds.
**bu** : float, array-like, shape :math:`\left(\textit{ndim}+\textit{ncon}\right)`
:math:`\mathrm{bu}` is :math:`\mathbf{u}`, the array of upper bounds.
**xbest** : float, array-like, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
Note: the :math:`i`\ th component of the best position of the :math:`j`\ th particle, :math:`\hat{x}_j\left(i\right)`, is stored in :math:`\mathrm{xbest}[i-1,j-1]`.
If using :math:`\text{‘Start'} = \texttt{'WARM'}`, the initial particle positions, :math:`\hat{\mathbf{x}}_j^0`.
**fbest** : float, array-like, shape :math:`\left(\textit{npar}\right)`
If using :math:`\text{‘Start'} = \texttt{'WARM'}`, objective function values, :math:`\hat{f}_j^0 = F\left(\hat{\mathbf{x}}_j^0\right)`, corresponding to the :math:`\textit{npar}` particle locations stored in :math:`\mathrm{xbest}`.
**cbest** : float, array-like, shape :math:`\left(\textit{ncon}, \textit{npar}\right)`
Note: the :math:`k`\ th constraint violation of the :math:`j`\ th particle is stored in :math:`\mathrm{cbest}[k-1,j-1]`.
If using :math:`\text{‘Start'} = \texttt{'WARM'}`, the initial constraint violations, :math:`\hat{\mathbf{e}}_j^0 = \mathbf{e}\left(\hat{\mathbf{x}}_j^0\right)`, corresponding to the :math:`\textit{npar}` particle locations.
**objfun** : callable (objf, vecout) = objfun(mode, x, objf, vecout, nstate, data=None)
:math:`\mathrm{objfun}` must, depending on the value of :math:`\mathrm{mode}`, calculate the objective function `and/or` calculate the gradient of the objective function for a :math:`\textit{ndim}`-variable vector :math:`\mathbf{x}`.
Gradients are only required if a local minimizer has been chosen which requires gradients.
See the option 'Local Minimizer' for more information.
**Parameters**
**mode** : int
Indicates which functionality is required.
:math:`\mathrm{mode} = 0`
:math:`F\left(\mathbf{x}\right)` should be returned in :math:`\mathrm{objf}`. The value of :math:`\mathrm{objf}` on entry may be used as an upper bound for the calculation. Any expected value of :math:`F\left(\mathbf{x}\right)` that is greater than :math:`\mathrm{objf}` may be approximated by this upper bound; that is :math:`\mathrm{objf}` can remain unaltered.
:math:`\mathrm{mode} = 1`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}` only
First derivatives can be evaluated and returned in :math:`\mathrm{vecout}`. Any unaltered elements of :math:`\mathrm{vecout}` will be approximated using finite differences.
:math:`\mathrm{mode} = 2`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}` only
:math:`F\left(\mathbf{x}\right)` `must` be calculated and returned in :math:`\mathrm{objf}`, and available first derivatives can be evaluated and returned in :math:`\mathrm{vecout}`. Any unaltered elements of :math:`\mathrm{vecout}` will be approximated using finite differences.
:math:`\mathrm{mode} = 5`
:math:`F\left(\mathbf{x}\right)` `must` be calculated and returned in :math:`\mathrm{objf}`. The value of :math:`\mathrm{objf}` on entry may not be used as an upper bound.
:math:`\mathrm{mode} = 6`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_conjgrd_comp'}` or :math:`\texttt{'opt.bounds_mod_deriv_easy'}` only
`All` first derivatives `must` be evaluated and returned in :math:`\mathrm{vecout}`.
:math:`\mathrm{mode} = 7`
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_conjgrd_comp'}` or :math:`\texttt{'opt.bounds_mod_deriv_easy'}` only
:math:`F\left(\mathbf{x}\right)` `must` be calculated and returned in :math:`\mathrm{objf}`, and `all` first derivatives `must` be evaluated and returned in :math:`\mathrm{vecout}`.
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathbf{x}`, the point at which the objective function and/or its gradient are to be evaluated.
**objf** : float
The value of :math:`\mathrm{objf}` passed to :math:`\mathrm{objfun}` varies with the argument :math:`\mathrm{mode}`.
:math:`\mathrm{mode} = 0`
:math:`\mathrm{objf}` is an upper bound for the value of :math:`F\left(\mathbf{x}\right)`, often equal to the best constraint penalised value of :math:`F\left(\mathbf{x}\right)` found so far by a given particle if the objective function is strictly positive (see `Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05sbf.html#algdetails>`__). Only objective function values less than the value of :math:`\mathrm{objf}` on entry will be used further. As such this upper bound may be used to stop further evaluation when this will only increase the objective function value above the upper bound.
:math:`\mathrm{mode} = 1`, :math:`2`, :math:`5`, :math:`6` or :math:`7`
:math:`\mathrm{objf}` is meaningless on entry.
**vecout** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
If :math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}`, the values of :math:`\mathrm{vecout}` are used internally to indicate whether a finite difference approximation is required. See :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>`.
**nstate** : int
:math:`\mathrm{nstate}` indicates various stages of initialization throughout the function. This allows for permanent global arguments to be initialized the least number of times. For example, you may initialize a random number generator seed.
:math:`\mathrm{nstate} = 2`
:math:`\mathrm{objfun}` is called for the very first time. You may save computational time if certain data must be read or calculated only once.
:math:`\mathrm{nstate} = 1`
:math:`\mathrm{objfun}` is called for the first time by a NAG local minimization function. You may save computational time if certain data required for the local minimizer need only be calculated at the initial point of the local minimization.
:math:`\mathrm{nstate} = 0`
Used in all other cases.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**objf** : float
The value of :math:`\mathrm{objf}` returned varies with the argument :math:`\mathrm{mode}`.
:math:`\mathrm{mode} = 0`
:math:`\mathrm{objf}` must be the value of :math:`F\left(\mathbf{x}\right)`. Only values of :math:`F\left(\mathbf{x}\right)` strictly less than :math:`\mathrm{objf}` on entry need be accurate.
:math:`\mathrm{mode} = 1` or :math:`6`
Need not be set.
:math:`\mathrm{mode} = 2`, :math:`5` or :math:`7`
:math:`F\left(\mathbf{x}\right)` must be calculated and returned in :math:`\mathrm{objf}`. The entry value of :math:`\mathrm{objf}` may not be used as an upper bound.
**vecout** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The required values of :math:`\mathrm{vecout}` returned to the calling function depend on the value of :math:`\mathrm{mode}`.
:math:`\mathrm{mode} = 0` or :math:`5`
The value of :math:`\mathrm{vecout}` need not be set.
:math:`\mathrm{mode} = 1` or :math:`2`
:math:`\mathrm{vecout}` can contain components of the gradient of the objective function :math:`\frac{{\partial F}}{{\partial x_i}}` for some :math:`i = 1,2,\ldots \mathrm{ndim}`, or acceptable approximations. Any unaltered elements of :math:`\mathrm{vecout}` will be approximated using finite differences.
:math:`\mathrm{mode} = 6` or :math:`7`
:math:`\mathrm{vecout}` must contain the gradient of the objective function :math:`\frac{{\partial F}}{{\partial x_i}}` for all :math:`i = 1,2,\ldots \mathrm{ndim}`. Approximation of the gradient is strongly discouraged, and no finite difference approximations will be performed internally (see :meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>` and :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>`).
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`optset`.
**confun** : None or callable (c, cjac) = confun(mode, needc, x, cjac, nstate, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
:math:`\mathrm{confun}` must calculate any constraints other than the box constraints.
If no constraints are required, :math:`\mathrm{confun}` may be **None**. For information on how a NAG local minimizer will use :math:`\mathrm{confun}` see the documentation for :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>`.
**Parameters**
**mode** : int
Indicates which values must be assigned during each call of :math:`\mathrm{confun}`. Only the following values need be assigned, for each value of :math:`k \in \left\{1,\ldots,\textit{ncon}\right\}` such that :math:`\mathrm{needc}[k-1] > 0`:
:math:`\mathrm{mode} = 0`
the constraint values :math:`c_k\left(\mathbf{x}\right)`.
:math:`\mathrm{mode} = 1`
rows of the constraint Jacobian, :math:`\frac{{\partial c_k}}{{\partial x_{\textit{i}}}}\left(\mathbf{x}\right)`, for :math:`\textit{i} = 1,2,\ldots,\textit{ndim}`.
:math:`\mathrm{mode} = 2`
the constraint values :math:`c_k\left(\mathbf{x}\right)` and the corresponding rows of the constraint Jacobian, :math:`\frac{{\partial c_k}}{{\partial x_{\textit{i}}}}\left(\mathbf{x}\right)`, for :math:`\textit{i} = 1,2,\ldots,\textit{ndim}`.
**needc** : int, ndarray, shape :math:`\left(\textit{ncon}\right)`
The indices of the elements of :math:`\mathrm{c}` and/or :math:`\mathrm{cjac}` that must be evaluated by :math:`\mathrm{confun}`. If :math:`\mathrm{needc}[k-1] > 0`, the :math:`k-1`\ th element of :math:`\mathrm{c}`, corresponding to the values of the :math:`k`\ th constraint, and/or the available elements of the :math:`k-1`\ th row of :math:`\mathrm{cjac}`, corresponding to the derivatives of the :math:`k`\ th constraint, must be evaluated at :math:`\mathbf{x}` (see argument :math:`\mathrm{mode}`).
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathbf{x}`, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
**cjac** : float, ndarray, shape :math:`\left(\textit{ncon}, \textit{ndim}\right)`
Note: the derivative of the :math:`k`\ th constraint with respect to the :math:`i`\ th component, :math:`\frac{{\partial c_k}}{{\partial x_i}}`, is stored in :math:`\mathrm{cjac}[k-1,i-1]`.
The elements of :math:`\mathrm{cjac}` are set to special values which enable ``nlp_pso`` to detect whether they are changed by :math:`\mathrm{confun}`.
**nstate** : int
:math:`\mathrm{nstate}` indicates various stages of initialization throughout the function. This allows for permanent global arguments to be initialized a minimum number of times. For example, you may initialize a random number generator seed. Note that unless the option :math:`\text{‘Optimize'} = \texttt{'CONSTRAINTS'}` has been set, :math:`\mathrm{objfun}` will be called before :math:`\mathrm{confun}`.
:math:`\mathrm{nstate} = 2`
:math:`\mathrm{confun}` is called for the very first time. This argument setting allows you to save computational time if certain data must be read or calculated only once.
:math:`\mathrm{nstate} = 1`
:math:`\mathrm{confun}` is called for the first time during a NAG local minimization function. This argument setting allows you to save computational time if certain data required for the local minimizer need only be calculated at the initial point of the local minimization.
:math:`\mathrm{nstate} = 0`
Used in all other cases.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**c** : float, array-like, shape :math:`\left(\textit{ncon}\right)`
If :math:`\mathrm{needc}[k-1] > 0` and :math:`\mathrm{mode} = 0` or :math:`2`, :math:`\mathrm{c}[k-1]` must contain the value of :math:`c_k\left(\mathbf{x}\right)`. The remaining elements of :math:`\mathrm{c}`, corresponding to the non-positive elements of :math:`\mathrm{needc}`, need not be set.
**cjac** : float, array-like, shape :math:`\left(\textit{ncon}, \textit{ndim}\right)`
If :math:`\mathrm{needc}[k-1] > 0` and :math:`\mathrm{mode} = 1` or :math:`2`, the elements of :math:`\mathrm{cjac}` corresponding to the :math:`k`\ th row of the constraint Jacobian should contain the available elements of the vector :math:`\nabla c_k` given by
.. math::
\nabla c_k = \left(\frac{{\partial c_k}}{{\partial x_1}},\frac{{\partial c_k}}{{\partial x_2}},\ldots,\frac{{\partial c_k}}{{\partial x_n}}\right)\text{,}
where :math:`\frac{{\partial c_k}}{{\partial x_i}}` is the partial derivative of the :math:`k`\ th constraint with respect to the :math:`i`\ th variable, evaluated at the point :math:`\mathbf{x}`; elements of :math:`\mathrm{cjac}` that remain unaltered will be approximated internally using finite differences. The remaining rows of :math:`\mathrm{cjac}`, corresponding to non-positive elements of :math:`\mathrm{needc}`, need not be set.
It must be emphasized that unassigned elements of :math:`\mathrm{cjac}` are not treated as constant; they are estimated by finite differences, at nontrivial expense.
An interval for each element of :math:`\mathbf{x}` is computed automatically at the start of the optimization.
The automatic procedure can usually identify constant elements of :math:`\mathrm{cjac}`, which are then computed once only by finite differences.
**monmod** : None or callable x = monmod(x, xb, fb, cb, xbest, fbest, cbest, itt, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
A user-specified monitoring and modification function. :math:`\mathrm{monmod}` is called once every complete iteration after a finalization check.
It may be used to modify the particle locations that will be evaluated at the next iteration.
This permits the incorporation of algorithmic modifications such as including additional advection heuristics and genetic mutations. :math:`\mathrm{monmod}` is only called during the main loop of the algorithm, and as such will be unaware of any further improvement from the final local minimization.
If no monitoring and/or modification is required, :math:`\mathrm{monmod}` may be **None**.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
Note: the :math:`i`\ th component of the :math:`j`\ th particle, :math:`x_j\left(i\right)`, is stored in :math:`\mathrm{x}[i-1,j-1]`.
The :math:`\mathrm{npar}` particle locations, :math:`\mathbf{x}_j`, which will currently be used during the next iteration unless altered in :math:`\mathrm{monmod}`.
**xb** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The location, :math:`\tilde{\mathbf{x}}`, of the best solution yet found.
**fb** : float
The objective value, :math:`\tilde{f} = {F\left(\tilde{\mathbf{x}}\right)}`, of the best solution yet found.
**cb** : float, ndarray, shape :math:`\left(\textit{ncon}\right)`
The constraint violations, :math:`\tilde{\mathbf{e}} = {\mathbf{e}\left(\tilde{\mathbf{x}}\right)}`, of the best solution yet found.
**xbest** : float, ndarray, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
Note: the :math:`i`\ th component of the position of the :math:`j`\ th particle's cognitive memory, :math:`\hat{x}_j\left(i\right)`, is stored in :math:`\mathrm{xbest}[i-1,j-1]`.
The locations currently in the cognitive memory, :math:`\hat{\mathbf{x}}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\textit{npar}` (see `Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05sbf.html#algdetails>`__).
**fbest** : float, ndarray, shape :math:`\left(\textit{npar}\right)`
The objective values currently in the cognitive memory, :math:`F\left(\hat{\mathbf{x}}_{\textit{j}}\right)`, for :math:`\textit{j} = 1,2,\ldots,\textit{npar}`.
**cbest** : float, ndarray, shape :math:`\left(\textit{ncon}, \textit{npar}\right)`
Note: the :math:`k`\ th constraint violation of the :math:`j`\ th particle's cognitive memory is stored in :math:`\mathrm{cbest}[k-1,j-1]`.
The constraint violations currently in the cognitive memory, :math:`\hat{\mathbf{e}} = {\mathbf{e}\left(\hat{\mathbf{x}}_{\textit{j}}\right)}`, for :math:`\textit{j} = 1,2,\ldots,\textit{npar}`, evaluated at :math:`\hat{\mathbf{x}}_j`.
**itt** : int, ndarray, shape :math:`\left(7\right)`
Iteration and function evaluation counters (see description of :math:`\mathrm{itt}` below).
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**x** : float, array-like, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
The particle locations to be used during the next iteration.
**data** : arbitrary, optional
User-communication data for callback functions.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**spiked_sorder** : str, optional
If :math:`\mathrm{xbest}` and :math:`\mathrm{cbest}` are spiked (i.e., have unit extent in all but one dimension, or have size :math:`1`), :math:`\mathrm{spiked\_sorder}` selects the storage order to associate with them in the NAG Engine:
spiked_sorder = :math:`\texttt{'C'}`
row-major storage will be used;
spiked_sorder = :math:`\texttt{'F'}`
column-major storage will be used.
Two-dimensional arrays returned from callback functions in this routine must then use the same storage order.
**Returns**
**xb** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The location of the best solution found, :math:`\tilde{\mathbf{x}}`, in :math:`R^{\textit{ndim}}`.
**fb** : float
The objective value of the best solution, :math:`\tilde{f} = {F\left(\tilde{\mathbf{x}}\right)}`.
**cb** : float, ndarray, shape :math:`\left(\textit{ncon}\right)`
The constraint violations of the best solution found, :math:`\tilde{\mathbf{e}} = {\mathbf{e}\left(\tilde{\mathbf{x}}\right)}`. These may have been deemed to be acceptable given the tolerance and scaling of the constraints. See `Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05sbf.html#algdetails>`__ and :ref:`Other Parameters <e05sb-py2-py-other_params>`.
**xbest** : float, ndarray, shape :math:`\left(\textit{ndim}, \textit{npar}\right)`
The best positions found, :math:`\hat{\mathbf{x}}_j`, by the :math:`\textit{npar}` particles in the swarm.
**fbest** : float, ndarray, shape :math:`\left(\textit{npar}\right)`
Objective function values, :math:`\hat{f}_j = F\left(\hat{\mathbf{x}}_j\right)`, corresponding to the locations returned in :math:`\mathrm{xbest}`.
**cbest** : float, ndarray, shape :math:`\left(\textit{ncon}, \textit{npar}\right)`
The final constraint violations, :math:`\hat{\mathbf{e}}_j`, corresponding to the locations returned in :math:`\mathrm{xbest}`.
**itt** : int, ndarray, shape :math:`\left(7\right)`
Integer iteration counters for ``nlp_pso``.
:math:`\mathrm{itt}[0]`
Number of complete iterations.
:math:`\mathrm{itt}[1]`
Number of complete iterations without improvement to the current optimum.
:math:`\mathrm{itt}[2]`
Number of particles converged to the current optimum.
:math:`\mathrm{itt}[3]`
Number of improvements to the optimum.
:math:`\mathrm{itt}[4]`
Number of function evaluations performed.
:math:`\mathrm{itt}[5]`
Number of particles reset.
:math:`\mathrm{itt}[6]`
Number of violated constraints at completion. Note this is always calculated using the :math:`L^1` norm and a nonzero result does not necessarily mean that the algorithm did not find a suitably constrained point with respect to the single norm used.
**inform** : int
Indicates which finalization criterion was reached. The possible values of :math:`\mathrm{inform}` are:
.. rst-class:: nag-rules-none nag-align-left
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\mathrm{inform}`|Meaning |
+=======================+====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`< 0` |Exit from a user-supplied function. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|0 |``nlp_pso`` has detected an error and terminated. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|1 |The provided objective target has been achieved. ('Target Objective Value'). |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|2 |The standard deviation of the location of all the particles is below the set threshold ('Swarm Standard Deviation'). If the solution returned is not satisfactory, you may try setting a smaller value of 'Swarm Standard Deviation', or try adjusting the options governing the repulsive phase ('Repulsion Initialize', 'Repulsion Finalize'). |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|3 |The total number of particles converged ('Maximum Particles Converged') to the current global optimum has reached the set limit. This is the number of particles which have moved to a distance less than 'Distance Tolerance' from the optimum with regard to the :math:`L^2` norm. If the solution is not satisfactory, you may consider lowering the 'Distance Tolerance'. However, this may hinder the global search capability of the algorithm. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|4 |The maximum number of iterations without improvement ('Maximum Iterations Static') has been reached, and the required number of particles ('Maximum Iterations Static Particles') have converged to the current optimum. Increasing either of these options will allow the algorithm to continue searching for longer. Alternatively if the solution is not satisfactory, re-starting the application several times with :math:`\text{‘Repeatability'} = \texttt{'OFF'}` may lead to an improved solution. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|5 |The maximum number of iterations ('Maximum Iterations Completed') has been reached. If the number of iterations since improvement is small, then a better solution may be found by increasing this limit, or by using the option 'Local Minimizer' with corresponding exterior options. Otherwise if the solution is not satisfactory, you may try re-running the application several times with :math:`\text{‘Repeatability'} = \texttt{'OFF'}` and a lower iteration limit, or adjusting the options governing the repulsive phase ('Repulsion Initialize', 'Repulsion Finalize').|
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|6 |The maximum allowed number of function evaluations ('Maximum Function Evaluations') has been reached. As with :math:`\mathrm{inform} = 5`, increasing this limit if the number of iterations without improvement is small, or decreasing this limit and running the algorithm multiple times with :math:`\text{‘Repeatability'} = \texttt{'OFF'}`, may provide a superior result. |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|7 |A feasible point has been found. The objective has not been minimized, although it has been evaluated at the final solutions given in :math:`\mathrm{xb}` and :math:`\mathrm{xbest}` (:math:`\text{‘Optimize'} = \texttt{'CONSTRAINTS'}`). |
+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
If you wish to continue from the final position gained from a previous simulation with adjusted options, you may set the option :math:`\text{‘Start'} = \texttt{'WARM'}`, and pass back in the returned arrays :math:`\mathrm{xbest}`, :math:`\mathrm{fbest}`, and :math:`\mathrm{cbest}`. You should either record the returned values of :math:`\mathrm{xb}`, :math:`\mathrm{fb}` and :math:`\mathrm{cb}` for comparison, as these will not be re-used by the algorithm, or include them in :math:`\mathrm{xbest}`, :math:`\mathrm{fbest}` and :math:`\mathrm{cbest}` respectively by overwriting the entries corresponding to one particle with the relevant information.
.. _e05sb-py2-py-other_params:
**Other Parameters**
**'Advance Cognitive'** : float
Default :math:`\text{} = 2.0`
The cognitive advance coefficient, :math:`C_s`.
When larger than the global advance coefficient, this will cause particles to be attracted toward their previous best positions.
Setting :math:`r = 0.0` will cause ``nlp_pso`` to act predominantly as a local optimizer.
Setting :math:`r > 2.0` may cause the swarm to diverge, and is generally inadvisable.
At least one of the global and cognitive coefficients must be nonzero.
**'Advance Global'** : float
Default :math:`\text{} = 2.0`
The global advance coefficient, :math:`C_g`.
When larger than the cognitive coefficient this will encourage convergence toward the best solution yet found.
Values :math:`r \in \left(0, 1\right)` will inhibit particles overshooting the optimum.
Values :math:`r \in \left[1, 2\right)` cause particles to fly over the optimum some of the time.
Larger values can prohibit convergence.
Setting :math:`r = 0.0` will remove any attraction to the current optimum, effectively generating a Monte Carlo multi-start optimization algorithm.
At least one of the global and cognitive coefficients must be nonzero.
**'Boundary'** : str
Default :math:`\text{} = \texttt{'FLOATING'}`
Determines the behaviour if particles leave the domain described by the box bounds.
This only affects the general PSO algorithm, and will not pass down to any NAG local minimizers chosen.
This option is only effective in those dimensions for which :math:`\mathrm{bl}[i-1]\neq \mathrm{bu}[i-1]`, :math:`i = 1,2,\ldots,\textit{ndim}`.
IGNORE
The box bounds are ignored. The objective function is still evaluated at the new particle position.
RESET
The particle is re-initialized inside the domain. :math:`\hat{\mathbf{x}}_j`, :math:`\hat{f}_j` and :math:`\hat{\mathbf{e}}_j` are not affected.
FLOATING
The particle position remains the same, however the objective function will not be evaluated at the next iteration. The particle will probably be advected back into the domain at the next advance due to attraction by the cognitive and global memory.
HYPERSPHERICAL
The box bounds are wrapped around an :math:`\textit{ndim}`-dimensional hypersphere. As such a particle leaving through a lower bound will immediately re-enter through the corresponding upper bound and vice versa. The standard distance between particles is also modified accordingly.
FIXED
The particle rests on the boundary, with the corresponding dimensional velocity set to :math:`0.0`.
**'Constraint Norm'** : str
Default :math:`\text{} = \mathrm{L1}`
Determines with respect to which norm the constraint residuals should be constructed.
These are automatically scaled with respect to :math:`\textit{ncon}` as stated.
For the set of (scaled) violations :math:`\mathbf{e}`, these may be,
L1
The :math:`L^1` norm will be used, :math:`\left\lVert \mathbf{e}\right\rVert_1 = \frac{1}{\textit{ncon}}\sum_1^{\textit{ncon}}\left\lvert e_k\right\rvert`
L2
The :math:`L^2` norm will be used, :math:`\left\lVert \mathbf{e}\right\rVert_2 = \frac{1}{\textit{ncon}}\sqrt{\sum_1^{\textit{ncon}}e_k^2}`
L2SQ
The square of the :math:`L^2` norm will be used, :math:`\left\lVert \mathbf{e}\right\rVert_{2^2} = \frac{1}{\textit{ncon}}\sum_1^{\textit{ncon}}e_k^2`
LMAX
The :math:`L^{\infty }` norm will be used, :math:`\left\lVert \mathbf{e}\right\rVert_{\infty } = \textit{max}_{{0 < k\leq \textit{ncon}}}\left(\left\lvert e_k\right\rvert \right)`
**'Constraint Scale Maximum'** : float
Default :math:`\text{} = 1.0e6`
Internally, each constraint violation is scaled with respect to the maximum violation yet achieved for that constraint.
This option acts as a ceiling for this scale.
**'Constraint Scaling'** : str
Default :math:`\text{} = \mathrm{INITIAL}`
Determines whether to scale the constraints and objective function when constructing the penalty function.
OFF
Neither the constraint violations nor the objective will be scaled automatically. This should only be used if the constraints and objective are similarly scaled everywhere throughout the domain.
INITIAL
The maximum of the initial cognitive memories, :math:`\hat{f}_j` and :math:`\hat{\mathbf{e}}_j`, will be used to scale the objective function and constraint violations respectively.
ADAPTIVE
Initially, the maximum of the initial cognitive memories, :math:`\hat{f}_j` and :math:`\hat{\mathbf{e}}_j`, will be used to scale the objective function and constraint violations respectively. If a significant change is detected in the behaviour of the constraints or the objective, these will be rescaled with respect to the current state of the cognitive memory.
**'Constraint Superiority'** : float
Default :math:`\text{} = 0.01`
The minimum scaled improvement in the constraint violation for a location to be immediately superior to that in memory, regardless of the objective value.
**'Constraint Tolerance'** : float
Default :math:`\text{} = 10^{-4}`
The maximum scaled violation of the constraints for which a sample particle is considered comparable to the current global optimum.
Should this not be exceeded, then the current global optimum will be updated if the value of the objective function of the sample particle is superior.
**'Constraint Warning'** : str
Default :math:`\text{} = \texttt{'ON'}`
Activates or deactivates the error exit associated with the inability to completely satisfy all constraints, :math:`\mathrm{errno}` = 4.
It is advisable to deactivate this option if the exit :math:`\mathrm{errno}` = 4 is preferred in such cases.
OFF
:math:`\mathrm{errno}` = 4 will not be returned.
ON
:math:`\mathrm{errno}` = 4 will be returned if any constraints are sufficiently violated at the end of the simulation.
**'Distance Scaling'** : str
Default :math:`\text{} = \texttt{'ON'}`
Determines whether distances should be scaled by box widths.
ON
When a distance is calculated between :math:`\mathbf{x}` and :math:`\mathbf{y}`, a scaled :math:`L^2` norm is used.
.. math::
L^2\left(\mathbf{x}, \mathbf{y}\right) = \left(\sum_{\left\{i|\mathbf{u}_i\neq \ell_i,i\leq \textit{ndim}\right\}}\left(\frac{{x_i-y_i}}{{\mathbf{u}_i-\ell_i}}\right)^2\right)^{\frac{1}{2}}\text{.}
OFF
Distances are calculated as the standard :math:`L^2` norm without any rescaling.
.. math::
L^2\left(\mathbf{x}, \mathbf{y}\right) = \left(\sum_{{i = 1}}^{\textit{ndim}}\left(x_i-y_i\right)^2\right)^{\frac{1}{2}}\text{.}
**'Distance Tolerance'** : float
Default :math:`\text{} = 10^{-4}`
This is the distance, :math:`\textit{dtol}` between particles and the global optimum which must be reached for the particle to be considered converged, i.e., that any subsequent movement of such a particle cannot significantly alter the global optimum.
Once achieved the particle is reset into the box bounds to continue searching.
**'Function Precision'** : float
Default :math:`\text{} = \epsilon^{0.9}`
The argument defines :math:`\epsilon_r`, which is intended to be a measure of the accuracy with which the problem function :math:`F\left(\mathbf{x}\right)` can be computed.
If :math:`r < \epsilon` or :math:`r\geq 1`, the default value is used.
The value of :math:`\epsilon_r` should reflect the relative precision of :math:`1+\left\lvert F\left(\mathbf{x}\right)\right\rvert`; i.e., :math:`\epsilon_r` acts as a relative precision when :math:`\left\lvert F\right\rvert` is large, and as an absolute precision when :math:`\left\lvert F\right\rvert` is small.
For example, if :math:`F\left(\mathbf{x}\right)` is typically of order :math:`1000` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-6}`.
In contrast, if :math:`F\left(\mathbf{x}\right)` is typically of order :math:`10^{-4}` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-10}`.
The choice of :math:`\epsilon_r` can be quite complicated for badly scaled problems; see Module 8 of Gill `et al.` (1981) for a discussion of scaling techniques.
The default value is appropriate for most simple functions that are computed with full accuracy.
However when the accuracy of the computed function values is known to be significantly worse than full precision, the value of :math:`\epsilon_r` should be large enough so that no attempt will be made to distinguish between function values that differ by less than the error inherent in the calculation.
**'Local Boundary Restriction'** : float
Default :math:`\text{} = 0.5`
Contracts the box boundaries used by a box constrained local minimizer to, :math:`\left[\beta_l, \beta_u\right]`, containing the start point :math:`x`, where
.. math::
\begin{array}{c} \partial_i = r \times \left(\mathbf{u}_i-\ell_i\right) \\ \beta_l^i = \mathrm{max}\left(\ell_i, {x_i-\frac{\partial_i}{2}}\right) \\ \beta_u^i = \mathrm{min}\left(\mathbf{u}_i, {x_i+\frac{\partial_i}{2}}\right) \text{, }\quad i = 1,\ldots,\textit{ndim} \text{.} \end{array}
Smaller values of :math:`r` thereby restrict the size of the domain exposed to the local minimizer, possibly reducing the amount of work done by the local minimizer.
**'Local Interior Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``nlp_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Interior Major Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``nlp_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Exterior Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``nlp_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Exterior Major Iterations'** : int
The maximum number of iterations or function evaluations the chosen local minimizer will perform inside (outside) the main loop if applicable.
For the NAG minimizers these correspond to:
.. rst-class:: nag-rules-none
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================================+=======================+============================================================+============================================================+
|:meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` |:math:`\textit{maxcal}`|:math:`\textit{ndim}+10` |:math:`2\times \textit{ndim}+15` |
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>`|'Iteration Limit' |:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(50, {5\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` |'Major Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-----------------------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
Unless set, these are functions of the arguments passed to ``nlp_pso``.
Setting :math:`i = 0` will disable the local minimizer in the corresponding algorithmic region.
For example, setting :math:`\text{‘Local Interior Iterations'} = 0` and :math:`\text{‘Local Exterior Iterations'} = 30` will cause the algorithm to perform no local minimizations inside the main loop of the algorithm, and a local minimization with upto :math:`30` iterations after the main loop has been exited.
Note: currently :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` or :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` are restricted to using :math:`400\times \textit{ndim}` and :math:`50\times \textit{ndim}` as function evaluation limits respectively. This applies to both local minimizations inside and outside the main loop. They may still be deactivated in either phase by setting :math:`i = 0`, and may subsequently be reactivated in either phase by setting :math:`i > 0`.
**'Local Interior Tolerance'** : float
Default :math:`\text{} = 10^{-4}`
This is the tolerance provided to a local minimizer in the interior (exterior) of the main loop of the algorithm.
**'Local Exterior Tolerance'** : float
Default :math:`\text{} = 10^{-4}`
This is the tolerance provided to a local minimizer in the interior (exterior) of the main loop of the algorithm.
**'Local Interior Minor Iterations'** : int
Where applicable, the secondary number of iterations the chosen local minimizer will use inside (outside) the main loop.
Currently the relevant default values are:
.. rst-class:: nag-rules-none
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================+=======================+============================================================+============================================================+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>`|'Minor Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
**'Local Exterior Minor Iterations'** : int
Where applicable, the secondary number of iterations the chosen local minimizer will use inside (outside) the main loop.
Currently the relevant default values are:
.. rst-class:: nag-rules-none
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
|Minimizer |Argument/option |Default Interior |Default Exterior |
+=============================================================+=======================+============================================================+============================================================+
|:meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>`|'Minor Iteration Limit'|:math:`\mathrm{max}\left(10, {2\times \textit{ndim}}\right)`|:math:`\mathrm{max}\left(30, {3\times \textit{ndim}}\right)`|
+-------------------------------------------------------------+-----------------------+------------------------------------------------------------+------------------------------------------------------------+
**'Local Minimizer'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Allows for a choice of submodule :mod:`~naginterfaces.library.opt` functions to be used as a coupled, dedicated local minimizer.
:math:`\text{‘Local Minimizer'} = \texttt{'OFF'}`
No local minimization will be performed in either the INTERIOR or EXTERIOR sections of the algorithm.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_simplex'}`
Use :meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>` as the local minimizer. This does not require the calculation of derivatives.
On a call to :math:`\mathrm{objfun}` during a local minimization, :math:`\mathrm{mode} = 5`.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.bounds_mod_deriv_easy'}`
Use :meth:`opt.bounds_mod_deriv_easy <naginterfaces.library.opt.bounds_mod_deriv_easy>` as the local minimizer. This requires the calculation of derivatives in :math:`\mathrm{objfun}`, as indicated by :math:`\mathrm{mode}`.
The box bounds forwarded to this function from ``nlp_pso`` will have been acted upon by 'Local Boundary Restriction'.
As such, the domain exposed may be greatly smaller than that provided to ``nlp_pso``.
Accurate derivatives must be provided to this function, and will not be approximated internally.
Each iteration of this local minimizer also requires the calculation of both the objective function and its derivative.
Hence on a call to :math:`\mathrm{objfun}` during a local minimization, :math:`\mathrm{mode} = 7`.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.bounds_quasi_func_easy'}`
Use :meth:`opt.bounds_quasi_func_easy <naginterfaces.library.opt.bounds_quasi_func_easy>` as the local minimizer. This does not require the calculation of derivatives.
On a call to :math:`\mathrm{objfun}` during a local minimization, :math:`\mathrm{mode} = 5`.
The box bounds forwarded to this function from ``nlp_pso`` will have been acted upon by 'Local Boundary Restriction'.
As such, the domain exposed may be greatly smaller than that provided to ``nlp_pso``.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.uncon_conjgrd_comp'}`
Use :meth:`opt.uncon_conjgrd_comp <naginterfaces.library.opt.uncon_conjgrd_comp>` as the local minimizer.
Accurate derivatives must be provided, and will not be approximated internally.
Additionally, each call to :math:`\mathrm{objfun}` during a local minimization will require either the objective to be evaluated alone, or both the objective and its gradient to be evaluated.
Hence on a call to :math:`\mathrm{objfun}`, :math:`\mathrm{mode} = 5` or :math:`7`.
:math:`\text{‘Local Minimizer'} = \texttt{'opt.nlp1_solve'}`
Use :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` as the local minimizer. This operates such that any derivatives of either the objective function or the constraint Jacobian, which you cannot supply, will be approximated internally using finite differences.
Either, the objective, objective gradient, or both may be requested during a local minimization, and as such on a call to :math:`\mathrm{objfun}`, :math:`\mathrm{mode} = 1`, :math:`2` or :math:`5`.
The box bounds forwarded to this function from ``nlp_pso`` will have been acted upon by 'Local Boundary Restriction'.
As such, the domain exposed may be greatly smaller than that provided to ``nlp_pso``.
**'Maximum Function Evaluations'** : int
Default :math:`= \textit{Imax}`
The maximum number of evaluations of the objective function.
When reached this will return :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 6`.
**'Maximum Iterations Completed'** : int
Default :math:`\text{} = 1000\times \textit{ndim}`
The maximum number of complete iterations that may be performed.
Once exceeded ``nlp_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 5`.
Unless set, this adapts to the parameters passed to ``nlp_pso``.
**'Maximum Iterations Static'** : int
Default :math:`\text{} = 100`
The maximum number of iterations without any improvement to the current global optimum.
If exceeded ``nlp_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 4`.
This exit will be hindered by setting 'Maximum Iterations Static Particles' to larger values.
**'Maximum Iterations Static Particles'** : int
Default :math:`\text{} = 0`
The minimum number of particles that must have converged to the current optimum before the function may exit due to 'Maximum Iterations Static' with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 4`.
**'Maximum Particles Converged'** : int
Default :math:`= \textit{Imax}`
The maximum number of particles that may converge to the current optimum.
When achieved, ``nlp_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 3`.
This exit will be hindered by setting '**Repulsion**' options, as these cause the swarm to re-expand.
**'Maximum Particles Reset'** : int
Default :math:`= \textit{Imax}`
The maximum number of particles that may be reset after converging to the current optimum.
Once achieved no further particles will be reset, and any particles within 'Distance Tolerance' of the global optimum will continue to evolve as normal.
**'Maximum Variable Velocity'** : float
Default :math:`\text{} = 0.25`
Along any dimension :math:`j`, the absolute velocity is bounded above by :math:`\left\lvert \mathbf{v}_j\right\rvert \leq r\times \left(\mathbf{u}_j-\ell_j\right) = \mathbf{V}_{\textit{max}}`.
Very low values will greatly increase convergence time.
There is no upper limit, although larger values will allow more particles to be advected out of the box bounds, and values greater than :math:`4.0` may cause significant and potentially unrecoverable swarm divergence.
**'Objective Scale'** : float
Default :math:`\text{} = 1.0`
The initial scale for the objective function.
This will remain fixed if :math:`\text{‘Objective Scaling'} = \textit{USER}` is selected.
**'Objective Scaling'** : str
Default :math:`\text{} = \mathrm{MAXIMUM}`
The method of (re)scaling applied to the objective function when the function detects a significant difference between the scale and the global and cognitive memory (:math:`\tilde{f}` and :math:`\hat{f}_j`).
This only has an effect when :math:`\textit{ncon} > 0` and 'Constraint Scaling' is active.
MAXIMUM
The objective is rescaled with respect to the maximum absolute value of the objective in the cognitive and global memory.
MEAN
The objective is rescaled with respect to the mean absolute value of the objective in the cognitive and global memory.
USER
The scale remains fixed at the value set using 'Objective Scale'.
**'Optimize'** : str
Default :math:`\text{} = \mathrm{MINIMIZE}`
Determines whether to maximize or minimize the objective function, or ignore the objective and search for a constrained point.
MINIMIZE
The objective function will be minimized.
MAXIMIZE
The objective function will be maximized. This is accomplished by minimizing the negative of the objective.
CONSTRAINTS
The objective function will be ignored, and the algorithm will attempt to find a feasible point given the provided constraints. The objective function will be evaluated at the best point found with regards to constraint violations, and the final positions returned in :math:`\mathrm{xbest}`. The objective will be calculated at the best point found in terms of constraints only. Should a constrained point be found, ``nlp_pso`` will exit with no exception or warning is raised and :math:`\mathrm{inform} = 6`.
**'Repeatability'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Allows for the same random number generator seed to be used for every call to ``nlp_pso``. :math:`\text{‘Repeatability'} = \texttt{'OFF'}` is recommended in general.
OFF
The internal generation of random numbers will be nonrepeatable.
ON
The same seed will be used.
**'Repulsion Finalize'** : int
Default :math:`= \textit{Imax}`
The number of iterations performed in a repulsive phase before re-contraction.
This allows a re-diversified swarm to contract back toward the current optimum, allowing for a finer search of the near optimum space.
**'Repulsion Initialize'** : int
Default :math:`= \textit{Imax}`
The number of iterations without any improvement to the global optimum before the algorithm begins a repulsive phase.
This phase allows the particle swarm to re-expand away from the current optimum, allowing more of the domain to be investigated.
The repulsive phase is automatically ended if a superior optimum is found.
**'Repulsion Particles'** : int
Default :math:`\text{} = 0`
The number of particles required to have converged to the current optimum before any repulsive phase may be initialized.
This will prevent repulsion before a satisfactory search of the near optimum area has been performed, which may happen for large dimensional problems.
**'Seed'** : int
Default :math:`\text{} = 0`
Sets the random number generator seed to be used when :math:`\text{‘Repeatability'} = \texttt{'ON'}`.
If set to 0, the default seed will be used.
If not, the absolute value of 'Seed' will be used to generate the random number generator seed.
**'Start'** : str
Default :math:`\text{} = \mathrm{COLD}`
Used to affect the initialization of the function.
COLD
The random number generators and all initialization data will be generated internally. The variables :math:`\mathrm{xbest}`, :math:`\mathrm{fbest}` and :math:`\mathrm{cbest}` need not be set.
WARM
You must supply the initial best location, function and constraint violation values :math:`\mathrm{xbest}`, :math:`\mathrm{fbest}` and :math:`\mathrm{cbest}`. This option is recommended if you already have a data set you wish to improve upon.
**'Swarm Standard Deviation'** : float
Default :math:`\text{} = 0.1`
The target standard deviation of the particle distances from the current optimum. Once the standard deviation is below this level, ``nlp_pso`` will exit with :math:`\mathrm{errno}` = 1 and :math:`\mathrm{inform} = 2`.
This criterion will be penalized by the use of '**Repulsion**' options, as these cause the swarm to re-expand, increasing the standard deviation of the particle distances from the best point.
**'Target Objective'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Activate or deactivate the use of a target value as a finalization criterion.
If active, then once the supplied target value for the objective function is found (beyond the first iteration if 'Target Warning' is active) ``nlp_pso`` will exit with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
Other than checking for feasibility only (:math:`\text{‘Optimize'} = \textit{CONSTRAINTS}`), this is the only finalization criterion that guarantees that the algorithm has been successful.
If the target value was achieved at the initialization phase or first iteration and 'Target Warning' is active, ``nlp_pso`` will exit with :math:`\mathrm{errno}` = 2.
This option may take any real value :math:`r`, or the character ON/OFF as well as DEFAULT.
If this option is queried using :meth:`optget`, the current value of :math:`r` will be returned in :math:`\textit{rvalue}`, and :math:`\textit{cvalue}` will indicate whether this option is ON or OFF.
The behaviour of the option is as follows:
:math:`r`
Once a point is found with an objective value within the 'Target Objective Tolerance' of :math:`r`, ``nlp_pso`` will exit successfully with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
OFF
The current value of :math:`r` will remain stored, however it will not be used as a finalization criterion.
ON
The current value of :math:`r` stored will be used as a finalization criterion.
DEFAULT
The stored value of :math:`r` will be reset to its default value (:math:`0.0`), and this finalization criterion will be deactivated.
**'Target Objective Value'** : float
Default :math:`\text{} = 0.0`
Activate or deactivate the use of a target value as a finalization criterion.
If active, then once the supplied target value for the objective function is found (beyond the first iteration if 'Target Warning' is active) ``nlp_pso`` will exit with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
Other than checking for feasibility only (:math:`\text{‘Optimize'} = \textit{CONSTRAINTS}`), this is the only finalization criterion that guarantees that the algorithm has been successful.
If the target value was achieved at the initialization phase or first iteration and 'Target Warning' is active, ``nlp_pso`` will exit with :math:`\mathrm{errno}` = 2.
This option may take any real value :math:`r`, or the character ON/OFF as well as DEFAULT.
If this option is queried using :meth:`optget`, the current value of :math:`r` will be returned in :math:`\textit{rvalue}`, and :math:`\textit{cvalue}` will indicate whether this option is ON or OFF.
The behaviour of the option is as follows:
:math:`r`
Once a point is found with an objective value within the 'Target Objective Tolerance' of :math:`r`, ``nlp_pso`` will exit successfully with no exception or warning is raised and :math:`\mathrm{inform} = 1`.
OFF
The current value of :math:`r` will remain stored, however it will not be used as a finalization criterion.
ON
The current value of :math:`r` stored will be used as a finalization criterion.
DEFAULT
The stored value of :math:`r` will be reset to its default value (:math:`0.0`), and this finalization criterion will be deactivated.
**'Target Objective Safeguard'** : float
Default :math:`\text{} = 10.0\epsilon`
If you have given a target objective value to reach in :math:`\textit{objval}` (the value of the option 'Target Objective Value'), :math:`\textit{objsfg}` sets your desired safeguarded termination tolerance, for when :math:`\textit{objval}` is close to zero.
**'Target Objective Tolerance'** : float
Default :math:`\text{} = 0.0`
The optional tolerance to a user-specified target value.
**'Target Warning'** : str
Default :math:`\text{} = \texttt{'OFF'}`
Activates or deactivates the error exit associated with the target value being achieved before entry into the main loop of the algorithm, :math:`\mathrm{errno}` = 2.
OFF
No error will be returned, and the function will exit normally.
ON
An error will be returned if the target objective is reached prematurely, and the function will exit with :math:`\mathrm{errno}` = 2.
**'Verify Gradients'** : str
Default :math:`\text{} = \texttt{'ON'}`
Adjusts the level of gradient checking performed when gradients are required.
Gradient checks are only performed on the first call to the chosen local minimizer if it requires gradients.
There is no guarantee that the gradient check will be correct, as the finite differences used in the gradient check are themselves subject to inaccuracies.
OFF
No gradient checking will be performed.
ON
A cheap gradient check will be performed on both the gradients corresponding to the objective through :math:`\mathrm{objfun}` and those provided via the constraint Jacobian through :math:`\mathrm{confun}`.
OBJECTIVE
A more expensive gradient check will be performed on the gradients corresponding to the objective :math:`\mathrm{objfun}`. The gradients of the constraints will not be checked.
CONSTRAINTS
A more expensive check will be performed on the elements of :math:`\mathrm{cjac}` provided via :math:`\mathrm{confun}`. The objective gradient will not be checked.
FULL
A more expensive check will be performed on both the gradient of the objective and the constraint Jacobian.
**'Weight Decrease'** : str
Default :math:`\text{} = \mathrm{INTEREST}`
Determines how particle weights decrease.
OFF
Weights do not decrease.
INTEREST
Weights decrease through compound interest as :math:`w_{{\textit{IT}+1}} = w_{\textit{IT}}\left(1-W_{\textit{val}}\right)`, where :math:`W_{\textit{val}}` is the 'Weight Value' and :math:`\textit{IT}` is the current number of iterations.
LINEAR
Weights decrease linearly following :math:`w_{{\textit{IT}+1}} = w_{\textit{IT}}-\textit{IT}\times \left(W_{\textit{max}}-W_{\textit{min}}\right)/\textit{IT}_{\textit{max}}`, where :math:`\textit{IT}` is the iteration number and :math:`\textit{IT}_{\textit{max}}` is the maximum number of iterations as set by 'Maximum Iterations Completed'.
**'Weight Initial'** : float
Default :math:`\text{} = W_{\textit{max}}`
The initial value of any particle's inertial weight, :math:`W_{\textit{ini}}`, or the minimum possible initial value if initial weights are randomized.
When set, this will override :math:`\text{‘Weight Initialize'} = \texttt{'RANDOMIZED'}` or :math:`\texttt{'MAXIMUM'}`, and as such these must be set afterwards if so desired.
**'Weight Initialize'** : str
Default :math:`\text{} = \mathrm{MAXIMUM}`
Determines how the initial weights are distributed.
INITIAL
All weights are initialized at the initial weight, :math:`W_{\textit{ini}}`, if set. If 'Weight Initial' has not been set, this will be the maximum weight, :math:`W_{\textit{max}}`.
MAXIMUM
All weights are initialized at the maximum weight, :math:`W_{\textit{max}}`.
RANDOMIZED
Weights are uniformly distributed in :math:`\left(W_{\textit{min}}, W_{\textit{max}}\right)` or :math:`\left(W_{\textit{ini}}, W_{\textit{max}}\right)` if 'Weight Initial' has been set.
**'Weight Maximum'** : float
Default :math:`\text{} = 1.0`
The maximum particle weight, :math:`W_{\textit{max}}`.
**'Weight Minimum'** : float
Default :math:`\text{} = 0.1`
The minimum achievable weight of any particle, :math:`W_{\textit{min}}`.
Once achieved, no further weight reduction is possible.
**'Weight Reset'** : str
Default :math:`\text{} = \mathrm{MAXIMUM}`
Determines how particle weights are re-initialized.
INITIAL
Weights are re-initialized at the initial weight if set. If 'Weight Initial' has not been set, this will be the maximum weight.
MAXIMUM
Weights are re-initialized at the maximum weight.
RANDOMIZED
Weights are uniformly distributed in :math:`\left(W_{\textit{min}}, W_{\textit{max}}\right)` or :math:`\left(W_{\textit{ini}}, W_{\textit{max}}\right)` if 'Weight Initial' has been set.
**'Weight Value'** : float
Default :math:`\text{} = 0.01`
The constant :math:`W_{\textit{val}}` used with :math:`\text{‘Weight Decrease'} = \texttt{'INTEREST'}`.
**'SMP Callback Thread Safe'** : str
Default :math:`\text{} = \mathrm{WARNING}`
Declare that the callback functions you provide are or are not thread safe.
In particular, this indicates that access to the shared memory arrays :math:`\mathrm{iuser}` and :math:`\mathrm{ruser}` from within your provided callbacks is done in a thread safe manner. If these arrays are just used to pass constant data, then you may assume they are thread safe. If these are also used for workspace, or passing variable data such as random number generator seeds, then you must ensure these are accessed and updated safely. Whilst this can be done using OpenMP critical sections, we suggest their use is minimized to prevent unnecessary bottlenecks, and that instead individual threads have access to independent subsections of the provided arrays where possible.
YES
The callback functions have been programmed in a thread safe way. The algorithm will use ``OMP_NUM_THREADS`` threads.
NO
The callback functions are not thread safe. Setting this option will force the algorithm to run on a single thread only, and is advisable only for debugging purposes, or if you wish to parallelize your callback functions.
WARNING
This will cause an immediate exit from ``nlp_pso`` with :math:`\mathrm{errno}` = 51 if multiple threads are detected. This is to inform you that you have not declared the callback functions either to be thread safe, or that they are thread unsafe and you wish the algorithm to run in serial.
**'SMP Local Minimizer External'** : str
Default :math:`\text{} = \mathrm{ALL}`
Determines how many threads will attempt to locally minimize the best found solution after the function has exited the main loop.
MASTER
Only the master thread will attempt to find any improvement. The local minimization will be launched from the best known solution. All other threads will remain effectively idle.
ALL
The master thread will perform a local minimization from the best known solution, while all other threads will perform a local minimization from randomly generated perturbations of the best known solution, increasing the chance of an improvement. Assuming all local minimizations will take approximately the same amount of computation, this will be effectively free in terms of real time. It will however increase the number of function evaluations performed.
**'SMP Monitor'** : str
Default :math:`\text{} = \mathrm{SINGLE}`
Determines whether the user-supplied function :math:`\mathrm{monmod}` is invoked once every sub-iteration each thread performs, or only once by a single thread after all threads have completed at least one sub-iteration.
SINGLE
Only one thread will invoke :math:`\mathrm{monmod}`, after all threads have performed at least one sub-iteration.
ALL
Each thread will invoke :math:`\mathrm{monmod}` each time it completes a sub-iteration. If you wish to alter :math:`\mathrm{x}` using :math:`\mathrm{monmod}` you should use this option, as :math:`\mathrm{monmod}` will only receive the arrays :math:`\mathrm{x}`, :math:`\mathrm{xbest}`, :math:`\mathrm{fbest}` and :math:`\mathrm{cbest}` private to the calling thread.
**'SMP Monmod'** : str
Default :math:`\text{} = \mathrm{SINGLE}`
Determines whether the user-supplied function :math:`\mathrm{monmod}` is invoked once every sub-iteration each thread performs, or only once by a single thread after all threads have completed at least one sub-iteration.
SINGLE
Only one thread will invoke :math:`\mathrm{monmod}`, after all threads have performed at least one sub-iteration.
ALL
Each thread will invoke :math:`\mathrm{monmod}` each time it completes a sub-iteration. If you wish to alter :math:`\mathrm{x}` using :math:`\mathrm{monmod}` you should use this option, as :math:`\mathrm{monmod}` will only receive the arrays :math:`\mathrm{x}`, :math:`\mathrm{xbest}`, :math:`\mathrm{fbest}` and :math:`\mathrm{cbest}` private to the calling thread.
**'SMP Subswarm'** : int
Default :math:`\text{} = 1`
Determines how many threads support a particle subswarm.
This is an extra collection of particles constrained to search only within a hypercube of edge length :math:`10.0\times \text{‘Distance Tolerance'}` of the best point known to an individual thread.
This may improve the number of iterations required to find a provided target, particularly if no local minimizer is in use.
If :math:`i\leq 0`, then this will be disabled on all the threads.
If :math:`i\geq \texttt{OMP_NUM_THREADS}`, then all the threads will support a particle subswarm.
**'SMP Thread Overrun'** : int
Default :math:`\text{} = \textit{Imax}`
This option provides control over the level of asynchronicity present in a simulation.
In particular, a barrier synchronization between all threads is performed if any thread completes :math:`i` sub-iterations more than the slowest thread, causing all threads to be exposed to the current best solution.
Allowing asynchronous behaviour does however allow individual threads to focus on different global optimum candidates some of the time, which can inhibit convergence to unwanted sub-optima.
It also allows for threads to continue searching when other threads are completing sub-iterations at a slower rate.
If :math:`i < 1`, the algorithm will force a synchronization between threads at the end of each iteration.
.. _e05sb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\geq 1`.
(`errno` :math:`12`)
On entry, :math:`\textit{npar} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{npar}\geq 5\times \mathbf{num\_threads}`, where **num_threads** is the value returned by the OpenMP environment variable ``OMP_NUM_THREADS``, or **num_threads** is :math:`1` for a serial version of this function.
(`errno` :math:`13`)
On entry, :math:`\textit{ncon} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ncon}\geq 0`.
(`errno` :math:`14`)
On entry, :math:`\mathrm{bl}[i] = \mathrm{bu}[i]` for all box bounds :math:`i`.
Constraint: :math:`\mathrm{bu}[i] > \mathrm{bl}[i]` for at least one box bound :math:`i`.
(`errno` :math:`14`)
On entry, :math:`\mathrm{bl}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{bu}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{bu}[i]\geq \mathrm{bl}[i]` for all :math:`i`.
(`errno` :math:`17`)
``nlp_pso`` has been called with :math:`\textit{ncon} > 0` and :math:`\mathrm{confun}\text{ is }\mathbf{None}`. Only use **None** with :math:`\textit{ncon} = 0`.
(`errno` :math:`18`)
The option :math:`\text{‘Optimize'} = \texttt{'CONSTRAINTS'}` is active, however :math:`\textit{ncon} = 0`.
(`errno` :math:`19`)
Error :math:`\langle\mathit{\boldsymbol{value}}\rangle` occurred whilst adjusting to interior local minimizer options.
(`errno` :math:`19`)
Error :math:`\langle\mathit{\boldsymbol{value}}\rangle` occurred whilst adjusting to exterior local minimizer options.
(`errno` :math:`21`)
Either the option arrays have not been initialized for ``nlp_pso``, or they have become corrupted.
(`errno` :math:`51`)
Multiple SMP threads have been detected; however, the option 'SMP Callback Thread Safe' has not been set.
Set :math:`\text{‘SMP Callback Thread Safe'} = \texttt{'YES'}` if the provided callbacks are thread safe.
Set :math:`\text{‘SMP Callback Thread Safe'} = \texttt{'NO'}` if the provided callbacks are not thread safe, to force serial execution.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
A finalization criterion was reached that cannot guarantee success.
On exit, :math:`\mathrm{inform} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{fbest}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle` but :math:`\text{‘Target Objective Value'} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
After initialization :math:`\mathrm{fb} = \langle\mathit{\boldsymbol{value}}\rangle` but :math:`\text{‘Target Objective Value'} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Target :math:`\langle\mathit{\boldsymbol{value}}\rangle` achieved after the first iteration.
:math:`\mathrm{fb} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
The option :math:`\text{‘Optimize'} = \texttt{'CONSTRAINTS'}` has been set and the first point sampled satisfied all constraints.
(`errno` :math:`4`)
Unable to locate strictly feasible point. :math:`\langle\mathit{\boldsymbol{value}}\rangle` constraints remain violated. This exit may be suppressed using the option 'Constraint Warning'.
(`errno` :math:`32`)
Derivative checks indicate possible errors in the supplied derivatives.
**NagCallbackTerminateWarning**
(`errno` :math:`3`)
User requested exit :math:`\langle\mathit{\boldsymbol{value}}\rangle` during call to :math:`\mathrm{objfun}`.
(`errno` :math:`3`)
User requested exit :math:`\langle\mathit{\boldsymbol{value}}\rangle` during call to :math:`\mathrm{confun}`.
(`errno` :math:`3`)
User requested exit :math:`\langle\mathit{\boldsymbol{value}}\rangle` during call to :math:`\mathrm{monmod}`.
.. _e05sb-py2-py-notes:
**Notes**
``nlp_pso`` uses a stochastic method based on Particle Swarm Optimization (PSO) to search for the global optimum of a nonlinear function :math:`F`, subject to a set of bound constraints on the variables, and optionally a set of general nonlinear constraints.
In the PSO algorithm (see `Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05sbf.html#algdetails>`__), a set of particles is generated in the search space, and advances each iteration to (hopefully) better positions using a heuristic velocity based upon `inertia`, `cognitive memory` and `global memory`.
The inertia is provided by a decreasingly weighted contribution from a particles current velocity, the cognitive memory refers to the best candidate found by an individual particle and the global memory refers to the best candidate found by all the particles.
This allows for a global search of the domain in question.
Further, this may be coupled with a selection of local minimization functions, which may be called during the iterations of the heuristic algorithm, the `interior` phase, to hasten the discovery of locally optimal points, and after the heuristic phase has completed to attempt to refine the final solution, the `exterior` phase.
Different options may be set for the local optimizer in each phase.
Without loss of generality, the problem is assumed to be stated in the following form:
.. math::
\textit{minimize}_{{\mathbf{x} \in R^{\textit{ndim}}}} F\left(\mathbf{x}\right)\quad \text{ subject to }\quad \ell \leq \begin{pmatrix}\mathbf{x}\\\mathbf{c}\left(\mathbf{x}\right)\end{pmatrix}\leq \mathbf{u}\text{,}
where the objective :math:`F\left(\mathbf{x}\right)` is a scalar function, :math:`\mathbf{c}\left(\mathbf{x}\right)` is a vector of scalar constraint functions, :math:`\mathbf{x}` is a vector in :math:`R^{\textit{ndim}}` and the vectors :math:`\ell \leq \mathbf{u}` are lower and upper bounds respectively for the :math:`\textit{ndim}` variables and :math:`\textit{ncon}` constraints.
Both the objective function and the :math:`\textit{ncon}` constraints may be nonlinear.
Continuity of :math:`F`, and the functions :math:`\mathbf{c}\left(\mathbf{x}\right)`, is not essential.
For functions which are smooth and primarily unimodal, faster solutions will almost certainly be achieved by using submodule :mod:`~naginterfaces.library.opt` functions directly.
For functions which are smooth and multi-modal, gradient dependent local minimization functions may be coupled with ``nlp_pso``.
For multi-modal functions for which derivatives cannot be provided, particularly functions with a significant level of noise in their evaluation, ``nlp_pso`` should be used either alone, or coupled with :meth:`opt.uncon_simplex <naginterfaces.library.opt.uncon_simplex>`.
For heavily constrained problems, ``nlp_pso`` should either be used alone, or coupled with :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` provided the function and the constraints are sufficiently smooth.
The :math:`\textit{ndim}` lower and upper box bounds on the variable :math:`\mathbf{x}` are included to initialize the particle swarm into a finite hypervolume, although their subsequent influence on the algorithm is user determinable (see the option 'Boundary' in :ref:`Other Parameters <e05sb-py2-py-other_params>`).
It is strongly recommended that sensible bounds are provided for all variables and constraints.
``nlp_pso`` may also be used to maximize the objective function, or to search for a feasible point satisfying the simple bounds and general constraints (see the option 'Optimize').
Due to the nature of global optimization, unless a predefined target is provided, there is no definitive way of knowing when to end a computation.
As such several stopping heuristics have been implemented into the algorithm.
If any of these is achieved, ``nlp_pso`` will exit with :math:`\mathrm{errno}` = 1, and the parameter :math:`\mathrm{inform}` will indicate which criteria was reached.
See :math:`\mathrm{inform}` for more information.
In addition, you may provide your own stopping criteria through :math:`\mathrm{monmod}`, :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
:meth:`bnd_pso` provides a simpler interface, without the inclusion of general nonlinear constraints.
.. _e05sb-py2-py-references:
**References**
Gill, P E, Murray, W and Wright, M H, 1981, `Practical Optimization`, Academic Press
Kennedy, J and Eberhart, R C, 1995, `Particle Swarm Optimization`, Proceedings of the 1995 IEEE International Conference on Neural Networks, 1942--1948
Koh, B, George, A D, Haftka, R T and Fregly, B J, 2006, `Parallel Asynchronous Particle Swarm Optimization`, International Journal for Numerical Methods in Engineering (67(4)), 578--595
Vaz, A I and Vicente, L N, 2007, `A Particle Swarm Pattern Search Method for Bound Constrained Global Optimization`, Journal of Global Optimization (39(2)), 197--219, Kluwer Academic Publishers
"""
raise NotImplementedError
[docs]def nlp_multistart_sqp(n, ncnln, bl, bu, objfun, npts, repeat, nb, comm, a=None, confun=None, start=None, data=None, io_manager=None, spiked_sorder='C'):
r"""
``nlp_multistart_sqp`` is designed to find the global minimum of an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.
Note: this function uses optional algorithmic parameters, see also: :meth:`optset`.
.. _e05uc-py2-py-doc:
For full information please refer to the NAG Library document for e05uc
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html
.. _e05uc-py2-py-parameters:
**Parameters**
**n** : int
:math:`n`, the number of variables.
**ncnln** : int
:math:`n_N`, the number of nonlinear constraints.
**bl** : float, array-like, shape :math:`\left(\mathrm{n}+\textit{nclin}+\mathrm{ncnln}\right)`
:math:`\mathrm{bl}` must contain the lower bounds for all the constraints.
**bu** : float, array-like, shape :math:`\left(\mathrm{n}+\textit{nclin}+\mathrm{ncnln}\right)`
:math:`\mathrm{bu}` must contain the upper bounds for all the constraints.
**objfun** : callable (objf, objgrd) = objfun(mode, x, objgrd, nstate, data=None)
:math:`\mathrm{objfun}` must calculate the objective function :math:`F\left(x\right)` and (optionally) its gradient :math:`g\left(x\right) = \frac{{\partial F}}{{\partial x}}` for a specified :math:`n`-vector :math:`x`.
**Parameters**
**mode** : int
Indicates which values must be assigned during each call of :math:`\mathrm{objfun}`. Only the following values need be assigned:
:math:`\mathrm{mode} = 0`
:math:`\mathrm{objf}`.
:math:`\mathrm{mode} = 1`
All available elements of :math:`\mathrm{objgrd}`.
:math:`\mathrm{mode} = 2`
:math:`\mathrm{objf}` and all available elements of :math:`\mathrm{objgrd}`.
**x** : float, ndarray, shape :math:`\left(n\right)`
:math:`x`, the vector of variables at which the objective function and/or all available elements of its gradient are to be evaluated.
**objgrd** : float, ndarray, shape :math:`\left(n\right)`
The elements of :math:`\mathrm{objgrd}` are set to special values which enable ``nlp_multistart_sqp`` to detect whether they are changed by :math:`\mathrm{objfun}`.
**nstate** : int
If :math:`\mathrm{nstate} = 1` then ``nlp_multistart_sqp`` is calling :math:`\mathrm{objfun}` for the first time on the current local optimization problem. This argument setting allows you to save computation time if certain data must be calculated only once.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**objf** : float
If :math:`\mathrm{mode} = 0` or :math:`2`, :math:`\mathrm{objf}` must be set to the value of the objective function at :math:`x`.
**objgrd** : float, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{mode} = 1` or :math:`2`, :math:`\mathrm{objgrd}` must return the available elements of the gradient evaluated at :math:`x`.
**npts** : int
The number of different starting points to be generated and used. The more points used, the more likely that the best returned solution will be a global minimum.
**repeat** : bool
Is passed as an argument to :math:`\mathrm{start}` and may be used to initialize a random number generator to a repeatable, or non-repeatable, sequence.
**nb** : int
The number of solutions to be returned. The function saves up to :math:`\mathrm{nb}` local minima ordered by increasing value of the final objective function. If the defining criterion for 'best solution' is only that the value of the objective function is as small as possible then :math:`\mathrm{nb}` should be set to :math:`1`. However, if you want to look at other solutions that may have desirable properties then setting :math:`\mathrm{nb} > 1` will produce :math:`\mathrm{nb}` local minima, ordered by increasing value of their objective functions at the minima.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`optset`.
**a** : None or float, array-like, shape :math:`\left(\textit{nclin}, :\right)`, optional
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\textit{nclin} > 0`: :math:`\mathrm{n}`; otherwise: :math:`1`.
The matrix :math:`A_L` of general linear constraints in `(1) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#eqn1>`__. That is, the :math:`\textit{i}`\ th row contains the coefficients of the :math:`\textit{i}`\ th general linear constraint, for :math:`\textit{i} = 1,2,\ldots,\textit{nclin}`.
**confun** : None or callable (c, cjsl) = confun(mode, needc, x, cjsl, nstate, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
:math:`\mathrm{confun}` must calculate the vector :math:`c\left(x\right)` of nonlinear constraint functions and (optionally) its Jacobian (:math:`\text{} = \frac{{\partial c}}{{\partial x}}`) for a specified :math:`n`-element vector :math:`x`. If there are no nonlinear constraints (i.e., :math:`\mathrm{ncnln} = 0`), :math:`\mathrm{confun}` will never be called by ``nlp_multistart_sqp`` and :math:`\mathrm{confun}` may be **None**. If there are nonlinear constraints, the first call to :math:`\mathrm{confun}` will occur before the first call to :math:`\mathrm{objfun}`.
**Parameters**
**mode** : int
Indicates which values must be assigned during each call of :math:`\mathrm{confun}`. Only the following values need be assigned, for each value of :math:`i` such that :math:`\mathrm{needc}[i-1] > 0`:
:math:`\mathrm{mode} = 0`
:math:`\mathrm{c}[i-1]`.
:math:`\mathrm{mode} = 1`
All available elements in the :math:`i`\ th row of :math:`\mathrm{cjsl}`.
:math:`\mathrm{mode} = 2`
:math:`\mathrm{c}[i-1]` and all available elements in the :math:`i`\ th row of :math:`\mathrm{cjsl}`.
**needc** : int, ndarray, shape :math:`\left(\textit{ncnln}\right)`
The indices of the elements of :math:`\mathrm{c}` and/or :math:`\mathrm{cjsl}` that must be evaluated by :math:`\mathrm{confun}`. If :math:`\mathrm{needc}[i-1] > 0`, :math:`\mathrm{c}[i-1]` and/or the available elements of the :math:`i`\ th row of :math:`\mathrm{cjsl}` (see argument :math:`\mathrm{mode}`) must be evaluated at :math:`x`.
**x** : float, ndarray, shape :math:`\left(n\right)`
:math:`x`, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
**cjsl** : float, ndarray, shape :math:`\left(\textit{ncnln}, n\right)`
:math:`\mathrm{cjsl}` may be regarded as a two-dimensional 'slice' of the three-dimensional array :math:`\mathrm{cjac}` of ``nlp_multistart_sqp``.
Unless :math:`\text{‘Derivative Level'} = 2` or :math:`3` (the default setting is :math:`\text{‘Derivative Level'} = 3`), the elements of :math:`\mathrm{cjsl}` are set to special values which enable ``nlp_multistart_sqp`` to detect whether they are changed by :math:`\mathrm{confun}`.
**nstate** : int
If :math:`\mathrm{nstate} = 1` then ``nlp_multistart_sqp`` is calling :math:`\mathrm{confun}` for the first time on the current local optimization problem. This argument setting allows you to save computation time if certain data must be calculated only once.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**c** : float, array-like, shape :math:`\left(\textit{ncnln}\right)`
If :math:`\mathrm{needc}[k-1] > 0` and :math:`\mathrm{mode} = 0` or :math:`2`, :math:`\mathrm{c}[k-1]` must contain the value of :math:`c_k\left(x\right)`. The remaining elements of :math:`\mathrm{c}`, corresponding to the non-positive elements of :math:`\mathrm{needc}`, need not be set.
**cjsl** : float, array-like, shape :math:`\left(\textit{ncnln}, n\right)`
If :math:`\mathrm{needc}[k-1] > 0` and :math:`\mathrm{mode} = 1` or :math:`2`, the :math:`k`\ th row of :math:`\mathrm{cjsl}` must contain the available elements of the vector :math:`\nabla c_k` given by
.. math::
\nabla c_k = \left(\frac{{\partial c_k}}{{\partial x_1}},\frac{{\partial c_k}}{{\partial x_2}},\ldots,\frac{{\partial c_k}}{{\partial x_n}}\right)^\mathrm{T}\text{,}
where :math:`\frac{{\partial c_k}}{{\partial x_j}}` is the partial derivative of the :math:`k`\ th constraint with respect to the :math:`j`\ th variable, evaluated at the point :math:`x`. See also the argument :math:`\mathrm{nstate}`. The remaining rows of :math:`\mathrm{cjsl}`, corresponding to non-positive elements of :math:`\mathrm{needc}`, need not be set.
If all elements of the constraint Jacobian are known (i.e., :math:`\text{‘Derivative Level'} = 2` or :math:`3`), any constant elements may be assigned to :math:`\mathrm{cjsl}` one time only at the start of each local optimization.
An element of :math:`\mathrm{cjsl}` that is not subsequently assigned in :math:`\mathrm{confun}` will retain its initial value throughout the local optimization.
Constant elements may be loaded into :math:`\mathrm{cjsl}` during the first call to :math:`\mathrm{confun}` for the local optimization (signalled by the value :math:`\mathrm{nstate} = 1`).
The ability to preload constants is useful when many Jacobian elements are identically zero, in which case :math:`\mathrm{cjsl}` may be initialized to zero and nonzero elements may be reset by :math:`\mathrm{confun}`.
Note that constant nonzero elements do affect the values of the constraints.
Thus, if :math:`\mathrm{cjsl}[k-1,j-1]` is set to a constant value, it need not be reset in subsequent calls to :math:`\mathrm{confun}`, but the value :math:`\mathrm{cjsl}[k-1,j-1]\times \mathrm{x}[j-1]` must nonetheless be added to :math:`\mathrm{c}[k-1]`.
For example, if :math:`\mathrm{cjsl}[0,0] = 2` and :math:`\mathrm{cjsl}[0,1] = -5` then the term :math:`2\times \mathrm{x}[0]-5\times \mathrm{x}[1]` must be included in the definition of :math:`\mathrm{c}[0]`.
It must be emphasized that, if :math:`\text{‘Derivative Level'} = 0` or :math:`1`, unassigned elements of :math:`\mathrm{cjsl}` are not treated as constant; they are estimated by finite differences, at nontrivial expense.
If you do not supply a value for the option 'Difference Interval', an interval for each element of :math:`x` is computed automatically at the start of each local optimization.
The automatic procedure can usually identify constant elements of :math:`\mathrm{cjsl}`, which are then computed once only by finite differences.
**start** : None or callable quas = start(quas, repeat, bl, bu, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
:math:`\mathrm{start}` must calculate the :math:`\mathrm{npts}` starting points to be used by the local optimizer.
If you do not wish to write a function specific to your problem then **None** may be used. In this case, a default function uses the NAG quasi-random number generators to distribute starting points uniformly across the domain.
It is affected by the value of :math:`\mathrm{repeat}`.
**Parameters**
**quas** : float, ndarray, shape :math:`\left(n, \textit{npts}\right)`
All elements of :math:`\mathrm{quas}` will have been set to zero, so only nonzero values need be set subsequently.
**repeat** : bool
Specifies whether a repeatable or non-repeatable sequence of points are to be generated.
**bl** : float, ndarray, shape :math:`\left(n\right)`
The lower bounds on the variables. These may be used to ensure that the starting points generated in some sense 'cover' the region, but there is no requirement that a starting point be feasible.
**bu** : float, ndarray, shape :math:`\left(n\right)`
The upper bounds on the variables. (See :math:`\mathrm{bl}`.)
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**quas** : float, array-like, shape :math:`\left(n, \textit{npts}\right)`
Must contain the starting points for the :math:`\mathrm{npts}` local minimizations, i.e., :math:`\mathrm{quas}[j-1,i-1]` must contain the :math:`j`\ th component of the :math:`i`\ th starting point.
**data** : arbitrary, optional
User-communication data for callback functions.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**spiked_sorder** : str, optional
If :math:`\mathrm{a}` is spiked (i.e., has unit extent in all but one dimension, or has size :math:`1`), :math:`\mathrm{spiked\_sorder}` selects the storage order to associate with it in the NAG Engine:
spiked_sorder = :math:`\texttt{'C'}`
row-major storage will be used;
spiked_sorder = :math:`\texttt{'F'}`
column-major storage will be used.
Two-dimensional arrays returned from callback functions in this routine must then use the same storage order.
**Returns**
**x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nb}\right)`
:math:`\mathrm{x}[\textit{j}-1,i-1]` contains the final estimate of the :math:`i`\ th solution, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}`.
**objf** : float, ndarray, shape :math:`\left(\mathrm{nb}\right)`
:math:`\mathrm{objf}[i-1]` contains the value of the objective function at the final iterate for the :math:`i`\ th solution.
**objgrd** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nb}\right)`
:math:`\mathrm{objgrd}[\textit{j}-1,i-1]` contains the gradient of the objective function for the :math:`i`\ th solution at the final iterate (or its finite difference approximation), for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}`.
**itera** : int, ndarray, shape :math:`\left(\mathrm{nb}\right)`
:math:`\mathrm{itera}[i-1]` contains the number of major iterations performed to obtain the :math:`i`\ th solution. If less than :math:`\mathrm{nb}` solutions are returned then :math:`\mathrm{itera}[\mathrm{nb}-1]` contains the number of starting points that have resulted in a converged solution. If this is close to :math:`\mathrm{npts}` then this might be indicative that fewer than :math:`\mathrm{nb}` local minima exist.
**c** : None or float, ndarray, shape :math:`\left(\mathrm{ncnln}, \mathrm{nb}\right)`
If :math:`\mathrm{ncnln} > 0`, :math:`\mathrm{c}[\textit{j}-1,\textit{i}-1]` contains the value of the :math:`\textit{j}`\ th nonlinear constraint function :math:`c_{\textit{j}}` at the final iterate, for the :math:`\textit{i}`\ th solution, for :math:`\textit{j} = 1,2,\ldots,\mathrm{ncnln}`.
If :math:`\mathrm{ncnln} = 0`, :math:`\mathrm{c}` is returned as **None**.
**cjac** : None or float, ndarray, shape :math:`\left(\mathrm{ncnln}, :, \mathrm{nb}\right)`
If :math:`\mathrm{ncnln} > 0`, :math:`\mathrm{cjac}` contains the Jacobian matrices of the nonlinear constraint functions at the final iterate for each of the returned solutions, i.e., :math:`\mathrm{cjac}[\textit{k}-1,\textit{j}-1,i-1]` contains the partial derivative of the :math:`\textit{k}`\ th constraint function with respect to the :math:`\textit{j}`\ th variable, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}`, for :math:`\textit{k} = 1,2,\ldots,\mathrm{ncnln}`, for the :math:`i`\ th solution. (See the discussion of argument :math:`\mathrm{cjsl}` under :math:`\mathrm{confun}`.)
If :math:`\mathrm{ncnln} = 0`, :math:`\mathrm{cjac}` is returned as **None**.
**r** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}, \mathrm{nb}\right)`
For each of the :math:`\mathrm{nb}` solutions :math:`\mathrm{r}` will contain a form of the Hessian; for the :math:`i`\ th returned solution :math:`\mathrm{r}[\textit{ldr},\textit{sdr},i]` contains the Hessian that would be returned from the local minimizer. If :math:`\text{‘Hessian'} = \texttt{'NO'}`, the default, each :math:`\mathrm{r}[\textit{ldr},\textit{sdr},i]` contains the upper triangular Cholesky factor :math:`R` of :math:`Q^\mathrm{T}HQ`, an estimate of the transformed and reordered Hessian of the Lagrangian at :math:`x`. If :math:`\text{‘Hessian'} = \texttt{'YES'}`, :math:`\mathrm{r}[\textit{ldr},\textit{sdr},i]` contains the upper triangular Cholesky factor :math:`R` of :math:`H`, the approximate (untransformed) Hessian of the Lagrangian, with the variables in the natural order.
**clamda** : float, ndarray, shape :math:`\left(\mathrm{n}+\textit{nclin}+\mathrm{ncnln}, \mathrm{nb}\right)`
The values of the QP multipliers from the last QP subproblem solved for the :math:`i`\ th solution. :math:`\mathrm{clamda}[j-1,i-1]` should be non-negative if :math:`\mathrm{istate}[j-1,i-1] = 1` and non-positive if :math:`\mathrm{istate}[j-1,i-1] = 2`.
**istate** : int, ndarray, shape :math:`\left(\mathrm{n}+\textit{nclin}+\mathrm{ncnln}, \mathrm{nb}\right)`
:math:`\mathrm{istate}[j-1,i-1]` contains the status of the constraints in the QP working set for the :math:`i`\ th solution. The significance of each possible value of :math:`\mathrm{istate}[j-1,i-1]` is as follows:
.. rst-class:: nag-rules-none nag-align-left
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\mathrm{istate}[j-1,i-1]`|Meaning |
+================================+========================================================================================================================================================================+
|:math:`0` |The constraint is satisfied to within the feasibility tolerance, but is not in the QP working set. |
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`1` |This inequality constraint is included in the QP working set at its lower bound. |
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`2` |This inequality constraint is included in the QP working set at its upper bound. |
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`3` |This constraint is included in the QP working set as an equality. This value of :math:`\mathrm{istate}` can occur only when :math:`\mathrm{bl}[j-1] = \mathrm{bu}[j-1]`.|
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
**info** : int, ndarray, shape :math:`\left(\mathrm{nb}\right)`
:math:`\mathrm{info}[i-1]` contains one of :math:`0`, :math:`1` or :math:`6`. Please see the description of each corresponding value of :math:`\textit{errno}` on exit from :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` for detailed explanations of these exit values. As usual :math:`0` denotes success.
If :math:`\mathrm{errno}` = 8 on exit, then not all :math:`\mathrm{nb}` solutions have been found, and :math:`\mathrm{info}[\mathrm{nb}-1]` contains the number of solutions actually found.
.. _e05uc-py2-py-other_params:
**Other Parameters**
**'Punch Unit'** : int
Default :math:`\text{} = 6`
This option allows you to send information arising from an appropriate setting of 'Out_Level' to be sent to the Fortran unit number defined by 'Punch Unit'.
If you wish this file to be different to the standard output unit where other output is displayed then this file should be attached by calling the ``FileObjManager`` method :meth:`~naginterfaces.base.utils.FileObjManager.unit_from_fileobj` prior to calling ``nlp_multistart_sqp``.
**'Out_Level'** : int
Default :math:`\text{} = 0`
This option defines the amount of extra information to be sent to the Fortran unit number defined by 'Punch Unit'.
The possible choices for :math:`i` are the following:
.. rst-class:: nag-rules-none nag-align-left
+---------+--------------------------------------------------------------------------------------------------------------+
|:math:`i`|Meaning |
+=========+==============================================================================================================+
|0 |No extra output. |
+---------+--------------------------------------------------------------------------------------------------------------+
|1 |Updated solutions only. This is useful during long runs to observe progress. |
+---------+--------------------------------------------------------------------------------------------------------------+
|2 |Successful start points only. This is useful to save the starting points that gave rise to the final solution.|
+---------+--------------------------------------------------------------------------------------------------------------+
|3 |Both updated solutions and successful start points. |
+---------+--------------------------------------------------------------------------------------------------------------+
**'Central Difference Interval'** : float
Default values are computed
If the algorithm switches to central differences because the forward-difference approximation is not sufficiently accurate, the value of :math:`r` is used as the difference interval for every element of :math:`x`.
The switch to central differences is indicated by ``C`` at the end of each line of intermediate printout produced by the major iterations (see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#fc-printedoutput>`__).
The use of finite differences is discussed further under the option 'Difference Interval'.
If you supply a value for this option, a small value between :math:`0.0` and :math:`1.0` is appropriate.
**'Crash Tolerance'** : float
Default :math:`\text{} = 0.01`
This value is used when ``nlp_multistart_sqp`` selects an initial working set.
If :math:`0\leq r\leq 1`, the initial working set will include (if possible) bounds or general inequality constraints that lie within :math:`r` of their bounds.
In particular, a constraint of the form :math:`a_j^\mathrm{T}x\geq l` will be included in the initial working set if :math:`\left\lvert a_j^\mathrm{T}x-l\right\rvert \leq r\left(1+\left\lvert l\right\rvert \right)`.
If :math:`r < 0` or :math:`r > 1`, the default value is used.
**'Defaults'** : valueless
This special keyword is used to reset all options to their default values, and any random state stored in the array :math:`\textit{comm}` will be destroyed.
Any option value given with this keyword will be ignored.
This option cannot be queried or got.
**'Derivative Level'** : int
Default :math:`\text{} = 3`
This argument indicates which derivatives are provided in functions :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are the following.
.. rst-class:: nag-rules-none nag-align-left
+---------+--------------------------------------------------------------------------------------------------------------------+
|:math:`i`|Meaning |
+=========+====================================================================================================================+
|3 |All elements of the objective gradient and the constraint Jacobian are provided. |
+---------+--------------------------------------------------------------------------------------------------------------------+
|2 |All elements of the constraint Jacobian are provided, but some elements of the objective gradient are not specified.|
+---------+--------------------------------------------------------------------------------------------------------------------+
|1 |All elements of the objective gradient are provided, but some elements of the constraint Jacobian are not specified.|
+---------+--------------------------------------------------------------------------------------------------------------------+
|0 |Some elements of both the objective gradient and the constraint Jacobian are not specified. |
+---------+--------------------------------------------------------------------------------------------------------------------+
The value :math:`i = 3` should be used whenever possible, since ``nlp_multistart_sqp`` is more reliable (and will usually be more efficient) when all derivatives are exact.
If :math:`i = 0` or :math:`2`, ``nlp_multistart_sqp`` will estimate the unspecified elements of the objective gradient, using finite differences.
The computation of finite difference approximations usually increases the total run-time, since a call to :math:`\mathrm{objfun}` is required for each unspecified element.
Furthermore, less accuracy can be attained in the solution (see Module 8 of Gill `et al.` (1981), for a discussion of limiting accuracy).
If :math:`i = 0` or :math:`1`, ``nlp_multistart_sqp`` will approximate unspecified elements of the constraint Jacobian.
One call to :math:`\mathrm{confun}` is needed for each variable for which partial derivatives are not available.
For example, if the Jacobian has the form
.. math::
\begin{pmatrix}\text{*}&\text{*}&\text{*}&\text{*}\\\text{*}&\text{?}&\text{?}&\text{*}\\\text{*}&\text{*}&\text{?}&\text{*}\\\text{*}&\text{*}&\text{*}&\text{*}\end{pmatrix}
where ':math:`*`' indicates an element provided by you and '?' indicates an unspecified element, ``nlp_multistart_sqp`` will call :math:`\mathrm{confun}` twice: once to estimate the missing element in column 2, and again to estimate the two missing elements in column :math:`3`. (Since columns :math:`1` and :math:`4` are known, they require no calls to :math:`\mathrm{confun}`.)
At times, central differences are used rather than forward differences, in which case twice as many calls to :math:`\mathrm{objfun}` and :math:`\mathrm{confun}` are needed. (The switch to central differences is not under your control.)
If :math:`i < 0` or :math:`i > 3`, the default value is used.
**'Difference Interval'** : float
Default values are computed
This option defines an interval used to estimate derivatives by finite differences in the following circumstances:
(a) For verifying the objective and/or constraint gradients (see the description of the option 'Verify').
(#) For estimating unspecified elements of the objective gradient or the constraint Jacobian.
In general, a derivative with respect to the :math:`j`\ th variable is approximated using the interval :math:`\delta_j`, where :math:`\delta_j = r\left(1+\left\lvert \hat{x}_j\right\rvert \right)`, with :math:`\hat{x}` the first point feasible with respect to the bounds and linear constraints.
If the functions are well scaled, the resulting derivative approximation should be accurate to :math:`\mathrm{O}\left(r\right)`.
See Gill `et al.` (1981) for a discussion of the accuracy in finite difference approximations.
If a difference interval is not specified, a finite difference interval will be computed automatically for each variable by a procedure that requires up to six calls of :math:`\mathrm{confun}` and :math:`\mathrm{objfun}` for each element.
This option is recommended if the function is badly scaled or you wish to have ``nlp_multistart_sqp`` determine constant elements in the objective and constraint gradients (see the descriptions of :math:`\mathrm{confun}` and :math:`\mathrm{objfun}` in :ref:`Parameters <e05uc-py2-py-parameters>`).
If you supply a value for this option, a small value between :math:`0.0` and :math:`1.0` is appropriate.
**'Feasibility Tolerance'** : float
Default :math:`\text{} = \sqrt{\epsilon }`
The scalar :math:`r` defines the maximum acceptable `absolute` violations in linear and nonlinear constraints at a 'feasible' point; i.e., a constraint is considered satisfied if its violation does not exceed :math:`r`.
If :math:`r < \epsilon` or :math:`r\geq 1`, the default value is used.
Using this keyword sets both options 'Linear Feasibility Tolerance' and 'Nonlinear Feasibility Tolerance' to :math:`r`, if :math:`\epsilon \leq r < 1`. (Additional details are given under the descriptions of these options.)
**'Function Precision'** : float
Default :math:`\text{} = \epsilon^{0.9}`
This argument defines :math:`\epsilon_r`, which is intended to be a measure of the accuracy with which the problem functions :math:`F\left(x\right)` and :math:`c\left(x\right)` can be computed.
If :math:`r < \epsilon` or :math:`r\geq 1`, the default value is used.
The value of :math:`\epsilon_r` should reflect the relative precision of :math:`1+\left\lvert F\left(x\right)\right\rvert`; i.e., :math:`\epsilon_r` acts as a relative precision when :math:`\left\lvert F\right\rvert` is large, and as an absolute precision when :math:`\left\lvert F\right\rvert` is small.
For example, if :math:`F\left(x\right)` is typically of order :math:`1000` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-6}`.
In contrast, if :math:`F\left(x\right)` is typically of order :math:`10^{-4}` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-10}`.
The choice of :math:`\epsilon_r` can be quite complicated for badly scaled problems; see Module 8 of Gill `et al.` (1981) for a discussion of scaling techniques.
The default value is appropriate for most simple functions that are computed with full accuracy.
However, when the accuracy of the computed function values is known to be significantly worse than full precision, the value of :math:`\epsilon_r` should be large enough so that ``nlp_multistart_sqp`` will not attempt to distinguish between function values that differ by less than the error inherent in the calculation.
**'Hessian'** : str
Default :math:`= \mathrm{NO}`
This option controls the contents of the upper triangular matrix :math:`R` (see :ref:`Parameters <e05uc-py2-py-parameters>`). ``nlp_multistart_sqp`` works exclusively with the `transformed and reordered` Hessian :math:`H_Q` `(6) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#eqn6>`__, and hence extra computation is required to form the Hessian itself.
If :math:`\text{‘Hessian'} = \texttt{'NO'}`, :math:`\mathrm{r}` contains the Cholesky factor of the transformed and reordered Hessian.
If :math:`\text{‘Hessian'} = \texttt{'YES'}`, the Cholesky factor of the approximate Hessian itself is formed and stored in :math:`\mathrm{r}`.
**'Infinite Bound Size'** : float
Default :math:`\text{} = 10^{20}`
This defines the 'infinite' bound :math:`\textit{infbnd}` in the definition of the problem constraints.
Any upper bound greater than or equal to :math:`\textit{infbnd}` will be regarded as :math:`\infty` (and similarly any lower bound less than or equal to :math:`{-\textit{infbnd}}` will be regarded as :math:`-\infty`).
**'Infinite Step Size'** : float
Default :math:`\text{} = \mathrm{max}\left(\textit{bigbnd}, 10^{20}\right)`
If :math:`r > 0`, :math:`r` specifies the magnitude of the change in variables that is treated as a step to an unbounded solution.
If the change in :math:`x` during an iteration would exceed the value of :math:`r`, the objective function is considered to be unbounded below in the feasible region.
If :math:`r\leq 0`, the default value is used.
**'Line Search Tolerance'** : float
Default :math:`\text{} = 0.9`
The value :math:`r` (:math:`0\leq r < 1`) controls the accuracy with which the step :math:`\alpha` taken during each iteration approximates a minimum of the merit function along the search direction (the smaller the value of :math:`r`, the more accurate the linesearch).
The default value :math:`r = 0.9` requests an inaccurate search, and is appropriate for most problems, particularly those with any nonlinear constraints.
If there are no nonlinear constraints, a more accurate search may be appropriate when it is desirable to reduce the number of major iterations -- for example, if the objective function is cheap to evaluate, or if a substantial number of derivatives are unspecified.
If :math:`r < 0` or :math:`r\geq 1`, the default value is used.
**'Linear Feasibility Tolerance'** : float
Default :math:`\text{} = \sqrt{\epsilon }`
The default value of :math:`r_2` is :math:`\epsilon^{0.33}` if :math:`\text{‘Derivative Level'} = 0` or :math:`1`, and :math:`\sqrt{\epsilon }` otherwise.
The scalars :math:`r_1` and :math:`r_2` define the maximum acceptable `absolute` violations in linear and nonlinear constraints at a 'feasible' point; i.e., a linear constraint is considered satisfied if its violation does not exceed :math:`r_1`, and similarly for a nonlinear constraint and :math:`r_2`.
If :math:`r_{\textit{m}} < \epsilon` or :math:`r_{\textit{m}}\geq 1`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
On entry to ``nlp_multistart_sqp``, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance :math:`r_1`.
All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless :math:`r_1` is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance :math:`r_2` defines the largest constraint violation that is acceptable at an optimal point.
Since nonlinear constraints are generally not satisfied until the final iterate, the value of option 'Nonlinear Feasibility Tolerance' acts as a partial termination criterion for the iterative sequence generated by ``nlp_multistart_sqp`` (see the discussion of option 'Optimality Tolerance').
These tolerances should reflect the precision of the corresponding constraints.
For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about :math:`6` decimal digits, it would be appropriate to specify :math:`r_1` as :math:`10^{-6}`.
**'Nonlinear Feasibility Tolerance'** : float
Default :math:`\text{} = \epsilon^{0.33}` or :math:`\sqrt{\epsilon }`
The default value of :math:`r_2` is :math:`\epsilon^{0.33}` if :math:`\text{‘Derivative Level'} = 0` or :math:`1`, and :math:`\sqrt{\epsilon }` otherwise.
The scalars :math:`r_1` and :math:`r_2` define the maximum acceptable `absolute` violations in linear and nonlinear constraints at a 'feasible' point; i.e., a linear constraint is considered satisfied if its violation does not exceed :math:`r_1`, and similarly for a nonlinear constraint and :math:`r_2`.
If :math:`r_{\textit{m}} < \epsilon` or :math:`r_{\textit{m}}\geq 1`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
On entry to ``nlp_multistart_sqp``, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance :math:`r_1`.
All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless :math:`r_1` is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance :math:`r_2` defines the largest constraint violation that is acceptable at an optimal point.
Since nonlinear constraints are generally not satisfied until the final iterate, the value of option 'Nonlinear Feasibility Tolerance' acts as a partial termination criterion for the iterative sequence generated by ``nlp_multistart_sqp`` (see the discussion of option 'Optimality Tolerance').
These tolerances should reflect the precision of the corresponding constraints.
For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about :math:`6` decimal digits, it would be appropriate to specify :math:`r_1` as :math:`10^{-6}`.
**'List'** : valueless
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.
**'Nolist'** : valueless
Default
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.
**'Major Iteration Limit'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Iteration Limit'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Iters'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Itns'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Major Print Level'** : int
Default :math:`\text{} = 0`
The value of :math:`i` controls the amount of printout produced by the major iterations of ``nlp_multistart_sqp``, as indicated below.
A detailed description of the printed output is given in `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#fc-printedoutput>`__ (summary output at each major iteration and the final solution) and `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#monitoring>`__ (monitoring information at each major iteration). (See also the description of the option 'Minor Print Level'.)
The following printout is sent to the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`):
.. rst-class:: nag-rules-none nag-align-left
+---------+----------+
|:math:`i`|Output |
+=========+==========+
|:math:`0`|No output.|
+---------+----------+
For the other values described below, the arguments used by :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` are displayed in addition to intermediate and final output.
.. rst-class:: nag-rules-none nag-align-left
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+=========================================================================================================================================================================================================================================+
|:math:`1` |The final solution only. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`5` |One line of summary output (:math:`\text{} < 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#fc-printedoutput>`__) for each major iteration (no printout of the final solution).|
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 10`|The final solution and one line of summary output for each major iteration. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
The following printout is sent to the logical unit number defined by the option 'Monitoring File':
.. rst-class:: nag-rules-none nag-align-left
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+==========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`\text{} < 5` |No output. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 5` |One long line of output (:math:`\text{} > 80` characters; see `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#monitoring>`__) for each major iteration (no printout of the final solution). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 20`|At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector :math:`c`), the values of the linear constraints (the vector :math:`A_Lx`), and the current values of the variables (the vector :math:`x`). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 30`|At each major iteration, the diagonal elements of the matrix :math:`T` associated with the :math:`TQ` factorization `(5) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#eqn5>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#ad-overview>`__) of the QP working set, and the diagonal elements of :math:`R`, the triangular factor of the transformed and reordered Hessian `(6) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#eqn6>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#ad-overview>`__).|
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
If :math:`\text{‘Major Print Level'} \geq 5` and the unit number defined by the option 'Monitoring File' is the advisory unit number, then the summary output for each major iteration is suppressed.
**'Print Level'** : int
Default :math:`\text{} = 0`
The value of :math:`i` controls the amount of printout produced by the major iterations of ``nlp_multistart_sqp``, as indicated below.
A detailed description of the printed output is given in `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#fc-printedoutput>`__ (summary output at each major iteration and the final solution) and `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#monitoring>`__ (monitoring information at each major iteration). (See also the description of the option 'Minor Print Level'.)
The following printout is sent to the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`):
.. rst-class:: nag-rules-none nag-align-left
+---------+----------+
|:math:`i`|Output |
+=========+==========+
|:math:`0`|No output.|
+---------+----------+
For the other values described below, the arguments used by :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` are displayed in addition to intermediate and final output.
.. rst-class:: nag-rules-none nag-align-left
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+=========================================================================================================================================================================================================================================+
|:math:`1` |The final solution only. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`5` |One line of summary output (:math:`\text{} < 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#fc-printedoutput>`__) for each major iteration (no printout of the final solution).|
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 10`|The final solution and one line of summary output for each major iteration. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
The following printout is sent to the logical unit number defined by the option 'Monitoring File':
.. rst-class:: nag-rules-none nag-align-left
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+==========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`\text{} < 5` |No output. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 5` |One long line of output (:math:`\text{} > 80` characters; see `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#monitoring>`__) for each major iteration (no printout of the final solution). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 20`|At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector :math:`c`), the values of the linear constraints (the vector :math:`A_Lx`), and the current values of the variables (the vector :math:`x`). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 30`|At each major iteration, the diagonal elements of the matrix :math:`T` associated with the :math:`TQ` factorization `(5) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#eqn5>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#ad-overview>`__) of the QP working set, and the diagonal elements of :math:`R`, the triangular factor of the transformed and reordered Hessian `(6) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#eqn6>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#ad-overview>`__).|
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
If :math:`\text{‘Major Print Level'} \geq 5` and the unit number defined by the option 'Monitoring File' is the advisory unit number, then the summary output for each major iteration is suppressed.
**'Minor Iteration Limit'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L+n_N\right)}\right)`
The value of :math:`i` specifies the maximum number of iterations for finding a feasible point with respect to the bounds and linear constraints (if any).
The value of :math:`i` also specifies the maximum number of minor iterations for the optimality phase of each QP subproblem.
If :math:`i\leq 0`, the default value is used.
**'Minor Print Level'** : int
Default :math:`\text{} = 0`
The value of :math:`i` controls the amount of printout produced by the minor iterations of ``nlp_multistart_sqp`` (i.e., the iterations of the quadratic programming algorithm), as indicated below.
A detailed description of the printed output is given in `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#fc-printedoutput>`__ (summary output at each minor iteration and the final QP solution) and `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#monitoring>`__ (monitoring information at each minor iteration). (See also the description of the option 'Major Print Level'.) The following printout is sent to the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`):
.. rst-class:: nag-rules-none nag-align-left
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+============================================================================================================================================================================================================================================+
|:math:`0` |No output. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`1` |The final QP solution only. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`5` |One line of summary output (:math:`\text{} < 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#fc-printedoutput>`__) for each minor iteration (no printout of the final QP solution).|
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 10`|The final QP solution and one line of summary output for each minor iteration. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
The following printout is sent to the logical unit number defined by the option 'Monitoring File':
.. rst-class:: nag-rules-none nag-align-left
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+=========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`\text{} < 5` |No output. |
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 5` |One long line of output (:math:`\text{} > 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#fc-printedoutput>`__) for each minor iteration (no printout of the final QP solution). |
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 20`|At each minor iteration, the current estimates of the QP multipliers, the current estimate of the QP search direction, the QP constraint values, and the status of each QP constraint. |
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 30`|At each minor iteration, the diagonal elements of the matrix :math:`T` associated with the :math:`TQ` factorization `(5) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#eqn5>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#ad-overview>`__) of the QP working set, and the diagonal elements of the Cholesky factor :math:`R` of the transformed Hessian `(6) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#eqn6>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05ucf.html#ad-overview>`__).|
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
If :math:`\text{‘Minor Print Level'} \geq 5` and the unit number defined by the option 'Monitoring File' is the advisory unit number, the summary output for each minor iteration is suppressed.
**'Monitoring File'** : int
Default :math:`\text{} = -1`
If :math:`i\geq 0` and :math:`\text{‘Major Print Level'} \geq 5` or :math:`i\geq 0` and :math:`\text{‘Minor Print Level'} \geq 5`, monitoring information produced by ``nlp_multistart_sqp`` at every iteration is sent to a file with logical unit number :math:`i`. If :math:`i < 0` and/or :math:`\text{‘Major Print Level'} < 5` and :math:`\text{‘Minor Print Level'} < 5`, no monitoring information is produced.
**'Optimality Tolerance'** : float
Default :math:`\text{} = \epsilon_R^{0.8}`
The argument :math:`r` (:math:`\epsilon_R\leq r < 1`) specifies the accuracy to which you wish the final iterate to approximate a solution of the problem.
Broadly speaking, :math:`r` indicates the number of correct figures desired in the objective function at the solution.
For example, if :math:`r` is :math:`10^{-6}` and ``nlp_multistart_sqp`` terminates successfully, the final value of :math:`F` should have approximately six correct figures.
If :math:`r < \epsilon_r` or :math:`r\geq 1`, the default value is used.
``nlp_multistart_sqp`` will terminate successfully if the iterative sequence of :math:`x` values is judged to have converged and the final point satisfies the first-order Kuhn--Tucker conditions (see `Overview <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#ad-overview>`__).
The sequence of iterates is considered to have converged at :math:`x` if
.. math::
\alpha \left\lVert p\right\rVert \leq \sqrt{r}\left(1+\left\lVert x\right\rVert \right)\text{,}
where :math:`p` is the search direction and :math:`\alpha` the step length from `(3) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#eqn3>`__.
An iterate is considered to satisfy the first-order conditions for a minimum if
.. math::
\left\lVert Z^\mathrm{T}g_{\mathrm{FR}}\right\rVert \leq \sqrt{r}\left(1+\mathrm{max}\left({1+\left\lvert F\left(x\right)\right\rvert }, \left\lVert g_{\mathrm{FR}}\right\rVert \right)\right)
and
.. math::
\left\lvert \textit{res}_j\right\rvert \leq \textit{ftol}\quad \text{ for all }\quad j\text{,}
where :math:`Z^\mathrm{T}g_{\mathrm{FR}}` is the projected gradient (see `Overview <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#ad-overview>`__), :math:`g_{\mathrm{FR}}` is the gradient of :math:`F\left(x\right)` with respect to the free variables, :math:`\textit{res}_j` is the violation of the :math:`j`\ th active nonlinear constraint, and :math:`\textit{ftol}` is the 'Nonlinear Feasibility Tolerance'.
**'Start Objective Check At Variable'** : int
Default :math:`\text{} = 1`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Stop Objective Check At Variable'** : int
Default :math:`\text{} = n`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Start Constraint Check At Variable'** : int
Default :math:`\text{} = 1`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Stop Constraint Check At Variable'** : int
Default :math:`\text{} = n`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Step Limit'** : float
Default :math:`\text{} = 2.0`
If :math:`r > 0,r` specifies the maximum change in variables at the first step of the linesearch.
In some cases, such as :math:`F\left(x\right) = ae^{{bx}}` or :math:`F\left(x\right) = ax^b`, even a moderate change in the elements of :math:`x` can lead to floating-point overflow.
The argument :math:`r` is, therefore, used to encourage evaluation of the problem functions at meaningful points.
Given any major iterate :math:`x`, the first point :math:`\tilde{x}` at which :math:`F` and :math:`c` are evaluated during the linesearch is restricted so that
.. math::
\left\lVert \tilde{x}-x\right\rVert_2\leq r\left(1+\left\lVert x\right\rVert_2\right)\text{.}
The linesearch may go on and evaluate :math:`F` and :math:`c` at points further from :math:`x` if this will result in a lower value of the merit function (indicated by L at the end of each line of output produced by the major iterations; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e04/e04ucf.html#fc-printedoutput>`__). If L is printed for most of the iterations, :math:`r` should be set to a larger value.
Wherever possible, upper and lower bounds on :math:`x` should be used to prevent evaluation of nonlinear functions at wild values.
The default value :math:`\text{‘Step Limit'} = 2.0` should not affect progress on well-behaved functions, but values such as :math:`0.1` or :math:`0.01` may be helpful when rapidly varying functions are present.
If a small value of 'Step Limit' is selected, a good starting point may be required.
An important application is to the class of nonlinear least squares problems.
If :math:`r\leq 0`, the default value is used.
**'Verify Level'** : int
Default :math:`\text{} = 0`
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify Constraint Gradients'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify Gradients'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify Objective Gradients'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
.. _e05uc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nb} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`1\leq \mathrm{nb}\leq \mathrm{npts}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{bl}[i-1] > \mathrm{bu}[i-1]`: :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{bl}[i-1]\leq \mathrm{bu}[i-1]`, for all :math:`i`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ncnln} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ncnln}\geq 0`.
(`errno` :math:`1`)
On entry, :math:`\textit{nclin} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{nclin}\geq 0`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} > 0`.
(`errno` :math:`1`)
On entry, :math:`\textit{ldclda} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{nclin} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{ncnln} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ldclda}\geq \mathrm{n}+\textit{nclin}+\mathrm{ncnln}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ncnln} > 0`, :math:`\textit{sdcjac} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{ncnln} > 0`, :math:`\textit{sdcjac}\geq \mathrm{n}`.
(`errno` :math:`1`)
On entry, :math:`\textit{listat} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{nclin} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{ncnln} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{listat}\geq \mathrm{n}+\textit{nclin}+\mathrm{ncnln}`.
(`errno` :math:`2`)
No solution obtained. Linear constraints may be infeasible.
(`errno` :math:`3`)
No solution obtained. Nonlinear constraints may be infeasible.
(`errno` :math:`4`)
No solution obtained. Many potential solutions reach iteration limit.
(`errno` :math:`7`)
User-supplied derivatives probably wrong.
(`errno` :math:`10`)
Failed to initialize option arrays.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`8`)
Only :math:`\langle\mathit{\boldsymbol{value}}\rangle` solutions obtained.
**NagCallbackTerminateWarning**
(`errno` :math:`9`)
User terminated computation from :math:`\mathrm{start}` procedure: :math:`\mathrm{mode} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e05uc-py2-py-notes:
**Notes**
The problem is assumed to be stated in the following form:
.. math::
\textit{minimize}_{{x \in R^n}}\text{ }F\left(x\right)\quad \text{ subject to }\quad l\leq \begin{pmatrix}x\\A_Lx\\c\left(x\right)\end{pmatrix}\leq u\text{,}
where :math:`F\left(x\right)` (the `objective function`) is a nonlinear function, :math:`A_L` is an :math:`n_L\times n` linear constraint matrix, and :math:`c\left(x\right)` is an :math:`n_N` element vector of nonlinear constraint functions. (The matrix :math:`A_L` and the vector :math:`c\left(x\right)` may be empty.) The objective function and the constraint functions are assumed to be smooth, i.e., at least twice-continuously differentiable. (This function will usually solve `(1) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05ucf.html#eqn1>`__ if there are only isolated discontinuities away from the solution.)
``nlp_multistart_sqp`` solves a user-specified number of local optimization problems with different starting points.
You may specify the starting points via the function :math:`\mathrm{start}`.
If a random number generator is used to generate the starting points then the argument :math:`\mathrm{repeat}` allows you to specify whether a repeatable set of points are generated or whether different starting points are generated on different calls.
The resulting local minima are ordered and the best :math:`\mathrm{nb}` results returned in order of ascending values of the resulting objective function values at the minima.
Thus the value returned in position :math:`1` will be the best result obtained.
If a sufficient number of different points are chosen then this is likely to be be the global minimum.
Please note that the default version of :math:`\mathrm{start}` uses a random number generator to generate the starting points.
.. _e05uc-py2-py-references:
**References**
Dennis, J E Jr and Moré, J J, 1977, `Quasi-Newton methods, motivation and theory`, SIAM Rev. (19), 46--89
Dennis, J E Jr and Schnabel, R B, 1981, `A new derivation of symmetric positive-definite secant updates`, nonlinear programming, (eds O L Mangasarian, R R Meyer and S M Robinson) (4), 167--199, Academic Press
Dennis, J E Jr and Schnabel, R B, 1983, `Numerical Methods for Unconstrained Optimization and Nonlinear Equations`, Prentice--Hall
Fletcher, R, 1987, `Practical Methods of Optimization`, (2nd Edition), Wiley
Gill, P E, Hammarling, S, Murray, W, Saunders, M A and Wright, M H, 1986, `Users' guide for LSSOL (Version 1.0)`, Report SOL 86-1, Department of Operations Research, Stanford University
Gill, P E, Murray, W, Saunders, M A and Wright, M H, 1984, `Users' guide for SOL/QPSOL version 3.2`, Report SOL, 84--5, Department of Operations Research, Stanford University
Gill, P E, Murray, W, Saunders, M A and Wright, M H, 1986, `Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming`, Report SOL 86-2, Department of Operations Research, Stanford University
Gill, P E, Murray, W, Saunders, M A and Wright, M H, 1986, `Some theoretical properties of an augmented Lagrangian merit function`, Report SOL, 86--6R, Department of Operations Research, Stanford University
Gill, P E, Murray, W and Wright, M H, 1981, `Practical Optimization`, Academic Press
Powell, M J D, 1974, `Introduction to constrained optimization`, Numerical Methods for Constrained Optimization, (eds P E Gill and W Murray), 1--28, Academic Press
Powell, M J D, 1983, `Variable metric methods in constrained optimization`, Mathematical Programming: the State of the Art, (eds A Bachem, M Grötschel and B Korte), 288--311, Springer--Verlag
"""
raise NotImplementedError
[docs]def nlp_multistart_sqp_lsq(ncnln, bl, bu, y, objfun, npts, nb, comm, a=None, confun=None, start=None, repeat1=False, data=None, io_manager=None):
r"""
``nlp_multistart_sqp_lsq`` is designed to find the global minimum of an arbitrary smooth sum of squares function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.
Note: this function uses optional algorithmic parameters, see also: :meth:`optset`, :meth:`opt.lsq_gencon_deriv <naginterfaces.library.opt.lsq_gencon_deriv>`.
.. _e05us-py2-py-doc:
For full information please refer to the NAG Library document for e05us
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html
.. _e05us-py2-py-parameters:
**Parameters**
**ncnln** : int
:math:`n_N`, the number of nonlinear constraints.
**bl** : float, array-like, shape :math:`\left(n+\textit{nclin}+\mathrm{ncnln}\right)`
:math:`\mathrm{bl}` must contain the lower bounds for all the constraints.
**bu** : float, array-like, shape :math:`\left(n+\textit{nclin}+\mathrm{ncnln}\right)`
:math:`\mathrm{bu}` must contain the upper bounds for all the constraints.
**y** : float, array-like, shape :math:`\left(m\right)`
The coefficients of the constant vector :math:`y` of the objective function.
**objfun** : callable f = objfun(mode, needfi, x, fjsl, nstate, data=None)
:math:`\mathrm{objfun}` must calculate either the :math:`i`\ th element of the vector :math:`f\left(x\right) = {\left({f_1\left(x\right)}, {f_2\left(x\right)}, \ldots, {f_m\left(x\right)}\right)}^\mathrm{T}` or all :math:`m` elements of :math:`f\left(x\right)` and (optionally) its Jacobian (:math:`\text{} = \frac{{\partial f}}{{\partial x}}`) for a specified :math:`n`-element vector :math:`x`.
**Parameters**
**mode** : int
Indicates which values must be assigned during each call of :math:`\mathrm{objfun}`. Only the following values need be assigned:
:math:`\mathrm{mode} = 0` and :math:`\mathrm{needfi} = i`, where :math:`i > 0`
:math:`\mathrm{f}[i-1]`.
:math:`\mathrm{mode} = 0` and :math:`\mathrm{needfi} < 0`
:math:`\mathrm{f}`.
:math:`\mathrm{mode} = 1` and :math:`\mathrm{needfi} < 0`
All available elements of :math:`\mathrm{fjsl}`.
:math:`\mathrm{mode} = 2` and :math:`\mathrm{needfi} < 0`
:math:`\mathrm{f}` and all available elements of :math:`\mathrm{fjsl}`.
**needfi** : int
If :math:`\mathrm{needfi} = i > 0`, only the :math:`i`\ th element of :math:`f\left(x\right)` needs to be evaluated at :math:`x`; the remaining elements need not be set. This can result in significant computational savings when :math:`m≫n`.
**x** : float, ndarray, shape :math:`\left(n\right)`
:math:`x`, the vector of variables at which the objective function and/or all available elements of its gradient are to be evaluated.
**fjsl** : float, ndarray, shape :math:`\left(m, n\right)`, to be modified in place
:math:`\mathrm{fjsl}` may be regarded as a two-dimensional 'slice' of the three-dimensional array :math:`\mathrm{fjac}` of ``nlp_multistart_sqp_lsq``.
`On entry`: is set to a special value.
`On exit`: if :math:`\mathrm{mode} = 1` or :math:`2` and :math:`\mathrm{needfi} < 0`, the :math:`i`\ th row of :math:`\mathrm{fjsl}` must contain the available elements of the vector :math:`\nabla f_i` given by
.. math::
\nabla f_i = \left(\partial f_i/\partial x_1,\partial f_i/\partial x_2,\ldots,\partial f_i/\partial x_n\right)^\mathrm{T}\text{,}
evaluated at the point :math:`x`. See also the argument :math:`\mathrm{nstate}`.
**nstate** : int
If :math:`\mathrm{nstate} = 1` then ``nlp_multistart_sqp_lsq`` is calling :math:`\mathrm{objfun}` for the first time on the current local optimization problem. This argument setting allows you to save computation time if certain data must be read or calculated only once.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**f** : float, array-like, shape :math:`\left(m\right)`
If :math:`\mathrm{mode} = 0` and :math:`\mathrm{needfi} = i > 0`, :math:`\mathrm{f}[i-1]` must contain the value of :math:`f_i` at :math:`x`.
If :math:`\mathrm{mode} = 0` or :math:`2` and :math:`\mathrm{needfi} < 0`, :math:`\mathrm{f}[\textit{i}-1]` must contain the value of :math:`f_{\textit{i}}` at :math:`x`, for :math:`\textit{i} = 1,2,\ldots,m`.
**npts** : int
The number of different starting points to be generated and used. The more points used, the more likely that the best returned solution will be a global minimum.
**nb** : int
The number of solutions to be returned. The function saves up to :math:`\mathrm{nb}` local minima ordered by increasing value of the final objective function. If the defining criterion for 'best solution' is only that the value of the objective function is as small as possible then :math:`\mathrm{nb}` should be set to :math:`1`. However, if you want to look at other solutions that may have desirable properties then setting :math:`\mathrm{nb} > 1` will produce :math:`\mathrm{nb}` local minima, ordered by increasing value of their objective functions at the minima.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`optset`.
**a** : None or float, array-like, shape :math:`\left(\textit{nclin}, :\right)`, optional
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\textit{nclin} > 0`: :math:`n`; otherwise: :math:`1`.
The matrix :math:`A_L` of general linear constraints in `(1) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#eqn1>`__. That is, the :math:`\textit{i}`\ th row contains the coefficients of the :math:`\textit{i}`\ th general linear constraint, for :math:`\textit{i} = 1,2,\ldots,\textit{nclin}`.
**confun** : None or callable c = confun(mode, needc, x, cjsl, nstate, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
:math:`\mathrm{confun}` must calculate the vector :math:`c\left(x\right)` of nonlinear constraint functions and (optionally) its Jacobian (:math:`\text{} = \frac{{\partial c}}{{\partial x}}`) for a specified :math:`n`-element vector :math:`x`. If there are no nonlinear constraints (i.e., :math:`\mathrm{ncnln} = 0`), :math:`\mathrm{confun}` will never be called by ``nlp_multistart_sqp_lsq`` and :math:`\mathrm{confun}` may be **None**. If there are nonlinear constraints, the first call to :math:`\mathrm{confun}` will occur before the first call to :math:`\mathrm{objfun}`.
**Parameters**
**mode** : int
Indicates which values must be assigned during each call of :math:`\mathrm{confun}`. Only the following values need be assigned, for each value of :math:`i` such that :math:`\mathrm{needc}[i-1] > 0`:
:math:`\mathrm{mode} = 0`
:math:`\mathrm{c}[i-1]`, the :math:`i`\ th nonlinear constraint.
:math:`\mathrm{mode} = 1`
All available elements in the :math:`i`\ th row of :math:`\mathrm{cjsl}`.
:math:`\mathrm{mode} = 2`
:math:`\mathrm{c}[i-1]` and all available elements in the :math:`i`\ th row of :math:`\mathrm{cjsl}`.
**needc** : int, ndarray, shape :math:`\left(\textit{ncnln}\right)`
The indices of the elements of :math:`\mathrm{c}` and/or :math:`\mathrm{cjsl}` that must be evaluated by :math:`\mathrm{confun}`. If :math:`\mathrm{needc}[i-1] > 0`, :math:`\mathrm{c}[i-1]` and/or the available elements of the :math:`i`\ th row of :math:`\mathrm{cjsl}` (see argument :math:`\mathrm{mode}`) must be evaluated at :math:`x`.
**x** : float, ndarray, shape :math:`\left(n\right)`
:math:`x`, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
**cjsl** : float, ndarray, shape :math:`\left(\textit{ncnln}, n\right)`, to be modified in place
:math:`\mathrm{cjsl}` may be regarded as a two-dimensional 'slice' of the three-dimensional array :math:`\mathrm{cjac}` of ``nlp_multistart_sqp_lsq``.
`On entry`: unless :math:`\text{‘Derivative Level'} = 2` or :math:`3`, the elements of :math:`\mathrm{cjsl}` are set to special values which enable ``nlp_multistart_sqp_lsq`` to detect whether they are changed by :math:`\mathrm{confun}`.
`On exit`: if :math:`\mathrm{needc}[i-1] > 0` and :math:`\mathrm{mode} = 1` or :math:`2`, the :math:`i`\ th row of :math:`\mathrm{cjsl}` must contain the available elements of the vector :math:`\nabla c_i` given by
.. math::
\nabla c_i = \left(\frac{{\partial c_i}}{{\partial x_1}},\frac{{\partial c_i}}{{\partial x_2}},\ldots,\frac{{\partial c_i}}{{\partial x_n}}\right)^\mathrm{T}\text{,}
where :math:`\frac{{\partial c_i}}{{\partial x_j}}` is the partial derivative of the :math:`i`\ th constraint with respect to the :math:`j`\ th variable, evaluated at the point :math:`x`. See also the argument :math:`\mathrm{nstate}`. The remaining rows of :math:`\mathrm{cjsl}`, corresponding to non-positive elements of :math:`\mathrm{needc}`, need not be set.
If all elements of the constraint Jacobian are known (i.e., :math:`\text{‘Derivative Level'} = 2` or :math:`3`; note the default is :math:`\text{‘Derivative Level'} = 3`), any constant elements may be assigned to :math:`\mathrm{cjsl}` one time only at the start of each local optimization.
An element of :math:`\mathrm{cjsl}` that is not subsequently assigned in :math:`\mathrm{confun}` will retain its initial value throughout the local optimization.
Constant elements may be loaded into :math:`\mathrm{cjsl}` during the first call to :math:`\mathrm{confun}` for the local optimization (signalled by the value :math:`\mathrm{nstate} = 1`).
The ability to preload constants is useful when many Jacobian elements are identically zero, in which case :math:`\mathrm{cjsl}` may be initialized to zero and nonzero elements may be reset by :math:`\mathrm{confun}`.
Note that constant nonzero elements do affect the values of the constraints.
Thus, if :math:`\mathrm{cjsl}[i-1,j-1]` is set to a constant value, it need not be reset in subsequent calls to :math:`\mathrm{confun}`, but the value :math:`\mathrm{cjsl}[i-1,j-1]\times \mathrm{x}[j-1]` must nonetheless be added to :math:`\mathrm{c}[i-1]`.
For example, if :math:`\mathrm{cjsl}[0,0] = 2` and :math:`\mathrm{cjsl}[0,1] = -5` then the term :math:`2\times \mathrm{x}[0]-5\times \mathrm{x}[1]` must be included in the definition of :math:`\mathrm{c}[0]`.
It must be emphasized that, if :math:`\text{‘Derivative Level'} = 0` or :math:`1`, unassigned elements of :math:`\mathrm{cjsl}` are not treated as constant; they are estimated by finite differences, at nontrivial expense.
If you do not supply a value for the option 'Difference Interval', an interval for each element of :math:`x` is computed automatically at the start of each local optimization.
The automatic procedure can usually identify constant elements of :math:`\mathrm{cjsl}`, which are then computed once only by finite differences.
**nstate** : int
If :math:`\mathrm{nstate} = 1` then ``nlp_multistart_sqp_lsq`` is calling :math:`\mathrm{confun}` for the first time on the current local optimization problem. This argument setting allows you to save computation time if certain data must be read or calculated only once.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**c** : float, array-like, shape :math:`\left(\textit{ncnln}\right)`
If :math:`\mathrm{needc}[i-1] > 0` and :math:`\mathrm{mode} = 0` or :math:`2`, :math:`\mathrm{c}[i-1]` must contain the value of :math:`c_i\left(x\right)`. The remaining elements of :math:`\mathrm{c}`, corresponding to the non-positive elements of :math:`\mathrm{needc}`, need not be set.
**start** : None or callable start(quas, repeat1, bl, bu, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
:math:`\mathrm{start}` must calculate the :math:`\mathrm{npts}` starting points to be used by the local optimizer.
If you do not wish to write a function specific to your problem then **None** may be used. In this case, a default function uses the NAG quasi-random number generators to distribute starting points uniformly across the domain.
It is affected by the value of :math:`\mathrm{repeat1}`.
**Parameters**
**quas** : float, ndarray, shape :math:`\left(n, \textit{npts}\right)`, to be modified in place
`On entry`: all elements of :math:`\mathrm{quas}` will have been set to zero, so only nonzero values need be set subsequently.
`On exit`: must contain the starting points for the :math:`\mathrm{npts}` local minimizations, i.e., :math:`\mathrm{quas}[j-1,i-1]` must contain the :math:`j`\ th component of the :math:`i`\ th starting point.
**repeat1** : bool
Specifies whether a repeatable or non-repeatable sequence of points are to be generated.
**bl** : float, ndarray, shape :math:`\left(n\right)`
The lower bounds on the variables. These may be used to ensure that the starting points generated in some sense 'cover' the region, but there is no requirement that a starting point be feasible.
**bu** : float, ndarray, shape :math:`\left(n\right)`
The upper bounds on the variables. (See :math:`\mathrm{bl}`.)
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**repeat1** : bool, optional
Is passed as an argument to :math:`\mathrm{start}` and may be used to initialize a random number generator to a repeatable, or non-repeatable, sequence. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#fcomments>`__ for more detail.
**data** : arbitrary, optional
User-communication data for callback functions.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**Returns**
**x** : float, ndarray, shape :math:`\left(n, \mathrm{nb}\right)`
:math:`\mathrm{x}[\textit{j}-1,i-1]` contains the final estimate of the :math:`i`\ th solution, for :math:`\textit{j} = 1,2,\ldots,n`.
**objf** : float, ndarray, shape :math:`\left(\mathrm{nb}\right)`
:math:`\mathrm{objf}[i-1]` contains the value of the objective function at the final iterate for the :math:`i`\ th solution.
**f** : float, ndarray, shape :math:`\left(m, \mathrm{nb}\right)`
:math:`\mathrm{f}[\textit{j}-1,i-1]` contains the value of the :math:`\textit{j}`\ th function :math:`f_j` at the final iterate, for :math:`\textit{j} = 1,2,\ldots,m`, for the :math:`\textit{i}`\ th solution, for :math:`\textit{i} = 1,2,\ldots,\mathrm{nb}`.
**fjac** : float, ndarray, shape :math:`\left(m, n, \mathrm{nb}\right)`
For the :math:`i`\ th returned solution, the Jacobian matrix of the functions :math:`f_1,f_2,\ldots,f_m` at the final iterate, i.e., :math:`\mathrm{fjac}[\textit{k}-1,\textit{j}-1,\textit{i}-1]` contains the partial derivative of the :math:`\textit{k}`\ th function with respect to the :math:`\textit{j}`\ th variable, for :math:`\textit{i} = 1,2,\ldots,\mathrm{nb}`, for :math:`\textit{j} = 1,2,\ldots,n`, for :math:`\textit{k} = 1,2,\ldots,m`. (See also the discussion of argument :math:`\mathrm{fjsl}` under :math:`\mathrm{objfun}`.)
**itera** : int, ndarray, shape :math:`\left(\mathrm{nb}\right)`
:math:`\mathrm{itera}[i-1]` contains the number of major iterations performed to obtain the :math:`i`\ th solution. If less than :math:`\mathrm{nb}` solutions are returned then :math:`\mathrm{itera}[\mathrm{nb}-1]` contains the number of starting points that have resulted in a converged solution. If this is close to :math:`\mathrm{npts}` then this might be indicative that fewer than :math:`\mathrm{nb}` local minima exist.
**c** : None or float, ndarray, shape :math:`\left(\mathrm{ncnln}, \mathrm{nb}\right)`
If :math:`\mathrm{ncnln} > 0`, :math:`\mathrm{c}[\textit{j}-1,\textit{i}-1]` contains the value of the :math:`\textit{j}`\ th nonlinear constraint function :math:`c_{\textit{j}}` at the final iterate, for the :math:`\textit{i}`\ th solution, for :math:`\textit{j} = 1,2,\ldots,\mathrm{ncnln}`.
If :math:`\mathrm{ncnln} = 0`, :math:`\mathrm{c}` is returned as **None**.
**cjac** : None or float, ndarray, shape :math:`\left(\mathrm{ncnln}, :, \mathrm{nb}\right)`
If :math:`\mathrm{ncnln} > 0`, :math:`\mathrm{cjac}` contains the Jacobian matrices of the nonlinear constraint functions at the final iterate for each of the returned solutions, i.e., :math:`\mathrm{cjac}[\textit{k}-1,\textit{j}-1,i-1]` contains the partial derivative of the :math:`\textit{k}`\ th constraint function with respect to the :math:`\textit{j}`\ th variable, for :math:`\textit{j} = 1,2,\ldots,n`, for :math:`\textit{k} = 1,2,\ldots,\mathrm{ncnln}`, for the :math:`i`\ th solution. (See the discussion of argument :math:`\mathrm{cjsl}` under :math:`\mathrm{confun}`.)
If :math:`\mathrm{ncnln} = 0`, :math:`\mathrm{cjac}` is returned as **None**.
**clamda** : float, ndarray, shape :math:`\left(n+\textit{nclin}+\mathrm{ncnln}, \mathrm{nb}\right)`
The values of the QP multipliers from the last QP subproblem solved for the :math:`i`\ th solution. :math:`\mathrm{clamda}[j-1,i-1]` should be non-negative if :math:`\mathrm{istate}[j-1,i-1] = 1` and non-positive if :math:`\mathrm{istate}[j-1,i-1] = 2`.
**istate** : int, ndarray, shape :math:`\left(n+\textit{nclin}+\mathrm{ncnln}, \mathrm{nb}\right)`
:math:`\mathrm{istate}[j-1,i-1]` contains the status of the constraints in the QP working set for the :math:`i`\ th solution. The significance of each possible value of :math:`\mathrm{istate}[j-1,i-1]` is as follows:
.. rst-class:: nag-rules-none nag-align-left
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\mathrm{istate}[j-1,i-1]`|Meaning |
+================================+========================================================================================================================================================================+
|:math:`0` |The constraint is satisfied to within the feasibility tolerance, but is not in the QP working set. |
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`1` |This inequality constraint is included in the QP working set at its lower bound. |
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`2` |This inequality constraint is included in the QP working set at its upper bound. |
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`3` |This constraint is included in the QP working set as an equality. This value of :math:`\mathrm{istate}` can occur only when :math:`\mathrm{bl}[j-1] = \mathrm{bu}[j-1]`.|
+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
**info** : int, ndarray, shape :math:`\left(\mathrm{nb}\right)`
If no exception or warning is raised, :math:`\mathrm{info}[i-1]` does not contain an error value returned by :meth:`opt.lsq_gencon_deriv <naginterfaces.library.opt.lsq_gencon_deriv>`.
If :math:`\mathrm{errno}` = 8 on exit, then not all :math:`\mathrm{nb}` solutions have been found, and :math:`\mathrm{info}[\mathrm{nb}-1]` contains the number of solutions actually found.
.. _e05us-py2-py-other_params:
**Other Parameters**
**'Central Difference Interval'** : float
Default values are computed
If the algorithm switches to central differences because the forward-difference approximation is not sufficiently accurate, the value of :math:`r` is used as the difference interval for every element of :math:`x`.
The switch to central differences is indicated by ``C`` at the end of each line of intermediate printout produced by the major iterations (see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#fc-printedoutput>`__).
The use of finite differences is discussed further under the option 'Difference Interval'.
If you supply a value for this option, a small value between :math:`0.0` and :math:`1.0` is appropriate.
**'Crash Tolerance'** : float
Default :math:`\text{} = 0.01`
This value is used when ``nlp_multistart_sqp_lsq`` selects an initial working set.
If :math:`0\leq r\leq 1`, the initial working set will include (if possible) bounds or general inequality constraints that lie within :math:`r` of their bounds.
In particular, a constraint of the form :math:`a_j^\mathrm{T}x\geq l` will be included in the initial working set if :math:`\left\lvert a_j^\mathrm{T}x-l\right\rvert \leq r\left(1+\left\lvert l\right\rvert \right)`.
If :math:`r < 0` or :math:`r > 1`, the default value is used.
**'Defaults'** : valueless
This special keyword is used to reset all options to their default values, and any random state stored in the array :math:`\textit{comm}` will be destroyed.
Any option value given with this keyword will be ignored.
This option cannot be queried or got.
**'Derivative Level'** : int
Default :math:`\text{} = 3`
This argument indicates which derivatives are provided in functions :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are the following.
.. rst-class:: nag-rules-none nag-align-left
+---------+--------------------------------------------------------------------------------------------------------------------+
|:math:`i`|Meaning |
+=========+====================================================================================================================+
|3 |All elements of the objective gradient and the constraint Jacobian are provided. |
+---------+--------------------------------------------------------------------------------------------------------------------+
|2 |All elements of the constraint Jacobian are provided, but some elements of the objective gradient are not specified.|
+---------+--------------------------------------------------------------------------------------------------------------------+
|1 |All elements of the objective gradient are provided, but some elements of the constraint Jacobian are not specified.|
+---------+--------------------------------------------------------------------------------------------------------------------+
|0 |Some elements of both the objective gradient and the constraint Jacobian are not specified. |
+---------+--------------------------------------------------------------------------------------------------------------------+
The value :math:`i = 3` should be used whenever possible, since ``nlp_multistart_sqp_lsq`` is more reliable (and will usually be more efficient) when all derivatives are exact.
If :math:`i = 0` or :math:`2`, ``nlp_multistart_sqp_lsq`` will estimate the unspecified elements of the objective gradient, using finite differences.
The computation of finite difference approximations usually increases the total run-time, since a call to :math:`\mathrm{objfun}` is required for each unspecified element.
Furthermore, less accuracy can be attained in the solution (see Module 8 of Gill `et al.` (1981), for a discussion of limiting accuracy).
If :math:`i = 0` or :math:`1`, ``nlp_multistart_sqp_lsq`` will approximate unspecified elements of the constraint Jacobian.
One call to :math:`\mathrm{confun}` is needed for each variable for which partial derivatives are not available.
For example, if the Jacobian has the form
.. math::
\begin{pmatrix}\text{*}&\text{*}&\text{*}&\text{*}\\\text{*}&\text{?}&\text{?}&\text{*}\\\text{*}&\text{*}&\text{?}&\text{*}\\\text{*}&\text{*}&\text{*}&\text{*}\end{pmatrix}
where ':math:`*`' indicates an element provided by you and '?' indicates an unspecified element, ``nlp_multistart_sqp_lsq`` will call :math:`\mathrm{confun}` twice: once to estimate the missing element in column 2, and again to estimate the two missing elements in column :math:`3`. (Since columns :math:`1` and :math:`4` are known, they require no calls to :math:`\mathrm{confun}`.)
At times, central differences are used rather than forward differences, in which case twice as many calls to :math:`\mathrm{objfun}` and :math:`\mathrm{confun}` are needed. (The switch to central differences is not under your control.)
If :math:`i < 0` or :math:`i > 3`, the default value is used.
**'Difference Interval'** : float
Default values are computed
This option defines an interval used to estimate derivatives by finite differences in the following circumstances:
(a) For verifying the objective and/or constraint gradients (see the description of the option 'Verify').
(#) For estimating unspecified elements of the objective gradient or the constraint Jacobian.
In general, a derivative with respect to the :math:`j`\ th variable is approximated using the interval :math:`\delta_j`, where :math:`\delta_j = r\left(1+\left\lvert \hat{x}_j\right\rvert \right)`, with :math:`\hat{x}` the first point feasible with respect to the bounds and linear constraints.
If the functions are well scaled, the resulting derivative approximation should be accurate to :math:`\mathrm{O}\left(r\right)`.
See Gill `et al.` (1981) for a discussion of the accuracy in finite difference approximations.
If a difference interval is not specified, a finite difference interval will be computed automatically for each variable by a procedure that requires up to six calls of :math:`\mathrm{confun}` and :math:`\mathrm{objfun}` for each element.
This option is recommended if the function is badly scaled or you wish to have ``nlp_multistart_sqp_lsq`` determine constant elements in the objective and constraint gradients (see the descriptions of :math:`\mathrm{confun}` and :math:`\mathrm{objfun}` in :ref:`Parameters <e05us-py2-py-parameters>`).
If you supply a value for this option, a small value between :math:`0.0` and :math:`1.0` is appropriate.
**'Feasibility Tolerance'** : float
Default :math:`\text{} = \sqrt{\epsilon }`
The scalar :math:`r` defines the maximum acceptable `absolute` violations in linear and nonlinear constraints at a 'feasible' point; i.e., a constraint is considered satisfied if its violation does not exceed :math:`r`.
If :math:`r < \epsilon` or :math:`r\geq 1`, the default value is used.
Using this keyword sets both options 'Linear Feasibility Tolerance' and 'Nonlinear Feasibility Tolerance' to :math:`r`, if :math:`\epsilon \leq r < 1`. (Additional details are given under the descriptions of these options.)
**'Function Precision'** : float
Default :math:`\text{} = \epsilon^{0.9}`
This argument defines :math:`\epsilon_r`, which is intended to be a measure of the accuracy with which the problem functions :math:`F\left(x\right)` and :math:`c\left(x\right)` can be computed.
If :math:`r < \epsilon` or :math:`r\geq 1`, the default value is used.
The value of :math:`\epsilon_r` should reflect the relative precision of :math:`1+\left\lvert F\left(x\right)\right\rvert`; i.e., :math:`\epsilon_r` acts as a relative precision when :math:`\left\lvert F\right\rvert` is large, and as an absolute precision when :math:`\left\lvert F\right\rvert` is small.
For example, if :math:`F\left(x\right)` is typically of order :math:`1000` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-6}`.
In contrast, if :math:`F\left(x\right)` is typically of order :math:`10^{-4}` and the first six significant digits are known to be correct, an appropriate value for :math:`\epsilon_r` would be :math:`10^{-10}`.
The choice of :math:`\epsilon_r` can be quite complicated for badly scaled problems; see Module 8 of Gill `et al.` (1981) for a discussion of scaling techniques.
The default value is appropriate for most simple functions that are computed with full accuracy.
However, when the accuracy of the computed function values is known to be significantly worse than full precision, the value of :math:`\epsilon_r` should be large enough so that ``nlp_multistart_sqp_lsq`` will not attempt to distinguish between function values that differ by less than the error inherent in the calculation.
**'Hessian'** : str
Default :math:`= \texttt{'NO'}`
This option controls the contents of the upper triangular matrix :math:`R` (see :ref:`Parameters <e05us-py2-py-parameters>`). ``nlp_multistart_sqp_lsq`` works exclusively with the `transformed and reordered` Hessian :math:`H_Q` `(6) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#eqn6>`__, and hence extra computation is required to form the Hessian itself.
If :math:`\text{‘Hessian'} = \texttt{'NO'}`, :math:`\textit{r}` contains the Cholesky factor of the transformed and reordered Hessian.
If :math:`\text{‘Hessian'} = \texttt{'YES'}`, the Cholesky factor of the approximate Hessian itself is formed and stored in :math:`\textit{r}`.
**'Infinite Bound Size'** : float
Default :math:`\text{} = 10^{20}`
This defines the 'infinite' bound :math:`\textit{infbnd}` in the definition of the problem constraints.
Any upper bound greater than or equal to :math:`\textit{infbnd}` will be regarded as :math:`\infty` (and similarly any lower bound less than or equal to :math:`{-\textit{infbnd}}` will be regarded as :math:`-\infty`).
**'Infinite Step Size'** : float
Default :math:`\text{} = \mathrm{max}\left(\textit{bigbnd}, 10^{20}\right)`
If :math:`r > 0`, :math:`r` specifies the magnitude of the change in variables that is treated as a step to an unbounded solution.
If the change in :math:`x` during an iteration would exceed the value of :math:`r`, the objective function is considered to be unbounded below in the feasible region.
If :math:`r\leq 0`, the default value is used.
**'Line Search Tolerance'** : float
Default :math:`\text{} = 0.9`
The value :math:`r` (:math:`0\leq r < 1`) controls the accuracy with which the step :math:`\alpha` taken during each iteration approximates a minimum of the merit function along the search direction (the smaller the value of :math:`r`, the more accurate the linesearch).
The default value :math:`r = 0.9` requests an inaccurate search, and is appropriate for most problems, particularly those with any nonlinear constraints.
If there are no nonlinear constraints, a more accurate search may be appropriate when it is desirable to reduce the number of major iterations -- for example, if the objective function is cheap to evaluate, or if a substantial number of derivatives are unspecified.
If :math:`r < 0` or :math:`r\geq 1`, the default value is used.
**'Linear Feasibility Tolerance'** : float
Default :math:`\text{} = \sqrt{\epsilon }`
The default value of :math:`r_2` is :math:`\epsilon^{0.33}` if :math:`\text{‘Derivative Level'} = 0` or :math:`1`, and :math:`\sqrt{\epsilon }` otherwise.
The scalars :math:`r_1` and :math:`r_2` define the maximum acceptable `absolute` violations in linear and nonlinear constraints at a 'feasible' point; i.e., a linear constraint is considered satisfied if its violation does not exceed :math:`r_1`, and similarly for a nonlinear constraint and :math:`r_2`.
If :math:`r_{\textit{m}} < \epsilon` or :math:`r_{\textit{m}}\geq 1`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
On entry to ``nlp_multistart_sqp_lsq``, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance :math:`r_1`.
All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless :math:`r_1` is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance :math:`r_2` defines the largest constraint violation that is acceptable at an optimal point.
Since nonlinear constraints are generally not satisfied until the final iterate, the value of option 'Nonlinear Feasibility Tolerance' acts as a partial termination criterion for the iterative sequence generated by ``nlp_multistart_sqp_lsq`` (see the discussion of option 'Optimality Tolerance').
These tolerances should reflect the precision of the corresponding constraints.
For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about :math:`6` decimal digits, it would be appropriate to specify :math:`r_1` as :math:`10^{-6}`.
**'Nonlinear Feasibility Tolerance'** : float
Default :math:`\text{} = \epsilon^{0.33}` or :math:`\sqrt{\epsilon }`
The default value of :math:`r_2` is :math:`\epsilon^{0.33}` if :math:`\text{‘Derivative Level'} = 0` or :math:`1`, and :math:`\sqrt{\epsilon }` otherwise.
The scalars :math:`r_1` and :math:`r_2` define the maximum acceptable `absolute` violations in linear and nonlinear constraints at a 'feasible' point; i.e., a linear constraint is considered satisfied if its violation does not exceed :math:`r_1`, and similarly for a nonlinear constraint and :math:`r_2`.
If :math:`r_{\textit{m}} < \epsilon` or :math:`r_{\textit{m}}\geq 1`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
On entry to ``nlp_multistart_sqp_lsq``, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance :math:`r_1`.
All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless :math:`r_1` is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance :math:`r_2` defines the largest constraint violation that is acceptable at an optimal point.
Since nonlinear constraints are generally not satisfied until the final iterate, the value of option 'Nonlinear Feasibility Tolerance' acts as a partial termination criterion for the iterative sequence generated by ``nlp_multistart_sqp_lsq`` (see the discussion of option 'Optimality Tolerance').
These tolerances should reflect the precision of the corresponding constraints.
For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about :math:`6` decimal digits, it would be appropriate to specify :math:`r_1` as :math:`10^{-6}`.
**'List'** : valueless
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.
**'Nolist'** : valueless
Default
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.
**'Major Iteration Limit'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Iteration Limit'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Iters'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Itns'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L\right)+10n_N}\right)`
The value of :math:`i` specifies the maximum number of major iterations allowed before termination of the subproblem.
Setting :math:`i = 0` and :math:`\text{‘Major Print Level'} > 0` means that the workspace needed will be computed and printed, but no iterations will be performed.
If :math:`i < 0`, the default value is used.
**'Major Print Level'** : int
Default :math:`\text{} = 0`
The value of :math:`i` controls the amount of printout produced by the major iterations of ``nlp_multistart_sqp_lsq``, as indicated below.
A detailed description of the printed output is given in `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#fc-printedoutput>`__ (summary output at each major iteration and the final solution) and `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#monitoring>`__ (monitoring information at each major iteration). (See also the description of the option 'Minor Print Level'.)
The following printout is sent to the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`):
.. rst-class:: nag-rules-none nag-align-left
+---------+----------+
|:math:`i`|Output |
+=========+==========+
|:math:`0`|No output.|
+---------+----------+
For the other values described below, the arguments used by :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` are displayed in addition to intermediate and final output.
.. rst-class:: nag-rules-none nag-align-left
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+=========================================================================================================================================================================================================================================+
|:math:`1` |The final solution only. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`5` |One line of summary output (:math:`\text{} < 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#fc-printedoutput>`__) for each major iteration (no printout of the final solution).|
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 10`|The final solution and one line of summary output for each major iteration. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
The following printout is sent to the logical unit number defined by the option 'Monitoring File':
.. rst-class:: nag-rules-none nag-align-left
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+==========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`\text{} < 5` |No output. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 5` |One long line of output (:math:`\text{} > 80` characters; see `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#monitoring>`__) for each major iteration (no printout of the final solution). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 20`|At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector :math:`c`), the values of the linear constraints (the vector :math:`A_Lx`), and the current values of the variables (the vector :math:`x`). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 30`|At each major iteration, the diagonal elements of the matrix :math:`T` associated with the :math:`TQ` factorization `(5) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#eqn5>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#ad-overview>`__) of the QP working set, and the diagonal elements of :math:`R`, the triangular factor of the transformed and reordered Hessian `(6) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#eqn6>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#ad-overview>`__).|
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
If :math:`\text{‘Major Print Level'} \geq 5` and the unit number defined by the option 'Monitoring File' is the advisory unit number, then the summary output for each major iteration is suppressed.
**'Print Level'** : int
Default :math:`\text{} = 0`
The value of :math:`i` controls the amount of printout produced by the major iterations of ``nlp_multistart_sqp_lsq``, as indicated below.
A detailed description of the printed output is given in `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#fc-printedoutput>`__ (summary output at each major iteration and the final solution) and `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#monitoring>`__ (monitoring information at each major iteration). (See also the description of the option 'Minor Print Level'.)
The following printout is sent to the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`):
.. rst-class:: nag-rules-none nag-align-left
+---------+----------+
|:math:`i`|Output |
+=========+==========+
|:math:`0`|No output.|
+---------+----------+
For the other values described below, the arguments used by :meth:`opt.nlp1_solve <naginterfaces.library.opt.nlp1_solve>` are displayed in addition to intermediate and final output.
.. rst-class:: nag-rules-none nag-align-left
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+=========================================================================================================================================================================================================================================+
|:math:`1` |The final solution only. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`5` |One line of summary output (:math:`\text{} < 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#fc-printedoutput>`__) for each major iteration (no printout of the final solution).|
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 10`|The final solution and one line of summary output for each major iteration. |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
The following printout is sent to the logical unit number defined by the option 'Monitoring File':
.. rst-class:: nag-rules-none nag-align-left
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+==========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`\text{} < 5` |No output. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 5` |One long line of output (:math:`\text{} > 80` characters; see `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#monitoring>`__) for each major iteration (no printout of the final solution). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 20`|At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector :math:`c`), the values of the linear constraints (the vector :math:`A_Lx`), and the current values of the variables (the vector :math:`x`). |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 30`|At each major iteration, the diagonal elements of the matrix :math:`T` associated with the :math:`TQ` factorization `(5) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#eqn5>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#ad-overview>`__) of the QP working set, and the diagonal elements of :math:`R`, the triangular factor of the transformed and reordered Hessian `(6) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#eqn6>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#ad-overview>`__).|
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
If :math:`\text{‘Major Print Level'} \geq 5` and the unit number defined by the option 'Monitoring File' is the advisory unit number, then the summary output for each major iteration is suppressed.
**'Minor Iteration Limit'** : int
Default :math:`\text{} = \mathrm{max}\left(50, {3\left(n+n_L+n_N\right)}\right)`
The value of :math:`i` specifies the maximum number of iterations for finding a feasible point with respect to the bounds and linear constraints (if any).
The value of :math:`i` also specifies the maximum number of minor iterations for the optimality phase of each QP subproblem.
If :math:`i\leq 0`, the default value is used.
**'Minor Print Level'** : int
Default :math:`\text{} = 0`
The value of :math:`i` controls the amount of printout produced by the minor iterations of ``nlp_multistart_sqp_lsq`` (i.e., the iterations of the quadratic programming algorithm), as indicated below.
A detailed description of the printed output is given in `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#fc-printedoutput>`__ (summary output at each minor iteration and the final QP solution) and `Monitoring Information <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#monitoring>`__ (monitoring information at each minor iteration). (See also the description of the option 'Major Print Level'.) The following printout is sent to the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`):
.. rst-class:: nag-rules-none nag-align-left
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+============================================================================================================================================================================================================================================+
|:math:`0` |No output. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`1` |The final QP solution only. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`5` |One line of summary output (:math:`\text{} < 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#fc-printedoutput>`__) for each minor iteration (no printout of the final QP solution).|
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 10`|The final QP solution and one line of summary output for each minor iteration. |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
The following printout is sent to the logical unit number defined by the option 'Monitoring File':
.. rst-class:: nag-rules-none nag-align-left
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`i` |Output |
+======================+=========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:`\text{} < 5` |No output. |
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 5` |One long line of output (:math:`\text{} > 80` characters; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#fc-printedoutput>`__) for each minor iteration (no printout of the final QP solution). |
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 20`|At each minor iteration, the current estimates of the QP multipliers, the current estimate of the QP search direction, the QP constraint values, and the status of each QP constraint. |
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:`\text{}\geq 30`|At each minor iteration, the diagonal elements of the matrix :math:`T` associated with the :math:`TQ` factorization `(5) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#eqn5>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#ad-overview>`__) of the QP working set, and the diagonal elements of the Cholesky factor :math:`R` of the transformed Hessian `(6) <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#eqn6>`__ (see `Overview <https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/e05/e05usf.html#ad-overview>`__).|
+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
If :math:`\text{‘Minor Print Level'} \geq 5` and the unit number defined by the option 'Monitoring File' is the advisory unit number, then the summary output for each minor iteration is suppressed.
**'Monitoring File'** : int
Default :math:`\text{} = -1`
If :math:`i\geq 0` and :math:`\text{‘Major Print Level'} \geq 5` or :math:`i\geq 0` and :math:`\text{‘Minor Print Level'} \geq 5`, monitoring information produced by ``nlp_multistart_sqp_lsq`` at every iteration is sent to a file with logical unit number :math:`i`. If :math:`i < 0` and/or :math:`\text{‘Major Print Level'} < 5` and :math:`\text{‘Minor Print Level'} < 5`, no monitoring information is produced.
**'Optimality Tolerance'** : float
Default :math:`\text{} = \epsilon_R^{0.8}`
The argument :math:`r` (:math:`\epsilon_R\leq r < 1`) specifies the accuracy to which you wish the final iterate to approximate a solution of the problem.
Broadly speaking, :math:`r` indicates the number of correct figures desired in the objective function at the solution.
For example, if :math:`r` is :math:`10^{-6}` and ``nlp_multistart_sqp_lsq`` terminates successfully, the final value of :math:`F` should have approximately six correct figures.
If :math:`r < \epsilon_r` or :math:`r\geq 1`, the default value is used.
``nlp_multistart_sqp_lsq`` will terminate successfully if the iterative sequence of :math:`x` values is judged to have converged and the final point satisfies the first-order Kuhn--Tucker conditions (see `Overview <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#ad-overview>`__). The sequence of iterates is considered to have converged at :math:`x` if
.. math::
\alpha \left\lVert p\right\rVert \leq \sqrt{r}\left(1+\left\lVert x\right\rVert \right)\text{,}
where :math:`p` is the search direction and :math:`\alpha` the step length from `(3) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#eqn3>`__. An iterate is considered to satisfy the first-order conditions for a minimum if
.. math::
\left\lVert Z^\mathrm{T}g_{\mathrm{FR}}\right\rVert \leq \sqrt{r}\left(1+\mathrm{max}\left({1+\left\lvert F\left(x\right)\right\rvert }, \left\lVert g_{\mathrm{FR}}\right\rVert \right)\right)
and
.. math::
\left\lvert \textit{res}_j\right\rvert \leq \textit{ftol}\quad \text{ for all }\quad j\text{,}
where :math:`Z^\mathrm{T}g_{\mathrm{FR}}` is the projected gradient (see `Overview <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#ad-overview>`__), :math:`g_{\mathrm{FR}}` is the gradient of :math:`F\left(x\right)` with respect to the free variables, :math:`\textit{res}_j` is the violation of the :math:`j`\ th active nonlinear constraint, and :math:`\textit{ftol}` is the 'Nonlinear Feasibility Tolerance'.
**'Start Objective Check At Variable'** : int
Default :math:`\text{} = 1`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Stop Objective Check At Variable'** : int
Default :math:`\text{} = n`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Start Constraint Check At Variable'** : int
Default :math:`\text{} = 1`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Stop Constraint Check At Variable'** : int
Default :math:`\text{} = n`
These keywords take effect only if :math:`\text{‘Verify Level'} > 0`.
They may be used to control the verification of gradient elements computed by :math:`\mathrm{objfun}` and/or Jacobian elements computed by :math:`\mathrm{confun}`.
For example, if the first :math:`30` elements of the objective gradient appeared to be correct in an earlier run, so that only element :math:`31` remains questionable, it is reasonable to specify :math:`\text{‘Start Objective Check At Variable'} = 31`.
If the first :math:`30` variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If :math:`i_{{2\textit{m}-1}}\leq 0` or :math:`i_{{2\textit{m}-1}} > \mathrm{min}\left(n, i_{{2\textit{m}}}\right)`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
If :math:`i_{{2\textit{m}}}\leq 0` or :math:`i_{{2\textit{m}}} > n`, the default value is used, for :math:`\textit{m} = 1,2,\ldots,2`.
**'Step Limit'** : float
Default :math:`\text{} = 2.0`
If :math:`r > 0,r` specifies the maximum change in variables at the first step of the linesearch.
In some cases, such as :math:`F\left(x\right) = ae^{{bx}}` or :math:`F\left(x\right) = ax^b`, even a moderate change in the elements of :math:`x` can lead to floating-point overflow.
The argument :math:`r` is, therefore, used to encourage evaluation of the problem functions at meaningful points.
Given any major iterate :math:`x`, the first point :math:`\tilde{x}` at which :math:`F` and :math:`c` are evaluated during the linesearch is restricted so that
.. math::
\left\lVert \tilde{x}-x\right\rVert_2\leq r\left(1+\left\lVert x\right\rVert_2\right)\text{.}
The linesearch may go on and evaluate :math:`F` and :math:`c` at points further from :math:`x` if this will result in a lower value of the merit function (indicated by L at the end of each line of output produced by the major iterations; see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e04/e04ucf.html#fc-printedoutput>`__). If L is printed for most of the iterations, :math:`r` should be set to a larger value.
Wherever possible, upper and lower bounds on :math:`x` should be used to prevent evaluation of nonlinear functions at wild values.
The default value :math:`\text{‘Step Limit'} = 2.0` should not affect progress on well-behaved functions, but values such as :math:`0.1` or :math:`0.01` may be helpful when rapidly varying functions are present.
If a small value of 'Step Limit' is selected, a good starting point may be required.
An important application is to the class of nonlinear least squares problems.
If :math:`r\leq 0`, the default value is used.
**'Verify Level'** : int
Default :math:`\text{} = 0`
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp_lsq`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp_lsq`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp_lsq`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp_lsq`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify Constraint Gradients'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp_lsq`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp_lsq`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify Gradients'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp_lsq`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp_lsq`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
**'Verify Objective Gradients'** : valueless
These keywords refer to finite difference checks on the gradient elements computed by :math:`\mathrm{objfun}` and :math:`\mathrm{confun}`.
The possible choices for :math:`i` are as follows:
.. rst-class:: nag-rules-none nag-align-left
+----------------+---------------------------------------------------------------------------------------------+
|:math:`i` |Meaning |
+================+=============================================================================================+
|:math:`-1` |No checks are performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`0` |Only a 'cheap' test will be performed. |
+----------------+---------------------------------------------------------------------------------------------+
|:math:`{\geq 1}`|Individual gradient elements will also be checked using a reliable (but more expensive) test.|
+----------------+---------------------------------------------------------------------------------------------+
It is possible to specify :math:`\text{‘Verify Level'} = 0` to :math:`3` in several ways.
For example, the nonlinear objective gradient (if any) will be verified if either 'Verify Objective Gradients' or :math:`\text{‘Verify Level'} = 1` is specified.
The constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 2` or 'Verify' is specified.
Similarly, the objective and the constraint gradients will be verified if :math:`\text{‘Verify'} = \texttt{'YES'}` or :math:`\text{‘Verify Level'} = 3` or 'Verify' is specified.
If :math:`0\leq i\leq 3`, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If :math:`i = 0`, only a 'cheap' test will be performed, requiring one call to :math:`\mathrm{objfun}` and (if appropriate) one call to :math:`\mathrm{confun}`.
If :math:`1\leq i\leq 3`, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the 'Start Constraint Check At Variable' and 'Stop Constraint Check At Variable' keywords.
A result of the form OK or BAD? is printed by ``nlp_multistart_sqp_lsq`` to indicate whether or not each element appears to be correct.
If a gradient element is determined to be extremely poor (i.e., if it appears to have no significant digits of accuracy at all) then ``nlp_multistart_sqp_lsq`` will also exit with an error indicator in argument :math:`\textit{errno}`.
If :math:`10\leq i\leq 13`, the action is the same as for :math:`i-10`, except that it will take place at the user-specified initial value of :math:`x`.
If :math:`i < -1` or :math:`4\leq i\leq 9` or :math:`i > 13`, the default value is used.
We suggest that :math:`\text{‘Verify Level'} = 3` be used whenever a new function function is being developed.
.. _e05us-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nb} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`1\leq \mathrm{nb}\leq \mathrm{npts}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{bl}[i-1] > \mathrm{bu}[i-1]`: :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{bl}[i-1]\leq \mathrm{bu}[i-1]`, for all :math:`i`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ncnln} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ncnln}\geq 0`.
(`errno` :math:`1`)
On entry, :math:`\textit{nclin} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{nclin}\geq 0`.
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`1`)
On entry, :math:`\textit{ldclda} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{nclin} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{ncnln} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ldclda}\geq n+\textit{nclin}+\mathrm{ncnln}`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m > 0`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ncnln} > 0`, :math:`\textit{sdcjac} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{ncnln} > 0`, :math:`\textit{sdcjac}\geq n`.
(`errno` :math:`1`)
On entry, :math:`\textit{listat} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{nclin} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{ncnln} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{listat}\geq n+\textit{nclin}+\mathrm{ncnln}`.
(`errno` :math:`2`)
No solution obtained. Linear constraints may be infeasible.
(`errno` :math:`3`)
No solution obtained. Nonlinear constraints may be infeasible.
(`errno` :math:`4`)
No solution obtained. Many potential solutions reach iteration limit.
(`errno` :math:`7`)
User-supplied derivatives probably wrong.
(`errno` :math:`10`)
Failed to initialize option arrays.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`8`)
Only :math:`\langle\mathit{\boldsymbol{value}}\rangle` solutions obtained.
**NagCallbackTerminateWarning**
(`errno` :math:`9`)
User terminated computation from :math:`\mathrm{start}` procedure: :math:`\mathrm{mode} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e05us-py2-py-notes:
**Notes**
The local minimization method is :meth:`opt.lsq_gencon_deriv <naginterfaces.library.opt.lsq_gencon_deriv>`. The problem is assumed to be stated in the following form:
.. math::
\textit{minimize}_{{x \in R^n}}\text{ }F\left(x\right) = \frac{1}{2}\sum_{{i = 1}}^m{\left(y_i-f_i\left(x\right)\right)}^2\quad \text{ subject to }\quad l\leq \begin{pmatrix}x\\A_Lx\\c\left(x\right)\end{pmatrix}\leq u\text{,}
where :math:`F\left(x\right)` (the `objective function`) is a nonlinear function which can be represented as the sum of squares of :math:`m` subfunctions :math:`\left(y_1-f_1\left(x\right)\right),\left(y_2-f_2\left(x\right)\right),\ldots,\left(y_m-f_m\left(x\right)\right)`, the :math:`y_i` are constant, :math:`A_L` is an :math:`n_L\times n` constant linear constraint matrix, and :math:`c\left(x\right)` is an :math:`n_N` element vector of nonlinear constraint functions. (The matrix :math:`A_L` and the vector :math:`c\left(x\right)` may be empty.) The objective function and the constraint functions are assumed to be smooth, i.e., at least twice-continuously differentiable. (This function will usually solve `(1) <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05usf.html#eqn1>`__ if any isolated discontinuities are away from the solution.)
``nlp_multistart_sqp_lsq`` solves a user-specified number of local optimization problems with different starting points.
You may specify the starting points via the function :math:`\mathrm{start}`.
If a random number generator is used to generate the starting points then the argument :math:`\mathrm{repeat1}` allows you to specify whether a repeatable set of points are generated or whether different starting points are generated on different calls.
The resulting local minima are ordered and the best :math:`\mathrm{nb}` results returned in order of ascending values of the resulting objective function values at the minima.
Thus the value returned in position :math:`1` will be the best result obtained.
If a sufficiently high number of different points are chosen then this is likely to be the global minimum.
.. _e05us-py2-py-references:
**References**
Gill, P E, Murray, W and Wright, M H, 1981, `Practical Optimization`, Academic Press
Hock, W and Schittkowski, K, 1981, `Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems` (187), Springer--Verlag
See Also
--------
:meth:`naginterfaces.library.examples.glopt.nlp_multistart_sqp_lsq_ex.main`
"""
raise NotImplementedError
[docs]def optset(optstr, comm, io_manager=None):
r"""
``optset`` either initializes or resets the option arrays or sets a single option for supported problem solving functions in submodule ``glopt``.
The following functions are supported:
:meth:`bnd_pso`,
:meth:`nlp_pso`,
:meth:`nlp_multistart_sqp`,
:meth:`nlp_multistart_sqp_lsq`.
.. _e05zk-py2-py-doc:
For full information please refer to the NAG Library document for e05zk
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05zkf.html
.. _e05zk-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying the option to be set.
Initialize = :math:`\textit{function name}`
Initialize the option arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] for use with function :math:`\textit{function name}`, where :math:`\textit{function name}` is the name associated with the function of interest.
Defaults
Resets all options to their default values.
:math:`\textit{option} = \textit{optval}`
See :ref:`Other Parameters for bnd_pso <e05sa-py2-py-other_params>`, :ref:`Other Parameters for nlp_pso <e05sb-py2-py-other_params>`, :ref:`Other Parameters for nlp_multistart_sqp <e05uc-py2-py-other_params>` and :ref:`Other Parameters for nlp_multistart_sqp_lsq <e05us-py2-py-other_params>` for details of valid values for :math:`\textit{option}` and :math:`\textit{optval}`. The equals sign (:math:`=`) delimiter must be used to separate the :math:`\textit{option}` from its :math:`\textit{optval}` value.
:math:`\mathrm{optstr}` is case insensitive.
Each token in the :math:`\textit{option}` and :math:`\textit{optval}` component must be separated by at least one space.
**comm** : dict, communication object, modified in place
Communication structure.
`On initial entry`: need not be set.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
.. _e05zk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
On entry, the option in :math:`\mathrm{optstr}` was not recognized: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`12`)
On entry, the expected delimiter ':math:`=`' was not found in :math:`\mathrm{optstr}`: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`13`)
The :math:`\textit{option}` in :math:`\mathrm{optstr}` is associated with a numerical value. However, the :math:`\textit{optval}`, :math:`\langle\mathit{\boldsymbol{value}}\rangle`, present in :math:`\mathrm{optstr}` could not be fully interpreted.
(`errno` :math:`13`)
On entry, could not convert the specified :math:`\textit{optval}` to an integer: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`13`)
On entry, could not convert the specified :math:`\textit{optval}` to a real: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`14`)
On entry, the :math:`\textit{option}` in :math:`\mathrm{optstr}` has been detected as Initialize, however the :math:`\textit{optval}`, :math:`\langle\mathit{\boldsymbol{value}}\rangle`, associated with :math:`\mathrm{optstr}` has not been recognized as a valid function name.
(`errno` :math:`15`)
On entry, the :math:`\textit{optval}` supplied for the integer option is not valid.
:math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`16`)
On entry, the :math:`\textit{optval}` supplied for the real option is not valid.
:math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`17`)
On entry, the :math:`\textit{optval}` supplied for the character option is not valid.
:math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`17`)
On entry, the option in :math:`\mathrm{optstr}` was not recognized: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`21`)
On entry, either the option arrays have not been initialized or they have been corrupted.
(`errno` :math:`21`)
On entry, the option in :math:`\mathrm{optstr}` was not recognized: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e05zk-py2-py-notes:
**Notes**
``optset`` has three purposes: to initialize option arrays; to reset all options to their default values; or to set a single option to a user-supplied value.
Options and their values are, in general, presented as a character string, :math:`\mathrm{optstr}`, of the form ':math:`\textit{option} = \textit{optval}`'; alphabetic characters can be supplied in either upper or lower case.
Both :math:`\textit{option}` and :math:`\textit{optval}` may consist of one or more tokens separated by white space.
The tokens that comprise :math:`\textit{optval}` will normally be either an integer, real or character value as defined in the description of the specific optional argument.
In addition all options can take an :math:`\textit{optval}` DEFAULT which resets the option to its default value.
It is imperative that option arrays are initialized before any options are set, before the relevant problem solving function is called and before any options are queried using :meth:`optget`.
Information relating to available option names and their corresponding valid values is given in :ref:`Other Parameters for bnd_pso <e05sa-py2-py-other_params>`, :ref:`Other Parameters for nlp_pso <e05sb-py2-py-other_params>`, :ref:`Other Parameters for nlp_multistart_sqp <e05uc-py2-py-other_params>` and :ref:`Other Parameters for nlp_multistart_sqp_lsq <e05us-py2-py-other_params>`.
See Also
--------
:meth:`naginterfaces.library.examples.glopt.nlp_multistart_sqp_lsq_ex.main`
"""
raise NotImplementedError
[docs]def optget(optstr, comm):
r"""
``optget`` is used to query the value of options available to supported problem solving functions in submodule ``glopt``.
Currently the following functions are supported:
:meth:`bnd_pso`,
:meth:`nlp_pso`,
:meth:`nlp_multistart_sqp`,
:meth:`nlp_multistart_sqp_lsq`.
.. _e05zl-py2-py-doc:
For full information please refer to the NAG Library document for e05zl
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e05/e05zlf.html
.. _e05zl-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying the option whose current value is required. See :ref:`Other Parameters for bnd_pso <e05sa-py2-py-other_params>` and :ref:`Other Parameters for nlp_pso <e05sb-py2-py-other_params>` for information on valid options. In addition, the following is a valid option:
Identify
``optget`` returns the function name supplied to :meth:`optset` when the option arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] were initialized.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`optset`.
**Returns**
**optvalue** : dict
The option-value ``dict``, with the following keys:
``'value'`` : float, int or str
The value of the requested option.
``'annotation'`` : None or str
Possible additional information about the option value.
.. _e05zl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
On entry, the :math:`\textit{option}` in :math:`\mathrm{optstr}` has not been recognized.
(`errno` :math:`61`)
The arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] have either not been initialized, have become corrupted, or are not compatible with this option setting function.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`41`)
On entry, :math:`\mathrm{optstr}` indicates a character option, but :math:`\textit{cvalue}` is too short to hold the stored value. The returned value will be truncated.
.. _e05zl-py2-py-notes:
**Notes**
``optget`` is used to query the current values of options.
It is necessary to initialize option arrays using :meth:`optset` before any options are queried.
Information on option names and whether these options are real, integer or character can be found in :ref:`Other Parameters for bnd_pso <e05sa-py2-py-other_params>`, :ref:`Other Parameters for nlp_pso <e05sb-py2-py-other_params>`, :ref:`Other Parameters for nlp_multistart_sqp <e05uc-py2-py-other_params>` and :ref:`Other Parameters for nlp_multistart_sqp_lsq <e05us-py2-py-other_params>`.
"""
raise NotImplementedError
