sr-murthy / continuedfractions

Object-oriented continued fractions with Python.

continuedfractions

A simple extension of the Python fractions standard library for working with continued fractions as Python objects.

The PyPI package is here. Only standard libraries are used, and the package can be installed on any Linux, Mac OS or Windows system supporting Python 3.10, 3.11, or 3.12.

pip install continuedfractions

See the project docs for more details, which includes the API reference.

Continued fractions are beautiful and interesting mathematical objects, with many connections in number theory and also very useful practical applications, including the rational approximation of real numbers.

The continuedfractions package is designed for:

• working with (finite) continued fractions as Python objects
• exploring their key properties, such as elements/coefficients, convergents, segments, remainders, and others
• operating on them as rationals and instances of the standard library fractions.Fraction class
• supporting approximations of and experimental computations for irrational numbers
• exploring other related objects, such as mediants, and special sequences of rational numbers such as Farey sequences

Currently, it does not support the following features:

• infinite and generalised continued fractions
• symbolic computations

These are planned for future releases.

The project is licensed under the Mozilla Public License 2.0.

continuedfractions's Issues

ci: move CodeQL to a separate CI workflow

• Move CodeQL to a separate CI workflow (YAML)

docs: fix broken ReadTheDocs build

RTD build is broken as pyproject.toml was updated to add myst_parser to docs requirements, but the docs/requirements.txt file was not updated.

fix: changes in `decimal` contextual precision <-> and caching of numeric properties of `ContinuedFraction`

Changes in decimal contextual precision might cause incorrect values to be returned for the cached, numerical properties of ContinuedFraction (excluding order). Investigate further.

feat: immutable Numpy arrays for `ContinuedFraction` elements [?]

If static / immutable Numpy arrays are
possible / practical, it may be useful to replace the current tuple implementation of the elements array (in ContinuedFraction.__init__, with the corresponding property) with an immutable Numpy array.

This is minimally refactoring, but really an enhancement.

The documentation should be updated.

refactor: tweak `ContinuedFraction.convergent` method to pass in the full sequence of elements

ATM the continuedfraction.ContinuedFraction.convergent method calls the lib.convergent method with the k-th segment (CF with the first k + 1 elements of the original).

As the k-th convergent is uniquely determined by the k-th segment this works fine, but by design lib.convergent should be given the full sequence of elements of the original.

docs: documentation of rational operations for `ContinuedFraction`

Sphinx docs need updating to add content on rational operations for ContinuedFraction objects, with examples.

feat: Farey sequences

Support for (efficiently) generating Farey sequences.

Ideally, this would be implemented by an O(n) implementation of a function for generating all pairs of coprime integers <= n for a given n.

feat: support for symbolic computations

Investigate adding support for symbolic computations involving parameterised class methods for convergents, remainders, mediants via Sympy.

feat: class framework for continued fractions

A class framework for continued fractions, including a base (or bases as appropriate) from which all concrete continued fraction classes will inherit, including the current ContinuedFraction, which can only deal with finite, simple continued fractions. Should be able to handle different types, and combinations of types:

• infinite
• generalised
• periodic

feat: `ContinuedFraction` input validation, object creation + initialisation of/from `ContinuedFraction` objects

Depends on #41.

ATM the ContinuedFraction methods for validation (the class method validate), object creation (the class magic method __new__), and object initialisation (__init__) do not permit inputs which are also of type ContinuedFraction.

This should be changed to allow ContinuedFraction to be created from any valid combination of ContinuedFraction objects, whcih are listed below:

• a single ContinuedFraction obj.
• a pair of ContinuedFraction objs.
• an int and a ContinuedFraction obj. (or in reverse order)
• a fractions.Fraction and a ContinuedFraction obj. (or in reverse order)

Where two valid inputs are given, as above, they represent the numerator and denominator of the new ContinuedFraction obj. that will be constructed.

Examples in docstrings and documentation should be updated as appropriate.

ci: PyPI release CI pipeline

Add a release CI pipeline to automatically build and push package artifacts to PyPI from a release PR.

For the moment, GitHub releases should still be created manually, just before the PyPI releases are published and the release PRs merged.

feat: cached properties for even- and odd-order convergents of `ContinuedFraction` objects

Cached properties for even- and odd-order convergents would be useful for approximations - as they have the property that they both converge monotonically to the same number but from opposite directions.

This is linked to #35, and can be implemented as part of the same PR.

The documentation should be updated with examples.

feat: `ContinuedFraction` methods for extending from and dropping given elements

Will impact implementation of #35, as in-place modification of object state will need object caches to be updated and/or cleared.

It would be nice to have ContinuedFraction instance methods for:

• extending from (extend(self, *elements: int) -> None)
• and dropping (drop(self, *elements: int) -> None)

given a sequence of elements, with in-place modification of the object state. For drop the given sequence must be a consecutive subsequence of elements of the original, given in remainder order (left -> right).

Hypothetical examples below for extend:

>>> cf = ContinuedFraction(649, 200)
>>> cf.elements
(3, 4, 12, 4)
>>> cf.extend(5, 2)
>>> cf
ContinuedFraction(7457, 2298)
>>> cf.elements
(3, 4, 12, 4, 5, 2)
>>> assert cf == ContinuedFraction.from_elements(3, 4, 12, 4, 5, 2)
# True

and drop:

>>> cf = ContinuedFraction(649, 200)
>>> cf.elements
(3, 4, 12, 4)
>>> cf.drop(4)
>>> cf.elements
(3, 4, 12)
>>> assert cf == ContinuedFraction.from_elements(3, 4, 12)
>>> cf = ContinuedFraction(649, 200)
>>> cf.drop(12, 4)
>>> cf
ContinuedFraction(3, 4)
>>> cf.elements
(3, 4)
>>> assert cf == ContinuedFraction.from_elements(3, 4)

docs: tidy up Sphinx docs

A general tidy up of the Sphinx docs source typesetting + HTML output is required. Details to be added later.

refactor: implement equality check for `ContinuedFraction` objects by comparing elements

Equality test for ContinuedFraction objects is not over-ridden, which means Fraction.__eq__ is used. This means that equality tests such as:

>>> ContinuedFraction(3, 2) == ContinuedFraction(6, 4)

involve a comparison of the numerators and denominators of the rational numbers these objects represent, and not a comparison of the elements of the simple continued fractions that the objects also represent.

>>> ContinuedFraction(3, 2).elements
(1, 2)
>>> ContinuedFraction(6, 4).elements
(1, 2)
>>> assert ContinuedFraction(6, 4) == ContinuedFraction(3, 2)
# True

A simple continued fraction where the last element > 1 is uniquely determined by a valid (ordered) sequence of elements.

A custom __eq__ should be implemented to check equality with other where other can be ContinuedFraction, or anything else comparable to fractions.Fraction:

• if other is a ContinuedFraction compare the elements
• if not compare with Fractions.__eq__

Equality checking should also be documented somewhere, given this is an extension of Fraction.__eq__.

Add docs site - move docs out of README

Move docs out of README, and publish them separately, as part of a CI release pipeline.

feat: support for infinite, generalised continued fractions

Add support for infinite, generalised continued fractions.

Implementation would probably require storing symbolic representations/expressions for the numerators and denominators, and generating the elements from those expressions.

ci: Sphinx docs CI pipeline, including RTD deployment on release PRs

A CI pipeline is required to build Sphinx docs on all non-main branch updates + a manually triggered job to deploy docs to RTD on release PRs.

ci: mypy type checking for ci

Add mypy type checking for CI as a GitHub Action + update TOML, lockfile.

perf: benchmarked CI performance tests for generating continued fractions for "very large" and "very small" rationals

Benchmarked CI performance tests for generating continued fractions for "very large" and "very small" rationals.

The tests should be documented (in the project docs).

feat: immutable elements for `ContinuedFraction` objects

ContinuedFraction instances to have an immutable elements attribute (_elements).

Docstrings and documentation to be updated as appropriate.

fix: validation of element sequences with negative integers

Additional validation required for ContinuedFraction objects constructed from sequences of elements with negative integers - this should only be possible if the first element (a_0 = first quotient) is negative, and negative values for a_1, a_2,... etc should be considered invalid.

# Is valid
>>> ContinuedFraction.from_elements(-1, 2, 3)
ContinuedFraction(-4, 7)

# Should be invalid
>>> ContinuedFraction.from_elements(1, -2, 3)
ContinuedFraction(2, 5)

Changes required in

• continuedfraction.ContinuedFraction.from_elements

Test cases should be updated and/or added.

Docstrings and documentation should be updated as appropriate.

refactor: self-referential type annotations for self-referential `ContinuedFraction` methods

ATM the type annotations for ContinuedFraction class or instance methods that actually return ContinuedFraction objects are incorrect - the current return type for these is fractions.Fraction, whereas in fact they should be ContinuedFraction. To enable this a future statement is required for type annotations:

from __future__ import annotations

This is also a problem for the ContinuedFraction.validate class method and the ContinuedFraction.__init__ method, which need to be amended to accept valid input combinations involving ContinuedFraction objects.

The methods that need to be fixed are:

• ContinuedFraction.validate
• ContinuedFraction.__new__
• ContinuedFraction.from_elements
• ContinuedFraction.__init__
• All the rational operational methods, e.g. __add__, __radd__, __sub__, __rsub__, etc.

Examples in docstrings and the documentation should be updated.

refactor: division ops for `ContinuedFraction`

All division operations in ContinuedFraction:

• continuedfraction.ContinuedFraction.__truediv__
• continuedfraction.ContinuedFraction.__rtruediv__
• continuedfraction.ContinuedFraction.__floordiv__
• continuedfraction.ContinuedFraction.__rfloordiv__

can be refactored by composing the division-free algorithms for the negation and inversion of simple continued fractions of positive rational numbers, which are described in the documentation.

refactor: negation op (`__neg__`) for `ContinuedFraction`

ATM the rational operation __neg__ for negation of a given ContinuedFraction object relies on the following sequence of calls:

• fractions.Fractions.__neg__ -> ContinuedFraction.__init__ -> lib.continued_fraction_from_real -> lib.continued_fraction_from_rational.

This is unnecessary and inefficient - a direct, much faster approach can be used by using the division-free algorithm for calculating the "negative" of a positive continued fraction from the elements of the positive, as described in the documentation.

feat: cached properties for convergents and remainders of `ContinuedFraction` objects

Implement cached properties for convergents and remainders to avoid manual recomputation on each new call. The cached properties would need the (integer) order of the convergent or remainder as its (sole) argument.

In its simplest implementation, this would just involve decorating the existing convergent and remainder methods with functools.cached_property.

Documentation should be updated with an explanation of the caching mechanism and examples.