# Benchmarks MHX benchmark workflows are intentionally command-line reproducible. The active catalog now includes a FAST reduced-MHD smoke run, exact linear physics gates, Harris tearing eigenvalue checks, nonlinear energy-budget and duration gates, Orszag--Tang and turbulence media, seed-QI, neural-ODE reproducibility, and restartable Rutherford-executor artifacts. ```bash mhx benchmark run \ --config examples/linear_tearing.toml \ --outdir outputs/benchmarks/linear_tearing_fast \ --gif mhx benchmark validate outputs/benchmarks/linear_tearing_fast ``` Expected files include: - `manifest.json` - `diagnostics.json` - `trajectory.npz` - `figures/energy_history.png` - `figures/flux_final.png` - `figures/mode_amplitude.png` - `figures/flux_movie.gif` - `report.json` - `report.md` - `validation.json` ## Detailed command index Use this section as the detailed command catalog that the README intentionally does not carry. Most benchmark commands write `claim_level = "validation"`; `mhx benchmark run` writes `smoke`, and campaign planning commands can write `production_template`. ```bash mhx benchmark run --config examples/linear_tearing.toml --outdir outputs/benchmarks/linear_tearing_fast --gif mhx benchmark validate outputs/benchmarks/linear_tearing_fast mhx benchmark decay --outdir outputs/benchmarks/resistive_decay mhx benchmark scaling --outdir outputs/benchmarks/reconnection_scaling mhx benchmark fkr-window --outdir outputs/benchmarks/fkr_window mhx benchmark fkr-growth --outdir outputs/benchmarks/fkr_growth_rate mhx benchmark harris-delta-prime --outdir outputs/benchmarks/harris_delta_prime mhx benchmark linear-tearing-eigenvalue --outdir outputs/benchmarks/linear_tearing_eigenvalue mhx benchmark linear-tearing-dispersion --outdir outputs/benchmarks/linear_tearing_dispersion mhx benchmark linear-tearing-layer --outdir outputs/benchmarks/linear_tearing_layer mhx benchmark linear-tearing-timedomain --outdir outputs/benchmarks/linear_tearing_timedomain mhx benchmark linearized-rhs --outdir outputs/benchmarks/linearized_rhs mhx benchmark reduced-mhd-eigenmode --outdir outputs/benchmarks/reduced_mhd_eigenmode mhx benchmark cosine-equilibrium-linearization --outdir outputs/benchmarks/cosine_equilibrium_linearization mhx benchmark current-sheet-eigenvalue --outdir outputs/benchmarks/periodic_current_sheet_eigenvalue mhx benchmark current-sheet-timedomain --outdir outputs/benchmarks/periodic_current_sheet_timedomain mhx benchmark current-sheet-nonlinear-bridge --outdir outputs/benchmarks/periodic_current_sheet_nonlinear_bridge mhx benchmark double-harris-growth --outdir outputs/benchmarks/periodic_double_harris_nonlinear_growth mhx benchmark double-harris-long-run --outdir outputs/benchmarks/periodic_double_harris_seeded_long_run --movies mhx benchmark double-harris-convergence --outdir outputs/benchmarks/periodic_double_harris_convergence mhx benchmark nonlinear-energy-budget --outdir outputs/benchmarks/nonlinear_energy_budget mhx benchmark orszag-tang --outdir outputs/benchmarks/orszag_tang_vortex --movies mhx benchmark decaying-turbulence --outdir outputs/benchmarks/decaying_mhd_turbulence --movies mhx benchmark forced-turbulent-reconnection --outdir outputs/benchmarks/forced_turbulent_reconnection --movies mhx benchmark forced-turbulent-reconnection-readiness-check outputs/benchmarks/forced_turbulent_reconnection mhx benchmark nonlinear-duration-audit --outdir outputs/benchmarks/nonlinear_duration_audit mhx benchmark duration-policy --outdir outputs/benchmarks/duration_policy mhx benchmark diffusion-eigenvalue --outdir outputs/benchmarks/diffusion_eigenvalue mhx benchmark power-iteration --outdir outputs/benchmarks/power_iteration mhx benchmark arnoldi --outdir outputs/benchmarks/arnoldi mhx benchmark timing --outdir outputs/benchmarks/timing --repeats 3 --warmups 1 mhx benchmark catalog --outdir outputs/benchmarks/catalog mhx benchmark seed-robust-qi --outdir outputs/benchmarks/seed_robust_qi mhx benchmark seed-robust-qi-sweep --outdir outputs/benchmarks/seed_robust_qi_sweep mhx neural-ode dataset --outdir outputs/neural_ode/seed_qi_fast mhx neural-ode train --outdir outputs/neural_ode/latent_ode_fast mhx campaign rutherford-template --outdir outputs/campaigns/rutherford_template mhx campaign rutherford-run-fast --outdir outputs/campaigns/rutherford_fast mhx campaign rutherford-plan-production --outdir outputs/campaigns/rutherford_production_plan mhx campaign rutherford-resume-plan outputs/campaigns/rutherford_production_plan mhx campaign rutherford-execute outputs/campaigns/rutherford_production_plan --max-steps 128 python examples/make_rutherford_production_plan.py --outdir outputs/examples/rutherford_production_plan python examples/run_rutherford_production_chunk.py --outdir outputs/examples/rutherford_chunk --movies python examples/run_orszag_tang.py --outdir outputs/examples/orszag_tang --nx 64 --ny 64 --t-end 6 python examples/train_latent_ode_fast.py --outdir outputs/examples/latent_ode_fast mhx validate all --outdir outputs/validation_suite mhx validate readiness --suite outputs/validation_suite --outdir outputs/validation_readiness mhx validate paper-pipeline --outdir outputs/paper_pipeline ``` `mhx validate all` includes the forced-turbulent-reconnection readiness check as a separate required public-release gate after generating a FAST forced run. This accounts for the validation-only claim boundary in release readiness while still leaving nonlinear publication claims blocked pending production evidence. `mhx validate paper-pipeline` wraps that suite, the readiness report, and a top-level recursive artifact manifest into the bundle documented in [paper_pipeline.md](paper_pipeline.md). The equation-heavy physics gates and still figures are on [validation.md](validation.md). Campaign scaffolds and restartable execution are documented in [campaigns.md](campaigns.md) and [campaign_runner.md](campaign_runner.md). Neural-ODE baseline comparison and fitted latent-ODE outputs are documented in [neural_ode_reproducibility.md](neural_ode_reproducibility.md). ## Orszag--Tang nonlinear vortex example ```bash mhx benchmark orszag-tang \ --outdir outputs/benchmarks/orszag_tang_vortex \ --nx 64 --ny 64 --t-end 6 --save-every 40 --movies ``` Expected files include: - `manifest.json` - `diagnostics.json` - `validation.json` - `orszag_tang_vortex.npz` - `figures/orszag_tang_summary.png` - `figures/orszag_tang_flux.gif` - `figures/orszag_tang_current.gif` - `figures/orszag_tang_vorticity.gif` This is an incompressible reduced-MHD adaptation of the [Orszag--Tang 1979](https://doi.org/10.1017/S002211207900210X) vortex. It is intended as a nonlinear morphology, energy-decay, divergence, and high-$k$ cascade gate, not as a compressible full-MHD shock benchmark. ## Decaying turbulence and forced turbulent reconnection ```bash mhx benchmark decaying-turbulence \ --outdir outputs/benchmarks/decaying_mhd_turbulence \ --nx 64 --ny 64 --t-end 8 --save-every 20 --movies mhx benchmark forced-turbulent-reconnection \ --outdir outputs/benchmarks/forced_turbulent_reconnection \ --nx 64 --ny 64 --t-end 80 --save-every 100 --movies ``` The decaying case starts from a deterministic band-limited reduced-MHD state and gates finite fields, dissipative total energy, current-density growth, and high-wavenumber transfer. The forced case adds a periodic current sheet, broadband perturbations, weak large-scale vorticity forcing, an X/O-aware reconnection proxy when critical points are found, and a conservative fallback proxy when they are not. Expected files include: - `diagnostics.json` - `validation.json` - `decaying_mhd_turbulence.npz` or `forced_turbulent_reconnection.npz` - `figures/decaying_mhd_turbulence_summary.png` or `figures/forced_turbulent_reconnection_summary.png` - optional `figures/*_flux.gif` and `figures/*_current.gif` with `--movies` These examples are anchored to 2-D MHD turbulence/current-sheet studies and turbulent reconnection ideas, but they remain validation media. They do not claim 3-D Lazarian--Vishniac fast reconnection or converged turbulence statistics. ## Exact-decay validation benchmark The first physics-gated numerical validation is a single Fourier mode in the resistive induction limit: ```bash mhx benchmark decay --outdir outputs/benchmarks/resistive_decay ``` This checks the literature-standard diffusion law $\psi_k(t)=\psi_k(0)\exp(-\eta |k|^2t)$ and $E_B(t)=E_B(0)\exp(-2\eta |k|^2t)$. It writes: - `diagnostics.json` - `validation.json` - `decay_history.npz` - `figures/decay_amplitude.png` - `figures/decay_energy.png` - `figures/decay_relative_error.png` The same benchmark is documented with figures on the [validation page](validation.md). ## Reconnection and linear-operator gates The benchmark roadmap includes analytic power-law gates for expected FKR, Sweet-Parker plasmoid, and ideal-tearing exponents plus linear operator and direct eigenvalue gates: ```bash mhx benchmark scaling --outdir outputs/benchmarks/reconnection_scaling mhx benchmark fkr-window --outdir outputs/benchmarks/fkr_window mhx benchmark fkr-growth --outdir outputs/benchmarks/fkr_growth_rate mhx benchmark harris-delta-prime --outdir outputs/benchmarks/harris_delta_prime mhx benchmark linear-tearing-eigenvalue --outdir outputs/benchmarks/linear_tearing_eigenvalue mhx benchmark linear-tearing-dispersion --outdir outputs/benchmarks/linear_tearing_dispersion mhx benchmark linear-tearing-layer --outdir outputs/benchmarks/linear_tearing_layer mhx benchmark linear-tearing-timedomain --outdir outputs/benchmarks/linear_tearing_timedomain mhx benchmark linearized-rhs --outdir outputs/benchmarks/linearized_rhs mhx benchmark reduced-mhd-eigenmode --outdir outputs/benchmarks/reduced_mhd_eigenmode mhx benchmark cosine-equilibrium-linearization --outdir outputs/benchmarks/cosine_equilibrium_linearization mhx benchmark current-sheet-eigenvalue --outdir outputs/benchmarks/periodic_current_sheet_eigenvalue mhx benchmark current-sheet-timedomain --outdir outputs/benchmarks/periodic_current_sheet_timedomain mhx benchmark current-sheet-nonlinear-bridge --outdir outputs/benchmarks/periodic_current_sheet_nonlinear_bridge mhx benchmark double-harris-growth --outdir outputs/benchmarks/periodic_double_harris_nonlinear_growth mhx benchmark double-harris-long-run --outdir outputs/benchmarks/periodic_double_harris_seeded_long_run mhx benchmark double-harris-convergence --outdir outputs/benchmarks/periodic_double_harris_convergence mhx benchmark nonlinear-energy-budget --outdir outputs/benchmarks/nonlinear_energy_budget mhx benchmark nonlinear-duration-audit --outdir outputs/benchmarks/nonlinear_duration_audit mhx benchmark duration-policy --outdir outputs/benchmarks/duration_policy mhx benchmark diffusion-eigenvalue --outdir outputs/benchmarks/diffusion_eigenvalue mhx benchmark power-iteration --outdir outputs/benchmarks/power_iteration mhx benchmark arnoldi --outdir outputs/benchmarks/arnoldi mhx benchmark catalog --outdir outputs/benchmarks/catalog ``` This writes: - `diagnostics.json` - `validation.json` - `scaling_history.npz` - `figures/fkr_scaling.png` - `figures/plasmoid_scaling.png` - `figures/ideal_tearing_scaling.png` The FKR-window command writes: - `diagnostics.json` - `validation.json` - `fkr_window.npz` - `figures/fkr_constant_psi_window.png` The FKR growth-rate command writes: - `diagnostics.json` - `validation.json` - `fkr_growth_rate.npz` - `figures/fkr_growth_rate.png` The Harris Delta-prime command writes: - `diagnostics.json` - `validation.json` - `harris_delta_prime.npz` - `figures/harris_delta_prime.png` The direct Harris-sheet tearing eigenvalue command writes: - `diagnostics.json` - `validation.json` - `linear_tearing_eigenvalue.npz` - `figures/linear_tearing_eigenvalue.png` The finite-domain tearing dispersion command writes: - `diagnostics.json` - `validation.json` - `linear_tearing_dispersion.npz` - `figures/linear_tearing_dispersion.png` The Harris eigenfunction-layer command writes: - `diagnostics.json` - `validation.json` - `linear_tearing_layer.npz` - `figures/linear_tearing_layer.png` The time-domain Harris eigenmode replay command writes: - `diagnostics.json` - `validation.json` - `linear_tearing_timedomain.npz` - `figures/linear_tearing_timedomain.png` The linearized-RHS command writes: - `diagnostics.json` - `validation.json` - `linearized_rhs.npz` - `figures/linearized_rhs_errors.png` The reduced-MHD eigenmode command writes: - `diagnostics.json` - `validation.json` - `reduced_mhd_linear_eigenmode.npz` - `figures/reduced_mhd_linear_eigenmode_errors.png` The cosine-equilibrium linearization command writes: - `diagnostics.json` - `validation.json` - `cosine_equilibrium_linearization.npz` - `figures/cosine_equilibrium_linearization_errors.png` The periodic current-sheet eigenvalue command writes: - `diagnostics.json` - `validation.json` - `periodic_current_sheet_eigenvalue.npz` - `figures/periodic_current_sheet_spectrum.png` The periodic current-sheet time-domain replay command writes: - `diagnostics.json` - `validation.json` - `periodic_current_sheet_timedomain.npz` - `figures/periodic_current_sheet_timedomain.png` The nonlinear current-sheet differentiability bridge command writes: - `diagnostics.json` - `validation.json` - `periodic_current_sheet_nonlinear_bridge.npz` - `figures/periodic_current_sheet_nonlinear_bridge.png` The periodic double-Harris nonlinear-growth command writes: - `diagnostics.json` - `validation.json` - `periodic_double_harris_nonlinear_growth.npz` - `figures/periodic_double_harris_nonlinear_growth.png` The periodic double-Harris seeded long-run command writes: - `diagnostics.json` - `validation.json` - `periodic_double_harris_seeded_long_run.npz`, including `reconnected_flux`, `seed_mode_reconnected_flux`, `rutherford_island_width`, dominant low-mode indices, X/O counts, energies, and saved base/seeded fields - `figures/periodic_double_harris_seeded_long_run.png` - optional `figures/periodic_double_harris_flux.gif` and `figures/periodic_double_harris_current.gif` with `--movies` The periodic double-Harris convergence command writes: - `diagnostics.json` - `validation.json` - `periodic_double_harris_convergence.npz` - `figures/periodic_double_harris_convergence.png` The periodic double-Harris parameter-sweep command writes: - `diagnostics.json` - `validation.json` - `periodic_double_harris_parameter_sweep.npz` - `figures/periodic_double_harris_parameter_sweep.png` The periodic double-Harris promotion checker writes: - `promotion_readiness.json` - `validation.json` - `figures/promotion_matrix.png` - `manifest.json` and `artifact_manifest.json` The nonlinear energy-budget command writes: - `diagnostics.json` - `validation.json` - `nonlinear_energy_budget.npz` - `figures/nonlinear_energy_budget.png` The nonlinear duration-audit command writes: - `diagnostics.json` - `validation.json` - `nonlinear_duration_audit.npz` - `figures/nonlinear_duration_audit.png` The duration-policy command writes: - `duration_policy.json` - `duration_policy.md` - `validation.json` - `manifest.json` The diffusion-eigenvalue command writes: - `diagnostics.json` - `validation.json` - `diffusion_eigenvalue.npz` - `figures/diffusion_eigenvalue_errors.png` The power-iteration command writes: - `diagnostics.json` - `validation.json` - `power_iteration_history.npz` - `figures/power_iteration_history.png` The Arnoldi command writes: - `diagnostics.json` - `validation.json` - `arnoldi_spectrum.npz` - `figures/arnoldi_ritz_values.png` The catalog command writes: - `benchmark_catalog.json` - `benchmark_catalog.md` - `manifest.json` ## CI artifacts Every push runs a `benchmark-artifacts` CI job. It executes deterministic FAST pipelines: ```bash mhx benchmark run --config examples/linear_tearing.toml --outdir outputs/ci/linear_tearing_fast --gif mhx benchmark validate outputs/ci/linear_tearing_fast mhx benchmark decay --outdir outputs/ci/resistive_decay mhx benchmark scaling --outdir outputs/ci/reconnection_scaling mhx benchmark fkr-window --outdir outputs/ci/fkr_window mhx benchmark fkr-growth --outdir outputs/ci/fkr_growth_rate mhx benchmark harris-delta-prime --outdir outputs/ci/harris_delta_prime mhx benchmark linear-tearing-eigenvalue --outdir outputs/ci/linear_tearing_eigenvalue mhx benchmark linear-tearing-dispersion --outdir outputs/ci/linear_tearing_dispersion mhx benchmark linear-tearing-layer --outdir outputs/ci/linear_tearing_layer mhx benchmark linear-tearing-timedomain --outdir outputs/ci/linear_tearing_timedomain mhx benchmark linearized-rhs --outdir outputs/ci/linearized_rhs mhx benchmark reduced-mhd-eigenmode --outdir outputs/ci/reduced_mhd_eigenmode mhx benchmark cosine-equilibrium-linearization --outdir outputs/ci/cosine_equilibrium_linearization mhx benchmark current-sheet-eigenvalue --outdir outputs/ci/periodic_current_sheet_eigenvalue mhx benchmark current-sheet-timedomain --outdir outputs/ci/periodic_current_sheet_timedomain mhx benchmark current-sheet-nonlinear-bridge --outdir outputs/ci/periodic_current_sheet_nonlinear_bridge mhx benchmark double-harris-growth --outdir outputs/ci/periodic_double_harris_nonlinear_growth mhx benchmark double-harris-convergence --outdir outputs/ci/periodic_double_harris_convergence mhx benchmark nonlinear-energy-budget --outdir outputs/ci/nonlinear_energy_budget mhx benchmark orszag-tang --outdir outputs/ci/orszag_tang_vortex mhx benchmark decaying-turbulence --outdir outputs/ci/decaying_mhd_turbulence mhx benchmark forced-turbulent-reconnection --outdir outputs/ci/forced_turbulent_reconnection mhx benchmark forced-turbulent-reconnection-readiness-check outputs/ci/forced_turbulent_reconnection mhx benchmark nonlinear-duration-audit --outdir outputs/ci/nonlinear_duration_audit mhx benchmark duration-policy --outdir outputs/ci/duration_policy mhx benchmark diffusion-eigenvalue --outdir outputs/ci/diffusion_eigenvalue mhx benchmark power-iteration --outdir outputs/ci/power_iteration mhx benchmark arnoldi --outdir outputs/ci/arnoldi mhx benchmark timing --outdir outputs/ci/timing --repeats 1 --warmups 0 mhx benchmark catalog --outdir outputs/ci/catalog mhx benchmark seed-robust-qi --outdir outputs/ci/seed_robust_qi mhx benchmark seed-robust-qi-sweep --outdir outputs/ci/seed_robust_qi_sweep mhx neural-ode dataset --outdir outputs/ci/neural_ode_dataset mhx neural-ode train --outdir outputs/ci/neural_ode_latent_fit mhx campaign rutherford-plan-production --outdir outputs/ci/rutherford_plan mhx campaign rutherford-execute outputs/ci/rutherford_plan --max-steps 4 mhx validate all --outdir outputs/ci/validation_suite mhx validate readiness --suite outputs/ci/validation_suite --outdir outputs/ci/readiness python examples/make_readme_media.py mhx run examples/linear_tearing_twofluid_toy.toml --outdir outputs/ci/twofluid_toy mhx figures outputs/ci/twofluid_toy --gif mhx report outputs/ci/twofluid_toy mhx run examples/linear_tearing_plugin_demo.toml --outdir outputs/ci/plugin_demo mhx figures outputs/ci/plugin_demo --gif mhx report outputs/ci/plugin_demo mhx artifact-manifest outputs/ci ``` The job uploads `outputs/ci` as the `mhx-fast-artifacts` GitHub Actions artifact. Readers can download it to inspect manifests, reports, PNG figures, GIF movies, and `artifact_manifest.json` checksums generated from the exact commit under test. The catalog file `outputs/ci/catalog/benchmark_catalog.md` gives readers a single table of active FAST gates, schemas, commands, and expected artifacts. For a single pass/fail evidence bundle, run: ```bash mhx validate all --outdir outputs/validation_suite ``` This command executes the active deterministic FAST validation gates and writes: - `outputs/validation_suite/validation_suite.json` - `outputs/validation_suite/validation_suite.md` - `outputs/validation_suite/artifact_manifest.json` - one subdirectory per validation case, each with its own `validation.json` and `manifest.json`. ## FAST timing benchmark MHX records performance as an artifact, not as a brittle absolute CI gate: ```bash mhx benchmark timing --outdir outputs/benchmarks/timing --repeats 3 --warmups 1 ``` This measures wall-clock time and Python allocation peaks for: - `linear_tearing_fast`: the active reduced-MHD smoke run. - `resistive_decay_fast`: the exact single-mode resistive validation case. - `reconnection_scaling`: analytic FKR/plasmoid/ideal-tearing scaling gates. The command writes: - `timing.json` - `timing.md` - `figures/timing_summary.png` - `manifest.json` The CI job uses `--repeats 1 --warmups 0` to keep runtime low and uploads the result in `outputs/ci/timing/`. Timing comparisons should be made between artifacts from the same runner class; MHX does not currently fail CI on absolute speed. ## Theory scaffolds MHX includes analytic scaling estimates for benchmark planning and reports. They are not replacements for calibrated eigenvalue calculations. For the constant-$\psi$ Furth-Killeen-Rosenbluth tearing regime, MHX uses the Harris-sheet outer-region proxy $$ \Delta' a = 2\left[(ka)^{-1} - ka\right], $$ and the order-unity-coefficient-free scaling $$ \gamma \tau_a \sim S_a^{-3/5}(ka)^{2/5}(\Delta'a)^{4/5}. $$ For Sweet-Parker plasmoid estimates, MHX includes the Loureiro scaling $$ \gamma_{\max}\tau_A \sim S^{1/4}, \qquad k_{\max}L \sim S^{3/8}. $$ For ideal tearing planning, MHX includes the Pucci-Velli aspect-ratio scaling $$ a/L \sim S^{-1/3}. $$ The separate FKR-window gate checks the sampled constant-$\psi$ regime by plotting $\gamma\tau_a$ and $\Delta'\delta$ versus $ka$ at fixed $S_a$. This prevents future numerical tearing comparisons from silently mixing FKR and large-$\Delta'$ Coppi regimes. The Harris Delta-prime gate numerically integrates the ideal outer tearing equation for a Harris sheet and recovers $\Delta'a=2[(ka)^{-1}-ka]$. It validates the outer-region target but still does not solve the resistive FKR inner-layer eigenvalue problem. The direct Harris-sheet tearing eigenvalue gate solves a finite-difference linear reduced-MHD eigenproblem for $S=1000$, $ka=0.5$, and $d/a=10$. It checks the unstable tearing eigenvalue against a published growth rate $\gamma\simeq0.0131$, verifies grid extrapolation in $\Delta x^2$, checks the dense eigenpair residual, confirms tearing parity, and verifies a stable $ka=1.2$ control has no positive-growth eigenvalue. This is a single reference eigenproblem, not yet a full FKR/Coppi dispersion scan. The finite-domain tearing dispersion gate repeats the same eigenproblem over a small $ka$ scan, verifies positive growth for sampled $0