naginterfaces.library.opt.one_​var_​deriv

naginterfaces.library.opt.one_var_deriv(funct, e1, e2, a, b, maxcal, data=None)

one_var_deriv searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function and first derivative values. The method (based on cubic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/e04/e04bbf.html

Parameters

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

You must supply this function to calculate the values of $F\left(x\right)$ and $\frac{dF}{dx}$ at any point $x$ in $[a,b]$.

It should be tested separately before being used in conjunction with one_var_deriv.

Parameters

xcfloat

The point $x$ at which the values of $F$ and $\frac{dF}{dx}$ are required.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

fcfloat

Must be set to the value of the function $F$ at the current point $x$.

gcfloat

Must be set to the value of the first derivative $\frac{dF}{dx}$ at the current point $x$.

e1float

The relative accuracy to which the position of a minimum is required. (Note that, since $e1$ is a relative tolerance, the scaling of $x$ is automatically taken into account.)

$e1$ should be no smaller than $2ϵ$, and preferably not much less than $\sqrt{ϵ}$, where $ϵ$ is the machine precision.

e2float

The absolute accuracy to which the position of a minimum is required. $e2$ should be no smaller than $2ϵ$.

afloat

The lower bound $a$ of the interval containing a minimum.

bfloat

The upper bound $b$ of the interval containing a minimum.

maxcalint

The maximum number of calls of $funct$ to be allowed.

dataarbitrary, optional

User-communication data for callback functions.

Returns

e1float

If you set $e1$ to $0.0$ (or to any value less than $ϵ$), $e1$ will be reset to the default value $\sqrt{ϵ}$ before starting the minimization process.

e2float

If you set $e2$ to $0.0$ (or to any value less than $ϵ$), $e2$ will be reset to the default value $\sqrt{ϵ}$.

afloat

An improved lower bound on the position of the minimum.

bfloat

An improved upper bound on the position of the minimum.

maxcalint

The total number of times that $funct$ was actually called.

xfloat

The estimated position of the minimum.

ffloat

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

gfloat

The value of the first derivative at the final point in $x$.

Warns

NagAlgorithmicWarning

(errno $1$)

On entry, $a+e2=⟨value⟩$ and $b=⟨value⟩$.

Constraint: $a+e2<b$.

(errno $1$)

On entry, $maxcal=⟨value⟩$.

Constraint: $maxcal\ge 2$.

(errno $2$)

The maximum number of function calls, $⟨value⟩$, have been performed. This may have happened simply because $maxcal$ was set too small for the particular problem, or may be due to a mistake in the user-supplied function $funct$. If no mistake can be found in $funct$, restart one_var_deriv (preferably with the values of $a$ and $b$ given on exit from the previous call to one_var_deriv).

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

one_var_deriv is applicable to problems of the form:

$$Minimize\left(F\right)\left(x\right)\text{subject to}a\le x\le b$$

when the first derivative $\frac{dF}{dx}$ can be calculated. The function normally computes a sequence of $x$ values which tend in the limit to a minimum of $F\left(x\right)$ subject to the given bounds. It also progressively reduces the interval $[a,b]$ in which the minimum is known to lie. It uses the safeguarded cubic-interpolation method described in Gill and Murray (1973).

You must supply a $funct$ to evaluate $F\left(x\right)$ and $\frac{dF}{dx}$. The arguments $e1$ and $e2$ together specify the accuracy

$$\text{Tol}\left(x\right)=e1\times \left|x\right|+e2$$

to which the position of the minimum is required. Note that $funct$ is never called at a point which is closer than $\text{Tol}\left(x\right)$ to a previous point.

If the original interval $[a,b]$ contains more than one minimum, one_var_deriv will normally find one of the minima.

References

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