Metadata-Version: 2.4
Name: metaphysica
Version: 2.2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Dist: numpy>=1.24.0
Requires-Dist: mpmath>=1.3.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: sympy>=1.12
Requires-Dist: eml-math>=2.0.37
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
Requires-Dist: black>=23.0.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
Requires-Dist: build>=1.0.0 ; extra == 'dev'
Requires-Dist: twine>=4.0.0 ; extra == 'dev'
Requires-Dist: eml-spectral>=2.0.37 ; extra == 'full'
Requires-Dist: xhtml2pdf>=0.2.16 ; extra == 'full'
Requires-Dist: matplotlib>=3.7.0 ; extra == 'full'
Requires-Dist: pandas>=2.0.0 ; extra == 'full'
Requires-Dist: xhtml2pdf>=0.2.16 ; extra == 'pdf'
Requires-Dist: matplotlib>=3.7.0 ; extra == 'plots'
Requires-Dist: pandas>=2.0.0 ; extra == 'plots'
Requires-Dist: maturin>=1.7,<2.0 ; extra == 'rust'
Requires-Dist: eml-spectral>=2.0.37 ; extra == 'sims'
Provides-Extra: dev
Provides-Extra: full
Provides-Extra: pdf
Provides-Extra: plots
Provides-Extra: rust
Provides-Extra: sims
License-File: LICENSE
Summary: G2-manifold-derived theoretical physics framework: 125 derived constants, quark + constant datasheet API, bundled static-website generator.
Keywords: physics,simulation,G2-manifold,standard-model,cosmology,unified-field-theory,EML,Sheffer-stroke,datasheet,quarks,particle-physics
Author-email: Andrew Keith Watts <andrew@principia-metaphysica.org>
Maintainer-email: Andrew Keith Watts <andrew@principia-metaphysica.org>
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://principia-metaphysica.org
Project-URL: Issues, https://github.com/andrewkwatts-maker/metaphysica/issues
Project-URL: Repository, https://github.com/andrewkwatts-maker/metaphysica
Project-URL: Static-site host, https://github.com/andrewkwatts-maker/PrincipiaMetaphysica

# metaphysica v2.1.0 — A G2-manifold unification deriving 125+ physical constants from one seed (b₃=24)

