Skip to content
uwplasmaPublic

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

MHX

CI Coverage Documentation

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.

Double-Harris reconnection: residual flux with flux contours and X/O markers

First run

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.py

The 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.

Example gallery

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
Double-Harris current sheet Decaying reduced-MHD turbulence Orszag-Tang current density

These images show bounded validation runs. The gallery plays them as movies, and the media inventory records their settings and claim limits.

Physics and numerics

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.

Parallel runs

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.py

Strong-scaling measurements

The 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.

Documentation

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.

Development

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/html

Use the release tag or commit SHA when you cite a run. Provisional citation metadata is in CITATION.cff.

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages