.. module:: bisection

Solving Equations by the Bisection Method
=========================================

We wish to calculate the root of a given function located between two given points by the known *bisection method* which does that by repeatedly approaching the two points around the root until they are close enough.
Specificly, given the function :math:`f` and the points :math:`x_1, x_2` such that there is a point :math:`x_0` such that  :math:`f(x_0) = 0`, the method repeatedly  calculates the middle point :math:`(x_1+x_2) / 2.0` (let's call it ``m``),
calculates its image ``f(m)``,
and compares the sign (positive or negative) of ``f(m)`` and the signs of ``f(x_1)`` and ``f(x_2)``.
The point whose image has the same sign of ``f(m)`` is moved to ``m``. This is illustrated by the following figure:

.. image:: bisection.png
   :scale: 100%
   :align: center

For example, for the second iteration it is necessary to move the point :math:`x_2` to
the midpoint :math:`m` and the point :math:`x_1` remains the same.

This iterative process continues until the distance between :math:`x_1` and :math:`x_2`is less than :math:`epsilon` and the root is calculated as the **average** of :math:`x_1` and :math:`x_2`.

The *bisection method* is garanteed to converge towards a root as long as the function
:math:`f(x)` is continuous between :math:`x_1` and :math:`x_2`, and that the initial values
:math:`f(x_1)` and :math:`f(x_2)` have opposite signs
(this ensures the existence of a root between :math:`x_1` and :math:`x_2`).

Please implement the following Python function in the :mod:`bisection` module (:file:`bisection.py` file) to compute a root of the specific function :math:`f(x) = x^3-3\,sin(x)+1`:

    .. py:function:: bisection_solve(x1, x2, eps)

    **given**

    - ``x1, x2``, :class:`float` such that ``x2 >= x1`` (they determine the search interval) and ``f(x1)*f(x2) < 0.0``
    - ``eps``, :class:`float` with the tolerance

    **returns** a :class:`float` ``x0`` obtained by applying the *bisection method* described above such that :math:`f(x0) == 0.0` with tolerance ``eps``.

For example:

   .. literalinclude:: bisection.test
      :language: python
      :start-after: --ini
      :end-before: --fi

Doctests are available at the :download:`bisection.test <bisection.test>` file.