Changes for release 0.11.3

docs/sources/contributing.rst

@@ -90,7 +90,7 @@ The CI/CD pipelines are defined in the `CI YML <.github/workflows/ci.yml>`_, and
 Versioning and Releases
 =======================
 
-The package is currently at version ``0.11.0`` - `semantic versioning <https://semver.org/>`_ is used.
+The package is currently at version ``0.11.3`` - `semantic versioning <https://semver.org/>`_ is used.
 
 There is currently no dedicated pipeline for releases - both `GitHub releases <https://github.com/sr-murthy/continuedfractions/releases>`_ and `PyPI packages <https://pypi.org/project/continuedfractions>`_ are published manually, but both have the same version tag.
 

docs/sources/creating-continued-fractions.rst

@@ -33,7 +33,7 @@ The continued fraction object for :math:`\frac{649}{200}` can be created as foll
 **Note**: The same object can also be constructed using ``ContinuedFraction('649/200')``, ``ContinuedFraction('3.245')``, ``ContinuedFraction(Fraction(649, 200))``, ``ContinuedFraction(Fraction(649), 200))``, ``ContinuedFraction(649, Fraction(200)))``, and ``ContinuedFraction(Decimal('3.245'))``. But passing a numeric literal such as ``649/200`` will result in an evaluation of the decimal integer division using `binary floating point division <https://docs.python.org/3/tutorial/floatingpoint.html>`_,
 thus producing a fractional approximation, in this case, ``ContinuedFraction(3653545197704315, 1125899906842624)``.
 
-The float value of ``ContinuedFraction(649, 200)`` is available via the ``.as_float()`` method, in this case, an exact value of :math:`3.245`.
+The float value of ``ContinuedFraction(649, 200)`` is available via the ``.as_float()`` method, in this case, a value of :math:`3.245`.
 
 .. code:: python
 
@@ -47,8 +47,6 @@ A ``decimal.Decimal`` value of ``ContinuedFraction(649, 200)`` is also available
    >>> cf.as_decimal()
    Decimal('3.245')
 
-**Note**: the ``.as_float()`` and ``.as_decimal`` methods are unique to ``ContinuedFraction`` - they are not defined in the ``fractions.Fraction`` superclass.
-
 Every finite continued fraction represents a rational number, and conversely every rational number can be represented as a finite continued fraction. On the other hand, infinite continued fractions can only represent `irrational numbers <https://en.wikipedia.org/wiki/Irrational_number>`_ and conversely every infinite continued fraction represents an irrational number.
 
 There are infinitely many rational and irrational numbers that cannot be represented exactly as binary fractions, and, therefore, also, as Python ``fractions.Fraction`` or ``float`` objects. In the current implementation of ``continuedfractions`` the ``fractions.Fraction`` class is the key type involved in creating continued fractions representations. This means that for infinitely many real numbers the package will only produce (finite) approximate representations.
@@ -99,7 +97,7 @@ Continued fractions can also be constructed from sequences of elements, using th
 Approximating Irrationals
 -------------------------
 
-Using ``ContinuedFraction.from_elements()`` can be very useful when trying to approximate irrational numbers with (finite) continued fractions. We know, for example, that the square root :math:`sqrt(n)` of any non-square (positive) integer :math:`n` is irrational. This can be proved quite easily by writing :math:`n = a^2 + r`, for integers :math:`a, r > 0`, from which we have:
+Using ``ContinuedFraction.from_elements()`` can be very useful when trying to approximate irrational numbers with (finite) continued fractions. We know, for example, that the square root :math:`\sqrt{n}` of any non-square (positive) integer :math:`n` is irrational. This can be proved quite easily by writing :math:`n = a^2 + r`, for integers :math:`a, r > 0`, from which we have:
 
 .. math::
    :nowrap:
@@ -275,15 +273,17 @@ https://plus.maths.org/content/chaos-numberland-secret-life-continued-fractionsU
 
 [3] Emory University Math Center. “Continued Fractions.” The Department of Mathematics and Computer Science, https://mathcenter.oxford.emory.edu/site/math125/continuedFractions/. Accessed 19 Feb 2024.
 
-[4] Wikipedia. “Mediant (mathematics)”. https://en.wikipedia.org/wiki/Mediant_(mathematics). Accessed 23 February 2024.
+[4] Khinchin, A. Ya. Continued Fractions. Dover Publications, 1997.
 
-[5] Python 3.12.2 Docs. “Floating Point Arithmetic: Issues and Limitations.” https://docs.python.org/3/tutorial/floatingpoint.html. Accessed 20 February 2024.
+[5] Python 3.12.2 Docs. “decimal - Decimal fixed point and floating point arithmetic.” https://docs.python.org/3/library/decimal.html. Accessed 21 February 2024.
 
