ParticleSim

A research simulation framework for cosmology, warp drive design, particle lasers, matter, and singularity physics, with pluggable theories of everything (string-inspired effective field theory by default).

Start with the design document.

Status

ParticleSim includes the foundations, spherical numerical relativity, particle-in-cell and laser scenarios, cosmology, relativistic hydrodynamics, lattice fields, string EFT modules, structure formation, adapters, and run dashboards, and matrix models. The child issues for milestones M0–M3 and M5–M9 are closed.

The remaining M4 work includes long-lived punctures and binary benchmarks, constraint-preserving outer boundaries, and modified CCZ4 evolution. IKKT complex Langevin reproduces a published bosonic dimension profile at N = 32; it omits fermions and does not establish three-dimensional space. A closed child issue does not imply every method in the design roadmap is implemented: see the measured scope and limitations in Benchmarks.

Milestone status records the completion criteria and the remaining acceptance tests, with links to the live GitHub issues.

Quick start

uv venv && uv pip install -e ".[dev]"
uv run particlesim run examples/configs/warp_alcubierre.yaml
uv run pytest -q -m "not slow"

The Alcubierre run writes fields.npz, report.json, energy_density.png, manifest.json, and a self-contained dashboard.html under runs/warp_alcubierre/.

Dashboards and the app

Every particlesim run writes a dashboard.html for its run directory. pytest --dashboard dashboards/benchmarks.html writes one for a benchmark run. It puts each result next to what Benchmarks says about it, and CI uploads one from every benchmark job. particlesim dashboard PATH… rebuilds either kind.

particlesim serve (with the serve extra) serves an app with four tabs:

• Runs: your runs' dashboards.
• Modified gravity, live: the Hu–Sawicki f(R) growth and P(k) enhancement, recomputed as you move |f_R0|, Ω_m and the scale factor.
• Warp, live: the matter a warp bubble needs under GR, GR+Λ or a string EFT plugin, in 3-D, recomputed as you move the theory's couplings. Below it, the view from inside the bubble as its speed changes.
• Theory plugins, live: any installed plugin, scored against the singularity battery on demand.

uv sync --extra serve
uv run particlesim serve --runs runs --show

# or from the Docker image
docker build -t particlesim .
docker run -p 5006:5006 -v "$PWD/runs:/runs" particlesim \
  serve --runs /runs --address 0.0.0.0 --allow-websocket-origin localhost:5006

Documentation

• Design document — scope, theory tiers, roadmap.
• Theory authoring guide — how to write a plugin, with a worked example that ships as real code.
• Hypothesis guide — how to write a singularity hypothesis the framework can test, and how to read its verdict.
• Benchmarks — what the code reproduces, and what it does not yet.
• Contributing — setup, checks, conventions.

Notebook

uv sync --extra notebook
uv run jupyter lab examples/warp_explorer.ipynb

warp_explorer() gives sliders over bubble velocity, radius and wall thickness with a live energy-density map. The physics is in explorer_state(), a plain function usable without a notebook.

Demos

Static pages, no Python and no backend. Source in demos/, deployed to GitHub Pages from that directory by .github/workflows/pages.yml on every push to main.

• Warp energy-density explorer: sliders for bubble velocity, radius, and wall thickness over a live heatmap and 1D cut of the Alcubierre Eulerian energy density, with the integrated negative energy. It computes the analytic Alcubierre result in the browser from the closed form in Section 3.2 of the design document.
• Warp bubble view: what a passenger inside an Alcubierre bubble sees. Light is traced back through the bubble on the GPU with WebGPU, or the CPU without it, and tinted by its exact frequency shift 1 − v cos α. Its physics file is tested in Node against the Python tracer, ray for ray. Its shader is tested in headless Chromium against the double-precision render, with every pixel within one level of 255.
• Two-stream instability: a one-dimensional electrostatic particle-in-cell code running live in the page. Two electron beams stream through each other and the measured growth rate is compared with the exact root of the dispersion relation.
• Friedmann integrator: the two background solvers, in the page. A ΛCDM budget integrated for ages and distances, and a theory plugin's own H²(ρ) integrated through a crunch under general relativity or a bounce under effective loop quantum cosmology. Its physics lives in demos/friedmann/friedmann.js, which the test suite loads in Node and compares against the Python solvers directly — the bounce time to 1e-8 and the ΛCDM ages and distances to 1e-9 — so "reproduces the solver" is a measurement rather than a claim.

Layout

particlesim/
  core/        units, grids, config schemas, provenance
  theories/    plugin contracts, registry, gr
  symbolic/    curvature tensors, ADM fast path, lambdify with CSE
  analysis/    energy conditions
  scenarios/   warp (metrics, analyzer)
docs/          DESIGN.md
tests/         unit, benchmarks
examples/      configs