# Wormhole Analog Lab

> A reproducible sandbox for exploring traversable wormhole simulations, state-dependent diagnostics, and visualization tooling. The code is intentionally neutral: it generates synthetic experiments for discussion rather than claiming verified physics.

## What Lives Here

- `run_smooth.py` – entry point for producing smooth wormhole feeds and per-seed diagnostics.
- `scripts/` – analysis helpers (GR analogue metrics, hotspot extraction, window sweep, etc.).
- `wormhole_proof/` – simulator package (core dynamics, analysis, FastAPI wireframe viewer).
- `artifacts/` – generated JSON/markdown/plots from recent runs, organized by suite name.

## Quickstart

```bash
python -m venv .venv
./.venv/Scripts/activate  # use source .venv/bin/activate on macOS/Linux
pip install -r requirements.txt
python run_smooth.py --output artifacts/smooth_demo --seed 7
```

This writes three artefacts into the requested directory:

1. `smooth_metrics.json` – simulator configuration and scalar metrics.
2. `smooth_summary.md` – human-readable summary table.
3. `wireframe.json` – sanitized feed for the 3D/high-dimensional viewers.

## Diagnostic Pipeline (ELI5)

1. **Simulate** a “wormhole” by running the smooth configuration for a chosen seed.
2. **Record** the 64D geometry, packet traces, and Hayden–Preskill checks into the artefacts folder.
3. **Analyse** the feed with scripts like `gr_metric_analysis.py` to compute curvature, stress, and divergence proxies.
4. **Spot hotspots** with `gr_hotspot_report.py`, which lists the frames where curvature or residuals spike.
5. **Visualize** with the FastAPI wireframe server (`wormhole_proof/wireframe/server.py`) or the static markdown reports.

Nothing here proves a physical wormhole exists; it simply explores what happens when you pretend it does and keep track of the diagnostics.

## Repository Layout

```
wormhole-analog-lab/
├── README.md
├── AGENTS.md                 # Lab notebook for experiments
├── run_smooth.py             # CLI entry point
├── scripts/                  # Analysis utilities
├── wormhole_proof/           # Simulator + wireframe server
└── artifacts/                # Generated outputs (checked in for transparency)
```

## Reproducibility Notes

- The artefacts folder is version-controlled so reviewers can inspect every run.
- Scripts log configurations alongside results to avoid mystery parameters.
- Change-point and calibration constants (e.g., κ) are documented in `AGENTS.md` and script output.

## Contributing

Treat this repository as a public lab notebook. If you extend the simulator or diagnostics:
- Add a short entry to `AGENTS.md` describing the change and artefacts produced.
- Keep speculative language in check; focus on what the code simulates, not what nature guarantees.
- Prefer deterministic seeds and logged config files so others can replay your run.

## License

Add your preferred license here before publishing.