-[6] Python 3.12.2 Docs. “fractions - Rational numbers.” https://docs.python.org/3/library/fractions.html. Accessed 21 February
-2024.
+[6] Python 3.12.2 Docs. “Floating Point Arithmetic: Issues and Limitations.” https://docs.python.org/3/tutorial/floatingpoint.html. Accessed 20 February 2024.
 
-[7] Python 3.12.2 Docs. “decimal - Decimal fixed point and floating point arithmetic.” https://docs.python.org/3/library/decimal.html. Accessed 21 February 2024.
+[7] Python 3.12.2 Docs. “fractions - Rational numbers.” https://docs.python.org/3/library/fractions.html. Accessed 21 February
+2024.
 
 [8] Wikipedia. “Continued Fraction”. https://en.wikipedia.org/wiki/Continued_fraction. Accessed 19 February 2024.
 
-[9] Wikipedia. “Stern-Brocot Tree”. https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree. Accessed 23 February 2024.
+[9] Wikipedia. “Mediant (mathematics)”. https://en.wikipedia.org/wiki/Mediant_(mathematics). Accessed 23 February 2024.
+
+[10] Wikipedia. “Stern-Brocot Tree”. https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree. Accessed 23 February 2024.

docs/sources/getting-started.rst

@@ -34,8 +34,8 @@ Package Structure
 
 This is a `library <https://github.com/sr-murthy/continuedfractions/blob/main/src/continuedfractions/lib.py>`_ of standalone functions, which are summarised below.
 
--  ``continued_fraction_rational`` - generates the (ordered) sequence of elements (coefficients) of a unique, finite, simple continued fraction representation of a given rational number, given as a ``fractions.Fraction`` object
--  ``continued_fraction_real`` - generates the sequence of elements of a continued fraction representation of a real number, given as a single ``int``, ``float``, ``fractions.Fraction``, ``decimal.Decimal`` object, or a pair of ``ints`` and/or ``fractions.Fraction`` objects representing the numerator and non-zero denominator, respectively, of the number. The continued fraction representation that this generates is, currently, finite and, for irrational numbers, approximate, because of the use of a rational representation of the number for computing the elements. This will be addressed in the future to make the continued fraction representation as exact and complete as required by the caller
+-  ``continued_fraction_rational`` - generates the (ordered) sequence of elements (coefficients) of a finite, simple continued fraction representation of a given rational number, given as a ``fractions.Fraction`` object. The representation will be unique if the given number is a rational number with an exact binary fractional representation, otherwise it will be approximate.
+-  ``continued_fraction_real`` - generates the sequence of elements of a finite, simple, continued fraction representation of a real number, given as a single ``int``, ``float``, ``fractions.Fraction``, ``decimal.Decimal`` object, or a pair of ``ints`` and/or ``fractions.Fraction`` objects representing the numerator and non-zero denominator, respectively, of the number. The resulting continued fraction representation will be exact for any rational number and which has an exact representation as a binary fraction, otherwise, it will only be approximate. The latter limitation will be addressed in future versions.
 -  ``convergent`` - returns the ``k``-th convergent (for a positive integer `k`) of a continued fraction representation of a number, from a sequence of its elements; the convergent is returned as a``fractions.Fraction`` object
 -  ``mediant`` - returns the ``k``-th left or right mediant of two rational numbers, given as ``fractions.Fraction`` objects
 

docs/sources/mediants.rst

@@ -36,7 +36,7 @@ The ``ContinuedFraction`` class provides a ``.mediant()`` method which can be us
    >>> assert ContinuedFraction(1, 2) < ContinuedFraction(1, 2).mediant(Fraction(3, 4)) < ContinuedFraction(3, 4)
    # True
 
