light-theory-realm 0.1.2

A geometry-first JAX engine for Light Theory: Quantum Geometric Tensor, Kaluza-Klein uplift, prime-gauge Wilson loops, and Reeb-flow dynamics. Like TensorFlow Quantum, but for information geometry.

Light Theory Realm

A geometry-first engine that measures the shape of information in particles and AI models using Clifford algebra and the Quantum Geometric Tensor (QGT).

• 🧮 Core engine: JAX-based Cl(1,3) Clifford algebra + Quantum Geometric Tensor
• 🧬 Standard Model toy: 9 fermion masses with ~2.3% average error from prime plaquettes
• 📐 Geometry everywhere: Fisher information, Berry curvature, Kaluza–Klein uplift, Reeb flow

---

📚 Start Here

1. Choose your depth

• For non-physicists / engineers
  👉 Foundations of Light Theory
  Plain-language explanation of "geometry of information", curvature, and prime barcodes.

• For physicists / theorists
  👉 Light Mechanics
  Full mathematical treatment: Cl(1,3), QGT, information field equations, KK uplift, Reeb flow, geometrodynamics.

• For decision makers / hiring managers
  👉 EXECUTIVE_SUMMARY.md
  One-pager with results, metrics, and impact.

2. Or just run it

pip install light-theory-realm

# Standard Model mass table (Pocket_U Lite)
light-realm sm-table

# Koide relation check for leptons
light-realm koide 0.511 105.66 1776.86

📦 PyPI: light-theory-realm

More first steps: GETTING_STARTED.md

---

⚙️ What this library actually does

At a high level:

1. Algebra layer – CliffordEngine Implements Cl(1,3) (gamma matrices, grades, wedge product) in JAX.

2. Geometry layer – CliffordQGT Given a state and its Jacobian, computes the full Quantum Geometric Tensor:

   • Fisher information (metric)
   • Berry curvature (geometric twist)

3. Theory layer – geometry as dynamics Builds higher structures on top of the QGT:

   • Information field equations (Einstein–Fisher-like)
   • 5D Kaluza–Klein uplift of the information metric
   • Contact geometry + Reeb flow (time and "dark-energy-like" terms)

4. Experiments – Pocket_U Lite & friends Uses prime plaquettes as discrete "labels" for excitations and shows that:

   • 9 Standard Model fermion masses can be reproduced at ~2–3% error
   • Each particle has a full geometric fingerprint (metric, curvature, KK, Reeb)

5. Models – geometric architectures Two complementary models demonstrating GDL principles:

   • Classical U(1) Clock – Thermodynamic sampling on a phase manifold (THRML/TSU)
   • Quantum QHBM/VQT – Hybrid classical-quantum variational thermalizer (PennyLane)

   Both encode symmetry and manifold structure directly into their state spaces. 👉 See models/README.md for details.

For a detailed architecture diagram and module-level docs, see: 👉 ARCHITECTURE.md and API_REFERENCE.md

---

🔍 Minimal code examples

Compute Fisher + Berry for your own model

import jax
import jax.numpy as jnp
from light_theory_realm import CliffordEngine, CliffordQGT

engine = CliffordEngine(seed=42)
qgt = CliffordQGT(engine)

# Example: a tiny 1-parameter family of states
def get_psi(theta):
    # user-defined: returns a normalized 4-component spinor
    # ...
    return psi

theta0 = 0.1
eps = 1e-4

psi = get_psi(theta0)
dpsi = (get_psi(theta0 + eps) - get_psi(theta0 - eps)) / (2 * eps)
jac = dpsi.reshape(-1, 1)

fisher, berry = qgt.compute_full_qgt(psi, jac)
print("Fisher metric:", fisher)
print("Berry curvature:", berry)

Inspect a particle's geometric fingerprint

from light_theory_realm import get_particle_profile

e = get_particle_profile("e")  # electron

print(f"Mass (MeV):       {e['m_phys_MeV']:.3f}")
print(f"Error vs PDG:     {e['error_pct']:.2f}%")
print(f"Dark energy ξ:    {e['xi']:.4f}")
print(f"Fisher trace:     {e['fisher_trace']:.6f}")
print(f"Berry norm:       {e['berry_norm']:.6f}")

More examples in examples/.

---

📓 Interactive Notebooks

Learn Light Theory Realm hands-on with our tutorial notebook series:

#	Notebook	Level	What it shows
1	Hello, Light Theory Realm	Beginner	First QGT + SM snapshot
2	Clifford Algebra 101	Beginner	Wedge, grades, multivectors
3	Basic QGT (Single Parameter)	Beginner	Fisher & Berry for a 1D curve
4	Standard Model Mass Explorer	Beginner	SM masses, screening, plots
5	Koide Playground	Beginner	Koide relation, interactive lepton toy
6	Geometric Fingerprints of Particles	Intermediate	xi, Fisher, Berry, KK metrics
7	Prime Plaquettes & Topological Mass	Intermediate	Primes -> masses via Wilson loops
8	Dark Energy Toy Model (Reeb Flow)	Intermediate	Reeb flow, xi, vacuum vs matter
9	U(1) Clock Playground	Intermediate	THRML lattice model, phases
10	Quantum QHBM / VQT Tutorial	Advanced	Quantum VQT, free energy

👉 Start with Notebook 1 for a 10-minute tour.

---

🧭 Who is this for?

• ML / AI researchers Use the QGT engine to probe the geometry of models: sharp directions, curvature, phase transitions, etc.

• Theoretical physicists Treat this as a concrete playground for geometrodynamics and holographic information geometry.

• Independent / self-taught researchers Everything is open, tested, and documented; you can run and modify any experiment locally.

---

🧪 Tests & quality

• 7/7 unit tests passing across algebra + geometry layers
• JAX-native, differentiable, GPU-ready
• Pocket_U Lite reproduces 9 fermion masses with ~2.3% average error

See TESTING_GUIDE.md for how to run and extend tests.

---

🤝 Contributing

Contributions, questions, and critiques are welcome.

• How to get started: GETTING_STARTED.md
• How to contribute: CONTRIBUTING.md
• Open implementation tasks: TODO_IMPLEMENTATION.md
• Release history: CHANGELOG.md

---

📜 Citation

If you use Light Theory Realm in research:

@software{jeannoel2025lighttheory,
  author = {Jean-Noel II, Dimitry},
  title = {Light Theory Realm: A Geometry-First Framework for Information-Geometric Physics},
  year = {2025},
  organization = {Pleroma Works, LLC},
  url = {https://github.com/Pleroma-Works/Light_Theory_Realm},
  orcid = {0009-0009-6082-8647},
  note = {Version 0.1.1}
}

Related paper: Koide relations from prime plaquettes – 17-page analysis of lepton mass relations using the Pocket_U Lite framework.

Author contact: Dimitry Jean-Noel II
Pleroma Works, LLC
[e-mail]
[e-mail]
ORCID: 0009-0009-6082-8647

---

License

This project is licensed under the Apache License 2.0 – see the LICENSE file for details.