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

lfm_physics-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug Report
+about: Report a bug in lfm-physics
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+```python
+import lfm
+
+config = lfm.SimulationConfig(grid_size=64)
+sim = lfm.Simulation(config)
+# ... steps to reproduce
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- OS: [e.g. Windows 11, Ubuntu 22.04]
+- Python: [e.g. 3.12]
+- lfm-physics version: [e.g. 0.3.0]
+- GPU (if applicable): [e.g. RTX 4060]
+- CuPy version (if applicable): [e.g. 13.0]
+
+**Additional context**
+Any other context — stack traces, screenshots, etc.

lfm_physics-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature Request
+about: Suggest a new physics module or enhancement
+title: "[FEATURE] "
+labels: enhancement
+assignees: ""
+---
+
+**What physics / feature is missing?**
+Describe the capability you need.
+
+**Use case**
+What simulation or analysis would this enable?
+
+**Proposed API**
+```python
+import lfm
+
+# How you'd like to use it:
+result = lfm.some_new_function(...)
+```
+
+**References**
+Links to relevant LFM papers, equations, or external references.

lfm_physics-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+Brief description of the change and why it's needed.
+
+## Changes
+
+- 
+
+## Testing
+
+- [ ] All existing tests pass (`pytest tests/`)
+- [ ] New tests added for new functionality
+- [ ] Tested with GPU backend (if kernel changes)
+
+## Checklist
+
+- [ ] Code follows project style (run `ruff check`)
+- [ ] Docstrings added for public functions
+- [ ] CHANGELOG.md updated

lfm_physics-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Pre-commit hooks for lfm-physics
+# Install: pip install pre-commit && pre-commit install
+# Run all: pre-commit run --all-files
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8
+    hooks:
+      - id: ruff          # lint
+        args: [--fix]
+      - id: ruff-format   # format

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

@@ -4,6 +4,47 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.0] - 2026-03-22
+
+### Added
+- **Metric analysis** (`lfm.analysis.metric`): `effective_metric_00`, `metric_perturbation`, `time_dilation_factor`, `gravitational_potential`, `schwarzschild_chi` — extract spacetime geometry from χ field
+- **Phase/charge analysis** (`lfm.analysis.phase`): `phase_field`, `charge_density`, `phase_coherence`, `coulomb_interaction_energy` — electromagnetic observables from complex fields
+- **Angular momentum** (`lfm.analysis.angular_momentum`): `angular_momentum_density`, `total_angular_momentum`, `precession_rate` — orbital and spin analysis
+- **Boosted solitons** (`lfm.fields.boosted`): `boosted_soliton` — momentum-encoded solitons with phase gradient (complex) or time-derivative kick (real) for scattering experiments
+- **2D parameter sweeps** (`lfm.sweep`): `sweep_2d()` — run all (v1, v2) combinations and collect metrics
+- **GitHub governance**: issue/PR templates, SECURITY.md, CODE_OF_CONDUCT.md
+- **Pre-commit hooks**: `.pre-commit-config.yaml` with ruff linting and formatting
+- **Docs build**: `docs/Makefile` and `docs/make.bat` for local Sphinx builds
+- **Coverage config**: `pyproject.toml` [tool.coverage.*] sections (excluding viz/ and kernel_source.py)
+
+### Fixed
+- **GPU NaN bug**: CUDA color kernel threshold mismatch (`psi_sq_total > 1e-30f` → `total_sq > 1e-30f`) that caused FTZ underflow to 0/0=NaN
+- **GPU boundary masking**: Added missing Psi boundary masking in color CUDA kernel
+- **Color variance RuntimeWarning**: Safe denominator pattern to avoid division-by-zero warning on zero-field input
+- **Schwarzschild chi RuntimeWarning**: Compute `np.where(r > r_s, 1.0 - r_s/r, 0.0)` before `np.sqrt` to avoid invalid-value warning
+
+### Improved
+- Test suite: 202 → **307 tests** (all passing)
+- Coverage: 64% → **91%** (excluding viz/ and CUDA kernel strings)
+- Docs version: aligned at 0.4.0 across pyproject.toml, lfm/__init__.py, docs/conf.py
+
+## [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.4.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in our
+project a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting/derogatory comments, and personal attacks
+* Public or private harassment
+* Publishing others' private information without permission
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainers.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lfm-physics
-Version: 0.2.2
+Version: 0.4.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.4.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.4.0/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.3.x   | :white_check_mark: |
+| < 0.3   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do not** open a public issue.
+2. Email the maintainer directly with details.
+3. Allow reasonable time for a fix before public disclosure.
+
+lfm-physics is a scientific simulation library with no network services,
+authentication, or user data handling.  Security concerns are limited to
+arbitrary code execution via pickle/eval (we use only numpy `.npz` for
+checkpoints, which is safe).

lfm_physics-0.4.0/docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help html clean livehtml
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean:
+	@rm -rf $(BUILDDIR)
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+# Catch-all target
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

{lfm_physics-0.2.2 → lfm_physics-0.4.0}/docs/conf.py

@@ -12,7 +12,7 @@ sys.path.insert(0, os.path.abspath(".."))
 project = "lfm-physics"
 copyright = "2026, Greg Partin"
 author = "Greg Partin"
-release = "0.1.3"
+release = "0.4.0"
 
 # -- General configuration ---------------------------------------------------
 

lfm_physics-0.4.0/docs/make.bat

@@ -0,0 +1,26 @@
+@ECHO OFF
+pushd %~dp0
+
+REM Minimal Windows batch file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+if "%1" == "clean" goto clean
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:clean
+rmdir /s /q %BUILDDIR% 2>NUL
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

lfm_physics-0.4.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.4.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.