-In particular, the mediant :math:`\frac{a + c}{b + d}` of :math:`\frac{a}{b}` and :math:`\frac{c}{d}` has the property that **if** :math:`bc - ad = 1` then :math:`\frac{a + c}{b + d}` is the fraction with the smallest denominator lying in the (open) interval :math:`(\frac{a}{b}, \frac{c}{d})`. As :math:`\frac{1}{2}` and :math:`\frac{2}{3}` satisfy the relation :math:`bc - ad = 2\cdot2 - 1\cdot3 = 4 - 3 = 1` it follows that their mediant :math:`\frac{3}{5}` is the "next" (or "first")  fraction after :math:`\frac{1}{2}`, but before :math:`\frac{2}{3}`, compared to any other fraction in that interval with a denominator :math:`\geq b + d = 5`.
+In particular, the mediant :math:`\frac{a + c}{b + d}` of :math:`\frac{a}{b}` and :math:`\frac{c}{d}` has the property that **if** :math:`bc - ad = 1` then :math:`\frac{a + c}{b + d}` is the fraction with the smallest denominator lying in the (open) interval :math:`(\frac{a}{b}, \frac{c}{d})` with denominator :math:`>= b + d`. As :math:`\frac{1}{2}` and :math:`\frac{2}{3}` satisfy the relation :math:`bc - ad = 2\cdot2 - 1\cdot3 = 4 - 3 = 1` it follows that their mediant :math:`\frac{3}{5}` is the "next" (or "first")  fraction after :math:`\frac{1}{2}`, but before :math:`\frac{2}{3}`, compared to any other fraction in that interval with a denominator :math:`\geq b + d = 5`.
 
 This is an ordering property that links mediants to ordered sequences of rational numbers such as `Farey sequences <https://en.wikipedia.org/wiki/Farey_sequence>`_ and the `Stern-Brocot tree <https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree>`_.
 
@@ -124,10 +124,12 @@ References
 
 [1] Baker, Alan. A concise introduction to the theory of numbers. Cambridge: Cambridge Univ. Pr., 2002.
 
-[2] Wikipedia. “Continued Fraction”. https://en.wikipedia.org/wiki/Continued_fraction. Accessed 19 February 2024.
+[2] Khinchin, A. Ya. Continued Fractions. Dover Publications, 1997.
 
-[3] Wikipedia. “Farey sequence”. https://en.wikipedia.org/wiki/Farey_sequence. Accessed 10 March 2024.
+[3] Wikipedia. “Continued Fraction”. https://en.wikipedia.org/wiki/Continued_fraction. Accessed 19 February 2024.
 
-[4] Wikipedia. “Mediant (mathematics)”. https://en.wikipedia.org/wiki/Mediant_(mathematics). Accessed 23 February 2024.
+[4] Wikipedia. “Farey sequence”. https://en.wikipedia.org/wiki/Farey_sequence. Accessed 10 March 2024.
 
-[5] Wikipedia. “Stern-Brocot Tree”. https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree. Accessed 23 February 2024.
+[5] Wikipedia. “Mediant (mathematics)”. https://en.wikipedia.org/wiki/Mediant_(mathematics). Accessed 23 February 2024.
+
+[6] Wikipedia. “Stern-Brocot Tree”. https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree. Accessed 23 February 2024.

docs/sources/properties-of-continued-fractions.rst

@@ -45,7 +45,7 @@ The elements and orders of ``ContinuedFraction`` objects are well behaved with r
 Convergents and Rational Approximations
 =======================================
 
-For an integer :math:`k >= 0` the :math:`k`-th **convergent** :math:`C_k` of a continued fraction :math:`[a_0; a_1,\ldots]` of a real number :math:`x` is defined to be the rational number and finite continued fraction represented by :math:`[a_0; a_1,\ldots,a_k]`, formed from the first :math:`k + 1` elements of the original.
+For an integer :math:`k >= 0` the (simple) :math:`k`-th **convergent** :math:`C_k` of a continued fraction :math:`[a_0; a_1,\ldots]` of a real number :math:`x` is defined to be the rational number and finite, simple continued fraction represented by :math:`[a_0; a_1,\ldots,a_k]`, formed from the first :math:`k + 1` elements of the original.
 
 .. math::
 
@@ -104,7 +104,7 @@ Obviously, we can only handle finite continued fractions in Python, so the conve
 Segments and Remainders
 =======================
 
-Convergents are linked to the concept of **segments**, which are finite subsequences of elements of a given continued fraction. More precisely, we can define the :math:`k`-th segment :math:`S_k` of a continued fraction :math:`[a_0; a_1,\ldots]` as the sequence of its first :math:`k + 1` elements, namely :math:`a_0,a_1,\ldots,a_k`, which uniquely determines the :math:`k`-order convergent :math:`C_k` of the continued fraction, as defined above.
+Convergents are linked to the concept of **segments**, which are finite subsequences of elements of a given continued fraction. More precisely, we can define the :math:`k`-th segment :math:`S_k` of a continued fraction :math:`[a_0; a_1,\ldots]` as the sequence :math:`(a_0,a_1,\ldots,a_k)` of its first :math:`k + 1` elements, which uniquely determines the :math:`k`-order (simple) convergent :math:`C_k` of the continued fraction, as defined above.
 
 The segments of ``ContinuedFraction`` objects can be obtained via the ``.segment()`` method, which takes a non-negative integer not exceeding the order.
 
