naginterfaces.library.opt.bounds_mod_deriv_comp¶

naginterfaces.library.opt.bounds_mod_deriv_comp(funct, monit, eta, ibound, bl, bu, x, lh, iprint=1, maxcal=None, xtol=0.0, delta=0.0, stepmx=100000.0, data=None, io_manager=None)[source]¶

bounds_mod_deriv_comp is a comprehensive modified Newton algorithm for finding:

an unconstrained minimum of a function of several variables;
a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.

First derivatives are required. The function is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

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

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/e04/e04kdf.html

Parameters

functcallable (fc, gc) = funct(iflag, xc, data=None)

$f u n c t$ must evaluate the function $F (x)$ and its first derivatives $\frac{\partial F}{\partial x_{j}}$ at a specified point. (However, if you do not wish to calculate $F$ or its first derivatives at a particular $x$ , there is the option of setting an argument to cause bounds_mod_deriv_comp to terminate immediately.)

Parameters

iflagint: Will have been set to $1$ or $2$ . The value $1$ indicates that only the first derivatives of $F$ need be supplied, and the value $2$ indicates that both $F$ itself and its first derivatives must be calculated.
xcfloat, ndarray, shape $(n)$: The point $x$ at which the $\frac{\partial F}{\partial x_{j}}$ , or $F$ and the $\frac{\partial F}{\partial x_{j}}$ , are required.
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

fcfloat: Unless $i f l a g = 1$ on entry, $f u n c t$ must set $f c$ to the value of the objective function $F$ at the current point $x$ .
gcfloat, array-like, shape $(n)$: $f u n c t$ must set $g c [j - 1]$ to the value of the first derivative $\frac{\partial F}{\partial x_{j}}$ at the point $x$ , for $j = 1, 2, \dots, n$ .

monitcallable monit(xc, fc, gc, istate, gpjnrm, cond, posdef, niter, nf, data=None)

If $i p r i n t \geq 0$ , you must supply $m o n i t$ which is suitable for monitoring the minimization process. $m o n i t$ must not change the values of any of its arguments.

If $i p r i n t < 0$ , a $m o n i t$ with the correct argument list must still be supplied, although it will not be called.

Parameters

xcfloat, ndarray, shape $(n)$

The coordinates of the current point $x$ .

fcfloat

The value of $F (x)$ at the current point $x$ .

gcfloat, ndarray, shape $(n)$

The value of $\frac{\partial F}{\partial x_{j}}$ at the current point $x$ , for $j = 1, 2, \dots, n$ .

istateint, ndarray, shape $(n)$

Information about which variables are currently fixed on their bounds and which are free.

If $i s t a t e [j - 1]$ is negative, $x_{j}$ is currently:

fixed on its upper bound if $i s t a t e [j - 1] = - 1$
fixed on its lower bound if $i s t a t e [j - 1] = - 2$
effectively a constant (i.e., $l_{j} = u_{j}$ ) if $i s t a t e [j - 1] = - 3$

If $i s t a t e [j - 1]$ is positive, its value gives the position of $x_{j}$ in the sequence of free variables.

gpjnrmfloat

The Euclidean norm of the current projected gradient vector $g_{z}$ .

condfloat

The ratio of the largest to the smallest elements of the diagonal factor $D$ of the approximated projected Hessian matrix. This quantity is usually a good estimate of the condition number of the projected Hessian matrix. (If no variables are currently free, $c o n d$ is set to zero.)

posdefbool

Specifies $T r u e$ or $F a l s e$ according to whether or not the approximation to the second derivative matrix for the current subspace, $H$ , is positive definite.

niterint

The number of iterations (as outlined in Notes) which have been performed by bounds_mod_deriv_comp so far.

nfint

The number of evaluations of $F (x)$ so far, i.e., the number of calls of $f u n c t$ with $i f l a g$ set to $2$ . Each such call of $f u n c t$ also calculates the first derivatives of $F$ . (In addition to these calls monitored by $n f$ , $f u n c t$ is called with $i f l a g$ set to $1$ not more than $n$ times per iteration.)

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

