maths.numerical_analysis.weierstrass_method
===========================================

.. py:module:: maths.numerical_analysis.weierstrass_method


Functions
---------

.. autoapisummary::

   maths.numerical_analysis.weierstrass_method.weierstrass_method


Module Contents
---------------

.. py:function:: weierstrass_method(polynomial: collections.abc.Callable[[numpy.ndarray], numpy.ndarray], degree: int, roots: numpy.ndarray | None = None, max_iter: int = 100) -> numpy.ndarray

   Approximates all complex roots of a polynomial using the
   Weierstrass (Durand-Kerner) method.
   Args:
       polynomial: A function that takes a NumPy array of complex numbers and returns
                   the polynomial values at those points.
       degree: Degree of the polynomial (number of roots to find). Must be ≥ 1.
       roots:  Optional initial guess as a NumPy array of complex numbers.
               Must have length equal to 'degree'.
               If None, perturbed complex roots of unity are used.
       max_iter: Number of iterations to perform (default: 100).

   Returns:
       np.ndarray: Array of approximated complex roots.

   Raises:
       ValueError: If degree < 1, or if initial roots length doesn't match the degree.

   Note:
       - Root updates are clipped to prevent numerical overflow.

   Example:
       >>> import numpy as np
       >>> def check(poly, degree, expected):
       ...     roots = weierstrass_method(poly, degree)
       ...     return np.allclose(np.sort(roots), np.sort(expected))

       >>> check(
       ...     lambda x: x**2 - 1,
       ...     2,
       ...     np.array([-1, 1]))
       True

       >>> check(
       ...     lambda x: x**3 - 4.5*x**2 + 5.75*x - 1.875,
       ...     3,
       ...     np.array([1.5, 0.5, 2.5])
       ... )
       True

   See Also:
       https://en.wikipedia.org/wiki/Durand%E2%80%93Kerner_method