MHX documentation

MHX is a validation-first, differentiable JAX framework for magnetic reconnection and magnetohydrodynamics.

The active package is under src/mhx/.

Active scope boundaries

The current repository supports deterministic FAST validation, seed-robust QI, fitted latent-ODE reproducibility, timing/readiness reports, nonlinear reduced-MHD media examples such as double-Harris, Orszag–Tang, decaying turbulence, and forced turbulent reconnection, plus short validation-grade Rutherford executor chunks. The latest bounded GPU double-Harris campaign (outputs/campaigns/gpu_nonlinear_20260522_085049/double_harris_long_n128_t160) is gate_ready = true for validation media and production_claim_ready = false; its promotion report explicitly permits only claim_level_if_passed = "validation". Long nonlinear Rutherford/plasmoid production campaigns are still gated as future production claims and must pass duration, checkpoint-restart, convergence, seed/QI, positive reconnecting-flux and island-width response, artifact-hash, and explicit production-claim checks before being used as paper evidence.

Evidence guide

Start with these pages when checking validation evidence and scope boundaries:

  • Evidence map links claims to source files, tests, reproduction commands, artifacts, and explicit limitations.

  • Physics validation contains the equations, citations, still-figure gallery, and numerical gates that are intentionally kept out of the README.

  • Benchmark command index lists validation, scaffold, comparison, campaign, and neural-ODE commands with expected output families.

  • Validation movies separates solver-generated movies from theory schematics, documents the residual-flux media policy, and keeps the literature anchors next to the visuals.

  • Publication checklist states which figures are ready as validation evidence and which remain roadmap or production-only.

  • Nonlinear campaign evidence claims is the claim table plus reviewer commands for double-Harris, Rutherford, and forced turbulent-reconnection long-run evidence.