metaphysica v2.2.1 — A speculative G₂-manifold model proposing ~125 candidate physical constants from one seed (b₃=24)

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

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:

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

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.

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:

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:

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

Catalog + iteration

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()

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:

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

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.

Build the extension:

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)

Documented divergences (2)

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

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

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:

Related repositories

• PrincipiaMetaphysica — thin static-site host. Calls metaphysica.build() to render and serve the rendered theory site at metaphysicæ.com. All HTML / JSON / JS under the site is regenerated each build.
• metaphysica-app — interactive PC + mobile (APK) GUI on top of metaphysica. Browse the framework, explore constants, run derivations interactively.
• Arithma — symbolic algebra engine; supplies the Arithma view in the triple-track contract.
• 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. 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.