etafloat

Every iteration of bounds_mod_deriv_comp involves a linear minimization (i.e., minimization of $F (x + α p)$ with respect to $α$ ). $e t a$ specifies how accurately these linear minimizations are to be performed. The minimum with respect to $α$ will be located more accurately for small values of $e t a$ (say, $0.01$ ) than large values (say, $0.9$ ).

Although accurate linear minimizations will generally reduce the number of iterations (and hence the number of calls of $f u n c t$ to estimate the second derivatives), they will tend to increase the number of calls of $f u n c t$ needed for each linear minimization.

On balance, it is usually more efficient to perform a low accuracy linear minimization when $n$ is small and a high accuracy minimization when $n$ is large.

Suggested value:

$e t a = 0.5$ if $1 < n < 10$

$e t a = 0.1$ if $10 \leq n \leq 20$

$e t a = 0.01$ if $n > 20$

If $n = 1$ , eta should be set to $0.0$ (also when the problem is effectively one-dimensional even though $n > 1$ ; i.e., if for all except one of the variables the lower and upper bounds are equal).

iboundint

Indicates whether the problem is unconstrained or bounded. If there are bounds on the variables, $i b o u n d$ can be used to indicate whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:

$i b o u n d = 0$

If the variables are bounded and you are supplying all the $l_{j}$ and $u_{j}$ individually.

$i b o u n d = 1$

If the problem is unconstrained.

$i b o u n d = 2$

If the variables are bounded, but all the bounds are of the form $0 \leq x_{j}$ .

$i b o u n d = 3$

If all the variables are bounded, and $l_{1} = l_{2} = \dots = l_{n}$ and $u_{1} = u_{2} = \dots = u_{n}$ .

$i b o u n d = 4$

If the problem is unconstrained. (The $i b o u n d = 4$ option is provided for consistency with other functions. In bounds_mod_deriv_comp it produces the same effect as $i b o u n d = 1 .$ )

blfloat, array-like, shape $(n)$

The fixed lower bounds $l_{j}$ .

If $i b o u n d$ is set to $0$ , you must set $b l [j - 1]$ to $l_{j}$ , for $j = 1, 2, \dots, n$ . (If a lower bound is not specified for any $x_{j}$ , the corresponding $b l [j - 1]$ should be set to a large negative number, e.g., $- 10^{6}$ .)

If $i b o u n d$ is set to $3$ , you must set $b l [0]$ to $l_{1}$ ; bounds_mod_deriv_comp will then set the remaining elements of $b l$ equal to $b l [0]$ .

If $i b o u n d$ is set to $1$ , $2$ or $4$ , $b l$ will be initialized by bounds_mod_deriv_comp.

bufloat, array-like, shape $(n)$

The fixed upper bounds $u_{j}$ .

If $i b o u n d$ is set to $0$ , you must set $b u [j - 1]$ to $u_{j}$ , for $j = 1, 2, \dots, n$ . (If an upper bound is not specified for any variable, the corresponding $b u [j - 1]$ should be set to a large positive number, e.g., $10^{6}$ .)

If $i b o u n d$ is set to $3$ , you must set $b u [0]$ to $u_{1}$ ; bounds_mod_deriv_comp will then set the remaining elements of $b u$ equal to $b u [0]$ .

If $i b o u n d$ is set to $1$ , $2$ or $4$ , $b u$ will be initialized by bounds_mod_deriv_comp.

xfloat, array-like, shape $(n)$

$x [j - 1]$ must be set to a guess at the $j$ th component of the position of the minimum, for $j = 1, 2, \dots, n$ .

lhint

The dimension of the array $h e s l$ .

iprintint, optional

The frequency with which $m o n i t$ is to be called.

$i p r i n t > 0$

$m o n i t$ is called once every $i p r i n t$ iterations and just before exit from bounds_mod_deriv_comp.

$i p r i n t = 0$

$m o n i t$ is just called at the final point.

$i p r i n t < 0$

$m o n i t$ is not called at all.

