tutorial.md

Tutorial: from first run to validation media

This tutorial keeps the first-pass path short while pointing to the evidence pages that carry the full reviewer context.

1. Create and run a config

mhx init outputs/tutorial/linear_tearing.toml
mhx run outputs/tutorial/linear_tearing.toml --outdir outputs/tutorial/smoke
mhx figures outputs/tutorial/smoke --gif
mhx report outputs/tutorial/smoke
mhx artifact-manifest outputs/tutorial/smoke

Expected outputs:

• outputs/tutorial/smoke/config_effective.json
• outputs/tutorial/smoke/diagnostics.json
• outputs/tutorial/smoke/trajectory.npz
• outputs/tutorial/smoke/figures/flux_movie.gif
• outputs/tutorial/smoke/report.md
• outputs/tutorial/smoke/artifact_manifest.json

2. Run a physics gate

mhx benchmark decay --outdir outputs/tutorial/resistive_decay

This checks the exact reduced-MHD induction limit $\psi_k(t)=\psi_k(0)\exp(-\eta k^2t)$ and writes the amplitude, energy, and relative-error plots documented on validation.md.

3. Generate nonlinear validation media

mhx benchmark orszag-tang --outdir outputs/tutorial/orszag_tang --nx 64 --ny 64 --t-end 6 --movies
mhx benchmark decaying-turbulence --outdir outputs/tutorial/decaying_turbulence --nx 64 --ny 64 --t-end 8 --movies
mhx benchmark forced-turbulent-reconnection --outdir outputs/tutorial/forced_reconnection --nx 64 --ny 64 --t-end 80 --save-every 100 --movies

These are claim_level = "validation" artifacts. They are good for learning the API, diagnostics, and plotting workflow; they are not production plasmoid or turbulence-statistics results.

4. Inspect extension points

mhx physics list
mhx diagnostics list
mhx run examples/linear_tearing_plugin_demo.toml --outdir outputs/tutorial/plugin_demo
mhx report outputs/tutorial/plugin_demo

The plugin demo shows how to register a local RHS term and diagnostic without editing MHX source. See plugins.md for the external package template and testing checklist.