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

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

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.3.0] - 2026-03-21
+
+### Added
+- **Visualisation module** (`lfm.viz`): 10 plotting functions for rapid exploration
+  - `plot_slice`, `plot_three_slices`, `plot_chi_histogram` — 2D field slices
+  - `plot_evolution`, `plot_energy_components` — time-series dashboards
+  - `plot_radial_profile` — χ(r) with 1/r reference overlay
+  - `plot_isosurface` — 3D voxel rendering of χ wells/voids
+  - `plot_power_spectrum` — Fourier P(k) visualisation
+  - `plot_trajectories` — peak motion scatter plots
+  - `plot_sweep` — parameter sweep line plots
+- **Power spectrum analyser** (`lfm.analysis.spectrum`): `power_spectrum()` — radially-averaged FFT P(k) for any 3D field
+- **Particle tracker** (`lfm.analysis.tracker`): `track_peaks()` and `flatten_trajectories()` — follow energy-density maxima across timesteps
+- **Parameter sweep runner** (`lfm.sweep`): `sweep()` — run a batch of simulations varying one parameter, collect metrics
+- **Docs**: `docs/troubleshooting.md` — common errors (NaN, CFL, slow, imports) with fixes
+- **Docs**: `docs/primer.md` — "LFM in Five Minutes" physics primer
+
 ## [0.2.1] - 2026-03-20
 
 ### Added

{lfm_physics-0.2.2 → lfm_physics-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lfm-physics
-Version: 0.2.2
+Version: 0.3.0
 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
@@ -214,6 +214,56 @@ 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)
+
+# Fourier power spectrum P(k) of any 3D field
+spec = lfm.power_spectrum(sim.chi, bins=50)
+# spec['k'], spec['power']
+
+# Track energy peaks across a run
+trajectories = lfm.track_peaks(sim, steps=5000, interval=200, n_peaks=3)
+```
+
+## Parameter Sweeps
+
+```python
+# Sweep amplitude from 2 to 10 and record chi_min at each value
+config = lfm.SimulationConfig(grid_size=32)
+results = lfm.sweep(config, param="amplitude", values=[2, 4, 6, 8, 10],
+                    steps=3000, metric_names=["chi_min", "well_fraction"])
+for r in results:
+    print(f"amp={r['amplitude']:.0f}  chi_min={r['chi_min']:.2f}")
+```
+
+## Visualisation *(New in 0.3.0)*
+
+Install with: `pip install "lfm-physics[viz]"`
+
+```python
+from lfm.viz import (
+    plot_slice,          # 2D slice through a 3D field
+    plot_three_slices,   # XY + XZ + YZ panels
+    plot_chi_histogram,  # distribution of χ values
+    plot_evolution,      # time-series of metrics
+    plot_energy_components,  # stacked kinetic / gradient / potential
+    plot_radial_profile, # χ(r) with 1/r reference overlay
+    plot_isosurface,     # 3D voxel rendering
+    plot_power_spectrum, # P(k) from Fourier analysis
+    plot_trajectories,   # peak motion in x-y / x-z / y-z
+    plot_sweep,          # sweep results line plot
+)
+
+# Example: slice through the chi field at z = 32
+fig, ax = plot_slice(sim.chi, axis=2, index=32, title="χ mid-plane")
+fig.savefig("chi_slice.png")
+
+# Three-panel overview
+fig = plot_three_slices(sim.chi, title="χ field")
+
+# Time evolution dashboard
+fig = plot_evolution(sim.history)
+
+# Radial profile with 1/r fit
+fig, ax = plot_radial_profile(sim.chi, center=(32,32,32))
 ```
 
 ## Checkpoints & Units

{lfm_physics-0.2.2 → lfm_physics-0.3.0}/README.md

@@ -172,6 +172,56 @@ 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)
+
+# Fourier power spectrum P(k) of any 3D field
+spec = lfm.power_spectrum(sim.chi, bins=50)
+# spec['k'], spec['power']
+
+# Track energy peaks across a run
+trajectories = lfm.track_peaks(sim, steps=5000, interval=200, n_peaks=3)
+```
+
+## Parameter Sweeps
+
+```python
+# Sweep amplitude from 2 to 10 and record chi_min at each value
+config = lfm.SimulationConfig(grid_size=32)
+results = lfm.sweep(config, param="amplitude", values=[2, 4, 6, 8, 10],
+                    steps=3000, metric_names=["chi_min", "well_fraction"])
+for r in results:
+    print(f"amp={r['amplitude']:.0f}  chi_min={r['chi_min']:.2f}")
+```
+
+## Visualisation *(New in 0.3.0)*
+
+Install with: `pip install "lfm-physics[viz]"`
+
+```python
+from lfm.viz import (
+    plot_slice,          # 2D slice through a 3D field
+    plot_three_slices,   # XY + XZ + YZ panels
+    plot_chi_histogram,  # distribution of χ values
+    plot_evolution,      # time-series of metrics
+    plot_energy_components,  # stacked kinetic / gradient / potential
+    plot_radial_profile, # χ(r) with 1/r reference overlay
+    plot_isosurface,     # 3D voxel rendering
+    plot_power_spectrum, # P(k) from Fourier analysis
+    plot_trajectories,   # peak motion in x-y / x-z / y-z
+    plot_sweep,          # sweep results line plot
+)
+
+# Example: slice through the chi field at z = 32
+fig, ax = plot_slice(sim.chi, axis=2, index=32, title="χ mid-plane")
+fig.savefig("chi_slice.png")
+
+# Three-panel overview
+fig = plot_three_slices(sim.chi, title="χ field")
+
+# Time evolution dashboard
+fig = plot_evolution(sim.history)
+
+# Radial profile with 1/r fit
+fig, ax = plot_radial_profile(sim.chi, center=(32,32,32))
 ```
 
 ## Checkpoints & Units