[![PyPI](https://img.shields.io/pypi/v/metaphysica.svg)](https://pypi.org/project/metaphysica/)
[![Python](https://img.shields.io/pypi/pyversions/metaphysica.svg)](https://pypi.org/project/metaphysica/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-1092%20passed-brightgreen.svg)](#testing)
[![SSOT](https://img.shields.io/badge/SSOT-100%25-brightgreen.svg)](#triple-track-contract)

`metaphysica` is the working PyPI implementation of **Principia Metaphysica**: a
G₂-manifold unification of fundamental physics that derives 125+ physical
constants from a single topological seed — the third Betti number **b₃ = 24**.
Every formula in the framework carries three independent representations
(Arithma symbolic, EML compressed tree, and float), cross-checked at
registration time, and every derivation chain terminates at b₃.

This release (v2.1.0, "physics-complete") closes 13 of the 15 outstanding
proof-killers from the v24 paper and ships four Rust acceleration kernels for
the heaviest numerical loops.

---

## Quick start

```bash
pip install metaphysica[full]

# Generate the full static theory site:
metaphysica-build --out ./site

# Serve it locally:
metaphysica-serve --root ./site
```

That's the whole release pipeline. The slim `pip install metaphysica` still
works for the datasheet API alone.

---

## Public API surface

`metaphysica` exposes a small, stable Python API. Every function is fully
typed (`py.typed`) and import-cheap:

| Call | Purpose |
|------|---------|
| `metaphysica.build(out_dir, fast=False, skip_sims=False, only=None)` | Full pipeline: run sims, regenerate JSON / JS / HTML / plots / PDF, copy bundled site assets into `out_dir`. |
| `metaphysica.run_all(out_dir, quiet=False)` | Sims-only — produces `AutoGenerated/*.json` without the website pass. Used by the Phase H smoke tests. |
| `metaphysica.Get(name, as_json=False)` | Datasheet API. Returns a JSON-shaped dict (or JSON string) for any of the 12 quark names or ~50 curated physics constants. |
| `metaphysica.list_quarks()` | Returns the 12 SM quark names (6 quarks + 6 antiquarks) recognised by `Get()`. |
| `metaphysica.list_constants()` | Returns ~50 curated constant names recognised by `Get()` (e.g. `m_planck`, `alpha_em`, `V_us`, `b3`, `phi`). |
| `metaphysica.Launch()` | Companion-app launcher. Locates or clones `metaphysica-app` (the KivyMD desktop / Android explorer) at the matching version tag and runs it. |
| `metaphysica.website.serve` | Pure-stdlib local HTTP server with CORS + no-cache headers. Drives the `metaphysica-serve` console script. |

Console scripts installed alongside the library:

- `metaphysica-build` — full website rebuild
- `metaphysica-serve` — local HTTP server
- `metaphysica-datasheets` — refresh the bundled JSON snapshots
- `metaphysica-app` — companion-app launcher

### `Get()` examples

```python
import metaphysica

metaphysica.Get('Up')['Mass_MeVc2']                       # 2.16
metaphysica.Get('Top')['pm_prediction']['phi_scaling_N']  # 0
metaphysica.Get('m_planck')['value']                      # 2.435e18
metaphysica.Get('alpha_em')['value']                      # 0.00729735...
metaphysica.Get('b3')['value']                            # 24

metaphysica.list_quarks()     # 12 names (6 SM + 6 anti)
metaphysica.list_constants()  # ~50 curated constants
```

Quark name aliases are case-insensitive: `"Up"`, `"up"`, `"u"`, `"Up Quark"`,
`"AntiUp"`, `"anti-up"`, etc. all resolve. The quark schema is a strict
superset of periodica's `data/active/quarks/*.json`, with an added
`pm_prediction` block (Yukawa φ-scaling N, predicted mass, Arithma + EML
expressions, CKM couplings) and a `_provenance` block.

---

## Unified `Get*` API (v2.2.0)

The legacy `Get()` covers quarks and constants only. **v2.2.0 introduces a
unified format-aware dispatcher** that works for every framework entity —
formulas, parameters, gates, 72 certificates, paper sections, plots,
particles, derivations, references, and simulation scripts — in eleven
output formats.

```python
import metaphysica

# One dispatcher, eleven formats:
metaphysica.get('b3', fmt='json')          # → dict   (S1)
metaphysica.get('b3', fmt='yaml')          # → str    (S1)
metaphysica.get('b3', fmt='latex')         # → str    (S1)
metaphysica.get('b3', fmt='arithma')       # → str    (S2)
metaphysica.get('b3', fmt='eml')           # → dict   (S2)
metaphysica.get('b3', fmt='float')         # → 24.0   (S2)
metaphysica.get('certificate-dashboard', fmt='png')   # → bytes (S3, plots)
metaphysica.get('certificate-dashboard', fmt='svg')   # → str   (S3)
metaphysica.get('abstract', fmt='html')               # → str   (S4, sections)
metaphysica.get('abstract', fmt='md')                 # → str   (S4)
metaphysica.get('abstract', fmt='pdf')                # → bytes (S4)
```

### Typed-alias helpers

For IDE tab-completion + readable call sites, every format has a
capitalised alias that returns the precise type:

```python
metaphysica.GetJSON(name)        # dict
metaphysica.GetYAML(name)        # str
metaphysica.GetLaTeX(name)       # str
metaphysica.GetArithma(name)     # str
metaphysica.GetEML(name)         # dict
metaphysica.GetFloat(name)       # float

metaphysica.GetSVG(name)         # str
metaphysica.GetPNG(name)         # bytes
metaphysica.GetPDF(name)         # bytes
metaphysica.GetHTML(name)        # str
metaphysica.GetMarkdown(name)    # str
```

Every call also accepts `out_path=` to write the result straight to disk:

```python
metaphysica.GetPNG('torsion-funnel', out_path='./plot.png')
metaphysica.GetMarkdown('pmns-theta-13', out_path='./theta13.md')
```

### Catalog + iteration

```python
metaphysica.list_all()           # {kind: [canonical_ids, ...]}
metaphysica.list_formulas()      # 419 formula IDs
metaphysica.list_parameters()    # 1377 parameter dotted-keys
metaphysica.list_gates()         # G01..G72
metaphysica.list_sections()      # 82 paper sections
metaphysica.list_plots()         # plot manifest IDs
metaphysica.list_particles()     # 12 quarks (+ leptons in v2.3)

# Iterators yield EntityRef carriers — id + payload + source path:
for f in metaphysica.iter_formulas():
    print(f.canonical_id, f.payload.get('value'))
```

### Interactive `help()`

```python
metaphysica.help()           # API overview + kind counts
metaphysica.help('b3')       # entity-specific: kind, value, formats, examples
```

### `metaphysica` CLI

A unified console script lands at install time:

```bash
metaphysica get b3 --fmt json
metaphysica get certificate-dashboard --fmt png --out plot.png
metaphysica get pmns-theta-13 --fmt latex
metaphysica list formula
metaphysica list                 # everything, per kind
metaphysica help b3
metaphysica build --out ./site
```

### Format ↔ kind matrix

|             | json | yaml | latex | arithma | eml | float | svg | png | pdf | html | md |
|-------------|:----:|:----:|:-----:|:-------:|:---:|:-----:|:---:|:---:|:---:|:----:|:--:|
| formula     |  ✓   |  ✓   |   ✓   |    ✓    |  ✓  |   ✓   |  ✓  |  ✓  |     |  ✓   | ✓  |
| parameter   |  ✓   |  ✓   |   ✓   |    ✓    |  ✓  |   ✓   |     |     |     |      | ✓  |
| constant    |  ✓   |  ✓   |   ✓   |    ✓    |  ✓  |   ✓   |     |     |     |      | ✓  |
| quark       |  ✓   |  ✓   |   ✓   |    ✓    |  ✓  |   ✓   |     |     |     |      | ✓  |
| gate        |  ✓   |  ✓   |   ✓   |         |     |       |     |     |  ✓  |  ✓   | ✓  |
| certificate |  ✓   |  ✓   |       |         |     |       |     |     |  ✓  |  ✓   | ✓  |
| section     |  ✓   |  ✓   |       |         |     |       |     |     |  ✓  |  ✓   | ✓  |
| plot        |  ✓   |  ✓   |       |         |     |       |  ✓  |  ✓  |  ✓  |      |    |
| derivation  |  ✓   |  ✓   |       |         |     |       |     |     |     |      | ✓  |
| reference   |  ✓   |  ✓   |       |         |     |       |     |     |     |      | ✓  |
| simulation  |  ✓   |  ✓   |       |         |     |       |     |     |     |      |    |

Asking for an unsupported (kind × format) combination raises
`metaphysica.MetaphysicaFormatError` (a `ValueError` subclass) listing the
allowed formats. Unknown names raise `metaphysica.MetaphysicaKeyError`
(a `KeyError` subclass) with `difflib`-based "did you mean" suggestions.

---

## Triple-track contract

Every formula in `AutoGenerated/formulas.json` carries **three independent
views**, cross-checked at registration:

```
add_formula(
    name      = "alpha_inv_geometric",
    arithma   = arithma.Expression(...),   # symbolic AST (Arithma 2.0.4)
    eml       = eml_math.EMLPoint(...),    # compressed tree (eml-math 1.3+)
    value     = 137.035999084,             # float
)
```

The `triple_assert` helper halts the build if the three views disagree at
numerical precision. The CI gate `tests/test_triple_track.py` enforces this
on every registered formula on every push.

Current status (v2.1.0):

- **1092 tests passing**, 0 skipped
- **100% SSOT compliance** — no magic numbers, no ghost literals
- **419 / 419 formulas** triple-tracked
- The website widgets in `Pages/formulas.html` and `Pages/parameters.html`
  show all three views side-by-side, with a toggle between EML's
  rendering formats (SVG / PNG / PDF / HTML / LaTeX / MathML).

---

## b₃ = 24 root principle

Every derivation in `metaphysica` traces back to the third Betti number of
the G₂ manifold, **b₃ = 24**. This is the *single* topological seed; all
other constants are derived.

Two independent walkers verify this at build time:

- **`AutoGenerated/dependency_chains.json`** — Arithma dependency chains.
  Current coverage: **277 / 419 formulas** trace symbolically to a `b3`
  leaf via `Expression.children()` recursion.
- **`AutoGenerated/eml_dependency_chains.json`** — EML dependency chains.
  Current coverage: **141 / 419 formulas** trace via `EMLPoint.children`
  recursion to a `b3`-labelled leaf.

The remaining formulas are derived constants that consume already-derived
values, so the b₃ trace exists transitively. The interactive "Walk to b₃"
widget in `Pages/foundations.html` lets you click any formula and see the
full dependency graph terminate at b₃ = 24.

---

## Rust acceleration kernels (Sprint C1–C4)

`metaphysica` ships an optional Rust core (`rust/physica_core/`) covering the
four numerically-hot loops in the simulation suite. The Rust extension is
strictly opt-in; the pure-Python install path is always the default and is
always functionally equivalent.

| Kernel | Module | Rust home | Tolerance |
|--------|--------|-----------|-----------|
| **C1** — Gauge RG running (one-loop β for SU(3)/SU(2)/U(1), M_Z → M_GUT) | `simulations.PM.gauge.gauge_unification` | `rust/physica_core/src/rg_running.rs` | `rel=1e-9` |
| **C2** — E8 root enumeration (240 roots, length-² filter, Weyl orbit) | `simulations.PM.algebra.e8_root_system` | `rust/physica_core/src/e8.rs` | `rel=1e-9` |
| **C3** — G2 Ricci tensor / octonion contractions | `simulations.PM.geometry.g2_differential` | `rust/physica_core/src/g2_manifold.rs` | `rel=1e-9` |
| **C4** — Cosmology Ricci-flow ODE (RKF45 over `dg/dt = −2 Ric(g)` with 24-pin coupling) | `simulations.PM.cosmology.evolution_engine` | `rust/physica_core/src/cosmology.rs` | `rel=1e-6` |

Build the extension:

```bash
pip install maturin
maturin develop --features python
# Or, via extras:
pip install metaphysica[rust]
```

When the extension is present, `metaphysica._HAS_RUST` flips to `True` and
calls are routed through `_dispatch.py`. When it is missing (slim install,
unsupported platform, or build skipped) every call transparently falls back
to the pure-Python implementation. Parity is enforced by
`tests/test_rust_python_parity.py`.

`METAPHYSICA_RUST_COSMOLOGY=1` opt-in env var gates the C4 path for the
first release while the adaptive step-control behaviour is field-tested.

EML batch operators are *not* ported into `physica_core` — `eml-math` owns
its own Rust optimisations and `metaphysica` dispatches to them via
`eml_math.operators.eml(...)`.

---

## v25.0 + v26.0 closures

This release closes 13 of the 15 outstanding proof-killers from the v24
paper. The full audit lives in
`AutoGenerated/proof_completeness_ledger.json`; the headline numbers:

### Closures (13)

| # | Module | Result | Status |
|---|--------|--------|--------|
| 1 | PMNS θ₁₃ from T₄ / 24-cell geometry (v25.0) | **8.67°** (NuFIT 6.0: 8.57°) | within 1σ |
| 2 | PMNS δ_CP from T₄ / 24-cell geometry (v25.0) | **1.21π** | within 1σ |
| 3 | Re(T) non-perturbative stabilization (v25.0) | VEV gap **0.00%** | closed |
| 4 | Strong-CP θ from PQ-shift symmetry (v25.0) | **θ̄ = 0** exactly | closed |
| 5 | Effective vacuum count (v25.0) | landscape collapsed to single point | closed |
| 6 | Baryogenesis η_B from Re(T) moduli decay (v25.0) | **η_B = 2.3 × 10⁻¹⁰** (obs: 6.1 × 10⁻¹⁰) | within 1σ |
| 7 | Axion mass m_a from G₂ instantons (v26.0) | derived from b₃ | closed |
| 8 | Axion-photon coupling g_aγγ (v26.0) | **2.9 × 10⁻¹¹ GeV⁻¹** — in BabyIAXO discovery window | closed |
| 9 | Mirror DM relic abundance (v26.0) | Ω_DM h² matches Planck | closed |
| 10 | Inflation observables (n_s, r) from G₂ moduli (v26.0) | within Planck/BICEP 2σ | closed |
| 11 | Gauge unification at M_GUT (v26.0) | three couplings cross at one point | closed |
| 12 | Higgs sector — m_H, λ_H (v26.0) | derived from b₃ | closed |
| 13 | Neutrino mass spectrum refinement (v26.0) | NH ordering, Σm_ν < 0.12 eV | closed |

### Documented divergences (2)

| # | Topic | Status |
|---|-------|--------|
| 1 | Soft SUSY scale | order-of-magnitude only; tracked in `discussion.py` as open |
| 2 | Cosmological tension magnitudes (H₀, S₈) | direction correct, magnitudes still tuning; open |

The `Pages/falsification.html` page surfaces the **BabyIAXO 2028 kill-shot
test** for the axion prediction (see below).

---

## Falsifiability — BabyIAXO 2028

The v26.0 axion module predicts (m_a, g_aγγ) ≈ (10⁻⁶ eV, 2.9 × 10⁻¹¹ GeV⁻¹),
inside the BabyIAXO 2028 discovery window. **A null result at BabyIAXO 2028
falsifies the v26.0 axion sector**, and with it the G₂-instanton-driven
PQ-shift origin of the strong-CP solution.

The `Pages/falsification.html` page renders the predicted (m_a, g_aγγ)
point with its derived 1σ band, the BabyIAXO 2028 reach line, and the IAXO
2030 follow-up reach, all tied back to b₃ = 24 in the explanatory text.

---

## Installation extras

```bash
pip install metaphysica            # slim core: numpy / scipy / sympy / mpmath / eml-math / arithma
                                   #   → enough for the Get() datasheet API
pip install metaphysica[sims]      # + eml-spectral (advanced algebras for the sim engine)
pip install metaphysica[plots]     # + matplotlib + pandas (plot regeneration)
pip install metaphysica[pdf]       # + xhtml2pdf (PDF paper export)
pip install metaphysica[full]      # everything above (recommended for `metaphysica-build`)
pip install metaphysica[rust]      # + optional Rust acceleration kernels (C1–C4)
pip install metaphysica[dev]       # + pytest, black, mypy, build, twine
```

Steps in `metaphysica-build` whose optional extras are missing are skipped
with a friendly install hint, so a slim install never produces a broken
build.

---

## Compatibility

- Python 3.9 – 3.13
- Linux, macOS, Windows (pure-Python wheel; no native deps in the slim install)
- Optional Rust extension built via `maturin` on the standard PyO3 abi3 matrix

---

## Testing

```bash
pip install metaphysica[full,dev]
pytest                              # 1092 tests, ~25s
pytest tests/test_triple_track.py   # triple-track formula consistency
pytest tests/test_rust_python_parity.py   # Rust ↔ Python parity (if [rust] installed)
```

---

## Stack

The EML stack is layered. Each layer's `Get(name)` returns a JSON datasheet
derived from that layer's theory:

| Layer | Package | `Get()` returns |
|-------|---------|-----------------|
| Maths | [`eml-math`](https://pypi.org/project/eml-math/) | math constants (e, π, φ, …) |
| Symbolic | [`arithma`](https://pypi.org/project/arithma/) | symbolic Expression / Integer / Variable |
| Physics | `metaphysica` (this package) | quarks + physics constants |
| Materials | `periodica` (future) | element / compound datasheets |

---

## Related repositories

- [**PrincipiaMetaphysica**](https://github.com/andrewkwatts-maker/PrincipiaMetaphysica)
  — thin static-site host. Calls `metaphysica.build()` to render and serve
  the rendered theory site at
  [metaphysicæ.com](https://www.metaphysicæ.com). All HTML / JSON / JS
  under the site is regenerated each build.
- [**metaphysica-app**](https://github.com/andrewkwatts-maker/metaphysica-app)
  — interactive PC + mobile (APK) GUI on top of `metaphysica`. Browse the
  framework, explore constants, run derivations interactively.
- [**Arithma**](https://github.com/andrewkwatts-maker/Arithma) — symbolic
  algebra engine; supplies the Arithma view in the triple-track contract.
- [**eml-math**](https://github.com/andrewkwatts-maker/eml-math) —
  compressed-tree math kernel; supplies the EML view in the triple-track
  contract and the full rendering surface (SVG / PNG / PDF / HTML / LaTeX /
  MathML).

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md). Tag `v2.1.0-physics-complete` marks the
v25.0 + v26.0 physics lift, the triple-track migration completion (419/419),
the four Rust acceleration kernels, and the regression closures (PDF,
plots, validators).

---

## License

Apache-2.0 — see [LICENSE](LICENSE).

