Metadata-Version: 2.4
Name: metaphysica
Version: 2.3.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: pandas>=2.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.2.1 — A speculative G₂-manifold model proposing ~125 candidate 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)
[![Status: Speculative / Unvalidated](https://img.shields.io/badge/Status-Speculative%20%2F%20Unvalidated-orange.svg)](#research-status)
[![Tests](https://img.shields.io/badge/tests-1232%20passed-brightgreen.svg)](#testing)

> ## Research status
>
> **Principia Metaphysica is a speculative theoretical model. It has not
> been peer-reviewed and is not scientifically validated.** All
> derivations, predictions, and "closures" documented in this repository
> are candidate proposals awaiting experimental confirmation and
> independent expert review. The framework is intended for exploration
> and research purposes only, and no claim in this repository
> represents established scientific fact.

`metaphysica` is the PyPI implementation of **Principia Metaphysica**: a
candidate G₂-manifold model that proposes derivations for ~125 physical
constants from a single topological seed — the third Betti number
**b₃ = 24**. Every formula in the model carries three independent
representations (Arithma symbolic, EML compressed tree, and float),
cross-checked at registration time, with every derivation chain rooted at
b₃.

This release (v2.2.0) proposes candidate resolutions for 13 of 15 open
issues surfaced during the v24 paper cycle, ships four Rust acceleration
kernels for the heaviest numerical loops, and introduces the unified
`get(name, fmt=...)` retrieval API across 11 output formats.

---

## 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 candidate resolutions

This release proposes candidate resolutions for 13 of the 15 open issues
surfaced during the v24 paper cycle. The full audit lives in
`AutoGenerated/proof_completeness_ledger.json`; the headline numbers below
are model-internal and are not independently validated.

### Candidate resolutions (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` marks the
v25.0 + v26.0 candidate physics additions, the triple-track migration
completion (419/419), the four Rust acceleration kernels, and the regression
closures (PDF, plots, validators). Tag `v2.2.0` adds the unified
`get(name, fmt=...)` retrieval API and the honesty polish (research-status
disclaimers, hype-language rewrite, numerology relabelling, seven textbook
consistency beacons).

---

## License

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