lfm_physics-0.3.0/docs/primer.md

@@ -0,0 +1,117 @@
+# LFM in Five Minutes
+
+A minimal introduction to the physics behind the `lfm-physics` library.
+
+---
+
+## One Sentence
+
+> The universe is a cubic lattice where every point stores two numbers —
+> a wave amplitude **Ψ** and a local stiffness **χ** — and they evolve
+> by two coupled wave equations.
+
+---
+
+## The Two Fields
+
+| Symbol | Name | Physical meaning |
+|--------|------|------------------|
+| **Ψ**  | Wave field | Energy / matter at each lattice point |
+| **χ**  | Chi field  | Stiffness of the lattice at each point |
+
+Empty space has χ = 19 everywhere.  Where energy concentrates, χ drops
+below 19, forming a potential well — what we call *gravity*.
+
+---
+
+## The Two Equations
+
+**GOV-01 — Wave Equation** (how Ψ evolves):
+
+```
+Ψⁿ⁺¹ = 2Ψⁿ − Ψⁿ⁻¹ + Δt²[c²∇²Ψⁿ − (χⁿ)²Ψⁿ]
+```
+
+Energy propagates through the lattice.  The `χ²Ψ` term means waves
+oscillate faster where χ is high (empty space) and slower where χ is low
+(near matter).  This is how gravity bends light.
+
+**GOV-02 — Chi Equation** (how χ evolves):
+
+```
+χⁿ⁺¹ = 2χⁿ − χⁿ⁻¹ + Δt²[c²∇²χⁿ − κ(|Ψⁿ|² − E₀²)]
+```
+
+Energy density |Ψ|² pushes χ down — matter curves spacetime.  The
+coupling κ = 1/63 is derived from the lattice geometry.
+
+**That's it.**  These two update rules, applied at every lattice point
+every timestep, produce gravity, waves, dark matter, expansion, and more.
+
+---
+
+## Why 19?
+
+The number 19 comes from counting non-propagating modes on a 3D cubic
+lattice:
+
+| Mode type | Count | k-vectors |
+|-----------|-------|-----------|
+| Centre    | 1     | (0,0,0) |
+| Faces     | 6     | (±1,0,0), (0,±1,0), (0,0,±1) |
+| Edges     | 12    | (±1,±1,0), etc. |
+| **Total** | **19** | **= χ₀** |
+
+The remaining 8 corner modes (±1,±1,±1) are propagating — identifying
+them with gluons gives N_gluons = 8.
+
+From χ₀ = 19 alone, LFM derives 40+ physical constants to high accuracy.
+
+---
+
+## What Emerges
+
+| Phenomenon | How it arises |
+|------------|---------------|
+| **Gravity** | Energy (|Ψ|²) dips χ → potential well → attraction |
+| **Dark matter** | χ wells persist after matter moves away (memory) |
+| **Electromagnetism** | Phase of complex Ψ = charge; interference = Coulomb |
+| **Expansion** | Voids evacuate → χ rises → photons slow down |
+| **Particles** | Standing waves trapped in self-consistent χ wells |
+| **Atoms** | Nuclear χ well + bound electron eigenmodes |
+
+---
+
+## Quick Start
+
+```python
+import lfm
+
+# Create a 64-cell cubic universe
+config = lfm.SimulationConfig(grid_size=64)
+sim = lfm.Simulation(config)
+
+# Drop a soliton — a localized energy concentration
+sim.place_soliton((32, 32, 32), amplitude=6.0)
+
+# Evolve for 1000 timesteps
+sim.run(steps=1000)
+
+# Look at what happened
+print(f"χ_min = {sim.chi.min():.2f}")  # Should be < 19 (gravity!)
+```
+
+See the [examples/](../examples/) directory for 14 runnable demos covering
+gravity, electromagnetism, atoms, orbits, cosmology, and more.
+
+---
+
+## Going Deeper
+
+| Topic | Resource |
+|-------|----------|
+| Full API reference | `help(lfm.Simulation)` |
+| All 14 examples | [examples/](../examples/) |
+| Visualization | `from lfm.viz import plot_slice` |
+| Parameter sweeps | `from lfm import sweep` |
+| Common errors | [troubleshooting.md](troubleshooting.md) |

