Document

scipy 1.8.0 Pypi GitHub Homepage

toms748(f, a, b, args=(), k=1, xtol=2e-12, rtol=8.881784197001252e-16, maxiter=100, full_output=False, disp=True)

Implements the Algorithm 748 method of Alefeld, Potro and Shi to find a zero of the function f on the interval :None:None:`[a , b]`, where :None:None:`f(a)` and :None:None:`f(b)` must have opposite signs.

It uses a mixture of inverse cubic interpolation and "Newton-quadratic" steps. [APS1995].

Notes

f must be continuous. Algorithm 748 with k=2 is asymptotically the most efficient algorithm known for finding roots of a four times continuously differentiable function. In contrast with Brent's algorithm, which may only decrease the length of the enclosing bracket on the last step, Algorithm 748 decreases it each iteration with the same asymptotic efficiency as it finds the root.

For easy statement of efficiency indices, assume that f has 4 continuouous deriviatives. For k=1 , the convergence order is at least 2.7, and with about asymptotically 2 function evaluations per iteration, the efficiency index is approximately 1.65. For k=2 , the order is about 4.6 with asymptotically 3 function evaluations per iteration, and the efficiency index 1.66. For higher values of k, the efficiency index approaches the kth root of (3k-2) , hence k=1 or k=2 are usually appropriate.

Parameters

f : function: Python function returning a scalar. The function $f$ must be continuous, and $f(a)$ and $f(b)$ have opposite signs.
a : scalar,: lower boundary of the search interval
b : scalar,: upper boundary of the search interval
args : tuple, optional: containing extra arguments for the function f. f is called by f(x, *args) .
k : int, optional: The number of Newton quadratic steps to perform each iteration. k>=1 .
xtol : scalar, optional: The computed root x0 will satisfy np.allclose(x, x0, atol=xtol, rtol=rtol) , where x is the exact root. The parameter must be nonnegative.
rtol : scalar, optional: The computed root x0 will satisfy np.allclose(x, x0, atol=xtol, rtol=rtol) , where x is the exact root.
maxiter : int, optional: If convergence is not achieved in :None:None:`maxiter` iterations, an error is raised. Must be >= 0.
full_output : bool, optional: If :None:None:`full_output` is False, the root is returned. If :None:None:`full_output` is True, the return value is (x, r) , where x is the root, and r is a RootResults object.
disp : bool, optional: If True, raise RuntimeError if the algorithm didn't converge. Otherwise, the convergence status is recorded in the RootResults return object.

Returns

x0 : float: Approximate Zero of f
r : `RootResults` (present if ``full_output = True``): Object containing information about the convergence. In particular, r.converged is True if the routine converged.

Find a zero using TOMS Algorithm 748 method.

Examples

>>> def f(x):
...     return (x**3 - 1)  # only one real root at x = 1

>>> from scipy import optimize
... root, results = optimize.toms748(f, 0, 2, full_output=True)
... root
1.0

>>> results
      converged: True
           flag: 'converged'
 function_calls: 11
     iterations: 5
           root: 1.0

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

scipy.optimize._zeros_py.toms748

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them