lfm-physics 0.2.1__tar.gz → 0.2.2__tar.gz

{lfm_physics-0.2.1 → lfm_physics-0.2.2}/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.2.1] - 2026-03-20
+
+### Added
+- GOV-02 v14: color variance term `κ_c·f_c·Σ|Ψₐ|²` with `KAPPA_C = 1/189`
+- GOV-01 v15: cross-color coupling `ε_cc·χ²·(Ψₐ − Ψ̄)` with `EPSILON_CC = 2/17`
+- `color_variance()` analysis function for color field diagnostics
+- `momentum_density()`, `weak_parity_asymmetry()`, `confinement_proxy()` observables
+- `continuity_residual()`, `fluid_fields()` for hydrodynamic analysis
+- Constants: `KAPPA_C`, `EPSILON_CC`, `ALPHA_S`, `N_COLORS`
+- Config: `kappa_c`, `epsilon_cc`, `n_colors` parameters
+- Example 13: weak force (parity asymmetry)
+- Example 14: strong force (color screening and confinement proxy)
+- Website tutorials 13-14 (emergentphysicslab.com)
+
+### Fixed
+- Ruff lint: import sorting, unused imports, line lengths
+- `PlanckScale` type annotation in `SimulationConfig.planck_scale`
+- Version alignment between `pyproject.toml` and `__init__.py`
+
 ## [0.1.3] - 2026-03-19
 
 ### Added

