Merge pull request #8 from sr-murthy/release-0.0.6

Release 0.0.6

Author: sr-murthy

README.md

@@ -19,7 +19,7 @@ A simple extension of the Python [`fractions`](https://docs.python.org/3/library
 ## Prelude
 
 $$
-\pi = 3 + \frac{1}{7 + \frac{1}{15 + \frac{1}{1 + \frac{1}{292 + \cdots}}}}
+\pi = 3 + \frac{1}{7 + \frac{1}{15 + \frac{1}{1 + \frac{1}{292 + \ddots}}}}
 $$
 
 ```python
@@ -43,7 +43,7 @@ ContinuedFraction(355, 113)
 >>> math.pi - pi_approx.as_float()
 -2.667641894049666e-07
 >>> import pytest
->>> pytest.approx(pi_approx.as_float(), rel=decimal.getcontext().prec) == math.pi
+>>> pytest.approx(pi_approx.as_float(), rel=1e-12) == math.pi
 True
 >>> ContinuedFraction('3.245')
 ContinuedFraction(649, 200)
@@ -85,7 +85,7 @@ The functions in `continuedfractions.lib` are standalone and thus useful on thei
 
 ### A Simple Introduction with Examples
 
-From a user perspective it is easiest to use the [`continuedfractions.continuedfraction.ContinuedFraction`](https://github.com/sr-murthy/continuedfractions/blob/main/src/continuedfraction.py) class. A simple introduction is given below with a variety of examples.
+The starting point is the [`continuedfractions.continuedfraction.ContinuedFraction`](https://github.com/sr-murthy/continuedfractions/blob/main/src/continuedfraction.py) class. A simple introduction is given below of it can be used, with a variety of examples.
 
 #### Importing the `ContinuedFraction` Class
 
@@ -221,32 +221,74 @@ A related concept is that of **remainders** of continued fractions, which are (p
 (ContinuedFraction(649, 200), ContinuedFraction(200, 49), ContinuedFraction(49, 4), ContinuedFraction(4, 1))
 ```
 
-Another feature which the package includes is [mediants](https://en.wikipedia.org/wiki/Mediant_(mathematics)). The mediant of two rational numbers $\frac{a}{b}$ and $\frac{c}{d}$, where $b, d \neq 0$, is given by the fraction:
+#### Mediants
+
+Another feature which the package includes is [mediants](https://en.wikipedia.org/wiki/Mediant_(mathematics)). The (simple) mediant of two rational numbers $\frac{a}{b}$ and $\frac{c}{d}$, where $b, d \neq 0$, is defined as the rational number:
 
 $$
 \frac{a + c}{b + d}
 $$
 
-and has the property that:
+Assuming that $\frac{a}{b} < \frac{c}{d}$ and $cd > 0$ the mediant above has the property that:
 
 $$
 \frac{a}{b} < \frac{a + c}{b + d} < \frac{c}{d}
 $$
 
-assuming $\frac{a}{b} < \frac{c}{d}$ and $cd > 0$.
-
-The `ContinuedFraction` class provides a `.mediant()` method for objects to compute their mediants with a given fraction, which could be another `ContinuedFraction` or `fractions.Fraction` object. The result is also a `ContinuedFraction` object. A few examples are given below.
+Mediants can give good rational approximations to real numbers of interest.
 
+The `ContinuedFraction` class provides a `.mediant()` method which can be used to calculate mediants with other `ContinuedFraction` or `fractions.Fraction` objects. The result is also a `ContinuedFraction` object. A few examples are given below of how to calculate mediants.
 
 ```python
 >>> ContinuedFraction('0.5').mediant(Fraction(2, 3))
 >>> ContinuedFraction(3, 5)
+>>> ContinuedFraction('0.6').elements
+(0, 1, 1, 2)
 >>> ContinuedFraction(1, 2).mediant(ContinuedFraction('2/3'))
 >>> ContinuedFraction(3, 5)
 >>> assert ContinuedFraction(1, 2) < ContinuedFraction(1, 2).mediant(Fraction(3, 4)) < ContinuedFraction(3, 4)
 # True
 ````
 
+The concept of the simple mediant of two fractions $\frac{a}{b}$ and $\frac{c}{d}$ as given above can be generalised to $k$-th mediants, which can be defined as follows:
+
+$$
+\frac{a + kc}{b + kd}
+$$ 
+
+Assuming that $\frac{a}{b} < \frac{c}{d}$ and $cd > 0$ we have, as $k$ increases, a strictly increasing sequence of fractions bounded by $\frac{a}{b}$ and $\frac{c}{d}$ on either side:
+
+$$
+\frac{a}{b} < \frac{a + c}{b + d} < \frac{a + 2c}{b + 2d} < \frac{a + 3c}{b + 3d} < \cdots < \frac{c}{d}
+$$
+
+Thus, the sequence of mediants as defined above converges to $\frac{c}{d}$ as $k$ increases.
+
+$$
+\lim_{k \to \infty} \frac{a + kc}{b + kd} = \frac{c}{d}
+$$
+
+We can illustrate this using `ContinuedFraction.mediant` using increasing values of the mediant order `k`, which defaults to `k=1`.
+
+```python
+>>> c1 = ContinuedFraction(1, 2)
+>>> c2 = ContinuedFraction(3, 5)
+>>> c1.mediant(c2)
+ContinuedFraction(4, 7)
+>>> c1.mediant(c2).as_float()
+0.5714285714285714
+>>> c1.mediant(c2, k=10)
+0.5961538461538461
+>>> c1.mediant(c2, k=100)
+0.599601593625498
+>>> c1.mediant(c2, k=10 ** 6)
+ContinuedFraction(3000001, 5000002)
+>>> c1.mediant(c2, k=10 ** 6).as_float()
+0.599999960000016
+```
+
+Mediants have other [interesting connections](https://en.wikipedia.org/wiki/Stern%E2%80%93Brocot_tree), including to sequences and orderings of rational numbers.
+
 ### Constructing Continued Fractions from Element Sequences
 
 Continued fractions can also be constructed from element sequences, using the `ContinuedFraction.from_elements()` class method. Because `ContinuedFraction` is a subclass of `fractions.Fraction` all `ContinuedFraction` objects are fully operable as rational numbers, including as negative rationals.
@@ -424,25 +466,30 @@ The CI/CD pipelines are defined in the [CI YML](.github/workflows/ci.yml), and p
 
 ### Versioning & Package Publishing
 
-The package is currently at version `0.0.4`, and packages are published manually to [PyPI](https://pypi.org/project/continuedfractions/). There is currently no release pipeline - this will be added later.
+The package is currently at version `0.0.6` ([semantic versioning](https://semver.org/) is used), and packages are published manually to [PyPI](https://pypi.org/project/continuedfractions/) using [twine](https://twine.readthedocs.io/en/stable/). There is currently no CI release pipeline - this will be added later.
 
 ## License
 
 The project is [licensed](LICENSE) under the [Mozilla Public License 2.0](https://opensource.org/licenses/MPL-2.0).
 
-
 ## References
 
-[1] Barrow, John D. “Chaos in Numberland: The secret life of continued fractions.” plus.maths.org, 1 June 2000, https://plus.maths.org/content/chaos-numberland-secret-life-continued-fractionsURL.
+[1] Baker, Alan. A concise introduction to the theory of numbers. Cambridge: Cambridge Univ. Pr., 2002.
+
+[2] Barrow, John D. “Chaos in Numberland: The secret life of continued fractions.” plus.maths.org, 1 June 2000, https://plus.maths.org/content/chaos-numberland-secret-life-continued-fractionsURL.
+
+[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] Python 3.12.2 Docs. "Floating Point Arithmetic: Issues and Limitations." https://docs.python.org/3/tutorial/floatingpoint.html. Accessed 20 February 2024.
 
-[2] 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.
+[5] Python 3.12.2 Docs. "fractions - Rational numbers." https://docs.python.org/3/library/fractions.html. Accessed 21 February 2024.
 
-[3] Python 3.12.2 Docs. "Floating Point Arithmetic: Issues and Limitations." https://docs.python.org/3/tutorial/floatingpoint.html. Accessed 20 February 2024.
+[6] 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.
 
-[4] Wikipedia. "Continued Fraction". https://en.wikipedia.org/wiki/Continued_fraction. Accessed 19 February 2024.
+[7] Wikipedia. "Continued Fraction". https://en.wikipedia.org/wiki/Continued_fraction. Accessed 19 February 2024.
 
 [^1]: Due to the nature of [binary floating point arithmetic](https://docs.python.org/3/tutorial/floatingpoint.html) it is not always possible to exactly represent a given [real number](https://en.wikipedia.org/wiki/Real_number). For the same reason, the continued fraction representations produced by the package will necessarily be [finite](https://en.wikipedia.org/wiki/Continued_fraction#Finite_continued_fractions).
 
 [^2]: The definition of "rational number" used here is standard: a ratio $\frac{a}{b}$ of integers $a$ and $b \neq 0$. If $a$ and $b$ have no common denominator then \frac{a}{b} is irreducible and unique.
 
-[^3]: This is due to the [theorem](https://en.wikipedia.org/wiki/Monotone_convergence_theorem) that every bounded monotonic sequence of real numbers converges.
+[^3]: This is due to the [theorem](https://en.wikipedia.org/wiki/Monotone_convergence_theorem) that every bounded monotonic sequence of real numbers converges.

src/continuedfractions/continuedfraction.py

@@ -25,7 +25,8 @@
     continued_fraction_rational,
     continued_fraction_real,
     fraction_from_elements,
-    kth_convergent,
+    convergent,
+    mediant,
 )
 
 
@@ -380,10 +381,10 @@ def __init__(self, *args:  int | float | str | Fraction | Decimal, **kwargs: Any
         else:      # pragma: no cover
             raise ValueError(self.__class__.__valid_inputs_msg__)
 
-        _kth_convergent = partial(kth_convergent, *self._elements)
+        _convergent = partial(convergent, *self._elements)
         self._convergents = MappingProxyType(
             {
-                k: _kth_convergent(k=k)
+                k: _convergent(k=k)
                 for k in range(len(self._elements))
             }
         )
@@ -591,39 +592,59 @@ def remainder(self, k: int, /) -> Fraction:
         """
         return self.__class__.from_elements(*self._elements[k:])
 
-    def mediant(self, other: Fraction) -> Fraction:
+    def mediant(self, other: Fraction, k: int = 1) -> Fraction:
         """
-        The continued fraction of the rational number formed by taking the
-        pairwise sum of the numerators and denominators of the original
-        continued fraction and a second fraction (`other`). The resulting
-        fraction has the property that its value lies between its two
-        constituents.        
+        Returns a `ContinuedFraction` object of the `fractions.Fraction`
+        objects representing two rational numbers `r = a / b` and `s = c / d`,
+        by taking their `k`-the mediant, for a positive integer `k`.
+
+        The `k`-th mediant of rationals `r = a / b` and `s = c / d`, where of
+        course the denominators are assumed to be non-zero and `k` is a 
+        positive integer, is given by
+        ::
+        
+            (a + kc) / (b + kd)
+
+        The 1st mediant is the fraction `(a + c) / (b + d)`.
+
+        Assuming that `a / b` < `c / d` and `cd > 0` their `k`-order mediants
+        have the property that:
+        ::
+
+            a / b < (a + c) / (b + d) < (a + 2c) / (a + 2d) < ... c / d
+        
+        As `k` goes to infinity the sequence of these mediants converges to
+        `s = c / d`, by the bounded monotone convergence theorem for real numbers.
 
         Parameters
         ----------
         other : fractions.Fraction or ContinuedFraction
-            The second fraction to use to calculate the mediant with the
-            first.
+            The second fraction to use to calculate the `k`-th mediant with
+            the first.
+        
+        k : int, default=1
+            The order of the mediant, as defined above.        
 
         Returns
         -------
         ContinuedFraction
-            The mediant of the original and the second fractions, as a
-            `ContinuedFraction` instance.
+            The `k`-th mediant of the original fraction and the second
+            fraction, as a `ContinuedFraction` instance.
 
         Examples
         --------
-        >>> cf = ContinuedFraction('.12345')
-        >>> cf
-        ContinuedFraction(2469, 20000)
-        >>> cf.mediant(Fraction('.1235'))
-        ContinuedFraction(679, 5500)
+        >>> c1 = ContinuedFraction('.5')
+        >>> c2 = ContinuedFraction(3, 5)
+        >>> c1, c2
+        (ContinuedFraction(1, 2), ContinuedFraction(3, 5))
+        >>> c1.mediant(c2)
+        ContinuedFraction(4, 7)
+        >>> c1.mediant(c2, k=2)
+        ContinuedFraction(7, 12)
+        >>> c1.mediant(c2, k=3)
+        ContinuedFraction(10, 17)
         """
-        return self.__class__(
-            self.numerator + other.numerator,
-            self.denominator + other.denominator
-        )
-
+        return self.__class__(mediant(self, other, k=k))
 
 
 if __name__ == "__main__":      # pragma: no cover

src/continuedfractions/lib.py

@@ -2,7 +2,8 @@
     'continued_fraction_real',
     'continued_fraction_rational',
     'fraction_from_elements',
-    'kth_convergent',
+    'convergent',
+    'mediant',
 ]
 
 
@@ -253,7 +254,7 @@ def fraction_from_elements(*elements: int) -> Fraction:
     return elements[0] + Fraction(1, fraction_from_elements(*elements[1:]))
 
 
-def kth_convergent(*elements: int, k: int = 1) -> Fraction:
+def convergent(*elements: int, k: int = 1) -> Fraction:
     """
     Returns a `fractions.Fraction` object representing the `k`-th convergent of
     a (finite) continued fraction given by an ordered sequence of its (integer)
@@ -292,24 +293,24 @@ def kth_convergent(*elements: int, k: int = 1) -> Fraction:
 
     Examples
     --------
-    >>> kth_convergent(3, 4, 12, 4, k=0)
+    >>> convergent(3, 4, 12, 4, k=0)
     Fraction(3, 1)
 
-    >>> kth_convergent(3, 4, 12, 4, k=1)
+    >>> convergent(3, 4, 12, 4, k=1)
     Fraction(13, 4)
 
-    >>> kth_convergent(3, 4, 12, 4, k=2)
+    >>> convergent(3, 4, 12, 4, k=2)
     Fraction(159, 49)
 
-    >>> kth_convergent(3, 4, 12, 4, k=3)
+    >>> convergent(3, 4, 12, 4, k=3)
     Fraction(649, 200)
 
-    >>> kth_convergent(3, 4, 12, 4, k=-1)
+    >>> convergent(3, 4, 12, 4, k=-1)
     Traceback (most recent call last):
     ...
     ValueError: `k` must be a non-negative integer less than the number of elements of the continued fraction
 
-    >>> kth_convergent(3, 4, 12, 4, k=4)
+    >>> convergent(3, 4, 12, 4, k=4)
     Traceback (most recent call last):
     ...
     ValueError: `k` must be a non-negative integer less than the number of elements of the continued fraction
@@ -323,6 +324,58 @@ def kth_convergent(*elements: int, k: int = 1) -> Fraction:
     return fraction_from_elements(*elements[:k + 1])
 
 
+def mediant(r: Fraction, s: Fraction, k: int = 1) -> Fraction:
+    """
+    Returns the `k-th mediant of two rational numbers `r = a / b` and
+    `s = c / d`, given as `fractions.Fraction` objects, where it is
+    assumed that the denominators `b` and `d` are non-zero. The `k`-th mediant
+    of `r` and `s` is defined as:
+    ::
+
+         (a + kc) / (b + kd)
+
+    The 1st mediant is given by `(a + c) / (b + d)`.
+
+    Assuming that `a / b` < `c / d` and `cd > 0` their `k`-order mediants have
+    the property that:
+    ::
+
+        a / b < (a + c) / (b + d) < (a + 2c) / (a + 2d) < ... c / d
+
+    As `k` goes to infinity the sequence of these mediants converges to
+    `s = c / d`, by the bounded monotone convergence theorem for real numbers.
+
+    Parameters
+    ----------
+    r : fractions.Fraction
+        The first rational number.
+
+    s : fractions.Fraction
+        The second rational number.
+
+    k : int, default=1
+        The order of the mediant, as defined above.
+
+    Returns
+    -------
+    fractions.Fraction
+        The `k`-th mediant of the two given rational numbers.
+
+    Examples
+    --------
+    >>> mediant(Fraction(1, 2), Fraction(3, 5))
+    Fraction(4, 7)
+    >>> mediant(Fraction(1, 2), Fraction(3, 5), k=2)
+    Fraction(7, 12)
+    >>> mediant(Fraction(1, 2), Fraction(3, 5), k=3)
+    Fraction(10, 17)
+    """
+    a, b = r.as_integer_ratio()
+    c, d = s.as_integer_ratio()
+
+    return Fraction(a + k * c, b + k * d)
+
+
 if __name__ == "__main__":      # pragma: no cover
     # Doctest the module from the project root using
     #

src/continuedfractions/version.py

@@ -1 +1 @@
-__version__ = "0.0.5"
+__version__ = "0.0.6"

tests/units/test_continuedfraction.py

@@ -333,6 +333,25 @@ def test_ContinuedFraction__creation_and_initialisation__valid_inputs__object_co
 
 		assert received.mediant(1) == expected_ref_mediant
 
+	@pytest.mark.parametrize(
+	    "cf1, cf2, k, expected_mediant",
+	    [
+	        (ContinuedFraction(1, 2), Fraction(3, 5), 1, ContinuedFraction(4, 7)),
+	        (ContinuedFraction(1, 2), ContinuedFraction(3, 5), 2, ContinuedFraction(7, 12)),
+	        (ContinuedFraction(1, 2), Fraction(3, 5), 3, ContinuedFraction(10, 17)),
+	        (ContinuedFraction(1, 2), ContinuedFraction(0), 1, ContinuedFraction(1, 3)),
+	        (ContinuedFraction(1, 2), Fraction(1, 2), 1, ContinuedFraction(1, 2)),
+	        (ContinuedFraction(1, -2), ContinuedFraction(1, 2), 1, ContinuedFraction(0, 1)),
+	        (ContinuedFraction(-1, 2), Fraction(1), 1, ContinuedFraction(0, 1)),
+	        (ContinuedFraction(-1, 2), ContinuedFraction(-1), 1, ContinuedFraction(-2, 3)),
+	        (ContinuedFraction(-1, 2), Fraction(1, -2), 1, ContinuedFraction(-1, 2)),
+	        (ContinuedFraction(1, 2), Fraction(3, 5), 10 ** 6, ContinuedFraction(3000001, 5000002)),
+	    ],
+	)
+	def test_mediant__two_ordered_fractions__correct_mediant_continued_fraction_returned(self, cf1, cf2, k, expected_mediant):
+	
+		assert cf1.mediant(cf2, k=k) == expected_mediant
+
 	def test_ContinuedFraction__operations(self):
 		f1 = ContinuedFraction(649, 200)
 		f2 = ContinuedFraction(-649, 200)