lfm_physics-0.3.0/docs/troubleshooting.md

@@ -0,0 +1,159 @@
+# Troubleshooting
+
+Common problems and how to fix them.
+
+---
+
+## My simulation gives NaN
+
+**Cause:** The wave amplitude is too large for the grid, causing the
+leapfrog integrator to diverge.
+
+**Fix:**
+```python
+# Lower the amplitude
+sim.place_soliton((32, 32, 32), amplitude=4.0)   # instead of 12.0
+
+# Or use a larger grid (more room to spread energy)
+config = lfm.SimulationConfig(grid_size=128)      # instead of 32
+```
+
+**Rule of thumb:** Keep amplitude below ~8 for `grid_size=32`, below ~12
+for `grid_size=64`.  When in doubt, start small and increase.
+
+---
+
+## Energy diverges over time
+
+**Cause:** The timestep `dt` exceeds the CFL stability limit.
+
+**Fix:** Use the default `dt=0.02` — it satisfies the CFL condition for
+all standard setups.  If you've changed `dt` manually:
+
+```python
+# Safe: dt = 0.02 (default, well inside CFL)
+config = lfm.SimulationConfig(dt=0.02)
+
+# The CFL limit for the 19-point stencil with χ₀=19:
+#   dt < 1/sqrt(16c²/(3·Δx²) + χ₀²) ≈ 0.104  (for Δx=c=1)
+# Our default 0.02 gives ~5× safety margin.
+```
+
+---
+
+## χ goes negative
+
+**This is not a bug.** In extreme-gravity scenarios (very high amplitude
+or dense clusters), χ can dip below zero.  This is the LFM equivalent of
+a black hole interior.
+
+**If you want to prevent it:** Enable the Mexican-hat self-interaction,
+which creates a stable second vacuum at −χ₀:
+
+```python
+config = lfm.SimulationConfig(
+    lambda_self=lfm.LAMBDA_H,  # 4/31 ≈ 0.129
+)
+```
+
+**If you don't care about extreme gravity:** Use gravity-only mode
+(default `lambda_self=0.0`) and lower the amplitude.
+
+---
+
+## Everything collapses into one blob
+
+**Cause:** With periodic boundaries and enough energy, gravity always
+wins — everything falls toward the centre of mass.  This is correct
+physics for a closed universe.
+
+**Fix:** Use frozen boundaries (the default) to simulate an open region
+embedded in the vacuum:
+
+```python
+config = lfm.SimulationConfig(
+    boundary_type=lfm.BoundaryType.FROZEN,  # default
+)
+```
+
+Frozen boundaries hold χ = 19 at the edges, representing infinite empty
+space beyond the simulation box.
+
+---
+
+## Simulation is very slow
+
+**Check 1 — Are you using GPU?**
+```python
+print(lfm.gpu_available())  # True if CuPy + CUDA detected
+
+# Force GPU
+sim = lfm.Simulation(config, backend="gpu")
+```
+
+Install GPU support:
+```bash
+pip install "lfm-physics[gpu]"
+```
+
+**Check 2 — Is your grid too large for CPU?**
+
+| Grid size | Cells     | CPU time/step | GPU time/step |
+|-----------|-----------|---------------|---------------|
+| 32³       | 32 K      | ~0.3 ms       | ~0.02 ms      |
+| 64³       | 262 K     | ~3 ms         | ~0.05 ms      |
+| 128³      | 2.1 M     | ~30 ms        | ~0.3 ms       |
+| 256³      | 16.8 M    | ~300 ms       | ~7 ms         |
+
+For grid_size ≥ 128 on CPU, expect minutes for long runs.  GPU gives
+50–200× speedup.
+
+---
+
+## ImportError: matplotlib not found
+
+The visualization module (`lfm.viz`) requires matplotlib:
+
+```bash
+pip install "lfm-physics[viz]"
+```
+
+Or install everything:
+```bash
+pip install "lfm-physics[all]"
+```
+
+---
+
+## How do I save and resume a run?
+
+```python
+# Save
+sim.save_checkpoint("my_run.npz")
+
+# Resume later
+sim2 = lfm.Simulation.load_checkpoint("my_run.npz")
+sim2.run(steps=5000)  # continues where it left off
+```
+
+Checkpoints preserve the full simulation state: fields, config, step
+count, and metric history.
+
+---
+
+## Which field level should I use?
+
+| I want to simulate...             | Field level           |
+|-----------------------------------|-----------------------|
+| Gravity, dark matter, cosmology   | `FieldLevel.REAL`     |
+| Electromagnetism, charged particles | `FieldLevel.COMPLEX` |
+| Strong force, color confinement   | `FieldLevel.COLOR`    |
+
+```python
+config = lfm.SimulationConfig(
+    field_level=lfm.FieldLevel.COMPLEX,  # for EM
+)
+```
+
+Start with REAL (simplest, fastest).  Upgrade only when your physics
+requires it.

