Metadata-Version: 2.1
Name: simplefractions
Version: 1.0.0
Summary: Find the simplest fraction for a given float or interval
Home-page: https://github.com/mdickinson/simplefractions
Author: Mark Dickinson
Author-email: dickinsm@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.6
Description-Content-Type: text/markdown

Given fractions *x* and *y*, say that *x* is **simpler** than *y* if, when both
*x* and *y* are written in lowest terms:

- the numerator of *x* is no larger in absolute value than the numerator of
  *y*, and
- the denominator of *x* is no larger than the denominator of *y*, and
- *x* and *y* are not equal to each other in absolute value

The **simplefractions** package provides two functions:

- `simplest_from_float` returns, for a given float ``x``, the unique simplest
  fraction with the property that ``float(simplest_from_float(x)) == x``.
- `simplest_in_interval` returns the unique simplest fraction in a given
  (open or closed, bounded or unbounded) nonempty interval.

## Example usage

Start by importing the functions from the module:

```python
>>> from simplefractions import *
```

The `simplest_from_float` takes a single finite float `x` and produces a
`Fraction` object that recovers that float:

```python
>>> simplest_from_float(0.25)
Fraction(1, 4)
>>> simplest_from_float(0.33)
Fraction(33, 100)
```

No matter what `x` is given, the invariant `float(simplest_from_float(x)) == x`
will always be true.

```python
>>> x = 0.7429667872099244
>>> simplest_from_float(x)
Fraction(88650459, 119319545)
>>> float(simplest_from_float(x))
0.7429667872099244
>>> float(simplest_from_float(x)) == x
True
```

If the float `x` was constructed by dividing two small integers, then
more often than not, `simplest_from_float` will recover those integers:

```python
>>> x = 231 / 199
>>> x
1.1608040201005025
>>> simplest_from_float(x)
Fraction(231, 199)
```

Though in some cases, `simplest_from_float` might discover a simpler fraction
that gives the same float:

```python
>>> x = 818421477165 / 1580973145504
>>> simplest_from_float(x)
Fraction(5171, 9989)
>>> 818421477165 / 1580973145504 == 5171 / 9989
True
```

Note that `simplest_from_float` does not magically fix floating-point
inaccuracies. For example:

```python
>>> x = 1.1 + 2.2
>>> simplest_from_float(x)
Fraction(675539944105597, 204709073971393)
```

You might have expected `Fraction(33, 10)` here, but when converted to float,
that gives a value very close to, but not exactly equal to, `x`. In contrast,
the return value of `simplest_from_float(x)` will always product exactly `x`
when converted to `float`.

To fix this, you might want to ask for the simplest float that lies within
some small error bound of `x` - for example, within 5 ulps (units in the
last place) in either direction. `simplest_from_float` can't do that, but
`simplest_in_interval` can! For example

```python
>>> from math import ulp
>>> x = 1.1 + 2.2
>>> simplest_in_interval(x - 5*ulp(x), x + 5*ulp(x))
Fraction(33, 10)
```

Here are some more examples of `simplest_in_interval` at work. The inputs
to `simplest_in_interval` can be floats, integers, or `Fraction` objects.

```python
>>> simplest_in_interval(3.14, 3.15)
Fraction(22, 7)
```

By default, `simplest_in_interval` assumes that you're specifying an
open interval:

```python
>>> simplest_in_interval(3, 4)
Fraction(7, 2)
```

Keyword arguments `include_left` and `include_right` allow you to specify
that one or both endpoints should be included in the interval:

```python
>>> simplest_in_interval(3, 4, include_left=True, include_right=True)
Fraction(3, 1)
```

The left and right endpoints of the interval are also both optional, alowing
a semi-infinite or infinite interval to be specified:

```python
>>> simplest_in_interval(right=4)  # simplest in (-inf, 4)
Fraction(0, 1)
>>> simplest_in_interval(left=4, include_left=True)  # simplest in [4, inf)
Fraction(4, 1)
>>> simplest_in_interval()  # simplest in (-inf, inf)
Fraction(0, 1)
```


