qreals 0.1.5

q-deformed rationals and reals via MGO continued fractions

qreals

Set it up with Claude (copy and paste)

You do not need to know anything about code, terminals, or installation. Open Claude and paste one of the prompts below. Claude does the whole setup for you: it figures out your computer, opens and runs the terminal itself, installs anything that is missing, and only stops to ask you one thing, where to save the files.

New here? Paste this to install qreals and learn the basics:

Install and set up the qreals package, a q-numbers calculator, from
https://github.com/patrickt6/qreals , and do it as autonomously as you can.
Detect my operating system yourself and use commands that work on it. Open and
run the terminal yourself rather than asking me to; if a command is not
recognized, switch to one that works. If a prerequisite such as Python (3.11 or
newer) or git is missing, install it for me without making me do it by hand.

The only thing to ask me first is where to save the files: suggest a sensible
default folder and let me confirm or change it. After that, proceed on your own:
clone the repository there, install the package, confirm the install succeeded,
then start the web app and tell me the exact address to open in my browser and
how to stop it later. If a step fails, fix it yourself and only involve me if
you genuinely cannot continue without a decision from me.

Once the web app is open, give me a short plain-English tour of what I can do in
it. Then explain that for anything beyond the app I can simply ask you, right
here in plain English, to compute q-numbers for me, and that you will do this by
running the qreals library itself so the answers come from the package rather
than from your own working (for example, "use qreals to compute the cyclotomic
factorisation of 7/12 and explain what it means").

Already have it? Paste this to update to the latest version:

Update my qreals package, a q-numbers calculator, to the newest version, and do
it as autonomously as you can. Detect my operating system yourself, open and run
the terminal yourself, and use commands that work on it; if a command is not
recognized, switch to one that works rather than asking me to fix it.

Work out on your own whether I installed it with pip or from a downloaded copy of
the repository (https://github.com/patrickt6/qreals), and update it the right way
for that case: either upgrade the pip package, or pull the latest copy and
reinstall it. Confirm the new version yourself with "pip show qreals", restart
the web app, tell me the address to open, and summarise in a line or two what is
new. Only involve me if you genuinely cannot continue without a decision from me.

A one-page cheat sheet with the same steps lives in the repository as CHEATSHEET.pdf, including a prompt you can paste to Claude if anything goes wrong. Prefer to do it by hand? The manual steps are under Getting started below.

What is qreals

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 exactly, and ships a browser app to explore them.

Getting started

You need Python 3.11 or newer. Check with python --version (Windows) or python3 --version (macOS). If you do not have it, install it first from python.org (on Windows, tick "Add Python to PATH" in the installer).

1. Install

Windows (PowerShell):

py -m pip install qreals

macOS (Terminal):

python3 -m pip install qreals

2. Run the web app

qreals serve

This starts a local server and opens the app in your browser at http://127.0.0.1:8000. Use qreals serve --port 9000 to pick a different port, or qreals serve --no-browser to skip opening a window. Press Ctrl+C in the terminal to stop it.

3. Update to the latest version

Re-run the install command with --upgrade to get the newest release:

Windows:

py -m pip install --upgrade qreals

macOS:

python3 -m pip install --upgrade qreals

Prefer the source? Download the repo as a ZIP from the green Code button on GitHub (or clone it), then run pip install . from inside the folder.

What it does

For a fraction p/s you get an exact rational function [p/s]_q, and for any real x you get the exact integer coefficients of its power series [x]_q, to any length. 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.
Denominator dossier qreals denom a/d	One screen per fraction: S(q) expanded and factored, the cyclotomic index set T, deg S vs d-1, the S(1) = d check, the class (FULL / COLLAPSE / REPEATED / NONCYC), a^2 mod d, and every coprime split d = d+ d- with its discrepancy classified EXACT, POLYNOMIAL, or RATIO. Flags: --json, --tex.
Reverse table qreals collapse d	The dossier mapped over every numerator coprime to d, grouped by identical S: index set T, factored S, residues per prime-power part of d, realized splits with discrepancy class, RATIO numerators flagged, and the c(d) / non-cyclotomic counts. --range d1..d2 emits the c(d) sequence one line per d, ready to pipe into qreals oeis. Flags: --json, --tex.
Conjecture falsifier qreals conj NAME	A registry of falsifiable conjectures (divisor, sqrt-law, indices-2ju, mult-two, floor3, negsum-period) scanned counterexample-first: the run stops at the FIRST counterexample, prints its full dossier, and exits 1; a survivor reports the range covered, the instance count, the wall time, and the three nearest misses by the entry's registered metric, exiting 0. Long scans checkpoint every 60 seconds and continue with --resume. qreals conj list prints the registry with each statement. Flags: --until N, --resume, --state FILE, --json.

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.

Worked example

$ qreals denom 19/60
fraction in lowest terms: 19/60
continued fraction: [0; 3, 6, 3]
S(q) factored = Phi_2 * Phi_3 * Phi_4 * Phi_5 * Phi_6
class: COLLAPSE
60 = 3 * 20   RATIO   (Phi_10 Phi_20) / Phi_6

$ qreals conj floor3 --until 24
conjecture: floor3
statement: The q-continuant is injective on tails whose entries are all at least 3.
range covered: tails with entries >= 3 and entry sum <= 24, ascending sum then lexicographic
instances checked: 5895
...
verdict: survives the scanned range

qreals denom --help and qreals conj --help carry full worked examples with their exact output; the test suite replays them, so the documentation cannot drift from the tools.

Tool reference

Each section below is generated from the tool's own --help worked example by python -m qreals.readme, so it is always the literal output of the current code.

qreals denom

One-shot denominator dossier of [a/d]_q.

worked example:

  $ qreals denom 4/15 --json
  {
    "a": 4,
    "d": 15,
    "cf": [
      0,
      3,
      1,
      3
    ],
    "k": 3,
    "N": "1 + q + q^2 + q^3",
    "S": "1 + 2*q + 3*q^2 + 3*q^3 + 3*q^4 + 2*q^5 + q^6",
    "S_factored": "Phi_3 * Phi_5",
    "T": [
      3,
      5
    ],
    "multiplicities": {
      "3": 1,
      "5": 1
    },
    "noncyclotomic_cofactor": null,
    "is_cyclotomic_product": true,
    "saturation_index": 15,
    "minimal_saturating_n": 15,
    "deg_S": 6,
    "deg_bound": 14,
    "S_at_1": 15,
    "S_at_1_ok": true,
    "klass": "COLLAPSE",
    "a_sq_mod_d": 1,
    "splits": [
      {
        "d_plus": 1,
        "d_minus": 15,
        "realized": false,
        "discrepancy_class": "POLYNOMIAL",
        "discrepancy": "Phi_15"
      },
      {
        "d_plus": 3,
        "d_minus": 5,
        "realized": true,
        "discrepancy_class": "EXACT",
        "discrepancy": "1"
      }
    ]
  }

qreals bricks

Cyclotomic reference card of [n]_q: every factor expanded, deg = phi(e), value at 1, prime-power vs composite divisors.

worked example:

  $ qreals bricks 12 --json
  {
    "n": 12,
    "qint": "1 + q + q^2 + q^3 + q^4 + q^5 + q^6 + q^7 + q^8 + q^9 + q^10 + q^11",
    "rows": [
      {
        "e": 2,
        "phi": "1 + q",
        "deg": 1,
        "phi_at_1": 2
      },
      {
        "e": 3,
        "phi": "1 + q + q^2",
        "deg": 2,
        "phi_at_1": 3
      },
      {
        "e": 4,
        "phi": "1 + q^2",
        "deg": 2,
        "phi_at_1": 2
      },
      {
        "e": 6,
        "phi": "1 - q + q^2",
        "deg": 2,
        "phi_at_1": 1
      },
      {
        "e": 12,
        "phi": "1 - q^2 + q^4",
        "deg": 4,
        "phi_at_1": 1
      }
    ],
    "prime_powers": [
      2,
      3,
      4
    ],
    "composites": [
      6,
      12
    ],
    "lcm": null,
    "at": null
  }

qreals conj

Conjecture falsifier: scan a registered conjecture for its first counterexample, or 'list' the registry.

worked example:

  $ qreals conj list --json
  {
    "conjectures": [
      {
        "name": "divisor",
        "statement": "Every cyclotomic index of the denominator S of a reduced fraction a/d divides d.",
        "space": "reduced fractions a/d up to denominator N",
        "miss_metric": "minus the degree of the non-cyclotomic cofactor of S (more non-cyclotomic mass = nearer)",
        "default_until": 60
      },
      {
        "name": "sqrt-law",
        "statement": "If every root of the denominator S of a reduced fraction a/d is a root of unity, then a^2 = 1 (mod d).",
        "space": "reduced fractions a/d up to denominator N",
        "miss_metric": "degree of the non-cyclotomic part of S among instances with a^2 != 1 (mod d) (smaller = nearer)",
        "default_until": 60
      },
      {
        "name": "indices-2ju",
        "statement": "Every cyclotomic index in the product-law discrepancy [d+]_q [d-]_q / S of a realized coprime split d = d+ d- has the form 2^j u with u odd and j >= 1.",
        "space": "reduced fractions a/d up to denominator N",
        "miss_metric": "least 2-adic valuation among the discrepancy indices (valuation 1 = nearest to an odd index)",
        "default_until": 60
      },
      {
        "name": "mult-two",
        "statement": "No cyclotomic factor of the denominator S of any reduced fraction appears with multiplicity above 2.",
        "space": "reduced fractions a/d up to denominator N",
        "miss_metric": "3 minus the largest multiplicity (0 would violate)",
        "default_until": 60
      },
      {
        "name": "floor3",
        "statement": "The q-continuant is injective on tails whose entries are all at least 3.",
        "space": "tails with entries >= 3, ordered by entry sum up to N",
        "miss_metric": "differing-coefficient count between two continuants of equal degree and equal value at 1",
        "default_until": 24
      },
      {
        "name": "negsum-period",
        "statement": "Whether [sqrt(D)]_q + [-sqrt(D)]_q is a finite Laurent polynomial is decided by the continued fraction period of sqrt(D).",
        "space": "non-square integers D up to N",
        "miss_metric": "shared period length between two surds with opposite finiteness verdicts (shorter = nearer)",
        "default_until": 60
      },
      {
        "name": "down-closed",
        "statement": "The cyclotomic index set of the denominator S of a reduced fraction a/d is downward closed for indices > 1: if the index-k cyclotomic factor divides S and l > 1 divides k, then the index-l factor divides S.",
        "space": "reduced fractions a/d up to denominator N",
        "miss_metric": "none reported (downward closure either holds or fails per fraction; the first failure is printed in full)",
        "default_until": 60
      },
      {
        "name": "residue-law",
        "statement": "The index-5 cyclotomic factor divides the denominator S of a reduced fraction a/d if and only if 5 divides d and a == +/-1 (mod 5); this is Byakuno, Ren and Yanagawa 2026, Corollary 3.8 part 2.",
        "space": "reduced fractions a/d up to denominator N",
        "miss_metric": "none reported (the law is a sharp iff; the first mismatch in either direction is printed in full)",
        "default_until": 60
      }
    ]
  }

qreals collapse

Reverse table at one modulus: numerators grouped by identical S, residues per prime-power part, realized splits, and c(d).

worked example:

  $ qreals collapse 12 --json
  {
    "d": 12,
    "prime_powers": [
      4,
      3
    ],
    "numerators_total": 4,
    "groups": [
      {
        "numerators": [
          1,
          11
        ],
        "klass": "FULL",
        "T": [
          2,
          3,
          4,
          6,
          12
        ],
        "multiplicities": {
          "2": 1,
          "3": 1,
          "4": 1,
          "6": 1,
          "12": 1
        },
        "S_factored": "Phi_2 * Phi_3 * Phi_4 * Phi_6 * Phi_12",
        "residues": {
          "4": [
            1,
            3
          ],
          "3": [
            1,
            2
          ]
        },
        "ratio_numerators": [],
        "splits": []
      },
      {
        "numerators": [
          5,
          7
        ],
        "klass": "COLLAPSE",
        "T": [
          2,
          3,
          4
        ],
        "multiplicities": {
          "2": 1,
          "3": 1,
          "4": 1
        },
        "S_factored": "Phi_2 * Phi_3 * Phi_4",
        "residues": {
          "4": [
            1,
            3
          ],
          "3": [
            2,
            1
          ]
        },
        "ratio_numerators": [],
        "splits": [
          {
            "d_plus": 1,
            "d_minus": 12,
            "discrepancy_class": "POLYNOMIAL",
            "discrepancy": "Phi_6 Phi_12",
            "realized_by": []
          },
          {
            "d_plus": 3,
            "d_minus": 4,
            "discrepancy_class": "EXACT",
            "discrepancy": "1",
            "realized_by": [
              5,
              7
            ]
          }
        ]
      }
    ],
    "c": 4,
    "repeated_count": 0,
    "noncyclotomic_count": 0,
    "noncyclotomic_numerators": []
  }

qreals check

Replay a directory of claim files through the public CLI and report PASS or DRIFT per claim, under a total time budget.

worked example:

  $ qreals check --show-schema
  {
    "schema": "the literal string 'qreals-claim/1'",
    "tool": "a public qreals subcommand, e.g. 'denom'",
    "args": "list of CLI argument strings (without --json)",
    "expected_sha256": "hex SHA-256 of the tool's --json stdout",
    "label": "free-text description; linted, ships publicly",
    "runtime_seconds": "wall time of the recording run, float"
  }

Optional extras

The web app works out of the box. These extras add the terminal interfaces:

pip install "qreals[app,proof,oeis]"

Extra	What it adds
[app]	Guided arrow-key menu, run qreals with no arguments
[proof]	Step-by-step certificates, run qreals certify
[oeis]	OEIS lookup
[features]	numpy for Fingerprint.as_numpy
[fast]	python-flint for fast exact polynomial arithmetic (large denominators)

License

MIT. See LICENSE.

Created by Patrick Taylor.