$i p r i n t$ should normally be set to a small positive number.

maxcalNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: $50 \times n$ .

The maximum permitted number of evaluations of $F (x)$ , i.e., the maximum permitted number of calls of $f u n c t$ with $i f l a g$ set to $2$ . It should be borne in mind that, in addition to the calls of $f u n c t$ which are limited directly by $m a x c a l$ , there will be calls of $f u n c t$ (with $i f l a g$ set to $1$ ) to evaluate only first derivatives.

xtolfloat, optional

The accuracy in $x$ to which the solution is required.

If $x_{t r u e}$ is the true value of $x$ at the minimum, then $x_{s o l}$ , the estimated position before a normal exit, is such that $∥ x_{s o l} - x_{t r u e} ∥ < x t o l \times (1.0 + ∥ x_{t r u e} ∥)$ where $∥ y ∥ = \sqrt{\sum_{j = 1}^{n} y_{j}^{2}}$ .

For example, if the elements of $x_{s o l}$ are not much larger than $1.0$ in modulus, and if $x t o l$ is set to $10^{- 5}$ , then $x_{s o l}$ is usually accurate to about five decimal places. (For further details see Accuracy.)

If the problem is scaled as described in Further Comments and $ϵ$ is the machine precision, then $\sqrt{ϵ}$ is probably the smallest reasonable choice for $x t o l$ .

This is because, normally, to machine accuracy, $F (x + \sqrt{ϵ} e_{j}) = F (x)$ , for any $j$ where $e_{j}$ is the $j$ th column of the identity matrix.

If you set $x t o l$ to $0.0$ (or any positive value less than $ϵ$ ), bounds_mod_deriv_comp will use $10.0 \times \sqrt{ϵ}$ instead of $x t o l$ .

deltafloat, optional

The differencing interval to be used for approximating the second derivatives of $F (x)$ . Thus, for the finite difference approximations, the first derivatives of $F (x)$ are evaluated at points which are $d e l t a$ apart. If $ϵ$ is the machine precision, $\sqrt{ϵ}$ will usually be a suitable setting for $d e l t a$ . If you set $d e l t a$ to $0.0$ (or to any positive value less than $ϵ$ ), bounds_mod_deriv_comp will automatically use $\sqrt{ϵ}$ as the differencing interval.

stepmxfloat, optional

An estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency a slight overestimate is preferable.)

bounds_mod_deriv_comp will ensure that, for each iteration,

\sqrt{n \sum j = 1 {[x_{j}^{(k)} - x_{j}^{(k - 1)}]}^{2}} \leq s t e p m x,

where $k$ is the iteration number.

Thus, if the problem has more than one solution, bounds_mod_deriv_comp is most likely to find the one nearest to the starting point.

On difficult problems, a realistic choice can prevent the sequence of $x^{(k)}$ entering a region where the problem is ill-behaved and can also help to avoid possible overflow in the evaluation of $F (x)$ .

However, an underestimate of $s t e p m x$ can lead to inefficiency.

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns

blfloat, ndarray, shape $(n)$

The lower bounds actually used by bounds_mod_deriv_comp, e.g., if $i b o u n d = 2$ , $b l [0] = b l [1] = \dots = b l [n - 1] = 0.0$ .

bufloat, ndarray, shape $(n)$

The upper bounds actually used by bounds_mod_deriv_comp, e.g., if $i b o u n d = 2$ , $b u [0] = b u [1] = \dots = b u [n - 1] = 10^{6}$ .

xfloat, ndarray, shape $(n)$

The final point $x^{(k)}$ . Thus, if no exception or warning is raised on exit, $x [j - 1]$ is the $j$ th component of the estimated position of the minimum.

heslfloat, ndarray, shape $(l h)$

During the determination of a direction $p_{z}$ (see Notes), $H + E$ is decomposed into the product $L D L^{T}$ , where $L$ is a unit lower triangular matrix and $D$ is a diagonal matrix. (The matrices $H$ , $E$ , $L$ and $D$ are all of dimension $n_{z}$ , where $n_{z}$ is the number of variables free from their bounds. $H$ consists of those rows and columns of the full estimated second derivative matrix which relate to free variables. $E$ is chosen so that $H + E$ is positive definite.)