@@ -115,7 +115,7 @@ The segments of ``ContinuedFraction`` objects can be obtained via the ``.segment
 
 **Note**: Unlike the :math:`k`-order convergents the segments are ``ContinuedFraction`` objects.
 
-A related concept is that of **remainders** of continued fractions, which are (possibly infinite) subsequences of elements of a given continued fraction, starting from a given element, usually the leading element :math:`a_0`. More precisely, we can define the :math:`k`-th remainder :math:`R_k` of a continued fraction given by :math:`[a_0; a_1,\ldots]` as the continued fraction :math:`[a_k;a_{k + 1},\ldots]`, whose elements form the segment :math:`S_k = a_k,a_{k + 1},\ldots`, as defined above.
+A related concept is that of **remainders** of continued fractions, which are (possibly infinite) subsequences of elements of a given continued fraction, starting from a given element, usually the leading element :math:`a_0`. More precisely, we can define the :math:`k`-th remainder :math:`R_k` of a continued fraction :math:`[a_0; a_1,\ldots]` as the continued fraction :math:`[a_k;a_{k + 1},\ldots]`, obtained by "removing" the elements of the :math:`k`-th segment :math:`S_k = (a_0,a_1,\ldots,a_k)` from :math:`[a_0; a_1,\ldots]`.
 
 .. math::
 
@@ -140,11 +140,11 @@ Using the continued fraction representation of :math:`\frac{649}{200}` we can ve
    & R_3 &&= [4;] = 4 = \frac{4}{1}
    \end{alignat*}
 
-Given a (possibly infinite) continued fraction :math:`[a_0; a_1, a_2,\ldots]` the remainders :math:`R_1,R_2,\ldots` satisfy the following relation:
+Given a (possibly infinite) continued fraction :math:`[a_0; a_1, a_2,\ldots]` the remainders :math:`R_1,R_2,\ldots` satisfy the following relation, for integers :math:`k > 0`:
 
 .. math::
 
-   R_{k - 1} = a_{k - 1} + \frac{1}{R_k}
+   R_k = \frac{1}{R_{k - 1} - a_{k - 1}}
 
 .. _properties-of-continued-fractions.references:
 
@@ -158,15 +158,17 @@ https://plus.maths.org/content/chaos-numberland-secret-life-continued-fractionsU
 
 [3] Emory University Math Center. “Continued Fractions.” The Department of Mathematics and Computer Science, https://mathcenter.oxford.emory.edu/site/math125/continuedFractions/. Accessed 19 Feb 2024.
 
-[4] Wikipedia. “Mediant (mathematics)”. https://en.wikipedia.org/wiki/Mediant_(mathematics). Accessed 23 February 2024.
+[4] Khinchin, A. Ya. Continued Fractions. Dover Publications, 1997.
 
-[5] Python 3.12.2 Docs. “Floating Point Arithmetic: Issues and Limitations.” https://docs.python.org/3/tutorial/floatingpoint.html. Accessed 20 February 2024.
+[5] Python 3.12.2 Docs. “decimal - Decimal fixed point and floating point arithmetic.” https://docs.python.org/3/library/decimal.html. Accessed 21 February 2024.
 
-[6] Python 3.12.2 Docs. “fractions - Rational numbers.” https://docs.python.org/3/library/fractions.html. Accessed 21 February
-2024.
+[6] Python 3.12.2 Docs. “Floating Point Arithmetic: Issues and Limitations.” https://docs.python.org/3/tutorial/floatingpoint.html. Accessed 20 February 2024.
 
-[7] Python 3.12.2 Docs. “decimal - Decimal fixed point and floating point arithmetic.” https://docs.python.org/3/library/decimal.html. Accessed 21 February 2024.
+[7] Python 3.12.2 Docs. “fractions - Rational numbers.” https://docs.python.org/3/library/fractions.html. Accessed 21 February
+2024.
 
 [8] Wikipedia. “Continued Fraction”. https://en.wikipedia.org/wiki/Continued_fraction. Accessed 19 February 2024.
 
-[9] Wikipedia. “Stern-Brocot Tree”. https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree. Accessed 23 February 2024.
+[9] Wikipedia. “Mediant (mathematics)”. https://en.wikipedia.org/wiki/Mediant_(mathematics). Accessed 23 February 2024.
+
+[10] Wikipedia. “Stern-Brocot Tree”. https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree. Accessed 23 February 2024.

src/continuedfractions/version.py

@@ -1 +1 @@
-__version__ = "0.11.2"
+__version__ = "0.11.3"