warpax

JAX tools for curvature, energy conditions, and geodesics in prescribed spacetimes. warpax uses automatic differentiation to evaluate the Einstein tensor, then tests energy conditions across observer directions. See the changelog for version 1.6.0.

Alcubierre wall and speed sweep. Left: expansion behind the bubble and contraction ahead. Right: non-positive Eulerian energy density. The inset shows the smallest normalized null contraction among 312 sampled directions. Heights and colors use fixed signed logarithmic scales. Each frame is a separate constant-speed metric centered at the origin; the final zero-speed frame is flat spacetime. These are scalar plots, not a spatial embedding or a simulation of acceleration.

The animation guide explains the complementary shear, directional-sampling and curvature views.

Install and run

Python 3.12 or newer:

pip install warpax

from warpax import certify
from warpax.metrics import RodalMetric

metric = RodalMetric(v_s=0.5, R=1.0, sigma=8.0)
result = certify(metric, shape=(16, 16, 16))
print(result.type_fractions)
print(result.invariant_nec_min)  # Minimum over sampled wall Type-I points.

The grid is a quick demonstration. Resolve the wall and vary the grid before interpreting extrema or type fractions. Geometric units are G = c = 1, with metric signature (-,+,+,+) and float64 enabled at import.

For a general GR starting point, the curvature tutorial checks Minkowski space and Schwarzschild vacuum against analytical results. The same curvature pipeline accepts custom metrics. The conventions specify index order, curvature sign and physical units.

For development and the examples:

git clone https://github.com/anindex/warpax.git
cd warpax
uv sync --locked --extra dev --extra viz --extra solver
uv run python examples/01_minkowski_sanity.py

What it computes

• Curvature and stress-energy from callable metrics, including ADM fields.
• Hawking–Ellis classification, Type-I eigenvalue margins, and linear matrix inequality (LMI) tests that do not require an algebraic type assignment.
• Continuous observer searches, exact checks for supplied rational certificates, and interval bounds on supported metric domains.
• Timelike and null geodesics, finite-segment energy integrals, tidal effects, and quantum-inequality reference diagnostics.
• Constraint residuals, TOV equilibrium, ADM mass, junction conditions, prescribed-source shell diagnostics, and metric optimization.
• WarpFactory, EinFields, and Cactus imports; Matplotlib and Manim visualization; Bondi flux and Newman–Penrose diagnostics.

Numerical classification and LMI searches use finite precision and tolerances. An unsuccessful certificate search is inconclusive. The exact energy-condition verdict is independent of the observer, but numerical margin magnitudes depend on the tetrad and normalization. Observer optimization also depends on its rapidity cap. The Eulerian normal remains timelike wherever the ADM lapse and spatial metric are valid, including regions where the coordinate vector ∂t is spacelike.

The null integrals cover finite segments. They establish no complete-geodesic ANEC sign or ranking. Grid spreads and polished extrema are numerical diagnostics; only reported interval bounds support continuum claims. Vorticity alone does not determine algebraic type, and the exact pointwise quadratic speed law requires zero momentum and fixed profiles and domains.

Documentation

Start with the quickstart or numbered examples. Each metric implements a callable (4,) -> (4, 4) from spacetime coordinates to the covariant metric tensor.

Example 07 implements a Gaussian warp metric. Examples 08–10 cover shape design and shell diagnostics. Example 11 reproduces the elastic-shell equilibrium, frame dragging, cavity tides and central clock shifts. Its datasets and definitions live in this repository; see the shell guide for commands and approximation limits. Animation commands and system dependencies are in the animation instructions and render script.

Checks and reproduction

uv run python -m pytest
uv run ruff check src/ tests/ scripts/ benchmarks/ examples/
uv run ruff format --check src/ tests/ scripts/ benchmarks/ examples/
uv sync --locked --extra docs
uv run mkdocs build --strict

Tests run in parallel by default. Use -n 2 to limit workers, or select a module such as tests/test_slemma.py.

The script guide lists reproduction commands and required extras. reproduce_all.sh clears generated caches by default; --keep-cache retains them, and --stage selects a stage. Interval enclosures are a separate, expensive stage. The optional paper-number check requires the corresponding manuscript sources and matching numerical inputs.

Citation

Use CITATION.cff for software metadata and cite the relevant paper:

• An T. Le, Observer-robust energy condition verification for warp drive spacetimes (2026).
• An T. Le, Relativistic elastic shells: material support and cavity geometry (2026).

The observer-robust paper received provisional acceptance by Classical and Quantum Gravity on September 21, 2026, pending the publisher's final checks. Example 11 supplies the elastic-shell numerical calculations. SShellMetric and TShellMetric implement separate prescribed metrics; see the shell guide for their limitations.

License

MIT; see LICENSE.

Questions and contributions

For a numerical discrepancy, open an issue with the metric and parameters, evaluation point or grid, expected identity, tolerances and a minimal runnable example. Contributions of metrics should include their coordinate domain, conventions, source reference and an independent curvature or stress-energy check.