MHX runs differentiable, two-dimensional reduced-MHD models in JAX. It builds the plasma equations and diagnostics. SOLVAX contains the linear, Krylov, and nonlinear solvers.
Use MHX to study periodic current sheets, tearing modes, reconnection, and reduced-MHD turbulence. MHX does not solve the full three-dimensional MHD equations.
Install the current source:
git clone https://github.com/uwplasma/MHX.git
cd MHX
python -m venv .venv
source .venv/bin/activate
python -m pip install .Create reconnection.py:
from pathlib import Path
import mhx
output = Path("outputs/reconnection")
simulation = mhx.Simulation(
shape=(64, 64),
equilibrium=mhx.PeriodicDoubleHarrisEquilibrium(
width=0.4,
perturbation_amplitude=4.0e-3,
perturbation_mode=(2, 1),
),
resistivity=5.0e-3,
viscosity=5.0e-3,
dt=2.0e-2,
t_end=40.0,
save_every=100,
)
result = simulation.run()
result.print_summary()
result.plot(output / "summary.png")
result.save(output)Run it:
python reconnection.pyThe run takes seconds on a laptop CPU. MHX prints the grid, physics settings, device count, compile time, run time, energy, and divergence error. The summary figure includes the island flux, the view that shows the growing tearing mode. The saved NPZ file holds the full field history.
The documentation walks through every step: run your first model, then make your first movie.
The scripts in examples/gallery/ use the same
structure as the first run. Edit the settings at the top of a script, then
run it from the repository root.
| Script | Purpose |
|---|---|
01_reconnection.py |
Seed and evolve a periodic double-Harris current sheet. |
02_tearing_mode.py |
Evolve a perturbed cosine current sheet. |
03_implicit_step.py |
Use backward Euler with SOLVAX Newton--Krylov solves. |
04_cpu_parallel.py |
Split one field across four local CPU devices. |
05_gpu_parallel.py |
Split one field across all visible GPUs. |
06_strong_scaling.py |
Strong-scale one fixed reconnection ensemble. |
07_multi_process.py |
Run one ensemble across JAX processes. |
08_gradient.py |
Differentiate a solve and check the gradient numerically. |
| Reconnection | Turbulence | Orszag--Tang |
|---|---|---|
![]() |
![]() |
![]() |
These images show bounded validation runs. The gallery plays them as movies, and the media inventory records their settings and claim limits.
MHX owns quantities that depend on the model:
- reduced-MHD states and equations
- periodic equilibria and source terms
- Fourier spatial operators
- plasma diagnostics and validation cases
SOLVAX owns general numerical algebra:
- matrix-free operators
- GMRES and recycled Krylov methods
- Newton--Krylov root solves
- preconditioners and implicit differentiation
The documentation states the equations and their derivation, the spectral method, and what differentiates.
Set device_count to shard one large field, or run independent cases as an
ensemble. Ensembles avoid communication inside the time loop, so prefer them
for scans and seed studies.
python examples/gallery/04_cpu_parallel.py
JAX_PLATFORM_NAME=gpu python examples/gallery/05_gpu_parallel.pyThe measured speedup is 2.38x on four logical CPU devices and 1.95x on two PCIe-connected RTX A4000 GPUs, for four fixed reconnection cases. The device guide and performance page hold the settings and data.
| Need | Read |
|---|---|
| Install and first steps | Get started |
| Equations and derivation | docs/physics/reduced_mhd.md |
| Gradients | docs/physics/differentiability.md |
| Validation gates and limits | docs/validation/index.md |
| TOML configuration | docs/reference/config_schema.md |
| Output files | docs/reference/output_schema.md |
| Movie gallery | docs/gallery.md |
The benchmark and campaign tools remain available for validation and long
production runs. Run mhx --help to list them.
Install the repository tools, then run the checks:
python -m pip install -e ".[dev]"
python -m ruff check src tests examples tools
python tools/check_prose.py
python -m pytest
sphinx-build -W -b html docs docs/_build/htmlUse the release tag or commit SHA when you cite a run. Provisional citation
metadata is in CITATION.cff.