$h e s l$ and $h e s d$ are used to store the factors $L$ and $D$ .

The elements of the strict lower triangle of $L$ are stored row by row in the first $n_{z} (n_{z} - 1) / 2$ positions of $h e s l$ .

The diagonal elements of $D$ are stored in the first $n_{z}$ positions of $h e s d$ .

In the last factorization before a normal exit, the matrix $E$ will be zero, so that $h e s l$ and $h e s d$ will contain, on exit, the factors of the final estimated second derivative matrix $H$ .

The elements of $h e s d$ are useful for deciding whether to accept the results produced by bounds_mod_deriv_comp (see Accuracy).

hesdfloat, ndarray, shape $(n)$

During the determination of a direction $p_{z}$ (see Notes), $H + E$ is decomposed into the product $L D L^{T}$ , where $L$ is a unit lower triangular matrix and $D$ is a diagonal matrix. (The matrices $H$ , $E$ , $L$ and $D$ are all of dimension $n_{z}$ , where $n_{z}$ is the number of variables free from their bounds. $H$ consists of those rows and columns of the full estimated second derivative matrix which relate to free variables. $E$ is chosen so that $H + E$ is positive definite.)

$h e s l$ and $h e s d$ are used to store the factors $L$ and $D$ .

The elements of the strict lower triangle of $L$ are stored row by row in the first $n_{z} (n_{z} - 1) / 2$ positions of $h e s l$ .

The diagonal elements of $D$ are stored in the first $n_{z}$ positions of $h e s d$ .

In the last factorization before a normal exit, the matrix $E$ will be zero, so that $h e s l$ and $h e s d$ will contain, on exit, the factors of the final estimated second derivative matrix $H$ .

The elements of $h e s d$ are useful for deciding whether to accept the results produced by bounds_mod_deriv_comp (see Accuracy).

istateint, ndarray, shape $(n)$

Information about which variables are currently on their bounds and which are free. If $i s t a t e [j - 1]$ is:

equal to $- 1$ , $x_{j}$ is fixed on its upper bound;
equal to $- 2$ , $x_{j}$ is fixed on its lower bound;
equal to $- 3$ , $x_{j}$ is effectively a constant (i.e., $l_{j} = u_{j}$ );
positive, $i s t a t e [j - 1]$ gives the position of $x_{j}$ in the sequence of free variables.

ffloat

The function value at the final point given in $x$ .

gfloat, ndarray, shape $(n)$

The first derivative vector corresponding to the final point given in $x$ . The components of $g$ corresponding to free variables should normally be close to zero.

Raises

NagValueError

(errno $1$ )

On entry, $i b o u n d = 0$ and $b l [j - 1] > b u [j - 1]$ for some $j$ .

(errno $1$ )

On entry, $i b o u n d = 3$ and $b l [0] > b u [0]$ .

(errno $1$ )

On entry, $i b o u n d = ⟨ v a l u e ⟩$ .

Constraint: $0 \leq i b o u n d \leq 4$ .

(errno $1$ )

On entry, $d e l t a = ⟨ v a l u e ⟩$ .

Constraint: $d e l t a \geq 0.0$ .

(errno $1$ )

On entry, $m a x c a l = ⟨ v a l u e ⟩$ .

Constraint: $m a x c a l \geq 1$ .

(errno $1$ )

On entry, $s t e p m x = ⟨ v a l u e ⟩$ and $x t o l = ⟨ v a l u e ⟩$ .

Constraint: $s t e p m x \geq x t o l$ .

(errno $1$ )

On entry, $e t a = ⟨ v a l u e ⟩$ .

Constraint: $0.0 \leq e t a < 1.0$ .

(errno $1$ )

On entry, $x t o l = ⟨ v a l u e ⟩$ .

Constraint: $x t o l \geq 0.0$ .

