Metadata-Version: 2.4
Name: qreals
Version: 0.1.0
Summary: q-deformed rationals and reals via MGO continued fractions
Project-URL: Homepage, https://github.com/patrickt6/qreals
Project-URL: Source, https://github.com/patrickt6/qreals
Project-URL: Issues, https://github.com/patrickt6/qreals/issues
Project-URL: Documentation, https://github.com/patrickt6/qreals/tree/main/docs
Project-URL: Changelog, https://github.com/patrickt6/qreals/blob/main/CHANGELOG.md
Author-email: Patrick Taylor <caymentechnologies@gmail.com>
License: MIT
License-File: LICENSE
Keywords: MGO,combinatorics,continued-fractions,mathematics,number-theory,q-analog,q-deformation,q-rationals,q-reals,sympy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: sympy>=1.12
Requires-Dist: uvicorn>=0.27
Provides-Extra: app
Requires-Dist: platformdirs>=3; extra == 'app'
Requires-Dist: questionary>=2; extra == 'app'
Requires-Dist: rich>=13; extra == 'app'
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: numpy>=1.21; extra == 'dev'
Requires-Dist: platformdirs>=3; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: questionary>=2; extra == 'dev'
Requires-Dist: requests>=2; extra == 'dev'
Requires-Dist: rich>=13; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: features
Requires-Dist: numpy>=1.21; extra == 'features'
Provides-Extra: oeis
Requires-Dist: requests>=2; extra == 'oeis'
Provides-Extra: proof
Requires-Dist: rich>=13; extra == 'proof'
Provides-Extra: serve
Description-Content-Type: text/markdown

# qreals

[![CI](https://github.com/patrickt6/qreals/actions/workflows/ci.yml/badge.svg)](https://github.com/patrickt6/qreals/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)

## Install

```bash
pip install qreals
```

Optional extras, comma-separated (`pip install "qreals[app,oeis]"`):

| Extra | What it adds |
|---|---|
| `[app]` | Guided arrow-key menu — run `qreals` with no arguments |
| `[serve]` | Local browser UI — run `qreals serve` |
| `[proof]` | Step-by-step certificates — run `qreals certify` |
| `[oeis]` | OEIS lookup |
| `[features]` | numpy for `Fingerprint.as_numpy` |

## What it does

A q-number replaces an ordinary number x with a series in a variable q that
collapses back to x at q = 1. qreals computes these: for a fraction p/s you get
an exact rational function `[p/s]_q`, and for any real x you get the integer
coefficients of its power series `[x]_q`, to any length, all exact. The math is
from Morier-Genoud and Ovsienko, "q-deformed rationals and q-continued
fractions" (Forum Math. Sigma, 2020).

Every feature below is reachable three ways: a Python function, a `qreals`
subcommand (add `--json` for machine output), and a card in `qreals serve`.

## Features

**q-rationals**

| Feature | What it does |
|---|---|
| Exact q-rational `[p/s]_q` | The exact rational function in q for a fraction p/s. |
| q-integer `[n]_q` | The q-analog of a whole number, `[n]_q` and `[n]_{1/q}`. |
| Factor R(q), S(q) | Factor numerator and denominator of `[a/b]_q` over Z[q], labelling each cyclotomic factor. |
| Roots of R(q) | Plot the complex roots of R(q) on the unit circle, splitting cyclotomic roots from the core. |
| Jump gap | The right and left q-versions of p/s and the factored gap between them. |

**q-reals**

| Feature | What it does |
|---|---|
| Coefficients `[x]_q` | The first N Taylor coefficients of `[x]_q` for any real x. |
| Laurent expansion | `[x]_q` written out to a chosen power, with its integer-part prefix. |
| Integer-part prefix | The forced opening block of `[x]_q` fixed by `floor(x)`. |
| Convergent locking | How many coefficients the n-th convergent of x pins down. |
| Shift by one `[x ± 1]_q` | `[x+1]_q = q[x]_q + 1`, `[x-1]_q = ([x]_q - 1)/q`. |
| Coefficient read-outs | First nonzero, first negative, largest size, zero count. |
| Radius of convergence | A running-max estimate of the radius of convergence of `[x]_q`. |
| Fingerprint | A named, fixed-length feature vector of `[x]_q` for nearest-neighbour. |
| Certificate | The coefficients of `[x]_q` with a ready-to-paste LaTeX table. |

**Arithmetic** (via the q-Gosper engine)

| Feature | What it does |
|---|---|
| q-sum `[x]_q + [y]_q` | The series sum of the two q-reals. |
| q-product `[x]_q · [y]_q` | The series product of the two q-reals. |
| Deficit | How far `[x]_q +/* [y]_q` sits from `[x +/* y]_q`, with the q=1 and q=0 checks. |

**Symmetry**

| Feature | What it does |
|---|---|
| q-negation `[-x]_q` | The Jouteur negation `[-x]_q` and the x → −x symmetry. |
| Negation-sum finiteness | Whether `[x]_q + [-x]_q` is a finite Laurent polynomial. |

**Visuals** (in `qreals serve`)

| Feature | What it does |
|---|---|
| Coefficient landscape | A 3D surface of the Taylor coefficients of `[x]_q` as n and x vary. |
| Root migration | The complex roots of R(q) as the denominator sweeps. |
| Radius landscape | The radius of convergence of `[a/b]_q` over a Farey grid. |
| Conway-Coxeter frieze | The frieze of a/b > 1 with the q-coefficient overlay on every cell. |

**Lookup**

| Feature | What it does |
|---|---|
| OEIS lookup | Look a coefficient sequence up in the OEIS, re-verified against the b-file. |

## License

MIT. See [LICENSE](./LICENSE).
