warpax 1.4.0__tar.gz

warpax-1.4.0/.gitignore

@@ -0,0 +1,69 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting
+.ruff_cache/
+
+# Manim renders
+media/
+animations/
+
+# Example output (generated by examples/*.py)
+examples/output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environments
+.env
+.venv/
+env/
+venv/
+
+# MkDocs build output
+site/
+
+# asv benchmark harness output
+.asv/
+benchmarks/env/
+benchmarks/.asv/
+
+# Generated figure outputs (reproducible via reproduce_all.sh / Manim)
+figures/*.pdf
+figures/*.gif
+figures/*.png
+!figures/.gitkeep
+!figures/wall_velocity_sweep.gif
+!figures/eulerian_kinematics.gif
+!figures/kretschmann_invariant.gif
+!figures/eulerian_vs_worstcase_nec.gif
+!figures/gaussian_warp_grid_comparison.png
+
+# Reproduction cache - large binary artifacts. The MANIFEST + json/tex
+# summaries stay tracked; npz and pdf are regenerated via reproduce_all.sh.
+results/**/*.npz
+results/**/*.pdf
+
+# TeX and renderer logs
+*.log

warpax-1.4.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to `warpax`, following
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0 history is
+in `docs/explanation/release_notes.md`.
+
+## [1.4.0] - 2026-08-31
+
+Type-free certification. The energy-condition verdict comes from a $4\times4$
+linear matrix inequality rather than from an eigendecomposition, so it holds at
+every Hawking-Ellis type, and each verdict carries an exact rational
+certificate.
+
+### Added
+
+- `energy_conditions.slemma.certify_point_lmi`: NEC/WEC/SEC/DEC over every
+  timelike and null observer from $\hat T + \sigma\eta \succeq 0$, at Types I
+  through IV alike, with no rapidity cap and no classification tolerance.
+  `witness_observer` returns the violating boost.
+- `energy_conditions.certificate`: exact rational certificates checked over
+  `Fraction`. A multiplier $\sigma$ when the condition holds, a boost $w$ with
+  $|w| \le 1$ and $q(w) < 0$ when it fails.
+- `energy_conditions.enclosure`: verified continuum enclosures of the worst-case
+  violation by interval branch-and-bound (Moore-Skelboe, `mpmath.iv`, outward
+  rounding), bracketing the extremum over the domain rather than over a grid.
+- `energy_conditions.interval_lmi`: the same certificate in interval arithmetic,
+  from the metric rather than from a sampled stress-energy tensor.
+- `grids.proper_volume_weights`: the slice Jacobian
+  $\mathrm{d}V = \sqrt{\det\gamma}\,\mathrm{d}^3x$. Every volume-weighted
+  fraction on a conformally scaled slice moves.
+- `analysis.extrema.refine_extremum`: polishes a grid extremum off the grid.
+
+### Fixed
+
+- `averaged.anec`: the on-cone witness is measured on the trajectory tangent
+  $\mathrm{d}x/\mathrm{d}\lambda$, not on the projected vector, which is null by
+  construction. `_project_to_null` uses the Citardauq form.
+- `averaged.awec`: a spacelike curve is reported rather than normalised as
+  timelike, and the line integral carries $\mathrm{d}\tau/\mathrm{d}\lambda$.
+- `analysis.convergence`: grid spacing is $1/(N-1)$ on endpoint-inclusive grids.
+  Non-geometric ladders are refused rather than fitted.
+- `energy_conditions.enclosure.tail_bound`: the minimum of $|x|$ over the slab,
+  not of $|$endpoint$|$, which excluded a slab straddling the origin.
+- `junction.darmois`: one-sided limits at $\Sigma$, so a smooth metric gives a
+  vanishing jump. A $\Sigma$ of changing causal character gives no verdict.
+- Every absolute floor is relative to the tensor or metric scale, so a verdict
+  survives a coordinate rescaling.
+- Both classifiers report no verdict on non-finite input, and agree with each
+  other.
+- `frame_free`: `lmi_substituted` marks margins taken from the LMI rather than
+  from the eigenvalue inequalities. Only their sign is comparable.
+- ANEC affine windows come from the ray's horizon crossing, not from a
+  stationarity search that walked into integrator drift.
+
+### Performance
+
+- Interval branch-and-bound 3.3x faster, with bit-identical enclosures.
+- Metric parameters are array leaves, so a velocity sweep no longer recompiles
+  the curvature chain per value.
+- `import warpax` drops from 2.5 s to 0.75 s; `design` and sympy load on first
+  use.
+
+### Removed
+
+- `exceptions`, `grids._refined`, `benchmarks.registry`,
+  `visualization.common._themes` and `_jit_cache`, none of which had a caller.
+
+## [1.3.0] - 2026-06-22
+
+Manim scenes renamed to physically accurate names, colormaps matched to each
+field's sign, and a headless 3D render path through OpenGL/EGL.
+
+## [1.2.0] - 2026-06-21
+
+New `warpax.bondi`: Bondi four-momentum radiated flux, Newman-Penrose Weyl
+scalars, and peeling falloff $\Psi_n \sim r^{-(5-n)}$ at null infinity.
+
+## [1.1.1] - 2026-06-20
+
+Reproduction artifacts and docs for the source-shell paper
+(arXiv:2605.25417). No API changes.
+
+## [1.1.0] - 2026-06-10
+
+Frame-independent certification.
+
+- `warpax.certify(metric)`: one-call all-observer certification from the
+  Hawking-Ellis eigenvalue test of $T^a{}_b$, valid at all warp speeds
+  including superluminal $v_s \ge 1$.
+- Closed-form Type-I worst observer, cross-checked against the BFGS optimizer.
+- Rigorous geodesic-integrated ANEC through a symplectic null integrator that
+  conserves $g_{ab}k^ak^b$ where the adaptive integrator drifts off the cone.
+- Shift vorticity controls the wall type: the Type-IV imaginary pair is linear
+  in it, and shear amplifies but does not open it.
+- Wall NEC deficit and curvature invariants as power laws in $v_s$, splitting
+  by vorticity ($v_s^2$ vortical, $v_s^4$ irrotational).
+- New `metrics.GarattiniMetric`, and cross-construction verification of the
+  Fuchs, WarpShell and Garattini-Zatrimaylov constructions.
+
+## [1.0.0] - 2026-05-26
+
+First stable release: Hawking-Ellis classification with exact Type-I margins,
+multistart BFGS observer optimization, source-first S-/T-shell construction from
+the Einstein constraints, a pure-JAX autodiff curvature chain, WarpFactory /
+Cactus / EinsteinFields IO, and a differentiable metric-design API.
+
+[1.4.0]: https://github.com/anindex/warpax/releases/tag/v1.4.0
+[1.3.0]: https://github.com/anindex/warpax/releases/tag/v1.3.0
+[1.2.0]: https://github.com/anindex/warpax/releases/tag/v1.2.0
+[1.1.1]: https://github.com/anindex/warpax/releases/tag/v1.1.1
+[1.1.0]: https://github.com/anindex/warpax/releases/tag/v1.1.0
+[1.0.0]: https://github.com/anindex/warpax/releases/tag/v1.0.0

