naginterfaces.library.roots.contfn_​cntin

naginterfaces.library.roots.contfn_cntin(x, f, eps=1.1102230246251565e-13, eta=0.0, nfmax=1000, data=None)

contfn_cntin attempts to locate a zero of a continuous function using a continuation method based on a secant iteration.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c05/c05awf.html

Parameters

xfloat

An initial approximation to the zero.

fcallable retval = f(x, data=None)

$f$ must evaluate the function $f$ whose zero is to be determined.

Parameters

xfloat

The point at which the function must be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of $f$ evaluated at $x$.

epsfloat, optional

An absolute tolerance to control the accuracy to which the zero is determined. In general, the smaller the value of $eps$ the more accurate $x$ will be as an approximation to $\alpha$. Indeed, for very small positive values of $eps$, it is likely that the final approximation will satisfy $|x-\alpha |<eps$. You are advised to call the function with more than one value for $eps$ to check the accuracy obtained.

etafloat, optional

A value such that if $\left|f\left(x\right)\right|<eta$, $x$ is accepted as the zero. $eta$ may be specified as $0.0$ (see Accuracy).

nfmaxint, optional

The maximum permitted number of calls to $f$ from contfn_cntin. If $f$ is inexpensive to evaluate, $nfmax$ should be given a large value (say $>1000$).

dataarbitrary, optional

User-communication data for callback functions.

Returns

xfloat

The final approximation to the zero, unless $errno$ = 1 or 2, in which case it contains no useful information.

Raises

NagValueError

(errno $1$)

On entry, $nfmax=⟨value⟩$.

Constraint: $nfmax>0$.

(errno $1$)

On entry, $eps=⟨value⟩$.

Constraint: $eps>0.0$.

(errno $2$)

Internal scale factor invalid for this problem. Consider using contfn_cntin_rcomm() instead and setting $\text{scal}$.

(errno $3$)

Either $f$ has no zero near $x$ or too much accuracy has been requested. Check the coding of $f$ or increase $eps$.

(errno $4$)

More than $nfmax$ calls have been made to $f$.

Notes

contfn_cntin attempts to obtain an approximation to a simple zero $\alpha$ of the function $f\left(x\right)$ given an initial approximation $x$ to $\alpha$. The zero is found by a call to contfn_cntin_rcomm() whose specification should be consulted for details of the method used.

The approximation $x$ to the zero $\alpha$ is determined so that at least one of the following criteria is satisfied:

1. $|x-\alpha |\sim eps$,

2. $\left|f\left(x\right)\right|<eta$.