Quickstart

Install the active package in editable mode:

python -m pip install -e ".[dev,docs]"

Check the installed version:

mhx version

Run the first deterministic smoke workflow:

mhx run examples/linear_tearing.toml --outdir outputs/smoke

Inspect the registered model pieces used by TOML configs:

mhx physics equilibria
mhx physics list
mhx diagnostics list

The command writes:

• config_effective.json

• diagnostics.json

• manifest.json

• trajectory.npz

Regenerate figures from the saved run:

mhx figures outputs/smoke --gif

Expected figures:

• outputs/smoke/figures/energy_history.png

• outputs/smoke/figures/flux_final.png

• outputs/smoke/figures/mode_amplitude.png

• outputs/smoke/figures/flux_movie.gif

Create a reviewer-readable summary:

mhx report outputs/smoke
mhx artifact-manifest outputs/smoke

Run the same workflow through the benchmark command group:

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 linearized-rhs --outdir outputs/benchmarks/linearized_rhs
mhx benchmark reduced-mhd-eigenmode --outdir outputs/benchmarks/reduced_mhd_eigenmode
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

The smoke run validates the JAX spectral derivative path on a periodic Cartesian mesh. The exact-decay benchmark adds a physics gate for \(\psi_k(t)=\psi_k(0)\exp(-\eta |k|^2t)\). These are deliberately small and deterministic; they are not yet the full tearing benchmark. The timing benchmark records wall-clock and Python-allocation summaries for comparing changes on the same machine or CI runner.

Run a nonlinear reduced-MHD Orszag–Tang example with movies:

mhx benchmark orszag-tang --outdir outputs/examples/orszag_tang --nx 64 --ny 64 --t-end 6 --movies
# equivalent thin Python wrapper
python examples/run_orszag_tang.py --outdir outputs/examples/orszag_tang_script --nx 64 --ny 64 --t-end 6

The command writes figures/orszag_tang_current.gif, figures/orszag_tang_vorticity.gif, figures/orszag_tang_flux.gif, and a summary figure with energy and high-wavenumber diagnostics.

Run the turbulence and forced-reconnection validation media used by the README:

mhx benchmark decaying-turbulence \
  --outdir outputs/examples/decaying_mhd_turbulence \
  --nx 64 --ny 64 --t-end 8 --save-every 20 --movies

mhx benchmark forced-turbulent-reconnection \
  --outdir outputs/examples/forced_turbulent_reconnection \
  --nx 64 --ny 64 --t-end 80 --save-every 100 --movies

These commands write diagnostics.json, validation.json, an NPZ history, summary PNGs, optional GIFs, and a manifest.json with claim_level = "validation".

Try a local extension module without editing MHX source:

mhx run examples/linear_tearing_plugin_demo.toml --outdir outputs/plugin_demo
mhx figures outputs/plugin_demo --gif
mhx report outputs/plugin_demo
mhx physics list-with-plugins --plugin-module examples.local_extension_plugin
mhx diagnostics list-with-plugins --plugin-module examples.local_extension_plugin
mhx physics lint example_flux_drive --plugin-module examples.local_extension_plugin
mhx diagnostics lint final_flux_l2 --plugin-module examples.local_extension_plugin

This demo registers a toy flux-drive physics term and a final_flux_l2 diagnostic from examples/local_extension_plugin.py. Installed plugin packages use the same registries through --entry-point-group mhx.physics and --entry-point-group mhx.diagnostics. The installable package skeleton in examples/plugin_template/ shows the recommended external-repository layout.