warpax-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 An T. Le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

warpax-1.4.0/PKG-INFO

@@ -0,0 +1,414 @@
+Metadata-Version: 2.5
+Name: warpax
+Version: 1.4.0
+Summary: Observer-robust energy condition verification for warp drive spacetimes
+Project-URL: Homepage, https://github.com/anindex/warpax
+Project-URL: Documentation, https://github.com/anindex/warpax#readme
+Project-URL: Repository, https://github.com/anindex/warpax
+Project-URL: Issues, https://github.com/anindex/warpax/issues
+Project-URL: Author, https://github.com/anindex
+Author-email: "An T. Le" <an@robot-learning.de>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Requires-Dist: beartype<0.23.0,>=0.22.9
+Requires-Dist: diffrax>=0.7.2
+Requires-Dist: equinox<0.14.0,>=0.13.6
+Requires-Dist: jax<0.11.0,>=0.10.0
+Requires-Dist: jaxtyping>=0.3.10
+Requires-Dist: matplotlib<4.0.0,>=3.10.9
+Requires-Dist: mpmath<1.4,>=1.3.0
+Requires-Dist: numpy<3.0.0,>=2.2.0
+Requires-Dist: optimistix>=0.1.0
+Requires-Dist: sympy>=1.14
+Requires-Dist: tqdm>=4.0
+Provides-Extra: bench
+Requires-Dist: asv<1.0,>=0.6.5; extra == 'bench'
+Provides-Extra: design
+Requires-Dist: interpax<0.4.0,>=0.3.14; extra == 'design'
+Provides-Extra: dev
+Requires-Dist: pytest-xdist>=3.6.0; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.15.16; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: griffe<3.0,>=2.0.2; extra == 'docs'
+Requires-Dist: mkdocs-material<10.0,>=9.7.6; extra == 'docs'
+Requires-Dist: mkdocstrings-python<3.0,>=2.0.3; extra == 'docs'
+Requires-Dist: mkdocstrings<2.0,>=1.0.4; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
+Provides-Extra: einfields
+Requires-Dist: flax<0.13,>=0.12; extra == 'einfields'
+Requires-Dist: orbax-checkpoint<0.13.0,>=0.11.40; extra == 'einfields'
+Provides-Extra: interop
+Requires-Dist: h5py<4.0.0,>=3.16.0; extra == 'interop'
+Requires-Dist: mat73<1.0,>=0.65; extra == 'interop'
+Provides-Extra: manim
+Requires-Dist: imageio-ffmpeg>=0.4.9; extra == 'manim'
+Requires-Dist: imageio>=2.31; extra == 'manim'
+Requires-Dist: manim<0.21.0,>=0.20.1; extra == 'manim'
+Provides-Extra: solver
+Requires-Dist: scipy>=1.17.0; extra == 'solver'
+Provides-Extra: viz
+Requires-Dist: imageio>=2.31; extra == 'viz'
+Requires-Dist: scipy>=1.17.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# warpax
+
+[![arXiv](https://img.shields.io/badge/arXiv-2602.18023-brown)](https://arxiv.org/abs/2602.18023)
+[![DOI](https://zenodo.org/badge/1162355401.svg)](https://doi.org/10.5281/zenodo.18715933)
+[![CI](https://github.com/anindex/warpax/actions/workflows/ci.yml/badge.svg)](https://github.com/anindex/warpax/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/anindex/warpax/blob/main/LICENSE)
+
+[**Observer-robust energy condition verification for warp drive spacetimes.**](https://arxiv.org/abs/2602.18023)
+
+`warpax` decides the energy-condition structure of warp-drive spacetimes for
+*every* observer at once, from the eigenstructure of the mixed stress-energy tensor
+$T^a{}_b$, with exact curvature from JAX forward-mode autodiff. The decision uses
+only the boost-invariant eigenvalues of $T^a{}_b$ and never requires the
+coordinate-stationary observer $\partial_t$ to be timelike, so it stays well-defined
+at all warp speeds, including superluminal $v_s \ge 1$ where $\partial_t$ turns
+spacelike and single-frame tools such as WarpFactory break down. Each Hawking-Ellis
+type is decided the same way: a $4\times4$ linear matrix inequality
+$\hat T + \sigma\eta \succeq 0$ over every timelike and null observer, with no
+rapidity cap and no classification tolerance, and each verdict backed by an exact
+rational certificate.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anindex/warpax/main/figures/wall_velocity_sweep.gif" width="760" alt="Alcubierre warp bubble: Eulerian energy density embedding and observer-robust NEC-margin slab"/>
+</p>
+
+<p align="center"><em>An Alcubierre warp bubble. The wireframe is the Eulerian energy density, negative everywhere across the wall (&rho;<sub>Eul</sub> &le; 0); the slab beneath is the NEC margin minimized over the whole null sphere, which never rises above zero. The sweep sharpens the wall (&sigma;: 1 &rarr; 16), then eases the velocity toward flat space. Both fields span about three decades over the sweep, so height and colour are on a signed log scale: monotone and sign-preserving, but not proportional.</em></p>
+
+## Features
+
+- Frame-independent, all-observer energy-condition certification at every warp
+  speed (including superluminal $v_s \ge 1$), from the eigenstructure of
+  $T^a{}_b$, exact and cap-free for every Hawking-Ellis type.
+- Hawking-Ellis classification (Type I-IV) with explicit Type-IV detection,
+  cross-checked by two eigensolver backends against a 50-digit `mpmath`
+  reference.
+- Exact decision at Type-III/IV points from the absence of a causal
+  eigenvector, with a closed-form Eulerian null witness for the
+  momentum-sourced case; a closed-form Type-I worst observer and a multistart
+  BFGS optimizer serve only to display violation severity.
+- Momentum-density control of the wall type through the discriminant
+  $\Delta=(\rho+S_\parallel)^2-4|j|^2$: a negative discriminant sends a point to
+  Type IV, and the same momentum density sets the wall NEC deficit and
+  curvature scaling.
+- Rigorous geodesic-integrated ANEC via a symplectic null integrator (with an
+  on-cone witness), plus a Ford-Roman quantum-inequality diagnostic.
+- Bondi four-momentum radiated-flux and Newman-Penrose peeling at null infinity
+  (`warpax.bondi`).
+- Exact curvature via forward-mode JAX autodiff, no finite-difference stencils.
+- Ten warp/shell metrics, constraint residuals, anisotropic TOV, ADM mass with
+  falloff, Israel junctions, transport diagnostics, and source-first S-/T-shell
+  construction with a five-criterion admissibility standard.
+
+## Two papers, one toolkit
+
+warpax backs two separate papers with disjoint claims. If you cite a result,
+cite the paper it belongs to:
+
+| | Certification paper ([arXiv:2602.18023](https://arxiv.org/abs/2602.18023)) | Companion note ([arXiv:2605.25417](https://arxiv.org/abs/2605.25417)) |
+|---|---|---|
+| **Question** | Which observers see energy-condition violations, at which warp speeds? | Can source-first shells satisfy the energy conditions at all? |
+| **Results** | Frame-free all-velocity certifier; velocity-resolved type map; momentum-density discriminant controlling the wall type; closed-form worst observer; exoticity ranking + two-term $v_s$ deficit law | S-/T-shell constructions from the Einstein constraints; five-criterion admissibility standard; boundary-cost analysis |
+| **Modules** | `energy_conditions`, `geometry`, `averaged`, `quantum`, `analysis`, `geodesics`, `transport`; metrics Alcubierre / Natário / Van den Broeck / Rodal / Lentz / WarpShell / Garattini | `constraints` (S-/T-shell solvers), `tov`, `adm`, `junction`, `design`, `optimization`; `metrics/sshell.py`, `metrics/tshell.py` |
+| **Examples** | 01-07 | 08-10 |
+
+The S-/T-shells are constructed and certified in the companion note, not in the
+certification paper; neither paper's results depend on the other's.
+
+## Quick start
+
+```bash
+# Create environment and install
+conda create -n warpax python=3.12 -y && conda activate warpax
+pip install -e ".[dev,viz,design,solver]"
+
+# Run a quick example
+python examples/01_minkowski_sanity.py
+```
+
+See [`examples/README.md`](examples/README.md) for a numbered learning path (01-10)
+and which optional extras each script needs.
+
+For a 5-10 minute walkthrough from install to seeing an energy condition violation,
+see the [Quickstart tutorial](docs/tutorials/quickstart.md).
+
+## Key results
+
+### Frame-independent type map across the luminal transition
+
+On matched, wall-resolved grids, the Rodal irrotational geometry is globally
+Hawking-Ellis Type I at every speed from $v_s = 0.1$ to $2.5$, while the
+Alcubierre/Natário/Van den Broeck bubble walls are Type-IV dominated (no rest
+frame, no invariant energy density) at every speed. The split is controlled by the
+Eulerian momentum density through the discriminant
+$\Delta=(\rho+S_\parallel)^2-4|j|^2$: an irrotational shift carries no wall momentum
+and stays globally Type I, while a vortical shift drives $\Delta<0$ and the wall to
+Type IV. For Rodal's globally Type-I drive the Eulerian frame does not register
+~73% of the wall weak-energy and ~74% of the wall dominant-energy violations seen
+by boosted observers, an exact eigenvalue statement rather than an optimizer
+artifact. A rigorous geodesic-integrated
+ANEC (symplectic integrator with an on-cone witness) and a Ford-Roman comparison
+preserve the ordering: every drive violates, and the irrotational Rodal geometry is
+the mildest by one to two orders of magnitude.
+
+### Composite exoticity ranking and scaling laws
+
+A composite exoticity ranking on the benchmark slice, from observer-independent
+inputs (NEC severity, Type-IV fraction, rigorous ANEC minimum), places the
+irrotational Rodal drive nearly two orders of magnitude below the bubble-wall
+drives (index 0.010 against 0.70 to 1.00), driven by its vanishing Type-IV
+fraction and tiny averaged-null energy, not by a milder pointwise NEC. The wall NEC deficit follows the two-term law
+$\min(\rho+p_i) = -C\,v_s^2 - D\,v_s$, single-term for the irrotational Rodal drive
+($D=0$) and with a vorticity-set linear correction for the vortical walls, in line
+with the Santiago-Schuster-Visser no-go. The wall curvature splits by the same
+vorticity: vortical walls grow as $v_s^2$, the irrotational Rodal wall as $v_s^4$
+($R^2 \ge 0.99$).
+
+### Observer-robust vs Eulerian
+
+Conditional on a violation existing, the Eulerian frame misses up to 29% of the
+DEC-violating points and 76% of the SEC-violating points across the tested
+drives (`results/comparison_table.json`).
+
+### Custom metrics
+
+Subclass `ADMMetric` and run the full pipeline. The figure below validates a
+Gaussian warp bubble on a 24x24x4 grid: SEC margins from the Eulerian observer
+(left), from the worst-case boosted observer found by BFGS (center), and the 1496
+grid points the Eulerian frame reports as SEC-satisfied while the boosted observer
+sees them violated (right). Regenerate it with
+`python examples/07_custom_warp_metric.py --readme-figure`.
+
+![Gaussian Warp Grid Comparison](https://raw.githubusercontent.com/anindex/warpax/main/figures/gaussian_warp_grid_comparison.png)
+
+<p align="center"><em>SEC comparison for a custom Gaussian warp bubble (v<sub>s</sub> = 0.5). Red marks violations the Eulerian frame misses.</em></p>
+
+See [`examples/07_custom_warp_metric.py`](examples/07_custom_warp_metric.py).
+
+### Shell admissibility
+
+`warpax` ships a five-criterion admissibility standard for warp shells:
+
+| Criterion | Checks |
+|-----------|--------|
+| A. Regularity | $C^2$ metric continuity (thick) or Israel conditions (thin) |
+| B. Constraints | Hamiltonian + momentum residuals $\epsilon_{\mathcal{H}}$, $\epsilon_{\mathcal{M}}$ |
+| C. Matter model | Identifiable source (anisotropic fluid, elastic shell) |
+| D. EC margins | Frame-free NEC/WEC/DEC from Hawking-Ellis eigenvalue slacks (exact, cap-free at Type-I; valid at all $v_s$) |
+| E. Global | Positive ADM mass, asymptotic falloff, tidal forces, invariant transport |
+
+Fuchs constant-velocity shell: source-aware $\epsilon_{\mathcal{H}} \approx
+3\times10^{-8}$; the bulk shell interior is Type-I and EC-compliant (0 of 13
+probes violate), while the smoothing tail turns Type-IV. The source-first S-/
+T-shells likewise pass criteria A-C and E with positive interior margins; the
+binding cost is a cap-free Type-I dominant-energy deficit at the inner shell edge
+($\approx -4.4\times10^{-4}$), localized at the smooth source-vacuum transition,
+and the tilted T-shell's shift vorticity drives a Type-IV onset at its
+low-density edge. These shell results belong to the companion note; see
+[The boundary cost of source consistency](docs/explanation/boundary_cost.md).
+
+## Examples
+
+See [`examples/README.md`](examples/README.md) for runtime estimates, install extras,
+and a suggested order for new users.
+
+| Script | Description |
+|--------|-------------|
+| `01_minkowski_sanity.py` | Flat-space sanity check (all ECs satisfied) |
+| `02_schwarzschild_verification.py` | Schwarzschild ground-truth validation |
+| `03_alcubierre_analysis.py` | Alcubierre warp drive EC analysis (**quickstart entry**) |
+| `04_warp_drive_comparison.py` | Multi-metric comparison (six warp drives) |
+| `05_grid_analysis.py` | Grid-based EC verification + comparison figure |
+| `06_geodesic_through_warp_bubble.py` | Geodesic integration with tidal forces |
+| `07_custom_warp_metric.py` | Custom warp manifold + robust EC validation |
+| `08_metric_design.py` | Shape-function metric design (B-spline reproduction) |
+| `09_admissibility_diagnostics.py` | Admissibility diagnostics on the Fuchs warp shell |
+| `10_phase_diagram.py` | Parameter-space sweep and EC-admissible transport phase diagram |
+
+```bash
+python examples/01_minkowski_sanity.py
+python examples/10_phase_diagram.py          # 8x6 demo (~2 min)
+python examples/10_phase_diagram.py --full   # 20x15 sweep (~30 min GPU)
+```
+
+## Architecture
+
+```
+metrics -> geometry -> energy_conditions -> analysis
+              |              |
+          geodesics    classification (Hawking-Ellis)
+              |
+         transport / tidal / blueshift
+```
+
+| Package | Description |
+|---------|-------------|
+| `geometry` | JAX autodiff pipeline: metric $\to$ Christoffel $\to$ Riemann $\to$ Ricci $\to$ Einstein $\to$ $T_{\mu\nu}$; ADM 3+1 split; $C^2$ regularity diagnostics |
+| `energy_conditions` | NEC/WEC/SEC/DEC via Hawking-Ellis classification, eigenvalue algebra, multi-start BFGS observer optimization |
+| `grids` | Non-uniform grid generators; wall-clustered sampling that resolves a bubble wall without a uniform refinement everywhere |
+| `metrics` | Nine warp/shell metrics: Natário, Lentz, Rodal, Van den Broeck, WarpShell, Fuchs, S-shell, T-shell, Garattini-Zatrimaylov (Alcubierre, Minkowski, and Schwarzschild ship in `benchmarks`, making ten warp metrics total) |
+| `constraints` | Hamiltonian + momentum constraint residuals; S-shell and T-shell constraint solvers (pure JAX) |
+| `tov` | Anisotropic TOV equilibrium checker |
+| `adm` | ADM mass with surface integral and asymptotic falloff verification |
+| `junction` | Israel/Darmois junction conditions and surface stress-energy |
+| `transport` | Invariant diagnostics: geodesic deviation, null coordinate-time asymmetry, blueshift hazard |
+| `optimization` | Bernstein basis, multi-objective loss, EC soft/hard constraints, parameter sweep |
+| `geodesics` | Timelike/null geodesic integration via Diffrax, tidal deviation, blueshift extraction |
+| `design` | Differentiable shape-function parametrization with constrained BFGS optimizer |
+| `analysis` | Eulerian vs. robust comparison, convergence tools (stability spreads + continuum polishing of wall extrema, `analysis.extrema`), kinematic scalars |
+| `io` | External metric loaders: WarpFactory (.mat), EinFields (checkpoint), Cactus (HDF5) |
+| `visualization` | Matplotlib publication figures, Manim animations, phase diagram plots |
+| `classify` | Bobrick-Martire subluminal/superluminal taxonomy |
+| `averaged` | ANEC/AWEC null-ray and geodesic line integrals |
+| `quantum` | Ford-Roman quantum inequality evaluator |
+| `bondi` | Bondi four-momentum, radiated flux, and Newman-Penrose peeling at null infinity |
+| `benchmarks` | Reference spacetimes (Alcubierre, Minkowski, Schwarzschild). Distinct from the top-level `benchmarks/` asv harness |
+| `numerics` | Shared numerical utilities: constants, regularity floors, autodiff-safe helpers |
+
+All metrics implement a common `MetricFunction` interface: a callable `(4,) -> (4,4)` mapping
+coordinates $x^\mu$ to the covariant metric tensor $g_{\mu\nu}$.
+
+## Running tests
+
+```bash
+pytest                      # Whole suite, ~3 min (1090 tests, parallel by default)
+pytest -m smoke             # Visualization import / render smoke tests
+pytest tests/test_slemma.py # One module
+```
+
+One tier only: `-n auto` comes from `pyproject.toml`, and no test is excluded by
+default.
+
+## Reproducing results
+
+To pin the exact Python environment used to produce the published results:
+
+```bash
+export PYTHON=$(uv run which python)
+bash reproduce_all.sh
+```
+
+Stages can be run individually:
+
+```bash
+bash reproduce_all.sh --stage core      # Core computation
+bash reproduce_all.sh --stage ablation  # Ablation studies
+bash reproduce_all.sh --stage figures   # Figure generation
+```
+
+Use `--keep-cache` to skip cache deletion and only recompute missing results.
+
+Per-paper reproduction guides map every figure, table and quoted number to the
+script that produces it:
+
+- [**Observer-robust energy condition paper**](docs/how-to/reproduce_observer_robust_paper.md) - stage list, table- and figure-to-script maps, and the two consistency checks
+- [**Warp-shell admissibility paper**](docs/how-to/reproduce_warpshell_paper.md) - per-figure, per-claim mapping to scripts and outputs
+
+The outer-edge ($r \ge R_2$) Type-IV verification (log-log slope $1.01 \pm 0.01$) and
+the ANEC impact-parameter scan are reproduced by
+`scripts/run_tshell_typeIV_onset.py` and `scripts/run_anec_impact_scan.py`.
+
+## Documentation
+
+warpax ships full documentation in [`docs/`](docs/), organized following the [Diataxis](https://diataxis.fr/) framework:
+
+### Tutorials
+
+- [**Quickstart**](docs/tutorials/quickstart.md) - 5-10 minutes from install to seeing an energy condition violation
+- [**First curvature computation**](docs/tutorials/first_curvature_computation.md) - full curvature chain on Minkowski as a warm-up
+
+### How-to guides
+
+- [**Define a custom warp metric**](docs/how-to/custom_metric_tutorial.md) - subclass `ADMMetric` and run the verification pipeline
+- [**Interpret EC results**](docs/how-to/interpreting_ec_results.md) - read margin signs, Hawking-Ellis types, and worst-case observers
+- [**Load an external metric**](docs/how-to/loading_external_metrics.md) - use WarpFactory, EinFields, or Cactus data
+- [**Reproduce the observer-robust paper**](docs/how-to/reproduce_observer_robust_paper.md) - stage list, table- and figure-to-script maps, and the two consistency checks
+- [**Reproduce the warp-shell admissibility paper**](docs/how-to/reproduce_warpshell_paper.md) - per-figure, per-claim mapping to scripts and outputs
+
+### Reference
+
+- [**API reference**](docs/reference/index.md) - autodoc of the public API
+- [**Metric catalog**](docs/reference/metric_catalog.md) - all ten shipped metrics
+- [**Benchmarks**](docs/reference/benchmarks.md) - asv regression harness
+
+### Explanation
+
+- [**Architecture**](docs/explanation/ARCHITECTURE.md) - package structure and design decisions
+- [**Theory: ADM 3+1 and Hawking-Ellis types**](docs/explanation/theory.md) - mathematical background
+- [**Release notes**](docs/explanation/release_notes.md) - pre-1.0 history
+
+## Manim visualizations
+
+Every scene comes from the same curvature and energy-condition code as the papers.
+Geometric units on the z = 0 slice; each frame is a frozen metric, a parameter
+sweep rather than a time evolution.
+
+<div align="center">
+<table>
+<tr>
+<td width="33%"><img src="https://raw.githubusercontent.com/anindex/warpax/main/figures/eulerian_kinematics.gif" alt="Expansion theta = -K and shear of the Eulerian congruence"/></td>
+<td width="33%"><img src="https://raw.githubusercontent.com/anindex/warpax/main/figures/kretschmann_invariant.gif" alt="Kretschmann curvature invariant"/></td>
+<td width="33%"><img src="https://raw.githubusercontent.com/anindex/warpax/main/figures/eulerian_vs_worstcase_nec.gif" alt="Eulerian vs observer-robust NEC margin"/></td>
+</tr>
+<tr>
+<td align="center"><em><strong>Eulerian kinematics.</strong> Expansion θ = −K: space stretches behind the ship (red) and squeezes in front (blue). Shear σ² as iso-contours, with the f = 0.5 wall on top.</em></td>
+<td align="center"><em><strong>Kretschmann invariant.</strong> K = R<sub>abcd</sub>R<sup>abcd</sup>, the same for every observer. Sign-indefinite in Lorentzian signature, so it dips negative, and spikes on the wall.</em></td>
+<td align="center"><em><strong>Observer-robust NEC.</strong> Six axis-aligned Eulerian nulls on the left, the worst case over the whole null sphere on the right (k·n<sub>Eul</sub> = −1). The gap is what observer-robust verification buys.</em></td>
+</tr>
+</table>
+</div>
+
+The full set: **WallAndVelocitySweep** / **VelocitySweep** (dual-layer 3D,
+ρ<sub>Eul</sub> above a NEC-margin slab), **BoostRapiditySweep** (energy density
+vs rapidity ζ, deepening as cosh²ζ), **EulerianKinematics2D**,
+**KretschmannInvariant2D**, **NECMargin2D** / **EulerianVsWorstCaseNEC**, and
+**WorstCaseNullDirections** / **WorstCaseBoostDirections**.
+
+```bash
+# System dependencies (Ubuntu/Debian)
+sudo apt install texlive-latex-extra texlive-fonts-recommended dvipng cm-super ffmpeg gifsicle
+
+# Python dependencies (Python <= 3.13 recommended for the renderer)
+pip install -e ".[manim]"
+
+# Render all scenes (2D via Cairo, 3D via the GPU OpenGL renderer)
+python scripts/render_all_scenes.py
+```
+
+Rendered videos and images are written to `media/` (not tracked by git). The 3D
+scenes render through manim's OpenGL renderer (EGL, headless).
+
+## Citation
+
+If you found this work useful, please consider citing:
+
+```bibtex
+@article{le2026observer,
+  title={Observer-robust energy condition verification for warp drive spacetimes},
+  author={Le, An T},
+  journal={arXiv preprint arXiv:2602.18023},
+  year={2026}
+}
+
+@article{le2026boundary,
+  title={On the boundary cost of source-consistent warp shells},
+  author={Le, An T},
+  journal={arXiv preprint arXiv:2605.25417},
+  year={2026}
+}
+```