lfm_physics-0.3.0/examples/15_visualization.py

@@ -0,0 +1,93 @@
+"""15 – Visualisation & Analysis
+
+The lfm.viz toolkit: plot slices, radial profiles, time-series
+dashboards, power spectra, and parameter sweeps without writing
+any matplotlib boilerplate.
+
+Requires: pip install "lfm-physics[viz]"
+"""
+
+import lfm
+
+# ── 1. Run a quick simulation ─────────────────────────────────────────
+
+config = lfm.SimulationConfig(grid_size=32)
+sim = lfm.Simulation(config)
+sim.place_soliton((16, 16, 16), amplitude=6.0)
+sim.equilibrate()
+sim.run(steps=3000)
+
+print("15 – Visualisation & Analysis")
+print("=" * 55)
+print()
+
+m = sim.metrics()
+print(f"  chi_min = {m['chi_min']:.2f}  (gravity well depth)")
+print(f"  wells   = {m['well_fraction']*100:.1f}%")
+print()
+
+# ── 2. 2D slice through the chi field ─────────────────────────────────
+
+from lfm.viz import plot_slice, plot_three_slices
+
+fig, ax = plot_slice(sim.chi, axis=2, index=16, title="χ mid-plane (z=16)")
+fig.savefig("tutorial_15_slice.png", dpi=120, bbox_inches="tight")
+print("Saved: tutorial_15_slice.png")
+
+# Three-panel overview (XY, XZ, YZ)
+fig = plot_three_slices(sim.chi, title="χ field — three planes")
+fig.savefig("tutorial_15_three_slices.png", dpi=120, bbox_inches="tight")
+print("Saved: tutorial_15_three_slices.png")
+
+# ── 3. Radial profile with 1/r reference ──────────────────────────────
+
+from lfm.viz import plot_radial_profile
+
+fig, ax = plot_radial_profile(sim.chi, center=(16, 16, 16), max_radius=12)
+fig.savefig("tutorial_15_radial.png", dpi=120, bbox_inches="tight")
+print("Saved: tutorial_15_radial.png")
+
+# ── 4. Chi histogram ──────────────────────────────────────────────────
+
+from lfm.viz import plot_chi_histogram
+
+fig, ax = plot_chi_histogram(sim.chi, title="χ distribution after 3000 steps")
+fig.savefig("tutorial_15_histogram.png", dpi=120, bbox_inches="tight")
+print("Saved: tutorial_15_histogram.png")
+
+# ── 5. Time-evolution dashboard ───────────────────────────────────────
+
+from lfm.viz import plot_evolution
+
+fig = plot_evolution(sim.history, title="Metric evolution")
+fig.savefig("tutorial_15_evolution.png", dpi=120, bbox_inches="tight")
+print("Saved: tutorial_15_evolution.png")
+
+# ── 6. Fourier power spectrum ─────────────────────────────────────────
+
+from lfm.viz import plot_power_spectrum
+
+fig, ax = plot_power_spectrum(sim.chi, title="P(k) of χ field")
+fig.savefig("tutorial_15_spectrum.png", dpi=120, bbox_inches="tight")
+print("Saved: tutorial_15_spectrum.png")
+
+# ── 7. Parameter sweep ───────────────────────────────────────────────
+
+from lfm.viz import plot_sweep
+
+sweep_cfg = lfm.SimulationConfig(grid_size=32)
+results = lfm.sweep(
+    sweep_cfg,
+    param="amplitude",
+    values=[2, 4, 6, 8],
+    steps=2000,
+    metric_names=["chi_min", "well_fraction"],
+)
+fig, ax = plot_sweep(results, x_param="amplitude", y_metric="chi_min",
+                     title="χ_min vs soliton amplitude")
+fig.savefig("tutorial_15_sweep.png", dpi=120, bbox_inches="tight")
+print("Saved: tutorial_15_sweep.png")
+
+print()
+print("All plots saved.  Open the PNG files to explore your simulation.")
+print("Every lfm.viz function returns (fig, ax) so you can customise further.")

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

