Iterative Methods

cxroots.iterative_methods.iterate_to_root(x0: complex, f: Callable[[complex | float], complex], df: Callable[[complex | float], complex] | None = None, step_tol: float = 1e-12, root_tol: float = 1e-12, max_iter: int = 20, refine_roots_beyond_tol: bool = False, callback: Callable[[complex, complex, complex, int], bool] | None = None) → complex | None

Starting with initial point x0 iterate to a root of f. This function is called during the rootfinding process to refine any roots found. If df is given then the Newton-Raphson method, newton(), will be used, otherwise Muller’s method, muller(), will be used instead.

Parameters:

• x0 (complex) – An initial point for the iteration.

• f (function) – Function of a single variable which we seek to find a root of.

• df (function, optional) – The derivative of f.

• step_tol (float, optional) – The routine ends if the step size, dx, between sucessive iterations satisfies abs(dx) < step_tol and refine_roots_beyond_tol is False.

• root_tol (float, optional) – A root, x, is only returned if abs(f(x)) < root_tol, otherwise None is returned

• max_iter (int, optional) – The routine ends after max_iter iterations.

• refine_roots_beyond_tol (bool, optional) – If True then the routine ends only once the error of the previous iteration, x0, was at least as good as the current iteration, x, in the sense that abs(f(x)) >= abs(f(x0)), and the previous iteration satisfied abs(dx0) < step_tol. In this case the previous iteration is returned as the approximation of the root, provided that it satisfies abs(f(x)) < root_tol

• callback (function, optional) – After each iteration callback(x, dx, f(x), iteration) will be called where ‘x’ is the current iteration of the estimated root, ‘dx’ is the step size between the previous and current ‘x’ and ‘iteration’ the number of iterations that have been taken. If the callback function evaluates to True then the routine will end.

Returns:

An approximation for a root of f. If the rootfinding was unsucessful then None will be returned instead.

Return type:

complex

cxroots.iterative_methods.muller(x1: complex, x2: complex, x3: complex, f: Callable[[complex | float], complex], step_tol: float = 1e-12, root_tol: float = 0, max_iter: int = 20, refine_roots_beyond_tol: bool = False, callback: Callable[[complex, complex, complex, int], bool] | None = None) → Tuple[complex, float]

A wrapper for mpmath’s implementation of Muller’s method.

Parameters:

• x1 (float or complex) – An initial point for iteration, should be close to a root of f.

• x2 (float or complex) – An initial point for iteration, should be close to a root of f. Should not equal x1.

• x3 (float or complex) – An initial point for iteration, should be close to a root of f. Should not equal x1 or x2.

• f (function) – Function of a single variable which we seek to find a root of.

• step_tol (float, optional) – The routine ends if the step size, dx, between sucessive iterations satisfies abs(dx) < step_tol and refine_roots_beyond_tol is False.

• root_tol (float, optional) – The routine ends if abs(f(x)) < root_tol and refine_roots_beyond_tol is False.

• max_iter (int, optional) – The routine ends after max_iter iterations.

• refine_roots_beyond_tol (bool, optional) – If True then routine ends if the error of the previous iteration, x0, was at least as good as the current iteration, x, in the sense that abs(f(x)) >= abs(f(x0)) and the previous iteration satisfied either abs(dx0) < step_tol or abs(f(x0)) < root_tol. In this case the previous iteration is returned as the approximation of the root.

• callback (function, optional) – After each iteration callback(x, dx, f(x), iteration) will be called where ‘x’ is the current iteration of the estimated root, ‘dx’ is the step size between the previous and current ‘x’ and ‘iteration’ the number of iterations that have been taken. If the callback function evaluates to True then the routine will end.

Returns:

• complex – The approximation to a root of f.

• float – abs(f(x)) where x is the final approximation for the root of f.

cxroots.iterative_methods.newton(x0: complex, f: Callable[[complex | float], complex], df: Callable[[complex | float], complex], step_tol: float = 1e-12, root_tol: float = 0, max_iter: int = 20, refine_roots_beyond_tol: bool = False, callback: Callable[[complex, complex, complex, int], bool] | None = None) → Tuple[complex, float]

Find an approximation to a point xf such that f(xf)=0 for a scalar function f using Newton-Raphson iteration starting at the point x0.

Parameters:

• x0 (float or complex) – Initial point for Newton iteration, should be as close as possible to a root of f

• f (function) – Function of a single variable which we seek to find a root of.

• df (function) – Function of a single variable, df(x), providing the derivative of the function f(x) at the point x

• step_tol (float, optional) – The routine ends if the step size, dx, between sucessive iterations satisfies abs(dx) < step_tol and refine_roots_beyond_tol is False.

• root_tol (float, optional) – The routine ends if abs(f(x)) < root_tol and refine_roots_beyond_tol is False.

• max_iter (int, optional) – The routine ends after max_iter iterations.

• refine_roots_beyond_tol (bool, optional) – If True then routine ends if the error of the previous iteration, x0, was at least as good as the current iteration, x, in the sense that abs(f(x)) >= abs(f(x0)) and the previous iteration satisfied either abs(dx0) < step_tol or abs(f(x0)) < root_tol. In this case the previous iteration is returned as the approximation of the root.

• callback (function, optional) – After each iteration callback(x, dx, f(x), iteration) will be called where ‘x’ is the current iteration of the estimated root, ‘dx’ is the step size between the previous and current ‘x’ and ‘iteration’ the number of iterations that have been taken. If the callback function evaluates to True then the routine will end.

Returns:

• complex – The approximation to a root of f.

• float – abs(f(x)) where x is the final approximation for the root of f.