maths.numerical_analysis.newton_raphson
=======================================

.. py:module:: maths.numerical_analysis.newton_raphson

.. autoapi-nested-parse::

   The Newton-Raphson method (aka the Newton method) is a root-finding algorithm that
   approximates a root of a given real-valued function f(x). It is an iterative method
   given by the formula

   x_{n + 1} = x_n + f(x_n) / f'(x_n)

   with the precision of the approximation increasing as the number of iterations increase.

   Reference: https://en.wikipedia.org/wiki/Newton%27s_method



Attributes
----------

.. autoapisummary::

   maths.numerical_analysis.newton_raphson.RealFunc


Functions
---------

.. autoapisummary::

   maths.numerical_analysis.newton_raphson.calc_derivative
   maths.numerical_analysis.newton_raphson.func
   maths.numerical_analysis.newton_raphson.newton_raphson


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

.. py:function:: calc_derivative(f: RealFunc, x: float, delta_x: float = 0.001) -> float

   Approximate the derivative of a function f(x) at a point x using the finite
   difference method

   >>> import math
   >>> tolerance = 1e-5
   >>> derivative = calc_derivative(lambda x: x**2, 2)
   >>> math.isclose(derivative, 4, abs_tol=tolerance)
   True
   >>> derivative = calc_derivative(math.sin, 0)
   >>> math.isclose(derivative, 1, abs_tol=tolerance)
   True


.. py:function:: func(x: float) -> float

.. py:function:: newton_raphson(f: RealFunc, x0: float = 0, max_iter: int = 100, step: float = 1e-06, max_error: float = 1e-06, log_steps: bool = False) -> tuple[float, float, list[float]]

   Find a root of the given function f using the Newton-Raphson method.

   :param f: A real-valued single-variable function
   :param x0: Initial guess
   :param max_iter: Maximum number of iterations
   :param step: Step size of x, used to approximate f'(x)
   :param max_error: Maximum approximation error
   :param log_steps: bool denoting whether to log intermediate steps

   :return: A tuple containing the approximation, the error, and the intermediate
       steps. If log_steps is False, then an empty list is returned for the third
       element of the tuple.

   :raises ZeroDivisionError: The derivative approaches 0.
   :raises ArithmeticError: No solution exists, or the solution isn't found before the
       iteration limit is reached.

   >>> import math
   >>> tolerance = 1e-15
   >>> root, *_ = newton_raphson(lambda x: x**2 - 5*x + 2, 0.4, max_error=tolerance)
   >>> math.isclose(root, (5 - math.sqrt(17)) / 2, abs_tol=tolerance)
   True
   >>> root, *_ = newton_raphson(lambda x: math.log(x) - 1, 2, max_error=tolerance)
   >>> math.isclose(root, math.e, abs_tol=tolerance)
   True
   >>> root, *_ = newton_raphson(math.sin, 1, max_error=tolerance)
   >>> math.isclose(root, 0, abs_tol=tolerance)
   True
   >>> newton_raphson(math.cos, 0)
   Traceback (most recent call last):
   ...
   ZeroDivisionError: No converging solution found, zero derivative
   >>> newton_raphson(lambda x: x**2 + 1, 2)
   Traceback (most recent call last):
   ...
   ArithmeticError: No converging solution found, iteration limit reached


.. py:data:: RealFunc