lfm_physics-0.2.2/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: lfm-physics
+Version: 0.2.2
+Summary: Lattice Field Medium physics simulation library
+Project-URL: Homepage, https://github.com/gpartin/lfm-physics
+Project-URL: Repository, https://github.com/gpartin/lfm-physics
+Project-URL: Issues, https://github.com/gpartin/lfm-physics/issues
+Author-email: Greg Partin <gpartin@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: field-theory,klein-gordon,lattice,physics,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: all
+Requires-Dist: cupy-cuda12x>=12.0; extra == 'all'
+Requires-Dist: matplotlib>=3.7; extra == 'all'
+Provides-Extra: benchmark
+Requires-Dist: pytest-benchmark>=4.0; extra == 'benchmark'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.1; extra == 'docs'
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=12.0; extra == 'gpu'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# lfm-physics
+
+[![Tests](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml/badge.svg)](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/lfm-physics)](https://pypi.org/project/lfm-physics/)
+[![Python 3.10 | 3.11 | 3.12](https://img.shields.io/pypi/pyversions/lfm-physics)](https://pypi.org/project/lfm-physics/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Lattice Field Medium** — a physics simulation library implementing the LFM framework.
+
+Two governing equations. One integer (χ₀ = 19). All of physics.
+
+LFM runs two coupled wave equations on a discrete 3D lattice.
+Gravity, electromagnetism, the strong and weak forces, dark matter, and cosmic
+structure all emerge from the dynamics — no forces injected, no constants
+assumed.  Just a grid, two update rules, and initial noise.
+
+## Install
+
+```bash
+pip install lfm-physics
+```
+
+GPU acceleration (NVIDIA, optional):
+```bash
+pip install "lfm-physics[gpu]"
+```
+
+## Quick Start
+
+```python
+import lfm
+
+# 1. Create a 64³ lattice — empty space has χ = 19 everywhere
+sim = lfm.Simulation(lfm.SimulationConfig(grid_size=64))
+
+# 2. Drop a soliton (energy blob) onto the grid
+sim.place_soliton((32, 32, 32), amplitude=6.0)
+
+# 3. Let the substrate settle into equilibrium
+sim.equilibrate()
+
+# 4. Run the two equations for 5 000 steps
+sim.run(steps=5000)
+
+# 5. Measure what emerged
+m = sim.metrics()
+print(f"χ_min = {m['chi_min']:.2f}")   # χ dropped — a gravity well!
+print(f"Wells = {m['well_fraction']*100:.1f}%")
+
+# 6. Look at the shape of gravity
+profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
+# profile['r'] and profile['profile'] — does it fall like 1/r?
+```
+
+## The Equations
+
+Everything in LFM follows from two coupled wave equations evaluated on a
+3D cubic lattice with a 19-point stencil (6 face + 12 edge neighbours):
+
+**GOV-01** — matter wave equation (Klein-Gordon on the lattice):
+
+```
+Ψⁿ⁺¹ = 2Ψⁿ − Ψⁿ⁻¹ + Δt²[ c²∇²Ψⁿ − (χⁿ)²Ψⁿ ]
+```
+
+**GOV-02** — substrate field equation (complete, v14):
+
+```
+χⁿ⁺¹ = 2χⁿ − χⁿ⁻¹ + Δt²[ c²∇²χⁿ
+        − κ(Σₐ|Ψₐⁿ|² + ε_W·jⁿ − E₀²)          ← gravity + weak
+        − 4λ_H·χⁿ((χⁿ)² − χ₀²)                  ← Higgs self-interaction
+        − κ_c·f_c·Σₐ|Ψₐⁿ|² ]                     ← color screening
+```
+
+| Term | Force | What it does |
+|------|-------|--------------|
+| `κ·Σ\|Ψ\|²` | **Gravity** | Energy density creates χ wells — waves curve toward low χ |
+| `ε_W·j` | **Weak** | Momentum current j breaks parity symmetry in χ |
+| `4λ_H·χ(χ²−χ₀²)` | **Higgs** | Mexican-hat potential makes χ₀ = 19 a dynamical attractor |
+| `κ_c·f_c·Σ\|Ψ\|²` | **Strong** | Color variance f_c gives extra χ deepening for non-singlet states |
+| Phase interference | **EM** | Same phase → constructive → repel; opposite → destructive → attract |
+
+### Field Levels
+
+| Level | Field | Components | Forces | Use for |
+|-------|-------|------------|--------|---------|
+| `REAL` | E ∈ ℝ | 1 real | Gravity | Cosmology, dark matter |
+| `COMPLEX` | Ψ ∈ ℂ | 1 complex | Gravity + EM | Atoms, charged particles |
+| `COLOR` | Ψₐ ∈ ℂ³ | 3 complex | All four | Full multi-force simulations |
+
+```python
+# Gravity-only cosmology (fastest)
+cfg = lfm.SimulationConfig(grid_size=128, field_level=lfm.FieldLevel.REAL)
+
+# Electromagnetism + gravity
+cfg = lfm.SimulationConfig(grid_size=64, field_level=lfm.FieldLevel.COMPLEX)
+
+# All four forces
+cfg = lfm.SimulationConfig(grid_size=64, field_level=lfm.FieldLevel.COLOR)
+```
+
+### Constants — All Derived from χ₀ = 19
+
+| Constant | Symbol | Value | Origin |
+|----------|--------|-------|--------|
+| `CHI0` | χ₀ | 19 | 3D lattice modes: 1 + 6 + 12 = 19 |
+| `KAPPA` | κ | 1/63 ≈ 0.0159 | Unit coupling on 4³ − 1 = 63 modes |
+| `LAMBDA_H` | λ_H | 4/31 ≈ 0.129 | z₂ lattice geometry |
+| `EPSILON_W` | ε_W | 2/(χ₀+1) = 0.1 | Weak mixing angle factorisation |
+| `KAPPA_C` | κ_c | κ/3 = 1/189 | Color variance coupling |
+| `ALPHA_S` | α_s | 2/17 ≈ 0.118 | Strong coupling at M_Z |
+| `EPSILON_CC` | ε_cc | 2/17 | Cross-color coupling (GOV-01 v15) |
+| `ALPHA_EM` | α | 11/(480π) ≈ 1/137.1 | Fine-structure constant |
+| `OMEGA_LAMBDA` | Ω_Λ | 13/19 ≈ 0.684 | Dark energy fraction |
+| `OMEGA_MATTER` | Ω_m | 6/19 ≈ 0.316 | Matter fraction |
+
+## Examples — Build a Universe in 14 Steps
+
+Each example builds on the one before, from empty space to a simulated cosmos:
+
+| # | Example | What you'll see |
+|---|---------|-----------------|
+| 1 | [01_empty_space.py](examples/01_empty_space.py) | A grid with χ = 19 everywhere — nothing happens |
+| 2 | [02_first_particle.py](examples/02_first_particle.py) | Add energy → χ drops → a gravity well appears |
+| 3 | [03_measuring_gravity.py](examples/03_measuring_gravity.py) | Measure χ(r) and check for 1/r falloff |
+| 4 | [04_two_bodies.py](examples/04_two_bodies.py) | Two solitons attract — gravitational interaction emerges |
+| 5 | [05_electric_charge.py](examples/05_electric_charge.py) | Phase = charge: same phase repels, opposite attracts |
+| 6 | [06_dark_matter.py](examples/06_dark_matter.py) | Remove matter — the χ-well persists (substrate memory) |
+| 7 | [07_matter_creation.py](examples/07_matter_creation.py) | Oscillate χ at 2χ₀ — matter appears from nothing |
+| 8 | [08_universe.py](examples/08_universe.py) | Random noise on 64³ → wells + voids → cosmic structure |
+| 9 | [09_hydrogen_atom.py](examples/09_hydrogen_atom.py) | Proton χ-well traps an electron — energy-level ladder emerges |
+| 10 | [10_hydrogen_molecule.py](examples/10_hydrogen_molecule.py) | Two H atoms bond — bonding vs anti-bonding orbitals |
+| 11 | [11_oxygen.py](examples/11_oxygen.py) | Heavier nucleus (8 electrons) — deeper well, richer structure |
+| 12 | [12_fluid_dynamics.py](examples/12_fluid_dynamics.py) | 40-soliton gas → Euler equation from the stress-energy tensor |
+| 13 | [13_weak_force.py](examples/13_weak_force.py) | Turn ε_W on/off and measure parity asymmetry from χ + j |
+| 14 | [14_strong_force.py](examples/14_strong_force.py) | Color fields — measure confinement proxy via χ line integrals |
+
+```bash
+cd examples
+python 01_empty_space.py        # start here
+python 08_universe.py           # the payoff — cosmic structure from noise
+python 14_strong_force.py       # all four forces active
+```
+
+**Interactive tutorials with visualisations:**
+[emergentphysicslab.com/tutorials](https://emergentphysicslab.com/tutorials)
+
+## Measurement & Analysis
+
+```python
+# Radial χ profile around a soliton
+profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
+
+# Find the N brightest energy peaks
+peaks = lfm.find_peaks(sim.energy_density, n=5)
+
+# Track separation between two bodies over time
+sep = lfm.measure_separation(sim.energy_density)
+
+# Energy conservation drift
+drift = lfm.energy_conservation_drift(sim)
+
+# Fluid velocity from the stress-energy tensor
+fields = lfm.fluid_fields(psi_real, psi_imag, chi, dt, c=1.0)
+# fields['velocity_x'], fields['pressure'], fields['energy_density']
+
+# Momentum density (Noether current — sources weak force)
+j = lfm.momentum_density(psi_real, psi_imag, dx=1.0)
+
+# Color variance (strong force diagnostic)
+fc = lfm.color_variance(psi_real_color, psi_imag_color)
+
+# Confinement proxy — χ line integral between peaks
+proxy = lfm.confinement_proxy(sim.chi, pos_a, pos_b)
+```
+
+## Checkpoints & Units
+
+```python
+# Save / resume a simulation
+sim.save_checkpoint("my_run.npz")
+sim2 = lfm.Simulation.load_checkpoint("my_run.npz")
+
+# Map lattice ticks to physical units
+scale = lfm.CosmicScale(box_mpc=100.0, grid_size=64)
+print(scale.format_cosmic_time(50_000))   # "1.28 Gyr"
+
+# Planck-resolution mode
+ps = lfm.PlanckScale.at_planck_resolution(grid_size=256)
+print(ps.cells_per_planck)                # 1.0 exactly
+```
+
+## Low-Level API — Evolver
+
+For maximum performance or custom evolution loops:
+
+```python
+from lfm import SimulationConfig, FieldLevel, Evolver
+
+cfg = SimulationConfig(grid_size=128, field_level=FieldLevel.COLOR)
+evo = Evolver(cfg, backend="auto")  # auto-selects GPU if available
+
+# Inject initial conditions
+evo.set_psi_real(my_array)
+evo.set_chi(my_chi)
+
+# Evolve 100 000 steps
+evo.evolve(100_000)
+
+# Extract fields as NumPy arrays
+chi = evo.get_chi()
+psi = evo.get_psi_real()
+```
+
+## GPU Support
+
+The library automatically uses your NVIDIA GPU when CuPy is installed:
+
+```python
+print(lfm.gpu_available())  # True if CuPy + CUDA detected
+
+# Force CPU even if GPU is available
+sim = lfm.Simulation(cfg, backend="cpu")
+```
+
+Typical speedup: **50-200×** for N ≥ 64 grids on modern NVIDIA GPUs.
+
+## Documentation
+
+- [Interactive Tutorials](https://emergentphysicslab.com/tutorials) — step-by-step guides with live visualisations
+- [LFM Physics Papers](https://zenodo.org/communities/lfm-physics) — 84+ published papers
+- [Constants Reference](https://github.com/gpartin/lfm-physics/blob/main/lfm/constants.py) — χ₀ = 19 and everything derived from it
+- [Changelog](CHANGELOG.md) — version history
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+MIT

lfm_physics-0.2.2/README.md

@@ -0,0 +1,238 @@
+# lfm-physics
+
+[![Tests](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml/badge.svg)](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/lfm-physics)](https://pypi.org/project/lfm-physics/)
+[![Python 3.10 | 3.11 | 3.12](https://img.shields.io/pypi/pyversions/lfm-physics)](https://pypi.org/project/lfm-physics/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Lattice Field Medium** — a physics simulation library implementing the LFM framework.
+
+Two governing equations. One integer (χ₀ = 19). All of physics.
+
+LFM runs two coupled wave equations on a discrete 3D lattice.
+Gravity, electromagnetism, the strong and weak forces, dark matter, and cosmic
+structure all emerge from the dynamics — no forces injected, no constants
+assumed.  Just a grid, two update rules, and initial noise.
+
+## Install
+
+```bash
+pip install lfm-physics
+```
+
+GPU acceleration (NVIDIA, optional):
+```bash
+pip install "lfm-physics[gpu]"
+```
+
+## Quick Start
+
+```python
+import lfm
+
+# 1. Create a 64³ lattice — empty space has χ = 19 everywhere
+sim = lfm.Simulation(lfm.SimulationConfig(grid_size=64))
+
+# 2. Drop a soliton (energy blob) onto the grid
+sim.place_soliton((32, 32, 32), amplitude=6.0)
+
+# 3. Let the substrate settle into equilibrium
+sim.equilibrate()
+
+# 4. Run the two equations for 5 000 steps
+sim.run(steps=5000)
+
+# 5. Measure what emerged
+m = sim.metrics()
+print(f"χ_min = {m['chi_min']:.2f}")   # χ dropped — a gravity well!
+print(f"Wells = {m['well_fraction']*100:.1f}%")
+
+# 6. Look at the shape of gravity
+profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
+# profile['r'] and profile['profile'] — does it fall like 1/r?
+```
+
+## The Equations
+
+Everything in LFM follows from two coupled wave equations evaluated on a
+3D cubic lattice with a 19-point stencil (6 face + 12 edge neighbours):
+
+**GOV-01** — matter wave equation (Klein-Gordon on the lattice):
+
+```
+Ψⁿ⁺¹ = 2Ψⁿ − Ψⁿ⁻¹ + Δt²[ c²∇²Ψⁿ − (χⁿ)²Ψⁿ ]
+```
+
+**GOV-02** — substrate field equation (complete, v14):
+
+```
+χⁿ⁺¹ = 2χⁿ − χⁿ⁻¹ + Δt²[ c²∇²χⁿ
+        − κ(Σₐ|Ψₐⁿ|² + ε_W·jⁿ − E₀²)          ← gravity + weak
+        − 4λ_H·χⁿ((χⁿ)² − χ₀²)                  ← Higgs self-interaction
+        − κ_c·f_c·Σₐ|Ψₐⁿ|² ]                     ← color screening
+```
+
+| Term | Force | What it does |
+|------|-------|--------------|
+| `κ·Σ\|Ψ\|²` | **Gravity** | Energy density creates χ wells — waves curve toward low χ |
+| `ε_W·j` | **Weak** | Momentum current j breaks parity symmetry in χ |
+| `4λ_H·χ(χ²−χ₀²)` | **Higgs** | Mexican-hat potential makes χ₀ = 19 a dynamical attractor |
+| `κ_c·f_c·Σ\|Ψ\|²` | **Strong** | Color variance f_c gives extra χ deepening for non-singlet states |
+| Phase interference | **EM** | Same phase → constructive → repel; opposite → destructive → attract |
+
+### Field Levels
+
+| Level | Field | Components | Forces | Use for |
+|-------|-------|------------|--------|---------|
+| `REAL` | E ∈ ℝ | 1 real | Gravity | Cosmology, dark matter |
+| `COMPLEX` | Ψ ∈ ℂ | 1 complex | Gravity + EM | Atoms, charged particles |
+| `COLOR` | Ψₐ ∈ ℂ³ | 3 complex | All four | Full multi-force simulations |
+
+```python
+# Gravity-only cosmology (fastest)
+cfg = lfm.SimulationConfig(grid_size=128, field_level=lfm.FieldLevel.REAL)
+
+# Electromagnetism + gravity
+cfg = lfm.SimulationConfig(grid_size=64, field_level=lfm.FieldLevel.COMPLEX)
+
+# All four forces
+cfg = lfm.SimulationConfig(grid_size=64, field_level=lfm.FieldLevel.COLOR)
+```
+
+### Constants — All Derived from χ₀ = 19
+
+| Constant | Symbol | Value | Origin |
+|----------|--------|-------|--------|
+| `CHI0` | χ₀ | 19 | 3D lattice modes: 1 + 6 + 12 = 19 |
+| `KAPPA` | κ | 1/63 ≈ 0.0159 | Unit coupling on 4³ − 1 = 63 modes |
+| `LAMBDA_H` | λ_H | 4/31 ≈ 0.129 | z₂ lattice geometry |
+| `EPSILON_W` | ε_W | 2/(χ₀+1) = 0.1 | Weak mixing angle factorisation |
+| `KAPPA_C` | κ_c | κ/3 = 1/189 | Color variance coupling |
+| `ALPHA_S` | α_s | 2/17 ≈ 0.118 | Strong coupling at M_Z |
+| `EPSILON_CC` | ε_cc | 2/17 | Cross-color coupling (GOV-01 v15) |
+| `ALPHA_EM` | α | 11/(480π) ≈ 1/137.1 | Fine-structure constant |
+| `OMEGA_LAMBDA` | Ω_Λ | 13/19 ≈ 0.684 | Dark energy fraction |
+| `OMEGA_MATTER` | Ω_m | 6/19 ≈ 0.316 | Matter fraction |
+
+## Examples — Build a Universe in 14 Steps
+
+Each example builds on the one before, from empty space to a simulated cosmos:
+
+| # | Example | What you'll see |
+|---|---------|-----------------|
+| 1 | [01_empty_space.py](examples/01_empty_space.py) | A grid with χ = 19 everywhere — nothing happens |
+| 2 | [02_first_particle.py](examples/02_first_particle.py) | Add energy → χ drops → a gravity well appears |
+| 3 | [03_measuring_gravity.py](examples/03_measuring_gravity.py) | Measure χ(r) and check for 1/r falloff |
+| 4 | [04_two_bodies.py](examples/04_two_bodies.py) | Two solitons attract — gravitational interaction emerges |
+| 5 | [05_electric_charge.py](examples/05_electric_charge.py) | Phase = charge: same phase repels, opposite attracts |
+| 6 | [06_dark_matter.py](examples/06_dark_matter.py) | Remove matter — the χ-well persists (substrate memory) |
+| 7 | [07_matter_creation.py](examples/07_matter_creation.py) | Oscillate χ at 2χ₀ — matter appears from nothing |
+| 8 | [08_universe.py](examples/08_universe.py) | Random noise on 64³ → wells + voids → cosmic structure |
+| 9 | [09_hydrogen_atom.py](examples/09_hydrogen_atom.py) | Proton χ-well traps an electron — energy-level ladder emerges |
+| 10 | [10_hydrogen_molecule.py](examples/10_hydrogen_molecule.py) | Two H atoms bond — bonding vs anti-bonding orbitals |
+| 11 | [11_oxygen.py](examples/11_oxygen.py) | Heavier nucleus (8 electrons) — deeper well, richer structure |
+| 12 | [12_fluid_dynamics.py](examples/12_fluid_dynamics.py) | 40-soliton gas → Euler equation from the stress-energy tensor |
+| 13 | [13_weak_force.py](examples/13_weak_force.py) | Turn ε_W on/off and measure parity asymmetry from χ + j |
+| 14 | [14_strong_force.py](examples/14_strong_force.py) | Color fields — measure confinement proxy via χ line integrals |
+
+```bash
+cd examples
+python 01_empty_space.py        # start here
+python 08_universe.py           # the payoff — cosmic structure from noise
+python 14_strong_force.py       # all four forces active
+```
+
+**Interactive tutorials with visualisations:**
+[emergentphysicslab.com/tutorials](https://emergentphysicslab.com/tutorials)
+
+## Measurement & Analysis
+
+```python
+# Radial χ profile around a soliton
+profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
+
+# Find the N brightest energy peaks
+peaks = lfm.find_peaks(sim.energy_density, n=5)
+
+# Track separation between two bodies over time
+sep = lfm.measure_separation(sim.energy_density)
+
+# Energy conservation drift
+drift = lfm.energy_conservation_drift(sim)
+
+# Fluid velocity from the stress-energy tensor
+fields = lfm.fluid_fields(psi_real, psi_imag, chi, dt, c=1.0)
+# fields['velocity_x'], fields['pressure'], fields['energy_density']
+
+# Momentum density (Noether current — sources weak force)
+j = lfm.momentum_density(psi_real, psi_imag, dx=1.0)
+
+# Color variance (strong force diagnostic)
+fc = lfm.color_variance(psi_real_color, psi_imag_color)
+
+# Confinement proxy — χ line integral between peaks
+proxy = lfm.confinement_proxy(sim.chi, pos_a, pos_b)
+```
+
+## Checkpoints & Units
+
+```python
+# Save / resume a simulation
+sim.save_checkpoint("my_run.npz")
+sim2 = lfm.Simulation.load_checkpoint("my_run.npz")
+
+# Map lattice ticks to physical units
+scale = lfm.CosmicScale(box_mpc=100.0, grid_size=64)
+print(scale.format_cosmic_time(50_000))   # "1.28 Gyr"
+
+# Planck-resolution mode
+ps = lfm.PlanckScale.at_planck_resolution(grid_size=256)
+print(ps.cells_per_planck)                # 1.0 exactly
+```
+
+## Low-Level API — Evolver
+
+For maximum performance or custom evolution loops:
+
+```python
+from lfm import SimulationConfig, FieldLevel, Evolver
+
+cfg = SimulationConfig(grid_size=128, field_level=FieldLevel.COLOR)
+evo = Evolver(cfg, backend="auto")  # auto-selects GPU if available
+
+# Inject initial conditions
+evo.set_psi_real(my_array)
+evo.set_chi(my_chi)
+
+# Evolve 100 000 steps
+evo.evolve(100_000)
+
+# Extract fields as NumPy arrays
+chi = evo.get_chi()
+psi = evo.get_psi_real()
+```
+
+## GPU Support
+
+The library automatically uses your NVIDIA GPU when CuPy is installed:
+
+```python
+print(lfm.gpu_available())  # True if CuPy + CUDA detected
+
+# Force CPU even if GPU is available
+sim = lfm.Simulation(cfg, backend="cpu")
+```
+
+Typical speedup: **50-200×** for N ≥ 64 grids on modern NVIDIA GPUs.
+
+## Documentation
+
+- [Interactive Tutorials](https://emergentphysicslab.com/tutorials) — step-by-step guides with live visualisations
+- [LFM Physics Papers](https://zenodo.org/communities/lfm-physics) — 84+ published papers
+- [Constants Reference](https://github.com/gpartin/lfm-physics/blob/main/lfm/constants.py) — χ₀ = 19 and everything derived from it
+- [Changelog](CHANGELOG.md) — version history
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+MIT

{lfm_physics-0.2.1 → lfm_physics-0.2.2}/lfm/__init__.py

@@ -15,7 +15,7 @@ Quick start::
     print(sim.metrics())
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 from lfm.analysis import (
     chi_statistics,

{lfm_physics-0.2.1 → lfm_physics-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lfm-physics"
-version = "0.2.1"
+version = "0.2.2"
 description = "Lattice Field Medium physics simulation library"
 readme = "README.md"
 license = "MIT"

lfm_physics-0.2.1/PKG-INFO

@@ -1,181 +0,0 @@
-Metadata-Version: 2.4
-Name: lfm-physics
-Version: 0.2.1
-Summary: Lattice Field Medium physics simulation library
-Project-URL: Homepage, https://github.com/gpartin/lfm-physics
-Project-URL: Repository, https://github.com/gpartin/lfm-physics
-Project-URL: Issues, https://github.com/gpartin/lfm-physics/issues
-Author-email: Greg Partin <gpartin@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: field-theory,klein-gordon,lattice,physics,simulation
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: >=3.10
-Requires-Dist: numpy>=1.24
-Requires-Dist: scipy>=1.10
-Provides-Extra: all
-Requires-Dist: cupy-cuda12x>=12.0; extra == 'all'
-Requires-Dist: matplotlib>=3.7; extra == 'all'
-Provides-Extra: benchmark
-Requires-Dist: pytest-benchmark>=4.0; extra == 'benchmark'
-Provides-Extra: dev
-Requires-Dist: pytest-cov>=4.0; extra == 'dev'
-Requires-Dist: pytest>=7.0; extra == 'dev'
-Requires-Dist: ruff>=0.4; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: furo>=2024.1; extra == 'docs'
-Requires-Dist: myst-parser>=2.0; extra == 'docs'
-Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == 'docs'
-Requires-Dist: sphinx>=7.0; extra == 'docs'
-Provides-Extra: gpu
-Requires-Dist: cupy-cuda12x>=12.0; extra == 'gpu'
-Provides-Extra: viz
-Requires-Dist: matplotlib>=3.7; extra == 'viz'
-Description-Content-Type: text/markdown
-
-# lfm-physics
-
-[![Tests](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml/badge.svg)](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml)
-[![PyPI](https://img.shields.io/pypi/v/lfm-physics?v=2)](https://pypi.org/project/lfm-physics/)
-[![Python 3.10+](https://img.shields.io/pypi/pyversions/lfm-physics?v=2)](https://pypi.org/project/lfm-physics/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-
-**Simulate a universe from two equations.**
-
-The Lattice Field Medium (LFM) framework runs two coupled wave equations on a
-discrete 3D lattice — and gravity, electromagnetism, dark matter, and cosmic
-structure all emerge from the dynamics.  No forces injected.  No constants
-assumed.  Just a grid, two update rules, and initial noise.
-
-## Install
-
-```bash
-pip install lfm-physics
-```
-
-GPU acceleration (NVIDIA):
-```bash
-pip install lfm-physics[gpu]
-```
-
-## Quick Start
-
-```python
-import lfm
-
-# 1. Create a 64³ lattice — empty space has χ = 19 everywhere
-sim = lfm.Simulation(lfm.SimulationConfig(grid_size=64))
-
-# 2. Drop a soliton (energy blob) onto the grid
-sim.place_soliton((32, 32, 32), amplitude=6.0)
-
-# 3. Let the substrate settle into equilibrium
-sim.equilibrate()
-
-# 4. Run the two equations for 5 000 steps
-sim.run(steps=5000)
-
-# 5. Measure what emerged
-m = sim.metrics()
-print(f"χ_min = {m['chi_min']:.2f}")   # χ dropped — a gravity well!
-print(f"Wells = {m['well_fraction']*100:.1f}%")
-
-# 6. Look at the shape of gravity
-profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
-# profile['r'] and profile['profile'] — does it fall like 1/r?
-```
-
-## Examples — Build a Universe in 14 Steps
-
-Each example builds on the one before, from empty space to a simulated cosmos.
-Run them in order:
-
-| # | Example | What you'll see |
-|---|---------|-----------------|
-| 1 | [01_empty_space.py](examples/01_empty_space.py) | A grid with χ=19 everywhere — nothing happens (that's the point) |
-| 2 | [02_first_particle.py](examples/02_first_particle.py) | Add energy → χ drops → a gravity well appears |
-| 3 | [03_measuring_gravity.py](examples/03_measuring_gravity.py) | Measure χ(r) and check for 1/r falloff |
-| 4 | [04_two_bodies.py](examples/04_two_bodies.py) | Two solitons attract — gravitational interaction emerges |
-| 5 | [05_electric_charge.py](examples/05_electric_charge.py) | Phase = charge: same phase repels, opposite attracts |
-| 6 | [06_dark_matter.py](examples/06_dark_matter.py) | Remove matter — the χ-well persists (substrate memory) |
-| 7 | [07_matter_creation.py](examples/07_matter_creation.py) | Oscillate χ at 2χ₀ — matter appears from nothing |
-| 8 | [08_universe.py](examples/08_universe.py) | Random noise on 64³ → wells + voids → cosmic structure |
-| 9 | [09_hydrogen_atom.py](examples/09_hydrogen_atom.py) | Proton χ-well traps an electron — energy-level ladder emerges |
-| 10 | [10_hydrogen_molecule.py](examples/10_hydrogen_molecule.py) | Two H atoms bond — bonding vs anti-bonding orbitals |
-| 11 | [11_oxygen.py](examples/11_oxygen.py) | Heavier nucleus (8 electrons) — deeper well, richer structure |
-| 12 | [12_fluid_dynamics.py](examples/12_fluid_dynamics.py) | 40-soliton gas → Euler equation from the stress-energy tensor |
-| 13 | [13_weak_force.py](examples/13_weak_force.py) | Turn epsilon_w on/off and measure parity asymmetry from chi + j |
-| 14 | [14_strong_force.py](examples/14_strong_force.py) | Run color fields and measure confinement proxy via chi line integrals |
-
-```bash
-cd examples
-python 01_empty_space.py    # 30 seconds
-# ... work through each one ...
-python 08_universe.py       # the payoff
-python 12_fluid_dynamics.py # fluid velocity from wave mechanics
-```
-
-**Interactive tutorials with visualisations:** https://emergentphysicslab.com/tutorials
-
-## What is LFM?
-
-Two coupled wave equations on a cubic lattice:
-
-**GOV-01** — what matter does:
-```
-∂²Ψ/∂t² = c²∇²Ψ − χ²Ψ
-```
-
-**GOV-02** — what the substrate does:
-```
-∂²χ/∂t² = c²∇²χ − κ(|Ψ|² − E₀²)
-```
-
-The substrate field χ starts at 19 everywhere (derived from 3D lattice
-geometry: 1 center + 6 face + 12 edge modes = 19).  Energy (|Ψ|²) pushes
-χ down, creating wells.  Waves curve toward low χ.  That's gravity.
-
-Complex phase differences in Ψ create interference — constructive (repulsion)
-or destructive (attraction).  That's electromagnetism.
-
-When matter leaves a region, χ doesn't snap back instantly — the well
-persists.  That's dark matter.
-
-No forces are coded in.  Everything emerges from the two update rules.
-
-## Measurement Tools
-
-The library includes tools to extract physics from your simulation:
-
-```python
-# Radial χ profile around a soliton
-profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
-
-# Find the N brightest energy peaks
-peaks = lfm.find_peaks(sim.energy_density, n=5)
-
-# Track separation between two bodies over time
-sep = lfm.measure_separation(sim.energy_density)
-
-# Map lattice ticks to physical units (Gyr, Mpc)
-scale = lfm.CosmicScale(box_mpc=100.0, grid_size=64)
-print(scale.format_cosmic_time(50_000))  # "1.28 Gyr"
-```
-
-## Documentation
-
-- [Interactive Tutorials](https://emergentphysicslab.com/tutorials) — step-by-step guides with live visualisations
-- [LFM Physics Papers](https://zenodo.org/communities/lfm-physics)
-- [Constants](https://github.com/gpartin/lfm-physics/blob/main/lfm/constants.py) — χ₀ = 19, κ = 1/63, and the rest
-- [Contributing](CONTRIBUTING.md)
-
-## License
-
-MIT

lfm_physics-0.2.1/README.md

@@ -1,139 +0,0 @@
-# lfm-physics
-
-[![Tests](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml/badge.svg)](https://github.com/gpartin/lfm-physics/actions/workflows/test.yml)
-[![PyPI](https://img.shields.io/pypi/v/lfm-physics?v=2)](https://pypi.org/project/lfm-physics/)
-[![Python 3.10+](https://img.shields.io/pypi/pyversions/lfm-physics?v=2)](https://pypi.org/project/lfm-physics/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-
-**Simulate a universe from two equations.**
-
-The Lattice Field Medium (LFM) framework runs two coupled wave equations on a
-discrete 3D lattice — and gravity, electromagnetism, dark matter, and cosmic
-structure all emerge from the dynamics.  No forces injected.  No constants
-assumed.  Just a grid, two update rules, and initial noise.
-
-## Install
-
-```bash
-pip install lfm-physics
-```
-
-GPU acceleration (NVIDIA):
-```bash
-pip install lfm-physics[gpu]
-```
-
-## Quick Start
-
-```python
-import lfm
-
-# 1. Create a 64³ lattice — empty space has χ = 19 everywhere
-sim = lfm.Simulation(lfm.SimulationConfig(grid_size=64))
-
-# 2. Drop a soliton (energy blob) onto the grid
-sim.place_soliton((32, 32, 32), amplitude=6.0)
-
-# 3. Let the substrate settle into equilibrium
-sim.equilibrate()
-
-# 4. Run the two equations for 5 000 steps
-sim.run(steps=5000)
-
-# 5. Measure what emerged
-m = sim.metrics()
-print(f"χ_min = {m['chi_min']:.2f}")   # χ dropped — a gravity well!
-print(f"Wells = {m['well_fraction']*100:.1f}%")
-
-# 6. Look at the shape of gravity
-profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
-# profile['r'] and profile['profile'] — does it fall like 1/r?
-```
-
-## Examples — Build a Universe in 14 Steps
-
-Each example builds on the one before, from empty space to a simulated cosmos.
-Run them in order:
-
-| # | Example | What you'll see |
-|---|---------|-----------------|
-| 1 | [01_empty_space.py](examples/01_empty_space.py) | A grid with χ=19 everywhere — nothing happens (that's the point) |
-| 2 | [02_first_particle.py](examples/02_first_particle.py) | Add energy → χ drops → a gravity well appears |
-| 3 | [03_measuring_gravity.py](examples/03_measuring_gravity.py) | Measure χ(r) and check for 1/r falloff |
-| 4 | [04_two_bodies.py](examples/04_two_bodies.py) | Two solitons attract — gravitational interaction emerges |
-| 5 | [05_electric_charge.py](examples/05_electric_charge.py) | Phase = charge: same phase repels, opposite attracts |
-| 6 | [06_dark_matter.py](examples/06_dark_matter.py) | Remove matter — the χ-well persists (substrate memory) |
-| 7 | [07_matter_creation.py](examples/07_matter_creation.py) | Oscillate χ at 2χ₀ — matter appears from nothing |
-| 8 | [08_universe.py](examples/08_universe.py) | Random noise on 64³ → wells + voids → cosmic structure |
-| 9 | [09_hydrogen_atom.py](examples/09_hydrogen_atom.py) | Proton χ-well traps an electron — energy-level ladder emerges |
-| 10 | [10_hydrogen_molecule.py](examples/10_hydrogen_molecule.py) | Two H atoms bond — bonding vs anti-bonding orbitals |
-| 11 | [11_oxygen.py](examples/11_oxygen.py) | Heavier nucleus (8 electrons) — deeper well, richer structure |
-| 12 | [12_fluid_dynamics.py](examples/12_fluid_dynamics.py) | 40-soliton gas → Euler equation from the stress-energy tensor |
-| 13 | [13_weak_force.py](examples/13_weak_force.py) | Turn epsilon_w on/off and measure parity asymmetry from chi + j |
-| 14 | [14_strong_force.py](examples/14_strong_force.py) | Run color fields and measure confinement proxy via chi line integrals |
-
-```bash
-cd examples
-python 01_empty_space.py    # 30 seconds
-# ... work through each one ...
-python 08_universe.py       # the payoff
-python 12_fluid_dynamics.py # fluid velocity from wave mechanics
-```
-
-**Interactive tutorials with visualisations:** https://emergentphysicslab.com/tutorials
-
-## What is LFM?
-
-Two coupled wave equations on a cubic lattice:
-
-**GOV-01** — what matter does:
-```
-∂²Ψ/∂t² = c²∇²Ψ − χ²Ψ
-```
-
-**GOV-02** — what the substrate does:
-```
-∂²χ/∂t² = c²∇²χ − κ(|Ψ|² − E₀²)
-```
-
-The substrate field χ starts at 19 everywhere (derived from 3D lattice
-geometry: 1 center + 6 face + 12 edge modes = 19).  Energy (|Ψ|²) pushes
-χ down, creating wells.  Waves curve toward low χ.  That's gravity.
-
-Complex phase differences in Ψ create interference — constructive (repulsion)
-or destructive (attraction).  That's electromagnetism.
-
-When matter leaves a region, χ doesn't snap back instantly — the well
-persists.  That's dark matter.
-
-No forces are coded in.  Everything emerges from the two update rules.
-
-## Measurement Tools
-
-The library includes tools to extract physics from your simulation:
-
-```python
-# Radial χ profile around a soliton
-profile = lfm.radial_profile(sim.chi, center=(32,32,32), max_radius=20)
-
-# Find the N brightest energy peaks
-peaks = lfm.find_peaks(sim.energy_density, n=5)
-
-# Track separation between two bodies over time
-sep = lfm.measure_separation(sim.energy_density)
-
-# Map lattice ticks to physical units (Gyr, Mpc)
-scale = lfm.CosmicScale(box_mpc=100.0, grid_size=64)
-print(scale.format_cosmic_time(50_000))  # "1.28 Gyr"
-```
-
-## Documentation
-
-- [Interactive Tutorials](https://emergentphysicslab.com/tutorials) — step-by-step guides with live visualisations
-- [LFM Physics Papers](https://zenodo.org/communities/lfm-physics)
-- [Constants](https://github.com/gpartin/lfm-physics/blob/main/lfm/constants.py) — χ₀ = 19, κ = 1/63, and the rest
-- [Contributing](CONTRIBUTING.md)
-
-## License
-
-MIT