MHX

MHX is a JAX-native, differentiable plasma and magnetohydrodynamics toolkit for magnetic reconnection, tearing-mode studies, reduced-MHD experiments, and future inverse-design workflows.

The active Python package lives under src/mhx/ and exposes command-line tools, benchmark runners, plotting utilities, artifact manifests, and a small public API for reproducible reduced-MHD studies.

MHD at a Glance

These previews keep the README visual and short. The first row shows residual double-Harris reconnecting fields, a forced turbulent current-sheet replay with magnetic-flux (Az/ψ) contours, and Orszag--Tang current sheets; the second row shows nonlinear reduced-MHD turbulence, Orszag--Tang roll-up, and a Harris tearing layer sweep. See docs/media.md for source commands, visual QA, and claim boundaries.

Residual double-Harris reconnection	Forced turbulent-reconnection proxy	Orszag--Tang current sheets
Single-sheet zoom from a 128×128, t=160 GPU validation bundle: residual reconnecting flux Δψ with total Az contours and diagnostic X/O markers; not separatrix-event, Rutherford, or plasmoid-production evidence.	64×64, t=80 forced-turbulence current sheet with reconnection-rate proxy diagnostics.	Solver-generated Orszag--Tang current-density morphology and high-$k$ transfer over a 96×96, t=10 validation run.

Decaying MHD turbulence	Orszag--Tang vorticity	Harris tearing layer
Solver-generated 64×64, t=8 decaying reduced-MHD turbulence with current filaments.	Vorticity roll-up and filamentation from the same nonlinear Orszag--Tang run.	Literature-anchored Harris eigenfunction localization sweep.

What Works Today

MHX currently supports deterministic reduced-MHD validation for spectral operators, resistive decay, finite-domain Harris tearing checks, nonlinear energy/dissipation budgets, Orszag--Tang vortex media, forced turbulent-reconnection readiness checks, bounded double-Harris promotion and convergence evidence, Rutherford execution-path checks, and seed-robust QI plus latent-ODE workflow tests on small datasets.

Current results should be read at their manifest claim level. MHX does not yet claim converged Rutherford island growth, Sweet-Parker plasmoid chains, calibrated production surrogates, turbulence statistics, or inverse-design results.

Install

git clone https://github.com/uwplasma/MHX.git
cd MHX
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,docs]"
mhx version

JAX accelerator wheels are platform-specific. For GPU/TPU installs, follow the official JAX instructions first, then install MHX.

Quickstart

Run a deterministic reduced-MHD smoke workflow:

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

Check the public API contract:

mhx api status
MHX_API_VERSION=v1 mhx api status --json

Use MHX from Python:

import mhx

manifest = mhx.run("examples/linear_tearing.toml", outdir="outputs/python_api")
cfg = mhx.load_config("examples/linear_tearing.toml")
print(manifest, cfg.physics.model)

Documentation

Need	Start here
First run and plugin demo	docs/quickstart.md
Installation and environments	docs/install.md
Guided tutorial	docs/tutorial.md
Media sources and claim boundaries	docs/media.md
Physics validation details	docs/validation.md
Reviewer evidence and claim boundaries	docs/reviewer_evidence.md, docs/publication_checklist.md
Benchmark commands and expected artifacts	docs/benchmarks.md
Diagnostics and output schemas	docs/diagnostics.md, docs/output_schema.md
Neural-ODE reproducibility	docs/neural_ode_reproducibility.md
Performance and timing	docs/performance.md
Long-run duration evidence	docs/long_run_evidence.md
Campaign planning and execution	docs/campaign_runner.md
API compatibility policy	docs/api_policy.md

Common entry points:

mhx validate all --outdir outputs/validation_suite
mhx benchmark catalog --outdir outputs/benchmarks/catalog
mhx benchmark double-harris-promotion-check \
  outputs/benchmarks/periodic_double_harris_seeded_long_run \
  --convergence-dir outputs/benchmarks/periodic_double_harris_convergence
mhx benchmark forced-turbulent-reconnection-readiness-check \
  outputs/benchmarks/forced_turbulent_reconnection
mhx campaign rutherford-plan-production --outdir outputs/campaigns/rutherford_production_plan
# Run restartable chunks until the target completes; then attach convergence and seed-QI evidence:
mhx campaign rutherford-execute outputs/campaigns/rutherford_production_plan --movies
mhx campaign rutherford-promotion-check outputs/campaigns/rutherford_production_plan
mhx validate readiness --suite outputs/validation_suite --outdir outputs/validation_readiness
mhx validate release-candidate --outdir outputs/release_candidate
mhx api deprecations
mhx physics list
mhx diagnostics list

Citation

Until a DOI is minted, cite the repository URL plus release tag or commit SHA, or use the provisional metadata in CITATION.cff.