@@ -15,7 +15,7 @@ Quick start::
     print(sim.metrics())
 """
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 from lfm.analysis import (
     chi_statistics,
@@ -28,13 +28,16 @@ from lfm.analysis import (
     energy_conservation_drift,
     find_peaks,
     fit_power_law,
+    flatten_trajectories,
     fluid_fields,
     interior_mask,
     measure_force,
     measure_separation,
     momentum_density,
+    power_spectrum,
     radial_profile,
     total_energy,
+    track_peaks,
     void_fraction,
     weak_parity_asymmetry,
     well_fraction,
@@ -81,6 +84,7 @@ from lfm.fields import (
     wave_kick,
 )
 from lfm.simulation import Simulation
+from lfm.sweep import sweep
 from lfm.units import CosmicScale, PlanckScale
 
 __all__ = [
@@ -154,6 +158,12 @@ __all__ = [
     "continuity_residual",
     # Color / Confinement
     "color_variance",
+    # Spectrum & Tracker
+    "power_spectrum",
+    "track_peaks",
+    "flatten_trajectories",
+    # Sweep
+    "sweep",
     # Units
     "CosmicScale",
     "PlanckScale",

{lfm_physics-0.2.2 → lfm_physics-0.3.0}/lfm/analysis/__init__.py

@@ -21,6 +21,7 @@ from lfm.analysis.observables import (
     radial_profile,
     weak_parity_asymmetry,
 )
+from lfm.analysis.spectrum import power_spectrum
 from lfm.analysis.structure import (
     chi_statistics,
     count_clusters,
@@ -28,6 +29,7 @@ from lfm.analysis.structure import (
     void_fraction,
     well_fraction,
 )
+from lfm.analysis.tracker import flatten_trajectories, track_peaks
 
 __all__ = [
     # energy
@@ -55,4 +57,9 @@ __all__ = [
     "confinement_proxy",
     # color
     "color_variance",
+    # spectrum
+    "power_spectrum",
+    # tracker
+    "track_peaks",
+    "flatten_trajectories",
 ]

lfm_physics-0.3.0/lfm/analysis/spectrum.py

@@ -0,0 +1,57 @@
+"""Fourier power-spectrum analysis of lattice fields."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def power_spectrum(
+    field: NDArray,
+    bins: int = 50,
+) -> dict[str, NDArray]:
+    """Compute the radially-averaged power spectrum of a 3-D field.
+
+    Parameters
+    ----------
+    field : ndarray (N, N, N)
+        Scalar field (e.g. ``sim.chi`` or ``sim.energy_density``).
+    bins : int
+        Number of radial k-bins.
+
+    Returns
+    -------
+    dict
+        ``k`` — bin centres, ``power`` — P(k) in each bin,
+        ``counts`` — number of modes per bin.
+    """
+    if field.ndim != 3:
+        raise ValueError(f"Expected 3-D array, got shape {field.shape}")
+
+    N = field.shape[0]
+    fft = np.fft.fftn(field)
+    pk = np.abs(fft) ** 2 / field.size
+
+    kx = np.fft.fftfreq(N) * N
+    ky = np.fft.fftfreq(N) * N
+    kz = np.fft.fftfreq(N) * N
+    KX, KY, KZ = np.meshgrid(kx, ky, kz, indexing="ij")
+    K = np.sqrt(KX**2 + KY**2 + KZ**2)
+
+    k_max = N // 2
+    bin_edges = np.linspace(0.5, k_max + 0.5, bins + 1)
+    k_centres = 0.5 * (bin_edges[:-1] + bin_edges[1:])
+    power = np.zeros(bins)
+    counts = np.zeros(bins, dtype=int)
+
+    k_flat = K.ravel()
+    pk_flat = pk.ravel()
+    idx = np.digitize(k_flat, bin_edges) - 1
+
+    for i in range(bins):
+        mask = idx == i
+        counts[i] = mask.sum()
+        if counts[i] > 0:
+            power[i] = pk_flat[mask].mean()
+
+    return {"k": k_centres, "power": power, "counts": counts}