Model assembly

MHX run configs assemble a reduced-MHD model from explicit, auditable pieces:

  1. mesh and time controls;

  2. an equilibrium builder;

  3. base resistive-viscous reduced-MHD coefficients;

  4. optional RHS physics terms;

  5. diagnostic definitions.

The current active model is reduced_mhd_linear_tearing. It evolves

\[ \partial_t \psi = -[\phi,\psi] + \eta\nabla^2\psi + S_\psi, \]
\[ \partial_t \omega = -[\phi,\omega] + [\psi,\nabla^2\psi] + \nu\nabla^2\omega + S_\omega, \]

with \(\nabla^2\phi=\omega\). The optional source terms \((S_\psi,S_\omega)\) are the sum of configured physics plugins.

TOML structure

[physics]
model = "reduced_mhd_linear_tearing"
equilibrium = "cosine_tearing"
resistivity = 0.001
viscosity = 0.001
plugin_modules = []
plugin_entry_point_groups = []
rhs_terms = ["hyper_resistivity", "vorticity_drag"]

[physics.equilibrium_parameters]
perturbation_amplitude = 0.001

[physics.term_parameters.hyper_resistivity]
eta4 = 1e-5
nu4 = 1e-5

[physics.term_parameters.vorticity_drag]
rate = 0.01

This is intentionally explicit. Saved run directories include config_effective.json, diagnostics.json, and manifest.json, so a figure or benchmark report can be traced back to the exact assembled model.

Diagnostics are assembled the same way:

[diagnostics]
quantities = ["energy", "mode_growth", "divergence_error"]
plugin_modules = []
plugin_entry_point_groups = []
mode = [1, 1]
fit_time_window = [0.02, 0.1]

Use mhx diagnostics list to inspect names and output keys. The built-in registry is documented in Diagnostics registry.

plugin_modules accepts importable Python modules exposing register_physics(registry) or register_diagnostics(registry). The demo examples/linear_tearing_plugin_demo.toml shows a local physics term and a local diagnostic assembled entirely from TOML.

plugin_entry_point_groups accepts installed Python package entry-point groups, usually mhx.physics and mhx.diagnostics. This is the reviewer-facing path for third-party plugins because the run manifest records the exact discovery groups in addition to the selected term and diagnostic names.

Built-in equilibria

Use mhx physics equilibria to inspect available equilibria.

cosine_tearing initializes a periodic tearing smoke problem:

\[ \psi(x,y,0)=\cos(y)+\epsilon\cos(x)\cos(y), \qquad \omega(x,y,0)=0. \]

zero initializes \(\psi=\omega=0\) and is primarily for plugin tests and IO validation.

Built-in RHS terms

Use mhx physics list to inspect available terms and mhx physics lint <name> to validate a registered term against the active API.

The current built-ins are:

  • hyper_resistivity: fourth-order damping of \(\psi\) and \(\omega\).

  • vorticity_drag: linear damping of \(\omega\).

  • electron_pressure_tensor: anisotropic current-smoothing closure motivated by the pressure-divergence term in generalized Ohm’s law.

  • toy_hall_ohm: reduced-state Hall-like bracket for exercising two-fluid plugin wiring.

These are deliberately simple terms. They test the extension path without claiming validated Hall, anisotropic-pressure, or two-fluid reconnection physics. The pressure-tensor and Hall examples are useful templates for API extension, but reviewer-facing physics claims require additional evolved fields and validation against Hall/two-fluid benchmarks.

Reproducible command

mhx run examples/linear_tearing_hyper.toml --outdir outputs/linear_tearing_hyper
mhx figures outputs/linear_tearing_hyper --gif
mhx report outputs/linear_tearing_hyper

Expected model-audit fields in outputs/linear_tearing_hyper/diagnostics.json include equilibrium, equilibrium_parameters, and physics_terms.