(errno $1$ )

On entry, $n = ⟨ v a l u e ⟩$ .

Constraint: $n \geq 1$ .

(errno $1$ )

On entry, $l h = ⟨ v a l u e ⟩$ .

Constraint: $l h \geq ⟨ v a l u e ⟩$ .

Warns

NagAlgorithmicWarning

(errno $2$ ): There have been $m a x c a l$ function evaluations.
(errno $3$ ): The conditions for a minimum have not all been satisfied, but a lower point could not be found.
(errno $5$ ): No further progress can be made.

NagCallbackTerminateWarning

(errno $i < 0$ ): User requested termination by setting $i f l a g$ negative in $f u n c t$ .

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

bounds_mod_deriv_comp is applicable to problems of the form:

M i n i m i z e (F) (x_{1}, x_{2}, \dots, x_{n}) subject to l_{j} \leq x_{j} \leq u_{j}, j = 1, 2, \dots, n .

Special provision is made for unconstrained minimization (i.e., problems which actually have no bounds on the $x_{j}$ ), problems which have only non-negativity bounds, and problems in which $l_{1} = l_{2} = \dots = l_{n}$ and $u_{1} = u_{2} = \dots = u_{n}$ . It is possible to specify that a particular $x_{j}$ should be held constant. You must supply a starting point, and a $f u n c t$ to calculate the value of $F (x)$ and its first derivatives $\frac{\partial F}{\partial x_{j}}$ at any point $x$ .

A typical iteration starts at the current point $x$ where $n_{z}$ (say) variables are free from their bounds. The vector $g_{z}$ , whose elements are the derivatives of $F (x)$ with respect to the free variables, is known. The matrix of second derivatives with respect to the free variables, $H$ , is estimated by finite differences. (Note that $g_{z}$ and $H$ are both of dimension $n_{z}$ .) The equations

(H + E) p_{z} = - g_{z}

are solved to give a search direction $p_{z}$ . (The matrix $E$ is chosen so that $H + E$ is positive definite.)

$p_{z}$ is then expanded to an $n$ -vector $p$ by the insertion of appropriate zero elements, $α$ is found such that $F (x + α p)$ is approximately a minimum (subject to the fixed bounds) with respect to $α$ ; and $x$ is replaced by $x + α p$ . (If a saddle point is found, a special search is carried out so as to move away from the saddle point.) If any variable actually reaches a bound, it is fixed and $n_{z}$ is reduced for the next iteration.

There are two sets of convergence criteria – a weaker and a stronger. Whenever the weaker criteria are satisfied, the Lagrange multipliers are estimated for all the active constraints. If any Lagrange multiplier estimate is significantly negative, then one of the variables associated with a negative Lagrange multiplier estimate is released from its bound and the next search direction is computed in the extended subspace (i.e., $n_{z}$ is increased). Otherwise minimization continues in the current subspace until the stronger convergence criteria are satisfied. If at this point there are no negative or near-zero Lagrange multiplier estimates, the process is terminated.

If you specify that the problem is unconstrained, bounds_mod_deriv_comp sets the $l_{j}$ to $- 10^{6}$ and the $u_{j}$ to $10^{6}$ . Thus, provided that the problem has been sensibly scaled, no bounds will be encountered during the minimization process and bounds_mod_deriv_comp will act as an unconstrained minimization algorithm.

References

Gill, P E and Murray, W, 1973, Safeguarded steplength algorithms for optimization using descent methods, NPL Report NAC 37, National Physical Laboratory

Gill, P E and Murray, W, 1974, Newton-type methods for unconstrained and linearly constrained optimization, Math. Programming (7), 311–350

Gill, P E and Murray, W, 1976, Minimization subject to bounds on the variables, NPL Report NAC 72, National Physical Laboratory

NAG and Python

Return to Front

naginterfaces.library.opt.bounds_mod_deriv_comp¶

naginterfaces.library.opt.bounds_​mod_​deriv_​comp¶

naginterfaces.library.opt.bounds_mod_deriv_comp¶