maths.numerical_analysis.nth_root
=================================

.. py:module:: maths.numerical_analysis.nth_root

.. autoapi-nested-parse::

   Approximate the nth root of a real number using Newton's Method.

   The nth root of a real number R can be computed with Newton's method,
   which starts with an initial guess x_0 and then iterates using the
   recurrence relation:

   x_{k + 1} = x_k - ((x_k)**n - R)/(n*(x_k)**(n-1))

   The recurrence relation can be rewritten for computational efficiency:

   x_{k + 1} = (n-1)/n*x_k + R/(n*(x_k)**(n-1))

   Given a tolerance TOL, a stopping criterion can be set as:

   abs(x_{k + 1} - x_k) < TOL

   References:
   - https://en.wikipedia.org/wiki/Nth_root#Using_Newton's_method
   - Sauer, T. (2011): Numerical analysis.
       USA. Addison-Wesley Publishing Company.



Functions
---------

.. autoapisummary::

   maths.numerical_analysis.nth_root.nth_root


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

.. py:function:: nth_root(radicand: float, index: int, tolerance: float = 0.0001) -> float

   Approximate the nth root of the radicand for the given index

   Args:
       radicand: number from which the root is taken
       index: positive integer which is the degree of the root
       tolerance: positive real number that establishes the stopping criterion

   Returns:
       new_approximation: approximation of the nth root of the radicand for the
       given index

   Raises:
       TypeError: radicand is not a real number
       TypeError: index is not an integer
       ValueError: index is not a positive integer
       TypeError: tolerance is not a real number
       ValueError: tolerance is not a positive real number
       ValueError: math domain error

   >>> round(nth_root(9, 2),1)
   3.0

   >>> int(round(nth_root(-8, 3, 0.001)))
   -2

   >>> int(round(nth_root(256, 4, 0.001)))
   4

   >>> round(nth_root(2, 2), 5)
   1.41421

   >>> round(nth_root(0.25, 2, 0.00000001), 1)
   0.5

   >>> round(nth_root(-8/27, 3, 0.0000001), 5)
   -0.66667

   >>> nth_root(0, 2, 0.1)
   0.0

   >>> nth_root(0.0, 5)
   0.0

   >>> all(abs(nth_root(k, k, 0.00000001) - k**(1/k)) <= 1e-10 for k in range(1,10))
   True

   >>> nth_root('invalid input', 3, 0.0001)
   Traceback (most recent call last):
       ...
   TypeError: radicand must be a real number, not a str

   >>> nth_root(4, 0.5, 0.0001)
   Traceback (most recent call last):
       ...
   TypeError: index must be an integer, not a float

   >>> nth_root(16, -4, 0.001)
   Traceback (most recent call last):
       ...
   ValueError: index must be a positive integer, -4 <= 0

   >>> nth_root(4, 2, '0.000001')
   Traceback (most recent call last):
       ...
   TypeError: tolerance must be a real number, not str

   >>> nth_root(9, 2, -0.01)
   Traceback (most recent call last):
       ...
   ValueError: tolerance must be a positive real number, -0.01 <= 0

   >>> nth_root(-256, 4, 0.0001)
   Traceback (most recent call last):
       ...
   ValueError: math domain error, radicand must be nonnegative for even index