Scoped Correspondence Formalism

A Python library and research methodology for stating formal correspondences between mathematical models — instead of claiming two things are "the same" across domains, it makes you state exactly how, under what transformation, and within what scope they correspond, then checks that claim against an independently reproduced control case.

What is this?

Most cross-domain modeling claims ("this ecological system behaves like that climate system") never get made precise enough to be wrong. This repo's core idea — the Correspondence contract in correspondence/contract.py — forces the claim into an explicit shape: a state map, a time map, a declared scope, and a residual that is either small or isn't. From that core, src/scoped_correspondence/ has grown into a large, largely independent set of modules spanning dynamical systems, information theory (including directed information / temporal information flow — not general causal inference), thermodynamics, viability theory, and more — each one a small, formally checkable model plus a verify_*.py that tries to break it, not just confirm it. See the module table below for the current, exact set (a headline count here would just go stale).

It is simultaneously:

• a usable Python library (pip install -e .) for anyone who wants a correspondence-contract pattern for their own model-linking work, and
• a living record of how far AI-assisted formal/scientific work holds up under adversarial review — most modules have an audit trail of independent reproduction and fixes, several with a full external review cycle, kept in HISTORY.md rather than lost to chat logs.

Quickstart

Install the package from PyPI:

pip install scoped-correspondence

To work on the repository and run the verification suites, install it from a checkout instead:

pip install -e .
python -m pip install -r verification/requirements.txt

from scoped_correspondence.dynamics.core import fixed_points

# Cubic normal form tau*dx/dt = -x^3 + a*x + b at b=0, a=3:
# fixed points are 0 and +-sqrt(a).
print(fixed_points(3.0, 0.0))
# [-1.7320508075688774, ~0.0, 1.7320508075688774]

A fuller example (a Correspondence contract with residual, scope, and an optional state-dependent time map) is in docs/correspondence_core.md.

Using AI (or anyone new) on this repo

The project's actual differentiator isn't any one module — it's the discipline that keeps ~70 of them independently trustworthy at once: hand-derive control cases before writing code, verify external claims against the real code before fixing anything, one reviewed "Paket" per commit with a full regression run first. CLAUDE.md states this discipline as concrete, followable steps — read it before extending anything here, whether you're an AI agent or a new human contributor. It also doubles as the honest answer to "how was this built": that file describes the actual process, not an idealized one.

Module overview (src/scoped_correspondence/)

Scope, composition and evidence

Since the J-series (SCOPE_COMPOSITION_EVIDENCE_ROADMAP.md), SCF can state under which assumptions, on which domain and with which error a relation between models may be used, chained or transferred: typed composition with exact scopes, clocks and separate flow/field error bounds; universal bounds over whole rational boxes with re-checkable certificates; exact affine identifiability; paired forecast comparisons whose inference is gated by declared applicability; joint sensitivity; weighted conformal calibration with an explicit guarantee status; exact finite causal abstraction and one checked transport rule; existing Markov reduction bounds as contracts. Each result separates what is proved, numerically sampled or empirically evaluated, and states what is not claimed (closing matrix in the roadmap). python scripts/run_scope_evidence_demo.py prints the six reference demonstrations as JSON.

Follow-up series built on this layer (all synthetic or exact unless stated): muonium gravity measurement model (MU0–MU7; real beam data deferred for licence reasons), candidate pilots (polyhedral observation fibres, stellar pulse measurement operator, Saturn quantity register) and adaptive modular networks (ON0–ON7: when do coupling and adaptation improve input discriminability, and how much of that is observation and decoder; real organoid data blocked behind data gates). A targeted mutation run (scripts/run_targeted_mutations.py, report) checks that the verification scripts actually catch registered errors.

Status

0.42.0 (alpha status, first public release; release notes) — the formal-hooks/stable-release milestone from ARCHITECTURE_ROADMAP.md is the one open original milestone before a SemVer 1.0. All checked-in verify_*.py suites currently pass:

python scripts/run_verification_suite.py --category all    # math + data
python scripts/run_verification_suite.py --category links  # doc link check

See docs/capability_overview.md for a per-module question/assumptions/evidence/limits table, and VERIFICATION.md for what each check actually proves. HISTORY.md has the full dated narrative: every external audit, every review-fix cycle, every real-data pilot result (including the ones where the model lost to the baseline — reported either way).

Further reading

License

This repository is dual-licensed:

• Source code (src/, verification/*.py, scripts/) — GNU General Public License v3.0 or later (GPLv3+).
• Documentation (all Markdown/prose content) — Creative Commons Attribution 4.0 International (CC BY 4.0).

If you use this work in academic writing, see CITATION.cff.