API reference

The stable public convenience API is intentionally small:

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)

Inspect CLI/API compatibility from the shell:

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

The detailed autogenerated API below is useful for extension authors and reviewers checking source-linked symbols.

Typed configuration objects and TOML loading.

class mhx.config.DiagnosticsConfig(quantities=('energy', 'mode_growth', 'divergence_error'), plugin_modules=(), plugin_entry_point_groups=(), mode=(1, 1), fit_time_window=None)

Diagnostics requested for a run.

Parameters:

  • quantities (tuple[str, ...])

  • plugin_modules (tuple[str, ...])

  • plugin_entry_point_groups (tuple[str, ...])

  • mode (tuple[int, int])

  • fit_time_window (tuple[float, float] | None)

class mhx.config.MeshConfig(shape=(32, 32), lower=(0.0, 0.0), upper=(6.283185307179586, 6.283185307179586), periodic=(True, True))

Uniform Cartesian mesh configuration.

Parameters:

  • shape (tuple[int, int])

  • lower (tuple[float, float])

  • upper (tuple[float, float])

  • periodic (tuple[bool, bool])

class mhx.config.NumericsConfig(method='spectral', enable_x64=True, enable_jit=True)

Numerical method switches.

Parameters:

  • method (str)

  • enable_x64 (bool)

  • enable_jit (bool)

class mhx.config.PhysicsConfig(model='reduced_mhd_linear_tearing', equilibrium='cosine_tearing', equilibrium_parameters=<factory>, resistivity=0.001, viscosity=0.001, plugin_modules=(), plugin_entry_point_groups=(), rhs_terms=(), term_parameters=<factory>)

Physics model parameters for early rebuild workflows.

Parameters:

  • model (str)

  • equilibrium (str)

  • equilibrium_parameters (dict[str, float])

  • resistivity (float)

  • viscosity (float)

  • plugin_modules (tuple[str, ...])

  • plugin_entry_point_groups (tuple[str, ...])

  • rhs_terms (tuple[str, ...])

  • term_parameters (dict[str, dict[str, float]])

class mhx.config.RunConfig(name='linear_tearing_smoke', output_dir=PosixPath('outputs/linear_tearing_smoke'), mesh=<factory>, time=<factory>, physics=<factory>, numerics=<factory>, diagnostics=<factory>)

Top-level MHX run configuration.

Parameters:
to_dict()

Serialize to JSON-compatible builtins.

Return type:

dict[str, Any]

to_toml()

Serialize a stable starter TOML representation.

Return type:

str

with_output_dir(output_dir)

Return a copy with a different output directory.

Return type:

RunConfig

Parameters:

output_dir (str | Path)

class mhx.config.TimeConfig(t0=0.0, t1=0.1, dt=0.01, save_every=1)

Time integration controls.

Parameters:

  • t0 (float)

  • t1 (float)

  • dt (float)

  • save_every (int)

mhx.config.load_config(path)

Load a TOML file into a RunConfig.

Return type:

RunConfig

Parameters:

path (str | Path)

Grid types.

class mhx.grids.CartesianGrid(shape, lower, upper, periodic=(True, True))

Uniform Cartesian grid with cell-centered coordinates.

Parameters:

  • shape (tuple[int, int])

  • lower (tuple[float, float])

  • upper (tuple[float, float])

  • periodic (tuple[bool, bool])

axes()

Return cell-centered coordinate axes.

Return type:

tuple[Array, Array]

property cell_volume: float

Cell area for the 2D grid.

cosinusoid(mode=(1, 1))

Return cos(kx x + ky y) on the grid.

Return type:

Array

Parameters:

mode (tuple[int, int])

classmethod from_mesh_config(config)

Build a grid from a mesh config.

Return type:

CartesianGrid

Parameters:

config (MeshConfig)

property lengths: tuple[float, float]

Domain lengths.

mesh()

Return cell-centered mesh arrays with matrix indexing.

Return type:

tuple[Array, Array]

property ndim: int

Number of spatial dimensions.

sinusoid(mode=(1, 1))

Return sin(kx x + ky y) on the grid.

Return type:

Array

Parameters:

mode (tuple[int, int])

property spacing: tuple[float, float]

Cell spacings.

Spectral numerical operators.

mhx.numerics.spectral.fft_derivative(field, *, axis, length, order=1)

Differentiate a periodic field along one axis using complex FFTs.

Return type:

Array

Parameters:

  • field (Array)

  • axis (int)

  • length (float)

  • order (int)

mhx.numerics.spectral.gradient(field, *, lengths)

Return the spectral gradient of a periodic field.

Return type:

tuple[Array, ...]

Parameters:

  • field (Array)

  • lengths (tuple[float, ...])

mhx.numerics.spectral.inverse_laplacian(field, *, lengths)

Invert the periodic Laplacian with the zero Fourier mode set to zero.

Return type:

Array

Parameters:

  • field (Array)

  • lengths (tuple[float, ...])

mhx.numerics.spectral.laplacian(field, *, lengths)

Return the spectral Laplacian of a periodic field.

Return type:

Array

Parameters:

  • field (Array)

  • lengths (tuple[float, ...])

mhx.numerics.spectral.spectral_wavenumbers(points, length)

Return angular FFT wavenumbers for a periodic axis.

Return type:

Array

Parameters:

  • points (int)

  • length (float)

Periodic pseudo-spectral reduced-MHD equations.

mhx.equations.reduced_mhd.current_density(psi, *, lengths)

Return j_z = -∇² ψ.

Return type:

Array

Parameters:

  • psi (Array)

  • lengths (tuple[float, float])

mhx.equations.reduced_mhd.finite_difference_linearized_reduced_mhd_rhs(state, perturbation, params, *, lengths, epsilon=0.0001, terms=())

Return a centered finite-difference approximation to the linearized RHS.

Return type:

ReducedMHDState

Parameters:

  • state (ReducedMHDState)

  • perturbation (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

  • epsilon (float)

  • terms (tuple[PhysicsTerm, ...])

mhx.equations.reduced_mhd.linearized_reduced_mhd_operator(state, params, *, lengths, terms=())

Return a flattened matrix-free linearized reduced-MHD operator.

Return type:

MatrixFreeOperator

Parameters:

  • state (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

  • terms (tuple[PhysicsTerm, ...])

mhx.equations.reduced_mhd.linearized_reduced_mhd_rhs(state, perturbation, params, *, lengths, terms=())

Return the matrix-free Jacobian-vector product of the reduced-MHD RHS.

This computes dF(state)[perturbation] with JAX forward-mode automatic differentiation, where F is reduced_mhd_rhs(). It is the first building block for eigenvalue and adjoint tearing-mode benchmarks.

Return type:

ReducedMHDState

Parameters:

  • state (ReducedMHDState)

  • perturbation (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

  • terms (tuple[PhysicsTerm, ...])

mhx.equations.reduced_mhd.poisson_bracket(a, b, *, lengths)

Return the 2D Poisson bracket [a,b] = a_x b_y - a_y b_x.

Return type:

Array

Parameters:

  • a (Array)

  • b (Array)

  • lengths (tuple[float, float])

mhx.equations.reduced_mhd.reduced_mhd_residual_norm(state)

Return a scalar finite-state sanity norm for debugging.

Return type:

Array

Parameters:

state (ReducedMHDState)

mhx.equations.reduced_mhd.reduced_mhd_rhs(state, params, *, lengths, terms=())

Return the resistive-viscous reduced-MHD right-hand side.

The convention is

ψ_t + [φ, ψ] = η ∇²ψ

ω_t + [φ, ω] = [ψ, ∇²ψ] + ν ∇²ω

with ∇²φ = ω on a periodic domain.

Return type:

ReducedMHDState

Parameters:

  • state (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

  • terms (tuple[PhysicsTerm, ...])

mhx.equations.reduced_mhd.stream_function(omega, *, lengths)

Solve ∇² φ = ω with zero mean.

Return type:

Array

Parameters:

  • omega (Array)

  • lengths (tuple[float, float])

Standardized diagnostics shared by MHX workflows.

class mhx.diagnostics.DiagnosticContext(trajectory, initial_state, lengths, mode, fit_time_window)

Inputs shared by reduced-MHD trajectory diagnostics.

Parameters:

  • trajectory (ReducedMHDTrajectory)

  • initial_state (ReducedMHDState)

  • lengths (tuple[float, float])

  • mode (tuple[int, int])

  • fit_time_window (tuple[float, float] | None)

class mhx.diagnostics.DiagnosticSpec(name, description, output_keys, compute, figure=None)

Metadata and callable for one named reduced-MHD diagnostic.

Parameters:

  • name (str)

  • description (str)

  • output_keys (tuple[str, ...])

  • compute (Callable[[DiagnosticContext], dict[str, Any]])

  • figure (Callable[[DiagnosticContext, dict[str, Any], Path], dict[str, str | Path]] | None)

class mhx.diagnostics.DiagnosticsRegistry

Registry for config-selectable reduced-MHD diagnostics.

compute(names, context)

Compute selected diagnostics and merge their output dictionaries.

Return type:

dict[str, Any]

Parameters:
get(name)

Return a diagnostic specification, raising a clear error if absent.

Return type:

DiagnosticSpec

Parameters:

name (str)

metadata()

Return JSON-compatible diagnostic metadata.

Return type:

tuple[dict[str, Any], ...]

names()

Return registered diagnostic names in deterministic order.

Return type:

tuple[str, ...]

register(spec)

Register a diagnostic specification by name.

Return type:

None

Parameters:

spec (DiagnosticSpec)

write_figures(names, context, diagnostics, figure_dir)

Write selected diagnostic figures and return paths by figure key.

Return type:

dict[str, Path]

Parameters:

  • names (tuple[str, ...])

  • context (DiagnosticContext)

  • diagnostics (dict[str, Any])

  • figure_dir (str | Path)

class mhx.diagnostics.FluxCriticalPoint(kind, index, position, psi, gradient_norm, hessian_determinant, hessian_trace, refined=False, newton_iterations=0, residual_norm=None)

One detected critical point of the magnetic flux function.

Parameters:

  • kind (str)

  • index (tuple[int, int])

  • position (tuple[float, float])

  • psi (float)

  • gradient_norm (float)

  • hessian_determinant (float)

  • hessian_trace (float)

  • refined (bool)

  • newton_iterations (int)

  • residual_norm (float | None)

mhx.diagnostics.compute_reduced_mhd_diagnostics(trajectory, *, initial_state, lengths, quantities, mode, fit_time_window, registry=None, plugin_modules=(), plugin_entry_point_groups=())

Compute selected reduced-MHD diagnostics through the registry API.

Return type:

dict[str, Any]

Parameters:

  • trajectory (ReducedMHDTrajectory)

  • initial_state (ReducedMHDState)

  • lengths (tuple[float, float])

  • quantities (tuple[str, ...])

  • mode (tuple[int, int])

  • fit_time_window (tuple[float, float] | None)

  • registry (DiagnosticsRegistry | None)

  • plugin_modules (tuple[str, ...])

  • plugin_entry_point_groups (tuple[str, ...])

mhx.diagnostics.critical_points_by_kind(points, kind)

Return detected critical points of one kind sorted by gradient norm.

Return type:

tuple[FluxCriticalPoint, ...]

Parameters:
mhx.diagnostics.default_diagnostics_registry()

Return the built-in reduced-MHD diagnostics registry.

Return type:

DiagnosticsRegistry

mhx.diagnostics.detect_flux_critical_points(psi, *, lengths=(6.283185307179586, 6.283185307179586), periodic=(True, True), max_points=16, min_separation=None, determinant_rtol=1e-08, refine=False, max_refinement_fraction=0.75)

Detect X/O points of a two-dimensional magnetic flux field.

The detector looks for local minima of |∇ψ| and classifies each candidate by the Hessian determinant: saddles are returned as "X" and elliptic extrema as "O". With refine=True, a local quadratic Newton correction estimates a sub-cell critical-point position.

Return type:

tuple[FluxCriticalPoint, ...]

Parameters:

  • psi (ndarray)

  • lengths (tuple[float, float])

  • periodic (tuple[bool, bool])

  • max_points (int)

  • min_separation (float | None)

  • determinant_rtol (float)

  • refine (bool)

  • max_refinement_fraction (float)

mhx.diagnostics.fit_exponential_growth(times, amplitudes)

Fit amplitude ≈ A exp(γ t) and return γ.

Return type:

Array

Parameters:

  • times (Array)

  • amplitudes (Array)

mhx.diagnostics.island_width_from_mode(state, *, mode, magnetic_shear)

Return the Rutherford full-width proxy from a saved Fourier mode.

Return type:

Array

Parameters:

  • state (ReducedMHDState)

  • mode (tuple[int, int])

  • magnetic_shear (float)

mhx.diagnostics.kinetic_energy(state, *, lengths)

Return mean kinetic energy 0.5 <|∇φ|²>.

Return type:

Array

Parameters:

  • state (ReducedMHDState)

  • lengths (tuple[float, float])

mhx.diagnostics.load_diagnostics_entry_points(registry, groups=('mhx.diagnostics',))

Load installed diagnostic plugins from Python package entry-point groups.

Each entry point must resolve either to a callable register(registry) hook or to an object exposing register_diagnostics(registry).

Return type:

DiagnosticsRegistry

Parameters:
mhx.diagnostics.load_diagnostics_plugin_modules(registry, module_names)

Load user diagnostics plugins exposing register_diagnostics(registry).

Return type:

DiagnosticsRegistry

Parameters:
mhx.diagnostics.magnetic_divergence_linf(state, *, lengths)

Return ||∇·B_\perp||_∞ for B_\perp=(∂_yψ,-∂_xψ).

Return type:

Array

Parameters:

  • state (ReducedMHDState)

  • lengths (tuple[float, float])

mhx.diagnostics.magnetic_energy(state, *, lengths)

Return mean magnetic perturbation energy 0.5 <|∇ψ|²>.

Return type:

Array

Parameters:

  • state (ReducedMHDState)

  • lengths (tuple[float, float])

mhx.diagnostics.mode_amplitude(state, *, mode)

Return the absolute normalized Fourier amplitude of psi for a mode.

Return type:

Array

Parameters:

  • state (ReducedMHDState)

  • mode (tuple[int, int])

mhx.diagnostics.reconnected_flux_amplitude(state, *, mode)

Return a real-harmonic reconnected-flux proxy for a Fourier mode.

mode_amplitude returns the normalized complex FFT coefficient |\hat\psi_k|. For a real field containing a single perturbation \psi_1 \cos(k\cdot x), the coefficient at +k is \psi_1/2. This helper therefore returns 2|\hat\psi_k| so that it recovers the physical cosine amplitude used in Rutherford island-width estimates.

Return type:

Array

Parameters:

  • state (ReducedMHDState)

  • mode (tuple[int, int])

mhx.diagnostics.rutherford_island_full_width(reconnected_flux, *, magnetic_shear)

Return the local Rutherford magnetic-island full width.

The local constant-shear estimate is

W = 4 sqrt(|\psi_1| / |B_y'(0)|),

where \psi_1 is the reconnecting flux perturbation at the resonant surface and B_y'(0) is the equilibrium reconnecting-field shear. The function is a diagnostic convention, not a substitute for resolving an island separatrix in a production nonlinear run.

Return type:

Array

Parameters:

  • reconnected_flux (float | Array)

  • magnetic_shear (float)

mhx.diagnostics.select_fit_window(times, amplitudes, *, window)

Select samples inside an inclusive fit-time window.

Return type:

tuple[Array, Array]

Parameters:

  • times (Array)

  • amplitudes (Array)

  • window (tuple[float, float] | None)

mhx.diagnostics.total_energy(state, *, lengths)

Return reduced-MHD magnetic plus kinetic energy.

Return type:

Array

Parameters:

  • state (ReducedMHDState)

  • lengths (tuple[float, float])

mhx.diagnostics.track_critical_points(frames, *, lengths=(6.283185307179586, 6.283185307179586), periodic=(True, True), max_link_distance=None)

Greedily associate critical points across frames by nearest neighbors.

Return type:

tuple[tuple[int, FluxCriticalPoint], ...]

Parameters:

  • frames (tuple[tuple[FluxCriticalPoint, ...], ...])

  • lengths (tuple[float, float])

  • periodic (tuple[bool, bool])

  • max_link_distance (float | None)

mhx.diagnostics.trajectory_energies(trajectory, *, lengths)

Return energy time series for a saved trajectory.

Return type:

dict[str, Array]

Parameters:

  • trajectory (ReducedMHDTrajectory)

  • lengths (tuple[float, float])

mhx.diagnostics.trajectory_mode_amplitude(trajectory, *, mode)

Return a saved trajectory’s mode-amplitude time series.

Return type:

Array

Parameters:

  • trajectory (ReducedMHDTrajectory)

  • mode (tuple[int, int])

Benchmark problem builders.

class mhx.benchmarks.ArnoldiValidationResult(expected_eigenvalues, ritz_values, max_ritz_abs_error, max_imag_abs, max_residual_estimate, residual_estimates, hessenberg, diagnostics, validation)

Known-operator Arnoldi result and validation gates.

Parameters:

  • expected_eigenvalues (ndarray)

  • ritz_values (ndarray)

  • max_ritz_abs_error (float)

  • max_imag_abs (float)

  • max_residual_estimate (float)

  • residual_estimates (ndarray)

  • hessenberg (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.BenchmarkCatalogEntry(name, command, schema, purpose, expected_outputs, literature_anchor)

One reproducible validation or benchmark workflow entry.

Parameters:

  • name (str)

  • command (str)

  • schema (str)

  • purpose (str)

  • expected_outputs (tuple[str, ...])

  • literature_anchor (str)

to_dict()

Return JSON-compatible entry metadata.

Return type:

dict[str, Any]

class mhx.benchmarks.CosineEquilibriumLinearizationResult(flow_tangent, expected_flow_tangent, tension_tangent, expected_tension_tangent, relative_errors, diagnostics, validation)

Analytic nonzero-equilibrium linearized-RHS coupling diagnostics.

Parameters:

  • flow_tangent (ReducedMHDState)

  • expected_flow_tangent (ReducedMHDState)

  • tension_tangent (ReducedMHDState)

  • expected_tension_tangent (ReducedMHDState)

  • relative_errors (dict[str, float])

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.DiffusionEigenvalueResult(eigenfunction, operator_action, expected_eigenvalue, measured_eigenvalue, eigenvalue_abs_error, residual_norm, diagnostics, validation)

Analytic diffusion eigenvalue result and validation gates.

Parameters:

  • eigenfunction (ndarray)

  • operator_action (ndarray)

  • expected_eigenvalue (float)

  • measured_eigenvalue (float)

  • eigenvalue_abs_error (float)

  • residual_norm (float)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.DurationAssessment(name, purpose, scope, t_end, growth_rate, required_efolds, safety_factor, required_t_end, observed_efolds, sufficient_for_intended_scope, sufficient_for_production_claim, sufficient_for_nonlinear_claim, action)

Assessment of whether a run is long enough for its declared purpose.

Parameters:

  • name (str)

  • purpose (str)

  • scope (str)

  • t_end (float)

  • growth_rate (float)

  • required_efolds (float)

  • safety_factor (float)

  • required_t_end (float)

  • observed_efolds (float)

  • sufficient_for_intended_scope (bool)

  • sufficient_for_production_claim (bool)

  • sufficient_for_nonlinear_claim (bool)

  • action (str)

to_dict()

Return JSON-compatible values.

Return type:

dict[str, Any]

class mhx.benchmarks.FKRConstantPsiEstimate(lundquist, ka, delta_prime_a, gamma_tau_a, inner_width_a)

Constant-psi tearing scaling estimate for a Harris-like sheet.

Parameters:

  • lundquist (float)

  • ka (float)

  • delta_prime_a (float)

  • gamma_tau_a (float)

  • inner_width_a (float)

to_dict()

Return JSON-compatible values.

Return type:

dict[str, float]

class mhx.benchmarks.FKRGrowthRateResult(lundquist, gamma_vs_lundquist, inner_width_vs_lundquist, ka, numerical_delta_prime_a, analytic_delta_prime_a, gamma_vs_delta_prime, analytic_gamma_vs_delta_prime, gamma_relative_error, diagnostics, validation)

Asymptotic FKR growth-rate arrays and pass/fail gates.

Parameters:

  • lundquist (ndarray)

  • gamma_vs_lundquist (ndarray)

  • inner_width_vs_lundquist (ndarray)

  • ka (ndarray)

  • numerical_delta_prime_a (ndarray)

  • analytic_delta_prime_a (ndarray)

  • gamma_vs_delta_prime (ndarray)

  • analytic_gamma_vs_delta_prime (ndarray)

  • gamma_relative_error (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.FKRWindowResult(ka, gamma_tau_a, inner_width_a, delta_prime_a, constant_psi_product, diagnostics, validation)

Computed FKR regime-window arrays and pass/fail gates.

Parameters:

  • ka (ndarray)

  • gamma_tau_a (ndarray)

  • inner_width_a (ndarray)

  • delta_prime_a (ndarray)

  • constant_psi_product (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.ForcedTurbulentReconnectionReadinessAssessment(run_dir, promotion_ready, diagnostics, validation)

Readiness assessment for a forced turbulent reconnection artifact.

Parameters:

  • run_dir (Path)

  • promotion_ready (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.HarrisDeltaPrimeResult(ka, numerical_delta_prime_a, analytic_delta_prime_a, relative_error, diagnostics, validation)

Numerical Harris-sheet outer-region Delta-prime validation artifacts.

Parameters:

  • ka (ndarray)

  • numerical_delta_prime_a (ndarray)

  • analytic_delta_prime_a (ndarray)

  • relative_error (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.LinearTearingDispersionResult(wavenumber, growth_rate, eigenvalue_imag, residual_norm, reference_wavenumber, reference_growth_rate, measured_reference_growth_rate, reference_relative_error, unstable_band_mask, stable_control_mask, diagnostics, validation)

Small Harris-sheet tearing dispersion validation artifacts.

Parameters:

  • wavenumber (ndarray)

  • growth_rate (ndarray)

  • eigenvalue_imag (ndarray)

  • residual_norm (ndarray)

  • reference_wavenumber (float)

  • reference_growth_rate (float)

  • measured_reference_growth_rate (float)

  • reference_relative_error (float)

  • unstable_band_mask (ndarray)

  • stable_control_mask (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.LinearTearingEigenvalueResult(grid_points, dx, growth_rates, fitted_growth_rates, extrapolated_growth_rate, reference_growth_rate, selected_grid_points, selected_eigenvalue, selected_residual_norm, selected_relative_growth_error, extrapolated_relative_growth_error, stable_control_wavenumber, stable_control_max_real_part, stable_control_residual_norm, flux_even_correlation, stream_odd_correlation, coordinate, selected_spectrum, flux_eigenfunction, streamfunction_imag, diagnostics, validation)

Direct reduced-MHD Harris-sheet tearing eigenvalue validation artifacts.

Parameters:

  • grid_points (ndarray)

  • dx (ndarray)

  • growth_rates (ndarray)

  • fitted_growth_rates (ndarray)

  • extrapolated_growth_rate (float)

  • reference_growth_rate (float)

  • selected_grid_points (int)

  • selected_eigenvalue (complex)

  • selected_residual_norm (float)

  • selected_relative_growth_error (float)

  • extrapolated_relative_growth_error (float)

  • stable_control_wavenumber (float)

  • stable_control_max_real_part (float)

  • stable_control_residual_norm (float)

  • flux_even_correlation (float)

  • stream_odd_correlation (float)

  • coordinate (ndarray)

  • selected_spectrum (ndarray)

  • flux_eigenfunction (ndarray)

  • streamfunction_imag (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.LinearTearingLayerResult(lundquist, growth_rate, stream_half_width, current_half_width, flux_half_width, residual_norm, stream_width_slope, growth_rate_slope, flux_width_relative_spread, selected_coordinate, selected_flux_eigenfunction, selected_streamfunction_imag, selected_current_density, diagnostics, validation)

Harris-sheet tearing eigenfunction localization diagnostics.

Parameters:

  • lundquist (ndarray)

  • growth_rate (ndarray)

  • stream_half_width (ndarray)

  • current_half_width (ndarray)

  • flux_half_width (ndarray)

  • residual_norm (ndarray)

  • stream_width_slope (float)

  • growth_rate_slope (float)

  • flux_width_relative_spread (float)

  • selected_coordinate (ndarray)

  • selected_flux_eigenfunction (ndarray)

  • selected_streamfunction_imag (ndarray)

  • selected_current_density (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.LinearTearingTimeDomainResult(times, amplitude, exact_amplitude, relative_amplitude_error, fitted_growth_rate, expected_growth_rate, relative_growth_error, max_relative_amplitude_error, final_mode_alignment, selected_eigenvalue, selected_residual_norm, diagnostics, validation)

Time-domain replay of the direct Harris-sheet tearing eigenmode.

Parameters:

  • times (ndarray)

  • amplitude (ndarray)

  • exact_amplitude (ndarray)

  • relative_amplitude_error (ndarray)

  • fitted_growth_rate (float)

  • expected_growth_rate (float)

  • relative_growth_error (float)

  • max_relative_amplitude_error (float)

  • final_mode_alignment (float)

  • selected_eigenvalue (complex)

  • selected_residual_norm (float)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.LinearizedRHSResult(jvp, finite_difference, absolute_errors, relative_errors, diagnostics, validation)

JVP/finite-difference consistency diagnostics for the reduced-MHD RHS.

Parameters:

  • jvp (ReducedMHDState)

  • finite_difference (ReducedMHDState)

  • absolute_errors (dict[str, float])

  • relative_errors (dict[str, float])

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.NonlinearDurationAuditResult(current_case_names, current_end_times, target_names, target_end_times, plasmoid_lundquist, plasmoid_efold_times, harris_growth_rate, requested_linear_efolds, diagnostics, validation)

Reviewer-facing audit of current nonlinear runtime versus physics windows.

Parameters:

  • current_case_names (tuple[str, ...])

  • current_end_times (ndarray)

  • target_names (tuple[str, ...])

  • target_end_times (ndarray)

  • plasmoid_lundquist (ndarray)

  • plasmoid_efold_times (ndarray)

  • harris_growth_rate (float)

  • requested_linear_efolds (float)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.NonlinearEnergyBudgetResult(time, magnetic_energy, kinetic_energy, total_energy, current_dissipation, viscous_dissipation, total_dissipation, cumulative_dissipation, budget_residual, relative_budget_residual, nonlinear_rhs_ratio, max_relative_budget_residual, max_relative_energy_growth, relative_energy_drop, initial_state, final_state, diagnostics, validation)

Saved arrays and validation gates for a nonlinear reduced-MHD energy budget.

Parameters:

  • time (ndarray)

  • magnetic_energy (ndarray)

  • kinetic_energy (ndarray)

  • total_energy (ndarray)

  • current_dissipation (ndarray)

  • viscous_dissipation (ndarray)

  • total_dissipation (ndarray)

  • cumulative_dissipation (ndarray)

  • budget_residual (ndarray)

  • relative_budget_residual (ndarray)

  • nonlinear_rhs_ratio (float)

  • max_relative_budget_residual (float)

  • max_relative_energy_growth (float)

  • relative_energy_drop (float)

  • initial_state (ReducedMHDState)

  • final_state (ReducedMHDState)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.OrszagTangVortexResult(time, psi, omega, current_density, magnetic_energy, kinetic_energy, total_energy, current_linf, vorticity_linf, current_high_k_fraction, vorticity_high_k_fraction, max_relative_energy_growth, relative_energy_drop, current_high_k_growth, vorticity_high_k_growth, final_magnetic_divergence_linf, initial_state, final_state, diagnostics, validation)

Saved arrays and validation gates for the reduced-MHD Orszag–Tang vortex.

Parameters:

  • time (ndarray)

  • psi (ndarray)

  • omega (ndarray)

  • current_density (ndarray)

  • magnetic_energy (ndarray)

  • kinetic_energy (ndarray)

  • total_energy (ndarray)

  • current_linf (ndarray)

  • vorticity_linf (ndarray)

  • current_high_k_fraction (ndarray)

  • vorticity_high_k_fraction (ndarray)

  • max_relative_energy_growth (float)

  • relative_energy_drop (float)

  • current_high_k_growth (float)

  • vorticity_high_k_growth (float)

  • final_magnetic_divergence_linf (float)

  • initial_state (ReducedMHDState)

  • final_state (ReducedMHDState)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PaperPipelineResult(outdir, validation_suite_path, readiness_path, pipeline_path, manifest_path, artifact_manifest_path, validation)

Summary of one reproducible paper/validation pipeline bundle.

Parameters:

  • outdir (Path)

  • validation_suite_path (Path)

  • readiness_path (Path)

  • pipeline_path (Path)

  • manifest_path (Path)

  • artifact_manifest_path (Path)

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicCurrentSheetEigenvalueResult(matrix, eigenvalues, selected_eigenvalue, selected_eigenvector, selected_residual_norm, gauge_residual_norms, gauge_mode_count, max_real_part, max_non_gauge_real_part, diagnostics, validation)

Tiny dense-spectrum validation around a periodic current-sheet equilibrium.

Parameters:

  • matrix (ndarray)

  • eigenvalues (ndarray)

  • selected_eigenvalue (complex)

  • selected_eigenvector (ndarray)

  • selected_residual_norm (float)

  • gauge_residual_norms (dict[str, float])

  • gauge_mode_count (int)

  • max_real_part (float)

  • max_non_gauge_real_part (float)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicCurrentSheetNonlinearBridgeResult(epsilons, relative_errors, convergence_order, tangent_norm, finest_relative_error, perturbation, tangent_final, diagnostics, validation)

Differentiability bridge for the nonlinear reduced-MHD RK4 time map.

Parameters:

  • epsilons (ndarray)

  • relative_errors (ndarray)

  • convergence_order (float)

  • tangent_norm (float)

  • finest_relative_error (float)

  • perturbation (ReducedMHDState)

  • tangent_final (ReducedMHDState)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicCurrentSheetTimeDomainResult(times, amplitudes, exact_amplitudes, relative_state_error, selected_eigenvalue, fitted_decay_rate, relative_decay_rate_error, selected_residual_norm, initial_state, final_state, diagnostics, validation)

Time-domain replay of one periodic current-sheet JVP eigenmode.

Parameters:

  • times (ndarray)

  • amplitudes (ndarray)

  • exact_amplitudes (ndarray)

  • relative_state_error (ndarray)

  • selected_eigenvalue (float)

  • fitted_decay_rate (float)

  • relative_decay_rate_error (float)

  • selected_residual_norm (float)

  • initial_state (ReducedMHDState)

  • final_state (ReducedMHDState)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicDoubleHarrisConvergenceResult(case_kind, resolution, dt, samples, fitted_early_growth_rate, early_growth_factor, max_growth_factor, reconnected_flux_amplification, island_width_amplification, relative_energy_increase, max_current_density_linf, max_kinetic_energy, diagnostics, validation)

Resolution/time-step sweep for seeded periodic double-Harris evidence.

Parameters:

  • case_kind (ndarray)

  • resolution (ndarray)

  • dt (ndarray)

  • samples (ndarray)

  • fitted_early_growth_rate (ndarray)

  • early_growth_factor (ndarray)

  • max_growth_factor (ndarray)

  • reconnected_flux_amplification (ndarray)

  • island_width_amplification (ndarray)

  • relative_energy_increase (ndarray)

  • max_current_density_linf (ndarray)

  • max_kinetic_energy (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicDoubleHarrisNonlinearGrowthResult(matrix, eigenvalues, selected_eigenvalue, selected_eigenvector, selected_residual_norm, time, perturbation_norm, expected_perturbation_norm, fitted_growth_rate, relative_growth_error, growth_factor, base_initial_state, base_final_state, perturbed_final_state, diagnostics, validation)

Nonlinear replay of an unstable periodic double-Harris eigenmode.

Parameters:

  • matrix (ndarray)

  • eigenvalues (ndarray)

  • selected_eigenvalue (complex)

  • selected_eigenvector (ndarray)

  • selected_residual_norm (float)

  • time (ndarray)

  • perturbation_norm (ndarray)

  • expected_perturbation_norm (ndarray)

  • fitted_growth_rate (float)

  • relative_growth_error (float)

  • growth_factor (float)

  • base_initial_state (ReducedMHDState)

  • base_final_state (ReducedMHDState)

  • perturbed_final_state (ReducedMHDState)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicDoubleHarrisParameterSweepResult(sweep_axis, case_index, case_label, mode_x, mode_y, width, resistivity, viscosity, dt, t_end, save_every, samples, passed, fitted_early_growth_rate, early_growth_factor, max_growth_factor, reconnected_flux_amplification, seed_mode_reconnected_flux_amplification, island_width_amplification, relative_energy_increase, max_current_density_linf, max_kinetic_energy, max_x_point_count, max_o_point_count, growth_rate_spread, max_growth_spread, diagnostics, validation)

Parameter sweep for seeded periodic double-Harris nonlinear response.

Parameters:

  • sweep_axis (str)

  • case_index (ndarray)

  • case_label (ndarray)

  • mode_x (ndarray)

  • mode_y (ndarray)

  • width (ndarray)

  • resistivity (ndarray)

  • viscosity (ndarray)

  • dt (ndarray)

  • t_end (ndarray)

  • save_every (ndarray)

  • samples (ndarray)

  • passed (ndarray)

  • fitted_early_growth_rate (ndarray)

  • early_growth_factor (ndarray)

  • max_growth_factor (ndarray)

  • reconnected_flux_amplification (ndarray)

  • seed_mode_reconnected_flux_amplification (ndarray)

  • island_width_amplification (ndarray)

  • relative_energy_increase (ndarray)

  • max_current_density_linf (ndarray)

  • max_kinetic_energy (ndarray)

  • max_x_point_count (ndarray)

  • max_o_point_count (ndarray)

  • growth_rate_spread (float)

  • max_growth_spread (float)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicDoubleHarrisPromotionAssessment(run_dir, promotion_ready, diagnostics, validation)

Promotion-boundary assessment for seeded periodic double-Harris evidence.

Parameters:

  • run_dir (Path)

  • promotion_ready (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PeriodicDoubleHarrisSeededLongRunResult(time, perturbation_norm, reconnected_flux, seed_mode_reconnected_flux, rutherford_island_width, dominant_flux_mode_x, dominant_flux_mode_y, magnetic_energy, kinetic_energy, total_energy, current_density_linf, x_point_count, o_point_count, fitted_early_growth_rate, early_growth_factor, max_growth_factor, reconnected_flux_amplification, island_width_amplification, base_trajectory, perturbed_trajectory, base_initial_state, perturbed_initial_state, diagnostics, validation)

Resolution-oriented nonlinear replay of a seeded periodic double-Harris sheet.

Parameters:

  • time (ndarray)

  • perturbation_norm (ndarray)

  • reconnected_flux (ndarray)

  • seed_mode_reconnected_flux (ndarray)

  • rutherford_island_width (ndarray)

  • dominant_flux_mode_x (ndarray)

  • dominant_flux_mode_y (ndarray)

  • magnetic_energy (ndarray)

  • kinetic_energy (ndarray)

  • total_energy (ndarray)

  • current_density_linf (ndarray)

  • x_point_count (ndarray)

  • o_point_count (ndarray)

  • fitted_early_growth_rate (float)

  • early_growth_factor (float)

  • max_growth_factor (float)

  • reconnected_flux_amplification (float)

  • island_width_amplification (float)

  • base_trajectory (ReducedMHDTrajectory)

  • perturbed_trajectory (ReducedMHDTrajectory)

  • base_initial_state (ReducedMHDState)

  • perturbed_initial_state (ReducedMHDState)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.PlasmoidScalingEstimate(lundquist, gamma_tau_a, fastest_mode_k_l)

Loureiro-type Sweet-Parker plasmoid scaling estimate.

Parameters:

  • lundquist (float)

  • gamma_tau_a (float)

  • fastest_mode_k_l (float)

to_dict()

Return JSON-compatible values.

Return type:

dict[str, float]

class mhx.benchmarks.PowerIterationValidationResult(expected_eigenvalue, measured_eigenvalue, eigenvalue_abs_error, residual_norm, rayleigh_history, residual_history, diagnostics, validation)

Known-operator power-iteration result and validation gates.

Parameters:

  • expected_eigenvalue (float)

  • measured_eigenvalue (float)

  • eigenvalue_abs_error (float)

  • residual_norm (float)

  • rayleigh_history (ndarray)

  • residual_history (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.QIMetricGate(metric='', statistic='', threshold=None, sense='less_equal', max_abs_cv=None, max_std=None, max_abs_mean=None, max_abs_max=None, cv_floor=1e-300)

Simple pass/fail gate for one seed-ensemble metric.

Parameters:

  • metric (str)

  • statistic (str)

  • threshold (float | None)

  • sense (str)

  • max_abs_cv (float | None)

  • max_std (float | None)

  • max_abs_mean (float | None)

  • max_abs_max (float | None)

  • cv_floor (float)

class mhx.benchmarks.ReadinessAssessment(public_release_ready, publication_claim_ready, diagnostics, validation)

Machine-readable release and paper-readiness assessment.

Parameters:

  • public_release_ready (bool)

  • publication_claim_ready (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.ReconnectionScalingResult(lundquist, fkr_gamma, fkr_inner_width, plasmoid_gamma, plasmoid_mode, ideal_aspect_ratio, diagnostics, validation)

Computed scaling arrays and pass/fail gates for analytic reconnection theory.

Parameters:

  • lundquist (ndarray)

  • fkr_gamma (ndarray)

  • fkr_inner_width (ndarray)

  • plasmoid_gamma (ndarray)

  • plasmoid_mode (ndarray)

  • ideal_aspect_ratio (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.ReducedMHDLinearEigenmodeResult(psi_eigenfunction, omega_eigenfunction, operator_psi_action, operator_omega_action, expected_eigenvalues, measured_eigenvalues, eigenvalue_abs_errors, residual_norms, diagnostics, validation)

Zero-state reduced-MHD linear eigenmode diagnostics and gates.

Parameters:

  • psi_eigenfunction (ndarray)

  • omega_eigenfunction (ndarray)

  • operator_psi_action (ndarray)

  • operator_omega_action (ndarray)

  • expected_eigenvalues (dict[str, float])

  • measured_eigenvalues (dict[str, float])

  • eigenvalue_abs_errors (dict[str, float])

  • residual_norms (dict[str, float])

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.ReleaseCandidateAssessment(release_candidate_ready, publication_claim_ready, diagnostics, validation)

Machine-readable static release-candidate assessment.

Parameters:

  • release_candidate_ready (bool)

  • publication_claim_ready (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.ResistiveDecayResult(trajectory, exact_psi, numerical_amplitude, exact_amplitude, numerical_energy, exact_energy, relative_amplitude_error, relative_energy_error, diagnostics, validation)

Numerical and exact histories for one Fourier-mode diffusion benchmark.

Parameters:

  • trajectory (ReducedMHDTrajectory)

  • exact_psi (Array)

  • numerical_amplitude (Array)

  • exact_amplitude (Array)

  • numerical_energy (Array)

  • exact_energy (Array)

  • relative_amplitude_error (Array)

  • relative_energy_error (Array)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.RutherfordCampaignRunResult(trajectory, time, reconnected_flux, island_width, current_density_linf, magnetic_energy, kinetic_energy, total_energy, diagnostics, validation)

Saved histories and gates for a validation-grade Rutherford run.

Parameters:

  • trajectory (ReducedMHDTrajectory)

  • time (ndarray)

  • reconnected_flux (ndarray)

  • island_width (ndarray)

  • current_density_linf (ndarray)

  • magnetic_energy (ndarray)

  • kinetic_energy (ndarray)

  • total_energy (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.RutherfordCampaignTemplate(config, duration_assessment, estimated_steps, estimated_saved_frames, diagnostics, validation)

Duration-guarded nonlinear island campaign configuration bundle.

Parameters:

  • config (RunConfig)

  • duration_assessment (DurationAssessment)

  • estimated_steps (int)

  • estimated_saved_frames (int)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

mhx.benchmarks.RutherfordFastCampaignResult

alias of RutherfordCampaignRunResult

class mhx.benchmarks.SeedRobustQIResult(seeds, metrics, metric_summary, trajectories, diagnostics_by_seed, diagnostics, validation, metric_names=(), metric_values=None, summaries=None)

Seed ensemble metrics and validation gates for a FAST reduced-MHD run.

Parameters:

  • seeds (tuple[int, ...])

  • metrics (dict[str, ndarray])

  • metric_summary (dict[str, dict[str, float]])

  • trajectories (tuple[ReducedMHDTrajectory, ...])

  • diagnostics_by_seed (tuple[dict[str, Any], ...])

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

  • metric_names (tuple[str, ...])

  • metric_values (ndarray | None)

  • summaries (dict[str, dict[str, Any]] | None)

class mhx.benchmarks.SeedRobustQISweepResult(seeds, noise_amplitudes, metric_names, metric_values, per_amplitude, metric_cv_max, metric_relative_mean_drift_max, diagnostics, validation)

Noise-amplitude sweep of seed-robust QI metrics.

Parameters:

  • seeds (tuple[int, ...])

  • noise_amplitudes (tuple[float, ...])

  • metric_names (tuple[str, ...])

  • metric_values (ndarray)

  • per_amplitude (tuple[SeedRobustQIResult, ...])

  • metric_cv_max (dict[str, float])

  • metric_relative_mean_drift_max (dict[str, float])

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.TimingBenchmarkResult(cases, diagnostics)

Timing benchmark results and environment metadata.

Parameters:
class mhx.benchmarks.TimingCaseResult(name, durations_seconds, peak_tracemalloc_bytes, details)

Timing summary for one benchmark case.

Parameters:

  • name (str)

  • durations_seconds (tuple[float, ...])

  • peak_tracemalloc_bytes (tuple[int, ...])

  • details (dict[str, Any])

property summary: dict[str, float]

Return stable scalar summary statistics for the measured repeats.

to_dict()

Serialize the timing case to JSON-compatible builtins.

Return type:

dict[str, Any]

class mhx.benchmarks.TurbulenceResult(schema, time, psi, omega, current_density, magnetic_energy, kinetic_energy, total_energy, current_linf, vorticity_linf, current_high_k_fraction, magnetic_divergence_linf, reconnection_proxy, reconnection_rate_proxy, initial_state, final_state, diagnostics, validation)

Saved arrays and gates for nonlinear reduced-MHD turbulence examples.

Parameters:

  • schema (str)

  • time (ndarray)

  • psi (ndarray)

  • omega (ndarray)

  • current_density (ndarray)

  • magnetic_energy (ndarray)

  • kinetic_energy (ndarray)

  • total_energy (ndarray)

  • current_linf (ndarray)

  • vorticity_linf (ndarray)

  • current_high_k_fraction (ndarray)

  • magnetic_divergence_linf (ndarray)

  • reconnection_proxy (ndarray | None)

  • reconnection_rate_proxy (ndarray | None)

  • initial_state (ReducedMHDState)

  • final_state (ReducedMHDState)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.benchmarks.ValidationSuiteCase(name, command, runner, append_outdir=True)

One executable validation-suite case.

Parameters:

  • name (str)

  • command (str)

  • runner (Callable[[Path], tuple[Path, dict[str, Any]]])

  • append_outdir (bool)

mhx.benchmarks.assess_duration(*, name, purpose, t_end, growth_rate=0.0131, required_efolds=10.0, safety_factor=1.0, scope='nonlinear_production')

Assess a simulation duration against an e-fold requirement.

Validation-only scopes are allowed to be shorter than production nonlinear targets, but the returned assessment explicitly marks them as not sufficient for nonlinear-island or plasmoid claims.

Return type:

DurationAssessment

Parameters:

  • name (str)

  • purpose (str)

  • t_end (float)

  • growth_rate (float)

  • required_efolds (float)

  • safety_factor (float)

  • scope (str)

mhx.benchmarks.assess_forced_turbulent_reconnection_readiness(run_dir, *, require_summary=True, require_movies=False, min_history_samples=20, min_t_end=20.0, min_reconnection_proxy_change=0.001, min_abs_reconnection_rate_proxy=1e-06, max_relative_energy_growth=2.0)

Assess whether a forced turbulent reconnection artifact is doc-ready.

This is a validation-only promotion boundary for the existing forced turbulent reconnection replay. Passing it does not promote the artifact to a production turbulent-reconnection claim.

Return type:

ForcedTurbulentReconnectionReadinessAssessment

Parameters:

  • run_dir (str | Path)

  • require_summary (bool)

  • require_movies (bool)

  • min_history_samples (int)

  • min_t_end (float)

  • min_reconnection_proxy_change (float)

  • min_abs_reconnection_rate_proxy (float)

  • max_relative_energy_growth (float)

mhx.benchmarks.assess_periodic_double_harris_promotion(run_dir, *, convergence_dirs=(), require_movies=True, min_history_samples=30, min_convergence_dirs=1, min_t_end=30.0, min_reconnected_flux_amplification=1.05, min_island_width_amplification=1.05, max_relative_energy_increase=1e-08)

Assess whether a seeded double-Harris bundle can be promoted in docs.

Passing this gate promotes a run to convergence-backed validation evidence, not to a production Rutherford/plasmoid claim. Production claims still need larger aspect-ratio, Lundquist-number, seed, and duration campaigns.

Return type:

PeriodicDoubleHarrisPromotionAssessment

Parameters:

  • run_dir (str | Path)

  • convergence_dirs (tuple[str | Path, ...])

  • require_movies (bool)

  • min_history_samples (int)

  • min_convergence_dirs (int)

  • min_t_end (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

  • max_relative_energy_increase (float)

mhx.benchmarks.build_rutherford_campaign_template(*, harris_growth_rate=0.0131, production_efolds=10.0, safety_factor=3.0, shape=(128, 128), dt=0.1, target_saved_frames=400, run_output_dir='outputs/production/rutherford_island', equilibrium='cosine_tearing', width=0.4, amplitude=1.0, perturbation_amplitude=0.001, perturbation_mode=(1, 1), resistivity=0.001, viscosity=0.001)

Build a long nonlinear-island campaign template without running it.

Return type:

RutherfordCampaignTemplate

Parameters:

  • harris_growth_rate (float)

  • production_efolds (float)

  • safety_factor (float)

  • shape (tuple[int, int])

  • dt (float)

  • target_saved_frames (int)

  • run_output_dir (str | Path)

  • equilibrium (str)

  • width (float)

  • amplitude (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

mhx.benchmarks.compute_metric_statistics(values, metric_names=None, *, gates=None)

Return mean/std/CV summaries and optional pass/fail gates.

Return type:

dict[str, float] | dict[str, dict[str, Any]]

Parameters:

  • values (ndarray)

  • metric_names (Sequence[str] | None)

  • gates (Mapping[str, QIMetricGate] | None)

mhx.benchmarks.default_seed_robust_qi_gates()

Return default seed-robust QI gates in metadata-friendly form.

Return type:

dict[str, QIMetricGate]

mhx.benchmarks.double_harris_seeded_long_run_presets()

Return named duration presets for seeded double-Harris media workflows.

Return type:

dict[str, dict[str, Any]]

mhx.benchmarks.duration_policy_assessments(*, harris_growth_rate=0.0131, production_efolds=10.0)

Return current and future duration assessments used by docs and CI.

Return type:

tuple[DurationAssessment, ...]

Parameters:

  • harris_growth_rate (float)

  • production_efolds (float)

mhx.benchmarks.fkr_constant_psi_estimate(lundquist, ka)

Return a dimensionless FKR constant-psi tearing scaling estimate.

The estimate intentionally omits order-unity coefficients:

γ τ_a ~ S_a^(-3/5) (ka)^(2/5) (Δ'a)^(4/5).

Return type:

FKRConstantPsiEstimate

Parameters:

  • lundquist (float)

  • ka (float)

mhx.benchmarks.generate_seed_ensemble(base_seed_or_grid, count=None, *, seeds=(0, 1, 2, 3), perturbation_amplitude=0.001, noise_amplitude=1e-06)

Return deterministic seeds, or seeded states when passed a grid.

Return type:

ndarray | tuple[ReducedMHDState, ...]

Parameters:

  • base_seed_or_grid (int | CartesianGrid)

  • count (int | None)

  • seeds (tuple[int, ...])

  • perturbation_amplitude (float)

  • noise_amplitude (float)

mhx.benchmarks.harris_sheet_delta_prime(ka)

Return the Harris-sheet outer-region proxy Δ' a = 2(1/(ka) - ka).

Return type:

float

Parameters:

ka (float)

mhx.benchmarks.ideal_tearing_aspect_ratio(lundquist)

Return Pucci-Velli ideal-tearing scaling a/L ~ S^(-1/3).

Return type:

float

Parameters:

lundquist (float)

mhx.benchmarks.linear_tearing_initial_state(grid, *, perturbation_amplitude=0.001)

Return a periodic current-sheet-like reduced-MHD initial condition.

This is a deterministic FAST smoke benchmark, not yet an FKR-calibrated tearing eigenmode. The equilibrium is ψ₀ = cos(y) with a small cos(x) cos(y) perturbation.

Return type:

ReducedMHDState

Parameters:
mhx.benchmarks.loglog_slope(x, y)

Return least-squares slope of log(y) against log(x).

Return type:

float

Parameters:

  • x (ndarray)

  • y (ndarray)

mhx.benchmarks.loureiro_plasmoid_estimate(lundquist)

Return Sweet-Parker plasmoid estimates γτ_A ~ S^(1/4), kL ~ S^(3/8).

Return type:

PlasmoidScalingEstimate

Parameters:

lundquist (float)

mhx.benchmarks.make_seeded_initial_state(grid_or_state, *, seed, perturbation_amplitude=0.001, noise_amplitude=1e-06, psi_noise_amplitude=None, omega_noise_amplitude=0.0)

Return a deterministic seeded reduced-MHD initial state.

Return type:

ReducedMHDState

Parameters:

  • grid_or_state (CartesianGrid | ReducedMHDState)

  • seed (int)

  • perturbation_amplitude (float)

  • noise_amplitude (float)

  • psi_noise_amplitude (float | None)

  • omega_noise_amplitude (float)

mhx.benchmarks.orszag_tang_initial_state(grid)

Return the incompressible reduced-MHD Orszag–Tang initial condition.

The stream and flux functions are

phi = cos(x) + cos(y), psi = cos(y) + 0.5 cos(2x).

With the MHX convention B_perp=(psi_y, -psi_x) and v_perp=(phi_y, -phi_x), this gives the classic 2-D Orszag–Tang large-scale vortex v=(-sin y, sin x) and B=(-sin y, sin 2x).

Return type:

ReducedMHDState

Parameters:

grid (CartesianGrid)

mhx.benchmarks.require_duration_for_claim(*, name, purpose, t_end, growth_rate=0.0131, required_efolds=10.0, safety_factor=1.0)

Return an assessment or raise if a production claim would be too short.

Return type:

DurationAssessment

Parameters:

  • name (str)

  • purpose (str)

  • t_end (float)

  • growth_rate (float)

  • required_efolds (float)

  • safety_factor (float)

mhx.benchmarks.required_time_for_efolds(growth_rate, *, required_efolds=10.0, safety_factor=1.0)

Return safety_factor * required_efolds / growth_rate.

Return type:

float

Parameters:

  • growth_rate (float)

  • required_efolds (float)

  • safety_factor (float)

mhx.benchmarks.resistive_decay_rate(*, resistivity, mode, lengths)

Return the exact scalar decay rate η|k|² for one periodic mode.

Return type:

float

Parameters:

  • resistivity (float)

  • mode (tuple[int, int])

  • lengths (tuple[float, float])

mhx.benchmarks.run_arnoldi_validation(*, krylov_dim=4, max_ritz_abs_error=1e-06, max_imag_abs=1e-08, max_residual_estimate=1e-06)

Validate Arnoldi Ritz values on a known non-normal upper-triangular operator.

Return type:

ArnoldiValidationResult

Parameters:

  • krylov_dim (int)

  • max_ritz_abs_error (float)

  • max_imag_abs (float)

  • max_residual_estimate (float)

mhx.benchmarks.run_cosine_equilibrium_linearization_validation(*, shape=(24, 24), amplitude=1.0, resistivity=0.001, viscosity=0.002, max_relative_error=0.0001)

Validate analytic linearized couplings around ψ₀=A cos(y).

The gate checks two Fourier perturbations with closed-form reduced-MHD JVPs:

  • δω = cos(k_x x), δψ=0 gives flow advection of the equilibrium flux plus viscous vorticity diffusion.

  • δψ = cos(k_x x)cos(2k_y y), δω=0 gives magnetic-tension coupling to vorticity plus resistive flux diffusion.

Return type:

CosineEquilibriumLinearizationResult

Parameters:

  • shape (tuple[int, int])

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • max_relative_error (float)

mhx.benchmarks.run_decaying_mhd_turbulence_validation(*, shape=(32, 32), resistivity=0.02, viscosity=0.02, dt=0.01, t_end=4.0, save_every=20, seed=7, min_relative_energy_drop=0.001, max_relative_energy_growth=1e-08, min_current_linf_growth=1e-06, max_magnetic_divergence_linf=1e-10)

Run a deterministic decaying 2-D reduced-MHD turbulence validation.

Return type:

TurbulenceResult

Parameters:

  • shape (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

  • dt (float)

  • t_end (float)

  • save_every (int)

  • seed (int)

  • min_relative_energy_drop (float)

  • max_relative_energy_growth (float)

  • min_current_linf_growth (float)

  • max_magnetic_divergence_linf (float)

mhx.benchmarks.run_diffusion_eigenvalue_validation(*, shape=(32, 32), mode=(2, 1), diffusivity=0.025, max_eigenvalue_abs_error=1e-06, max_residual_norm=5e-06)

Validate a matrix-free spectral diffusion eigenpair against theory.

Return type:

DiffusionEigenvalueResult

Parameters:

  • shape (tuple[int, int])

  • mode (tuple[int, int])

  • diffusivity (float)

  • max_eigenvalue_abs_error (float)

  • max_residual_norm (float)

mhx.benchmarks.run_fkr_growth_rate_validation(*, lundquist=(10000.0, 30000.0, 100000.0, 300000.0, 1000000.0), ka=(0.15, 0.25, 0.35, 0.5, 0.7), fixed_ka=0.35, fixed_lundquist=1000000.0, xmax_over_a=18.0, steps=4000, max_slope_error=1e-10, max_gamma_relative_error=1e-07, max_constant_psi_product=0.5)

Gate FKR growth-rate scaling using numerical Harris Δ' matching.

This benchmark converts the numerically recovered Harris-sheet outer matching parameter into the constant-$psi$ FKR asymptotic growth estimate

γτ_a ~ S_a^(-3/5) (ka)^(2/5) (Δ'a)^(4/5).

It is a calibrated asymptotic growth-rate gate: it tests the numerical outer-region Δ' path, the FKR exponent assembly, and the constant-$psi$ window. It is still not a direct resistive inner-layer/global eigenvalue solve.

Return type:

FKRGrowthRateResult

Parameters:

  • lundquist (tuple[float, ...])

  • ka (tuple[float, ...])

  • fixed_ka (float)

  • fixed_lundquist (float)

  • xmax_over_a (float)

  • steps (int)

  • max_slope_error (float)

  • max_gamma_relative_error (float)

  • max_constant_psi_product (float)

mhx.benchmarks.run_fkr_window_validation(*, lundquist=1000000.0, ka=(0.15, 0.25, 0.35, 0.5, 0.7), max_inner_width_a=0.05, max_constant_psi_product=0.5)

Validate that sampled modes lie in a conservative FKR regime window.

The gate checks the constant-$psi$ conditions used when applying the Furth-Killeen-Rosenbluth scaling estimate: positive Harris-sheet $Delta’a$, a thin resistive layer $delta/a$, and $Delta’delta ll 1$. It is an analytic regime-selection benchmark, not an eigenvalue solve.

Return type:

FKRWindowResult

Parameters:

  • lundquist (float)

  • ka (tuple[float, ...])

  • max_inner_width_a (float)

  • max_constant_psi_product (float)

mhx.benchmarks.run_forced_turbulent_reconnection_validation(*, shape=(32, 32), width=0.32, resistivity=0.0015, viscosity=0.0015, perturbation_amplitude=0.01, turbulent_flux_amplitude=0.015, turbulent_flow_amplitude=0.015, forcing_amplitude=0.002, dt=0.02, t_end=20.0, save_every=50, seed=11, min_reconnection_proxy_change=0.001, min_current_linf_growth=1e-06, max_relative_energy_growth=2.0, max_magnetic_divergence_linf=1e-10)

Run a 2-D reduced-MHD current sheet with deterministic large-scale forcing.

Return type:

TurbulenceResult

Parameters:

  • shape (tuple[int, int])

  • width (float)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • turbulent_flux_amplitude (float)

  • turbulent_flow_amplitude (float)

  • forcing_amplitude (float)

  • dt (float)

  • t_end (float)

  • save_every (int)

  • seed (int)

  • min_reconnection_proxy_change (float)

  • min_current_linf_growth (float)

  • max_relative_energy_growth (float)

  • max_magnetic_divergence_linf (float)

mhx.benchmarks.run_harris_delta_prime_validation(*, ka=(0.15, 0.25, 0.35, 0.5, 0.7), xmax_over_a=18.0, steps=4000, max_relative_error=1e-08)

Numerically recover the Harris-sheet outer-region Δ'a formula.

For the Harris equilibrium B_y=B_0 tanh(x/a), the ideal outer tearing equation in dimensionless ξ=x/a is

ψ'' - [(ka)^2 - 2 sech^2(ξ)] ψ = 0.

Decaying solutions on each side give the matching parameter

Δ'a = 2 ψ'(0+)/ψ(0) = 2[(ka)^(-1)-ka].

This gate integrates the outer ODE backward from a large positive xmax_over_a using RK4 and compares the recovered matching parameter against the analytic expression. It validates the outer-region tearing target used by FKR scaling; it is not yet the resistive inner-layer eigenvalue problem.

Return type:

HarrisDeltaPrimeResult

Parameters:

  • ka (tuple[float, ...])

  • xmax_over_a (float)

  • steps (int)

  • max_relative_error (float)

mhx.benchmarks.run_linear_tearing_dispersion_validation(*, grid_points=192, half_width=10.0, lundquist=1000.0, wavenumber=(0.3, 0.5, 0.7, 0.9, 1.1, 1.2), reference_wavenumber=0.5, reference_growth_rate=0.0131, max_reference_relative_error=0.06, max_residual_norm=1e-10, max_stable_control_real_part=0.0)

Validate a small Harris-sheet tearing dispersion scan.

This gate applies the same 1D finite-difference reduced-MHD eigenproblem as run_linear_tearing_eigenvalue_validation() to a wavenumber scan. It is intentionally conservative: it checks the unstable interval 0 < ka < 1, stable controls above ka=1, residuals, and the published ka=0.5 reference point. It is not yet a full asymptotic FKR/Coppi dispersion study.

Return type:

LinearTearingDispersionResult

Parameters:

  • grid_points (int)

  • half_width (float)

  • lundquist (float)

  • wavenumber (tuple[float, ...])

  • reference_wavenumber (float)

  • reference_growth_rate (float)

  • max_reference_relative_error (float)

  • max_residual_norm (float)

  • max_stable_control_real_part (float)

mhx.benchmarks.run_linear_tearing_eigenvalue_validation(*, grid_points=(192, 256, 320), half_width=10.0, lundquist=1000.0, wavenumber=0.5, reference_growth_rate=0.0131, stable_control_wavenumber=1.2, stable_control_grid_points=192, max_selected_relative_growth_error=0.03, max_extrapolated_relative_growth_error=0.01, max_stable_control_real_part=0.0, max_residual_norm=1e-10, max_imag_abs=1e-10, min_parity_correlation=0.995)

Solve a direct 1D Harris-sheet tearing eigenproblem and gate it.

The benchmark discretizes the inviscid linear reduced-MHD tearing equations for B_y=tanh(x) with conducting/no-slip Dirichlet perturbation boundaries on [-d, d]:

σ(Du) = i k B Db - i k B'' b and σ b = i k B u + S^{-1}Db, where D=d²/dx²-k².

It gates the unstable eigenvalue at S=1000, k=0.5, and d=10 against the published reduced-MHD reference value γ ≈ 0.0131 while also checking second-order grid extrapolation, residuals, and tearing parity.

Return type:

LinearTearingEigenvalueResult

Parameters:

  • grid_points (tuple[int, ...])

  • half_width (float)

  • lundquist (float)

  • wavenumber (float)

  • reference_growth_rate (float)

  • stable_control_wavenumber (float)

  • stable_control_grid_points (int)

  • max_selected_relative_growth_error (float)

  • max_extrapolated_relative_growth_error (float)

  • max_stable_control_real_part (float)

  • max_residual_norm (float)

  • max_imag_abs (float)

  • min_parity_correlation (float)

mhx.benchmarks.run_linear_tearing_layer_validation(*, grid_points=192, half_width=10.0, lundquist=(250.0, 500.0, 1000.0, 2000.0), wavenumber=0.5, max_residual_norm=1e-10, min_stream_width_contraction=1.25, max_flux_width_relative_spread=0.002, stream_width_slope_bounds=(-0.8, -0.15), growth_rate_slope_bounds=(-0.8, -0.2))

Validate Harris tearing eigenfunction localization over a FAST S scan.

The direct eigenvalue gate proves one growth-rate reference point. This diagnostic adds a conservative eigenfunction-shape check: as S rises, the tearing flow layer around the resonant surface should narrow while the outer magnetic-flux envelope remains nearly unchanged. The fitted exponents are intentionally broad FAST gates, not a production asymptotic FKR/Coppi claim.

Return type:

LinearTearingLayerResult

Parameters:

  • grid_points (int)

  • half_width (float)

  • lundquist (tuple[float, ...])

  • wavenumber (float)

  • max_residual_norm (float)

  • min_stream_width_contraction (float)

  • max_flux_width_relative_spread (float)

  • stream_width_slope_bounds (tuple[float, float])

  • growth_rate_slope_bounds (tuple[float, float])

mhx.benchmarks.run_linear_tearing_smoke(config, *, perturbation_amplitude=0.001)

Run the deterministic FAST reduced-MHD smoke benchmark.

Return type:

tuple[ReducedMHDTrajectory, dict[str, float]]

Parameters:

  • config (RunConfig)

  • perturbation_amplitude (float)

mhx.benchmarks.run_linear_tearing_timedomain_validation(*, grid_points=192, half_width=10.0, lundquist=1000.0, wavenumber=0.5, dt=0.25, t_end=80.0, fit_start_fraction=0.25, max_relative_growth_error=1e-05, max_relative_amplitude_error=0.0001, min_final_mode_alignment=0.999999, max_residual_norm=1e-10)

Replay the Harris tearing eigenmode in time and recover γ.

The gate integrates the finite-dimensional linear system dq/dt=Lq from the direct Harris-sheet eigenvector. The measured norm growth is fitted over the configured time window and compared against the real part of the dense eigenvalue. This validates the growth-rate fitting path independently of any nonlinear or periodic-domain assumptions.

Return type:

LinearTearingTimeDomainResult

Parameters:

  • grid_points (int)

  • half_width (float)

  • lundquist (float)

  • wavenumber (float)

  • dt (float)

  • t_end (float)

  • fit_start_fraction (float)

  • max_relative_growth_error (float)

  • max_relative_amplitude_error (float)

  • min_final_mode_alignment (float)

  • max_residual_norm (float)

mhx.benchmarks.run_linearized_rhs_validation(*, shape=(16, 16), resistivity=0.001, viscosity=0.001, epsilon=0.001, max_relative_error=0.001)

Compare JAX JVP linearization against a centered finite difference.

Return type:

LinearizedRHSResult

Parameters:

  • shape (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

  • epsilon (float)

  • max_relative_error (float)

mhx.benchmarks.run_nonlinear_duration_audit(*, harris_growth_rate=0.0131, requested_linear_efolds=10.0, fast_smoke_t_end=0.1, nonlinear_budget_t_end=0.8, linear_timedomain_t_end=80.0, plasmoid_lundquist=(10000.0, 100000.0, 1000000.0))

Audit whether current nonlinear FAST runs can support island/plasmoid claims.

A growth-rate validation that aims to observe N e-foldings must satisfy t_end >= N/gamma. The current CI nonlinear runs are intentionally much shorter: they validate differentiability, energy signs, and artifact generation, not nonlinear Rutherford-island or plasmoid-chain physics.

Return type:

NonlinearDurationAuditResult

Parameters:

  • harris_growth_rate (float)

  • requested_linear_efolds (float)

  • fast_smoke_t_end (float)

  • nonlinear_budget_t_end (float)

  • linear_timedomain_t_end (float)

  • plasmoid_lundquist (tuple[float, ...])

mhx.benchmarks.run_nonlinear_energy_budget_validation(*, shape=(16, 16), resistivity=0.02, viscosity=0.02, dt=0.01, steps=80, save_every=1, max_budget_residual=2e-05, max_relative_energy_growth=1e-09, min_nonlinear_rhs_ratio=0.05, min_relative_energy_drop=0.01)

Validate the nonlinear reduced-MHD energy/dissipation budget.

For periodic resistive-viscous reduced MHD,

dE/dt = -η <j²> - ν <ω²>,

where E = 0.5<|∇ψ|² + |∇φ|²> and j=-∇²ψ. This benchmark starts from a deliberately nonlinear multi-mode state, advances the full nonlinear RHS with RK4, and gates both monotone energy decay and the integrated budget residual.

Return type:

NonlinearEnergyBudgetResult

Parameters:

  • shape (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

  • dt (float)

  • steps (int)

  • save_every (int)

  • max_budget_residual (float)

  • max_relative_energy_growth (float)

  • min_nonlinear_rhs_ratio (float)

  • min_relative_energy_drop (float)

mhx.benchmarks.run_orszag_tang_vortex_validation(*, shape=(24, 24), resistivity=0.01, viscosity=0.01, dt=0.005, t_end=2.0, save_every=20, min_relative_energy_drop=0.005, max_relative_energy_growth=1e-08, min_current_high_k_growth=1e-06, min_vorticity_high_k_growth=1e-06, max_magnetic_divergence_linf=1e-10)

Run a periodic nonlinear Orszag–Tang reduced-MHD validation.

This is a compact nonlinear benchmark rather than a compressible full-MHD shock-capturing Orszag–Tang run. It verifies that nonlinear advection, magnetic tension, diffusion, spectral current/vorticity diagnostics, and media generation operate coherently on a standard vortex testbed.

Return type:

OrszagTangVortexResult

Parameters:

  • shape (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

  • dt (float)

  • t_end (float)

  • save_every (int)

  • min_relative_energy_drop (float)

  • max_relative_energy_growth (float)

  • min_current_high_k_growth (float)

  • min_vorticity_high_k_growth (float)

  • max_magnetic_divergence_linf (float)

mhx.benchmarks.run_periodic_current_sheet_eigenvalue_validation(*, shape=(8, 8), amplitude=1.0, resistivity=0.02, viscosity=0.02, gauge_eigenvalue_radius=1e-09, max_spurious_growth=1e-09, min_diffusive_decay_fraction=0.25, max_selected_residual_norm=1e-09, max_gauge_residual_norm=1e-10)

Solve a tiny dense JVP spectrum around ψ₀=A cos(y).

This is deliberately not advertised as an FKR growth-rate benchmark. It is a stricter bridge between analytic JVP gates and future tearing calculations: the test assembles the flattened nonzero-equilibrium reduced-MHD operator, checks the two gauge/mean modes, solves the complete dense spectrum on a tiny grid, and verifies that the non-gauge spectrum is damped rather than showing spurious positive growth.

Return type:

PeriodicCurrentSheetEigenvalueResult

Parameters:

  • shape (tuple[int, int])

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • gauge_eigenvalue_radius (float)

  • max_spurious_growth (float)

  • min_diffusive_decay_fraction (float)

  • max_selected_residual_norm (float)

  • max_gauge_residual_norm (float)

mhx.benchmarks.run_periodic_current_sheet_nonlinear_bridge_validation(*, shape=(8, 8), amplitude=1.0, resistivity=0.02, viscosity=0.02, dt=0.02, steps=8, save_every=2, epsilons=(0.01, 0.005, 0.0025, 0.00125), min_convergence_order=1.8, max_finest_relative_error=1e-07)

Validate the nonlinear RK4 time-map derivative around a current sheet.

This benchmark compares the JAX JVP of the complete saved-trajectory map \Phi(q_0) to centered finite differences of nonlinear trajectories:

[\Phi(q_0+\epsilon p)-\Phi(q_0-\epsilon p)]/(2\epsilon).

For smooth reduced-MHD RHS terms and x64 arithmetic, the centered finite-difference error should converge as O(epsilon**2) until roundoff.

Return type:

PeriodicCurrentSheetNonlinearBridgeResult

Parameters:

  • shape (tuple[int, int])

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • dt (float)

  • steps (int)

  • save_every (int)

  • epsilons (tuple[float, ...])

  • min_convergence_order (float)

  • max_finest_relative_error (float)

mhx.benchmarks.run_periodic_current_sheet_timedomain_validation(*, shape=(8, 8), amplitude=1.0, resistivity=0.02, viscosity=0.02, dt=0.05, t_end=5.0, save_every=5, real_eigenvalue_imag_tolerance=1e-08, min_decay_rate=0.001, max_selected_residual_norm=1e-09, max_relative_state_error=1e-08, max_relative_decay_rate_error=1e-08)

Replay a real decaying eigenmode of the periodic current-sheet JVP.

The benchmark assembles the same dense matrix-free JVP operator used by the spectrum gate, selects the least-damped real non-gauge eigenmode, advances dq/dt=Lq with RK4, and compares the trajectory to q(t)=\exp(\lambda t)q(0). This validates the time-domain path without claiming a nonlinear FKR/Coppi tearing result.

Return type:

PeriodicCurrentSheetTimeDomainResult

Parameters:

  • shape (tuple[int, int])

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • dt (float)

  • t_end (float)

  • save_every (int)

  • real_eigenvalue_imag_tolerance (float)

  • min_decay_rate (float)

  • max_selected_residual_norm (float)

  • max_relative_state_error (float)

  • max_relative_decay_rate_error (float)

mhx.benchmarks.run_periodic_double_harris_convergence_validation(*, resolutions=(16, 24), dt_values=(0.02, 0.01), reference_resolution=16, width=0.4, amplitude=1.0, resistivity=0.005, viscosity=0.005, perturbation_amplitude=0.001, perturbation_mode=(2, 1), reference_dt=0.01, t_end=8.0, save_interval=1.0, fit_window=(0.0, 4.0), min_saved_samples=5, min_early_growth_rate=0.001, min_early_growth_factor=1.01, min_max_growth_factor=1.05, max_relative_energy_increase=1e-08, max_relative_growth_rate_spread=1.5, max_relative_max_growth_spread=3.0, max_relative_flux_amplification_spread=3.0, max_relative_width_amplification_spread=3.0)

Run a deterministic tiny convergence sweep for seeded double-Harris replay.

Return type:

PeriodicDoubleHarrisConvergenceResult

Parameters:

  • resolutions (tuple[int, ...])

  • dt_values (tuple[float, ...])

  • reference_resolution (int)

  • width (float)

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • reference_dt (float)

  • t_end (float)

  • save_interval (float)

  • fit_window (tuple[float, float])

  • min_saved_samples (int)

  • min_early_growth_rate (float)

  • min_early_growth_factor (float)

  • min_max_growth_factor (float)

  • max_relative_energy_increase (float)

  • max_relative_growth_rate_spread (float)

  • max_relative_max_growth_spread (float)

  • max_relative_flux_amplification_spread (float)

  • max_relative_width_amplification_spread (float)

mhx.benchmarks.run_periodic_double_harris_nonlinear_growth_validation(*, shape=(8, 8), width=0.4, amplitude=1.0, resistivity=0.005, viscosity=0.005, perturbation_amplitude=1e-06, dt=0.01, t_end=4.0, save_every=20, gauge_eigenvalue_radius=1e-09, min_linear_growth_rate=0.05, min_nonlinear_growth_factor=2.0, max_relative_growth_error=0.15, max_selected_residual_norm=1e-09, max_selected_eigenvalue_imag=1e-08)

Validate nonlinear growth from an unstable double-Harris eigenmode.

The gate closes the gap left by the stable cosine-current-sheet checks. It builds a periodic double-Harris current sheet, assembles the dense matrix-free reduced-MHD Jacobian on a tiny grid, selects the most unstable real eigenmode, then advances two full nonlinear trajectories: the base sheet and the base sheet plus a small eigenmode perturbation. The measured difference norm must grow exponentially at a rate close to the frozen-base eigenvalue.

Return type:

PeriodicDoubleHarrisNonlinearGrowthResult

Parameters:

  • shape (tuple[int, int])

  • width (float)

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • dt (float)

  • t_end (float)

  • save_every (int)

  • gauge_eigenvalue_radius (float)

  • min_linear_growth_rate (float)

  • min_nonlinear_growth_factor (float)

  • max_relative_growth_error (float)

  • max_selected_residual_norm (float)

  • max_selected_eigenvalue_imag (float)

mhx.benchmarks.run_periodic_double_harris_parameter_sweep_validation(*, shape=(16, 16), sweep_axis='width', modes=((2, 1), (2, 2), (4, 1)), widths=(0.35, 0.4, 0.45), resistivities=(0.004, 0.005, 0.006), viscosity_values=None, width=0.4, amplitude=1.0, resistivity=0.005, viscosity=0.005, perturbation_amplitude=0.001, perturbation_mode=(2, 1), dt=0.01, t_end=6.0, save_interval=1.0, fit_window=(0.0, 3.0), min_saved_samples=5, min_early_growth_rate=0.001, min_early_growth_factor=1.01, min_max_growth_factor=1.05, min_reconnected_flux_amplification=1.01, min_island_width_amplification=1.01, max_relative_energy_increase=1e-08, max_relative_growth_rate_spread=10.0, max_relative_max_growth_spread=20.0)

Run a small physical-parameter sweep for seeded double-Harris response.

This gate is intentionally distinct from convergence: it checks that the nonlinear response diagnostics remain finite, dissipative, and visibly reconnecting over a deterministic family of seed modes, sheet widths, or resistivities. The spread limits are anomaly checks, not claims that these physically different cases should agree.

Return type:

PeriodicDoubleHarrisParameterSweepResult

Parameters:

  • shape (tuple[int, int])

  • sweep_axis (str)

  • modes (tuple[tuple[int, int], ...])

  • widths (tuple[float, ...])

  • resistivities (tuple[float, ...])

  • viscosity_values (tuple[float, ...] | None)

  • width (float)

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • dt (float)

  • t_end (float)

  • save_interval (float)

  • fit_window (tuple[float, float])

  • min_saved_samples (int)

  • min_early_growth_rate (float)

  • min_early_growth_factor (float)

  • min_max_growth_factor (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

  • max_relative_energy_increase (float)

  • max_relative_growth_rate_spread (float)

  • max_relative_max_growth_spread (float)

mhx.benchmarks.run_periodic_double_harris_seeded_long_run_validation(*, shape=(64, 64), width=0.4, amplitude=1.0, resistivity=0.005, viscosity=0.005, perturbation_amplitude=0.001, perturbation_mode=(2, 1), dt=0.01, t_end=160.0, save_every=100, fit_window=(0.0, 16.0), duration_label=None, min_saved_samples=8, min_early_growth_rate=0.05, min_early_growth_factor=1.5, min_max_growth_factor=2.0, min_reconnected_flux_amplification=1.05, min_island_width_amplification=1.05, max_relative_energy_increase=1e-08)

Run a longer seeded periodic double-Harris nonlinear replay.

Unlike run_periodic_double_harris_nonlinear_growth_validation(), this benchmark does not assemble a dense Jacobian and does not require the whole trajectory to follow a frozen linear eigenvalue. It is a scalable nonlinear evidence run: the base sheet and a seeded sheet are advanced at the requested resolution, an early-time exponential window is fitted, and the full saved trajectory is checked for finite fields, dissipative total-energy behavior, and sustained resolved current-sheet diagnostics.

Return type:

PeriodicDoubleHarrisSeededLongRunResult

Parameters:

  • shape (tuple[int, int])

  • width (float)

  • amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • dt (float)

  • t_end (float)

  • save_every (int)

  • fit_window (tuple[float, float])

  • duration_label (str | None)

  • min_saved_samples (int)

  • min_early_growth_rate (float)

  • min_early_growth_factor (float)

  • min_max_growth_factor (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

  • max_relative_energy_increase (float)

mhx.benchmarks.run_power_iteration_validation(*, iterations=30, max_eigenvalue_abs_error=1e-06, max_residual_norm=1e-06)

Validate power iteration on a known diagonal matrix-free operator.

Return type:

PowerIterationValidationResult

Parameters:

  • iterations (int)

  • max_eigenvalue_abs_error (float)

  • max_residual_norm (float)

mhx.benchmarks.run_readiness_assessment(validation_suite, *, required_cases=('linear_tearing_fast', 'resistive_decay', 'reconnection_scaling', 'fkr_window', 'fkr_growth_rate', 'harris_delta_prime', 'linear_tearing_eigenvalue', 'linear_tearing_dispersion', 'linear_tearing_layer', 'linear_tearing_timedomain', 'linearized_rhs', 'reduced_mhd_eigenmode', 'cosine_equilibrium_linearization', 'periodic_current_sheet_eigenvalue', 'periodic_current_sheet_timedomain', 'periodic_current_sheet_nonlinear_bridge', 'periodic_double_harris_nonlinear_growth', 'periodic_double_harris_convergence', 'nonlinear_energy_budget', 'orszag_tang_vortex', 'decaying_mhd_turbulence', 'forced_turbulent_reconnection', 'forced_turbulent_reconnection_readiness', 'nonlinear_duration_audit', 'seed_robust_qi', 'seed_robust_qi_sweep', 'neural_ode_reproducibility', 'neural_ode_latent_fit', 'rutherford_production_execution', 'duration_policy', 'diffusion_eigenvalue', 'power_iteration', 'arnoldi'))

Assess whether current artifacts support public release and paper claims.

Return type:

ReadinessAssessment

Parameters:

  • validation_suite (str | Path | dict[str, Any])

  • required_cases (tuple[str, ...])

mhx.benchmarks.run_reconnection_scaling_validation(*, lundquist=(10000.0, 100000.0, 1000000.0, 10000000.0), ka=0.5, max_slope_error=1e-12)

Validate analytic FKR, plasmoid, and ideal-tearing power-law exponents.

Return type:

ReconnectionScalingResult

Parameters:

  • lundquist (tuple[float, ...])

  • ka (float)

  • max_slope_error (float)

mhx.benchmarks.run_reduced_mhd_linear_eigenmode_validation(*, shape=(24, 24), mode=(2, 1), resistivity=0.02, viscosity=0.03, max_eigenvalue_abs_error=1e-06, max_residual_norm=5e-06)

Validate zero-state reduced-MHD linear diffusion eigenmodes.

Return type:

ReducedMHDLinearEigenmodeResult

Parameters:

  • shape (tuple[int, int])

  • mode (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

  • max_eigenvalue_abs_error (float)

  • max_residual_norm (float)

mhx.benchmarks.run_release_candidate_assessment(repo_root='.', *, readiness=None, require_readiness=False)

Assess static repository gates for public release handoff.

This gate is intentionally static and fast. It checks that the repository has packaging, CI, ReadTheDocs, citation, release, examples, media provenance, and current figure-hash metadata. Dynamic physics gates remain owned by mhx validate all, mhx validate readiness, and promoted production campaign reports.

Return type:

ReleaseCandidateAssessment

Parameters:

  • repo_root (str | Path)

  • readiness (str | Path | dict[str, Any] | None)

  • require_readiness (bool)

mhx.benchmarks.run_resistive_decay_validation(*, shape=(32, 32), mode=(1, 0), resistivity=0.05, t1=1.0, dt=0.01, save_every=1, max_relative_amplitude_error=1e-06, max_relative_energy_error=2e-06, max_decay_rate_relative_error=1e-06)

Run a literature-anchored exact Fourier-mode resistive-diffusion gate.

Return type:

ResistiveDecayResult

Parameters:

  • shape (tuple[int, int])

  • mode (tuple[int, int])

  • resistivity (float)

  • t1 (float)

  • dt (float)

  • save_every (int)

  • max_relative_amplitude_error (float)

  • max_relative_energy_error (float)

  • max_decay_rate_relative_error (float)

mhx.benchmarks.run_rutherford_campaign_fast(outdir=None, *, seeds=None, shape=(16, 16), t_end=None, steps=20, dt=0.01, save_every=1, seed=0, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, noise_amplitude=1e-06, mode=(1, 1), magnetic_shear=1.0, max_fast_time=2.0, max_relative_energy_growth=1e-10, max_divergence_linf=1e-10, claim_level='validation', make_figures=True)

Run or write a deterministic FAST Rutherford validation campaign.

With outdir=None this preserves the in-memory single-seed runner. With outdir set, it writes seed-ensemble histories, validation JSON, a manifest, and cheap figures while keeping the claim level at validation or smoke.

Return type:

RutherfordCampaignRunResult | tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path | None)

  • seeds (int | Sequence[int] | None)

  • shape (tuple[int, int])

  • t_end (float | None)

  • steps (int | None)

  • dt (float)

  • save_every (int)

  • seed (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • noise_amplitude (float)

  • mode (tuple[int, int])

  • magnetic_shear (float)

  • max_fast_time (float)

  • max_relative_energy_growth (float)

  • max_divergence_linf (float)

  • claim_level (str)

  • make_figures (bool)

mhx.benchmarks.run_seed_robust_qi(*, seeds=(0, 1, 2, 3), shape=(16, 16), t_end=0.12, dt=0.01, save_every=1, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, noise_amplitude=1e-06, max_gamma_normalized_std=0.05, max_energy_normalized_std=0.001, max_relative_energy_growth=1e-10, max_divergence_linf=1e-10)

Run a deterministic seed ensemble and gate metric sensitivity.

The ensemble perturbs the same coherent tearing seed with smooth low-mode noise. This is not a turbulent-statistics claim; it is a quality indicator that the FAST benchmark metrics are insensitive to tiny admissible seed perturbations.

Return type:

SeedRobustQIResult

Parameters:

  • seeds (tuple[int, ...])

  • shape (tuple[int, int])

  • t_end (float)

  • dt (float)

  • save_every (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • noise_amplitude (float)

  • max_gamma_normalized_std (float)

  • max_energy_normalized_std (float)

  • max_relative_energy_growth (float)

  • max_divergence_linf (float)

mhx.benchmarks.run_seed_robust_qi_sweep(*, shape=(16, 16), seed_count=4, base_seed=20240512, seeds=None, noise_amplitudes=(0.0, 1e-09, 1e-08), perturbation_amplitude=0.001, resistivity=0.001, viscosity=0.001, dt=0.01, steps=12, save_every=1, metric_names=('gamma_fit', 'final_total_energy', 'final_magnetic_energy', 'final_kinetic_energy', 'final_magnetic_divergence_linf'), max_relative_mean_drift=None, max_cv=None, max_divergence_linf=1e-09)

Run a common-seed noise-amplitude sweep and gate metric sensitivity.

This is stronger than a single-amplitude seed ensemble: it checks that FAST diagnostics remain stable both across seeds and across an ordered family of admissible perturbation amplitudes. The default remains intentionally cheap enough for CI.

Return type:

SeedRobustQISweepResult

Parameters:

  • shape (tuple[int, int])

  • seed_count (int)

  • base_seed (int)

  • seeds (Sequence[int] | None)

  • noise_amplitudes (Sequence[float])

  • perturbation_amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • dt (float)

  • steps (int)

  • save_every (int)

  • metric_names (Sequence[str])

  • max_relative_mean_drift (Mapping[str, float] | None)

  • max_cv (Mapping[str, float] | None)

  • max_divergence_linf (float)

mhx.benchmarks.run_seed_robust_qi_validation(*, shape=(16, 16), seed_count=6, base_seed=20240511, seeds=None, perturbation_amplitude=0.001, psi_noise_amplitude=1e-08, omega_noise_amplitude=0.0, resistivity=0.001, viscosity=0.001, dt=0.01, steps=24, save_every=1, mode=(1, 1), fit_time_window=None, metric_names=('gamma_fit', 'final_total_energy', 'final_magnetic_energy', 'final_kinetic_energy', 'final_magnetic_divergence_linf'), gates=None)

Run a tiny seeded reduced-MHD ensemble and validate QI robustness.

Return type:

SeedRobustQIResult

Parameters:

  • shape (tuple[int, int])

  • seed_count (int)

  • base_seed (int)

  • seeds (Sequence[int] | None)

  • perturbation_amplitude (float)

  • psi_noise_amplitude (float)

  • omega_noise_amplitude (float)

  • resistivity (float)

  • viscosity (float)

  • dt (float)

  • steps (int)

  • save_every (int)

  • mode (tuple[int, int])

  • fit_time_window (tuple[float, float] | None)

  • metric_names (Sequence[str])

  • gates (Mapping[str, QIMetricGate] | None)

mhx.benchmarks.run_timing_benchmark(*, repeats=3, warmups=1, cases=('linear_tearing_fast', 'resistive_decay_fast', 'reconnection_scaling'))

Run a small timing matrix without fragile absolute pass/fail thresholds.

Return type:

TimingBenchmarkResult

Parameters:

  • repeats (int)

  • warmups (int)

  • cases (tuple[str, ...])

mhx.benchmarks.seeded_perturbation(shape_or_grid, seed=None, *, amplitude=None, noise_amplitude=None)

Return a deterministic zero-mean seed perturbation.

Passing a CartesianGrid preserves the smooth low-mode perturbation used by the FAST trajectory runner. Passing a shape returns a pure NumPy zero-mean, unit-RMS field for statistical tests and downstream QI tooling.

Return type:

ndarray | Array

Parameters:

  • shape_or_grid (tuple[int, int] | CartesianGrid)

  • seed (int | None)

  • amplitude (float | None)

  • noise_amplitude (float | None)

mhx.benchmarks.seeded_tearing_initial_state(grid, *, seed, perturbation_amplitude=0.001, noise_amplitude=1e-06)

Return a cosine-tearing state with deterministic smooth seed noise.

Return type:

ReducedMHDState

Parameters:

  • grid (CartesianGrid)

  • seed (int)

  • perturbation_amplitude (float)

  • noise_amplitude (float)

mhx.benchmarks.turbulent_initial_state(grid, *, seed=0, flux_amplitude=0.25, flow_amplitude=0.25, kmin=1, kmax=5, spectral_slope=1.6666666666666667)

Return a deterministic broadband reduced-MHD turbulent initial state.

Return type:

ReducedMHDState

Parameters:

  • grid (CartesianGrid)

  • seed (int)

  • flux_amplitude (float)

  • flow_amplitude (float)

  • kmin (int)

  • kmax (int)

  • spectral_slope (float)

mhx.benchmarks.validate_run(run_dir, *, max_relative_energy_growth=1e-10, require_finite_gamma=True)

Validate a run directory against lightweight regression checks.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • max_relative_energy_growth (float)

  • require_finite_gamma (bool)

mhx.benchmarks.validation_catalog_entries()

Return the active reviewer-facing FAST validation catalog.

Return type:

tuple[BenchmarkCatalogEntry, ...]

mhx.benchmarks.validation_suite_cases()

Return the deterministic validation cases executed by mhx validate all.

Return type:

tuple[ValidationSuiteCase, ...]

mhx.benchmarks.write_arnoldi_validation(outdir, **kwargs)

Write Arnoldi validation JSON, NPZ, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_benchmark_catalog(outdir)

Write validation catalog JSON, Markdown, and manifest artifacts.

Return type:

tuple[Path, Path]

Parameters:

outdir (str | Path)

mhx.benchmarks.write_cosine_equilibrium_linearization_validation(outdir, **kwargs)

Write cosine-equilibrium linearization JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_decaying_mhd_turbulence_validation(outdir, *, movies=False, **kwargs)

Write decaying turbulence artifacts and optional movies.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • movies (bool)

  • kwargs (Any)

mhx.benchmarks.write_diffusion_eigenvalue_validation(outdir, **kwargs)

Write diffusion eigenvalue JSON, NPZ, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_duration_policy(outdir, *, harris_growth_rate=0.0131, production_efolds=10.0)

Write duration-policy JSON, Markdown, validation, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • harris_growth_rate (float)

  • production_efolds (float)

mhx.benchmarks.write_fkr_growth_rate_validation(outdir, **kwargs)

Write FKR growth-rate validation JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_fkr_window_validation(outdir, **kwargs)

Write FKR regime-window JSON, NPZ, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_forced_turbulent_reconnection_readiness_report(run_dir, *, outdir=None, require_summary=True, require_movies=False, min_history_samples=20, min_t_end=20.0, min_reconnection_proxy_change=0.001, min_abs_reconnection_rate_proxy=1e-06, max_relative_energy_growth=2.0)

Write a validation-only readiness report for forced turbulent reconnection.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • outdir (str | Path | None)

  • require_summary (bool)

  • require_movies (bool)

  • min_history_samples (int)

  • min_t_end (float)

  • min_reconnection_proxy_change (float)

  • min_abs_reconnection_rate_proxy (float)

  • max_relative_energy_growth (float)

mhx.benchmarks.write_forced_turbulent_reconnection_validation(outdir, *, movies=False, **kwargs)

Write forced turbulent reconnection artifacts and optional movies.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • movies (bool)

  • kwargs (Any)

mhx.benchmarks.write_harris_delta_prime_validation(outdir, **kwargs)

Write Harris outer Delta-prime validation JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_linear_tearing_dispersion_validation(outdir, **kwargs)

Write small Harris-sheet tearing dispersion artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_linear_tearing_eigenvalue_validation(outdir, **kwargs)

Write direct Harris-sheet tearing eigenvalue artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_linear_tearing_layer_validation(outdir, **kwargs)

Write Harris-sheet tearing eigenfunction-layer artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_linear_tearing_timedomain_validation(outdir, **kwargs)

Write Harris-sheet tearing time-domain replay artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_linearized_rhs_validation(outdir, **kwargs)

Write linearized-RHS validation JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_nonlinear_duration_audit(outdir, **kwargs)

Write nonlinear-duration audit JSON, NPZ, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_nonlinear_energy_budget_validation(outdir, **kwargs)

Write nonlinear energy-budget JSON, NPZ, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_orszag_tang_vortex_validation(outdir, *, movies=False, **kwargs)

Write Orszag–Tang JSON, NPZ, figures, optional GIFs, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • movies (bool)

  • kwargs (Any)

mhx.benchmarks.write_paper_pipeline(outdir, *, case_names=None, require_release_ready=True)

Generate validation figures, readiness reports, manifests, and checksums.

With case_names=None this is the full deterministic FAST paper/release pipeline. Tests and local previews can pass a subset and set require_release_ready=False; the resulting manifest is still useful, but it is explicitly marked as an incomplete validation bundle.

Return type:

PaperPipelineResult

Parameters:

  • outdir (str | Path)

  • case_names (tuple[str, ...] | None)

  • require_release_ready (bool)

mhx.benchmarks.write_periodic_current_sheet_eigenvalue_validation(outdir, **kwargs)

Write periodic-current-sheet eigenvalue JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_periodic_current_sheet_nonlinear_bridge_validation(outdir, **kwargs)

Write nonlinear current-sheet differentiability JSON, NPZ, figure, manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_periodic_current_sheet_timedomain_validation(outdir, **kwargs)

Write periodic-current-sheet time-domain JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_periodic_double_harris_convergence_validation(outdir, **kwargs)

Write seeded double-Harris convergence JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_periodic_double_harris_nonlinear_growth_validation(outdir, **kwargs)

Write double-Harris nonlinear-growth JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_periodic_double_harris_parameter_sweep_validation(outdir, **kwargs)

Write seeded double-Harris parameter-sweep JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_periodic_double_harris_promotion_report(run_dir, *, outdir=None, convergence_dirs=(), require_movies=True, min_history_samples=30, min_convergence_dirs=1, min_t_end=30.0, min_reconnected_flux_amplification=1.05, min_island_width_amplification=1.05, max_relative_energy_increase=1e-08)

Write a promotion-boundary report for seeded double-Harris validation.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • outdir (str | Path | None)

  • convergence_dirs (tuple[str | Path, ...])

  • require_movies (bool)

  • min_history_samples (int)

  • min_convergence_dirs (int)

  • min_t_end (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

  • max_relative_energy_increase (float)

mhx.benchmarks.write_periodic_double_harris_seeded_long_run_validation(outdir, *, movies=False, **kwargs)

Write seeded double-Harris long-run JSON, NPZ, figures, GIFs, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • movies (bool)

  • kwargs (Any)

mhx.benchmarks.write_power_iteration_validation(outdir, **kwargs)

Write power-iteration validation JSON, NPZ, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_readiness_report(outdir, validation_suite)

Write readiness JSON, Markdown, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • validation_suite (str | Path | dict[str, Any])

mhx.benchmarks.write_reconnection_scaling_validation(outdir, **kwargs)

Write analytic scaling validation JSON, NPZ, figures, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_reduced_mhd_linear_eigenmode_validation(outdir, **kwargs)

Write reduced-MHD linear eigenmode JSON, NPZ, figure, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_release_candidate_report(outdir, *, repo_root='.', readiness=None, require_readiness=False)

Write release-candidate diagnostics, validation, Markdown, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • repo_root (str | Path)

  • readiness (str | Path | dict[str, Any] | None)

  • require_readiness (bool)

mhx.benchmarks.write_resistive_decay_validation(outdir, **kwargs)

Run the exact-decay validation and write JSON, NPZ, plots, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_run_report(run_dir)

Write JSON and Markdown summaries for a completed run directory.

Return type:

tuple[Path, Path]

Parameters:

run_dir (str | Path)

mhx.benchmarks.write_rutherford_campaign_fast(outdir, *, write_gif=False, **kwargs)

Write a validation-grade Rutherford campaign run artifact bundle.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • write_gif (bool)

  • kwargs (Any)

mhx.benchmarks.write_rutherford_campaign_template(outdir, **kwargs)

Write a reviewer-facing long nonlinear Rutherford-campaign template.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_seed_robust_qi(outdir, **kwargs)

Write seed-robust QI JSON, NPZ, figures, seed trajectories, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

mhx.benchmarks.write_seed_robust_qi_sweep(outdir, *, write_figures=True, **kwargs)

Write seed-robust amplitude-sweep diagnostics and reviewer figures.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • write_figures (bool)

  • kwargs (Any)

mhx.benchmarks.write_seed_robust_qi_validation(outdir, *, write_figures=True, **kwargs)

Write QI diagnostics, validation, ensemble NPZ, optional figures, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • write_figures (bool)

  • kwargs (Any)

mhx.benchmarks.write_timing_benchmark(outdir, *, repeats=3, warmups=1, cases=('linear_tearing_fast', 'resistive_decay_fast', 'reconnection_scaling'))

Write FAST timing JSON, Markdown, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • repeats (int)

  • warmups (int)

  • cases (tuple[str, ...])

mhx.benchmarks.write_validation_suite(outdir, *, cases=None)

Run all selected FAST validation gates and write a suite summary.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

Analytic scaling estimates used by benchmark reports.

class mhx.benchmarks.theory.FKRConstantPsiEstimate(lundquist, ka, delta_prime_a, gamma_tau_a, inner_width_a)

Constant-psi tearing scaling estimate for a Harris-like sheet.

Parameters:

  • lundquist (float)

  • ka (float)

  • delta_prime_a (float)

  • gamma_tau_a (float)

  • inner_width_a (float)

to_dict()

Return JSON-compatible values.

Return type:

dict[str, float]

class mhx.benchmarks.theory.PlasmoidScalingEstimate(lundquist, gamma_tau_a, fastest_mode_k_l)

Loureiro-type Sweet-Parker plasmoid scaling estimate.

Parameters:

  • lundquist (float)

  • gamma_tau_a (float)

  • fastest_mode_k_l (float)

to_dict()

Return JSON-compatible values.

Return type:

dict[str, float]

mhx.benchmarks.theory.fkr_constant_psi_estimate(lundquist, ka)

Return a dimensionless FKR constant-psi tearing scaling estimate.

The estimate intentionally omits order-unity coefficients:

γ τ_a ~ S_a^(-3/5) (ka)^(2/5) (Δ'a)^(4/5).

Return type:

FKRConstantPsiEstimate

Parameters:

  • lundquist (float)

  • ka (float)

mhx.benchmarks.theory.harris_sheet_delta_prime(ka)

Return the Harris-sheet outer-region proxy Δ' a = 2(1/(ka) - ka).

Return type:

float

Parameters:

ka (float)

mhx.benchmarks.theory.ideal_tearing_aspect_ratio(lundquist)

Return Pucci-Velli ideal-tearing scaling a/L ~ S^(-1/3).

Return type:

float

Parameters:

lundquist (float)

mhx.benchmarks.theory.loureiro_plasmoid_estimate(lundquist)

Return Sweet-Parker plasmoid estimates γτ_A ~ S^(1/4), kL ~ S^(3/8).

Return type:

PlasmoidScalingEstimate

Parameters:

lundquist (float)

Exact resistive-decay validation benchmark.

class mhx.benchmarks.decay.ResistiveDecayResult(trajectory, exact_psi, numerical_amplitude, exact_amplitude, numerical_energy, exact_energy, relative_amplitude_error, relative_energy_error, diagnostics, validation)

Numerical and exact histories for one Fourier-mode diffusion benchmark.

Parameters:

  • trajectory (ReducedMHDTrajectory)

  • exact_psi (Array)

  • numerical_amplitude (Array)

  • exact_amplitude (Array)

  • numerical_energy (Array)

  • exact_energy (Array)

  • relative_amplitude_error (Array)

  • relative_energy_error (Array)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

mhx.benchmarks.decay.resistive_decay_rate(*, resistivity, mode, lengths)

Return the exact scalar decay rate η|k|² for one periodic mode.

Return type:

float

Parameters:

  • resistivity (float)

  • mode (tuple[int, int])

  • lengths (tuple[float, float])

mhx.benchmarks.decay.run_resistive_decay_validation(*, shape=(32, 32), mode=(1, 0), resistivity=0.05, t1=1.0, dt=0.01, save_every=1, max_relative_amplitude_error=1e-06, max_relative_energy_error=2e-06, max_decay_rate_relative_error=1e-06)

Run a literature-anchored exact Fourier-mode resistive-diffusion gate.

Return type:

ResistiveDecayResult

Parameters:

  • shape (tuple[int, int])

  • mode (tuple[int, int])

  • resistivity (float)

  • t1 (float)

  • dt (float)

  • save_every (int)

  • max_relative_amplitude_error (float)

  • max_relative_energy_error (float)

  • max_decay_rate_relative_error (float)

mhx.benchmarks.decay.write_resistive_decay_validation(outdir, **kwargs)

Run the exact-decay validation and write JSON, NPZ, plots, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

Literature-anchored reconnection scaling validation artifacts.

class mhx.benchmarks.scaling.ReconnectionScalingResult(lundquist, fkr_gamma, fkr_inner_width, plasmoid_gamma, plasmoid_mode, ideal_aspect_ratio, diagnostics, validation)

Computed scaling arrays and pass/fail gates for analytic reconnection theory.

Parameters:

  • lundquist (ndarray)

  • fkr_gamma (ndarray)

  • fkr_inner_width (ndarray)

  • plasmoid_gamma (ndarray)

  • plasmoid_mode (ndarray)

  • ideal_aspect_ratio (ndarray)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

mhx.benchmarks.scaling.loglog_slope(x, y)

Return least-squares slope of log(y) against log(x).

Return type:

float

Parameters:

  • x (ndarray)

  • y (ndarray)

mhx.benchmarks.scaling.run_reconnection_scaling_validation(*, lundquist=(10000.0, 100000.0, 1000000.0, 10000000.0), ka=0.5, max_slope_error=1e-12)

Validate analytic FKR, plasmoid, and ideal-tearing power-law exponents.

Return type:

ReconnectionScalingResult

Parameters:

  • lundquist (tuple[float, ...])

  • ka (float)

  • max_slope_error (float)

mhx.benchmarks.scaling.write_reconnection_scaling_validation(outdir, **kwargs)

Write analytic scaling validation JSON, NPZ, figures, and manifest.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • kwargs (Any)

Deterministic FAST timing artifacts for reviewer-facing performance tracking.

class mhx.benchmarks.timing.TimingBenchmarkResult(cases, diagnostics)

Timing benchmark results and environment metadata.

Parameters:
class mhx.benchmarks.timing.TimingCaseResult(name, durations_seconds, peak_tracemalloc_bytes, details)

Timing summary for one benchmark case.

Parameters:

  • name (str)

  • durations_seconds (tuple[float, ...])

  • peak_tracemalloc_bytes (tuple[int, ...])

  • details (dict[str, Any])

property summary: dict[str, float]

Return stable scalar summary statistics for the measured repeats.

to_dict()

Serialize the timing case to JSON-compatible builtins.

Return type:

dict[str, Any]

mhx.benchmarks.timing.run_timing_benchmark(*, repeats=3, warmups=1, cases=('linear_tearing_fast', 'resistive_decay_fast', 'reconnection_scaling'))

Run a small timing matrix without fragile absolute pass/fail thresholds.

Return type:

TimingBenchmarkResult

Parameters:

  • repeats (int)

  • warmups (int)

  • cases (tuple[str, ...])

mhx.benchmarks.timing.write_timing_benchmark(outdir, *, repeats=3, warmups=1, cases=('linear_tearing_fast', 'resistive_decay_fast', 'reconnection_scaling'))

Write FAST timing JSON, Markdown, figure, and manifest artifacts.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • repeats (int)

  • warmups (int)

  • cases (tuple[str, ...])

Deterministic neural-ODE reproducibility datasets and baseline artifacts.

class mhx.neural_ode.BaselineEvaluation(metrics, calibration, predictions)

Baseline metrics, calibration summaries, and prediction arrays.

Parameters:

  • metrics (dict[str, Any])

  • calibration (dict[str, Any])

  • predictions (dict[str, ndarray])

class mhx.neural_ode.LatentODEFit(model, metrics, predictions, validation)

Deterministic random-feature latent-ODE fit and forecast metrics.

Parameters:

  • model (dict[str, Any])

  • metrics (dict[str, Any])

  • predictions (ndarray)

  • validation (dict[str, Any])

class mhx.neural_ode.NeuralODEDataset(seeds, times, features, targets, feature_names, target_names, diagnostics, source_diagnostics)

Array bundle for deterministic reduced-MHD neural-ODE experiments.

Parameters:

  • seeds (ndarray)

  • times (ndarray)

  • features (ndarray)

  • targets (ndarray)

  • feature_names (tuple[str, ...])

  • target_names (tuple[str, ...])

  • diagnostics (dict[str, Any])

  • source_diagnostics (dict[str, Any])

class mhx.neural_ode.SplitManifest(train, validation, test, diagnostics)

Deterministic train/validation/test sample split.

Parameters:

  • train (tuple[int, ...])

  • validation (tuple[int, ...])

  • test (tuple[int, ...])

  • diagnostics (dict[str, Any])

mhx.neural_ode.build_seed_qi_trajectory_dataset(*, shape=(16, 16), seeds=None, seed_count=6, base_seed=20240511, steps=24, dt=0.01, save_every=1, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, psi_noise_amplitude=1e-08, mode=(1, 1), target_names=('mode_amplitude', 'total_energy', 'magnetic_divergence_linf'))

Build a deterministic seed-QI trajectory dataset for neural-ODE studies.

The dataset shape is (n_seed, n_time, n_feature). Targets are selected by name from the feature tensor so baseline and neural-ODE experiments use exactly the same time grid and target convention.

Return type:

NeuralODEDataset

Parameters:

  • shape (tuple[int, int])

  • seeds (Sequence[int] | None)

  • seed_count (int)

  • base_seed (int)

  • steps (int)

  • dt (float)

  • save_every (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • psi_noise_amplitude (float)

  • mode (tuple[int, int])

  • target_names (Sequence[str])

mhx.neural_ode.evaluate_baselines(dataset, split, *, observation_count=2)

Evaluate deterministic no-training baselines and calibration coverage.

Return type:

BaselineEvaluation

Parameters:
mhx.neural_ode.evaluate_latent_ode_failure_modes(dataset, split, baseline, latent, *, observation_count=2)

Return deterministic failure-mode diagnostics for the fitted latent ODE.

Return type:

dict[str, Any]

Parameters:
mhx.neural_ode.fit_latent_ode(dataset, split, baseline, *, observation_count=2, hidden_size=8, ridge=1e-08, random_seed=0)

Fit a deterministic random-feature neural ODE to train trajectories.

The model uses the autonomous form dz/dt = W phi(z) where z is the target vector and phi concatenates z, random tanh features, and a constant bias. W is solved by ridge regression from train-set finite differences, then integrated forward with explicit Euler on the saved time grid.

Return type:

LatentODEFit

Parameters:
mhx.neural_ode.make_train_val_test_split(sample_ids, *, split_seed=0, train_fraction=0.5, validation_fraction=0.25)

Return deterministic disjoint train/validation/test split indices.

Return type:

SplitManifest

Parameters:

  • sample_ids (Sequence[int])

  • split_seed (int)

  • train_fraction (float)

  • validation_fraction (float)

mhx.neural_ode.write_neural_ode_reproducibility_bundle(outdir, *, shape=(16, 16), seeds=None, seed_count=6, base_seed=20240511, split_seed=314159, steps=24, dt=0.01, save_every=1, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, psi_noise_amplitude=1e-08, observation_count=2, write_figures=True)

Write a complete deterministic neural-ODE reproducibility bundle.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • shape (tuple[int, int])

  • seeds (Sequence[int] | None)

  • seed_count (int)

  • base_seed (int)

  • split_seed (int)

  • steps (int)

  • dt (float)

  • save_every (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • psi_noise_amplitude (float)

  • observation_count (int)

  • write_figures (bool)

mhx.neural_ode.write_neural_ode_training_bundle(outdir, *, shape=(16, 16), seeds=None, seed_count=6, base_seed=20240511, split_seed=314159, steps=24, dt=0.01, save_every=1, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, psi_noise_amplitude=1e-08, observation_count=2, hidden_size=8, ridge=1e-08, model_seed=0, write_figures=True)

Write dataset, baselines, fitted latent ODE, predictions, and figures.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • shape (tuple[int, int])

  • seeds (Sequence[int] | None)

  • seed_count (int)

  • base_seed (int)

  • split_seed (int)

  • steps (int)

  • dt (float)

  • save_every (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • psi_noise_amplitude (float)

  • observation_count (int)

  • hidden_size (int)

  • ridge (float)

  • model_seed (int)

  • write_figures (bool)

Deterministic neural-ODE dataset, baseline, and fitted latent-ODE artifacts.

This module freezes the data contract that neural-ODE experiments consume and ships a deterministic random-feature latent ODE fit. The fit is deliberately small enough for CI, but it is a real train/validation/test experiment with baselines, calibration, model parameters, predictions, figures, and hashes.

class mhx.neural_ode.reproducibility.BaselineEvaluation(metrics, calibration, predictions)

Baseline metrics, calibration summaries, and prediction arrays.

Parameters:

  • metrics (dict[str, Any])

  • calibration (dict[str, Any])

  • predictions (dict[str, ndarray])

class mhx.neural_ode.reproducibility.LatentODEFit(model, metrics, predictions, validation)

Deterministic random-feature latent-ODE fit and forecast metrics.

Parameters:

  • model (dict[str, Any])

  • metrics (dict[str, Any])

  • predictions (ndarray)

  • validation (dict[str, Any])

class mhx.neural_ode.reproducibility.NeuralODEDataset(seeds, times, features, targets, feature_names, target_names, diagnostics, source_diagnostics)

Array bundle for deterministic reduced-MHD neural-ODE experiments.

Parameters:

  • seeds (ndarray)

  • times (ndarray)

  • features (ndarray)

  • targets (ndarray)

  • feature_names (tuple[str, ...])

  • target_names (tuple[str, ...])

  • diagnostics (dict[str, Any])

  • source_diagnostics (dict[str, Any])

class mhx.neural_ode.reproducibility.SplitManifest(train, validation, test, diagnostics)

Deterministic train/validation/test sample split.

Parameters:

  • train (tuple[int, ...])

  • validation (tuple[int, ...])

  • test (tuple[int, ...])

  • diagnostics (dict[str, Any])

mhx.neural_ode.reproducibility.build_seed_qi_trajectory_dataset(*, shape=(16, 16), seeds=None, seed_count=6, base_seed=20240511, steps=24, dt=0.01, save_every=1, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, psi_noise_amplitude=1e-08, mode=(1, 1), target_names=('mode_amplitude', 'total_energy', 'magnetic_divergence_linf'))

Build a deterministic seed-QI trajectory dataset for neural-ODE studies.

The dataset shape is (n_seed, n_time, n_feature). Targets are selected by name from the feature tensor so baseline and neural-ODE experiments use exactly the same time grid and target convention.

Return type:

NeuralODEDataset

Parameters:

  • shape (tuple[int, int])

  • seeds (Sequence[int] | None)

  • seed_count (int)

  • base_seed (int)

  • steps (int)

  • dt (float)

  • save_every (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • psi_noise_amplitude (float)

  • mode (tuple[int, int])

  • target_names (Sequence[str])

mhx.neural_ode.reproducibility.evaluate_baselines(dataset, split, *, observation_count=2)

Evaluate deterministic no-training baselines and calibration coverage.

Return type:

BaselineEvaluation

Parameters:
mhx.neural_ode.reproducibility.evaluate_latent_ode_failure_modes(dataset, split, baseline, latent, *, observation_count=2)

Return deterministic failure-mode diagnostics for the fitted latent ODE.

Return type:

dict[str, Any]

Parameters:
mhx.neural_ode.reproducibility.fit_latent_ode(dataset, split, baseline, *, observation_count=2, hidden_size=8, ridge=1e-08, random_seed=0)

Fit a deterministic random-feature neural ODE to train trajectories.

The model uses the autonomous form dz/dt = W phi(z) where z is the target vector and phi concatenates z, random tanh features, and a constant bias. W is solved by ridge regression from train-set finite differences, then integrated forward with explicit Euler on the saved time grid.

Return type:

LatentODEFit

Parameters:
mhx.neural_ode.reproducibility.make_train_val_test_split(sample_ids, *, split_seed=0, train_fraction=0.5, validation_fraction=0.25)

Return deterministic disjoint train/validation/test split indices.

Return type:

SplitManifest

Parameters:

  • sample_ids (Sequence[int])

  • split_seed (int)

  • train_fraction (float)

  • validation_fraction (float)

mhx.neural_ode.reproducibility.write_neural_ode_reproducibility_bundle(outdir, *, shape=(16, 16), seeds=None, seed_count=6, base_seed=20240511, split_seed=314159, steps=24, dt=0.01, save_every=1, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, psi_noise_amplitude=1e-08, observation_count=2, write_figures=True)

Write a complete deterministic neural-ODE reproducibility bundle.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • shape (tuple[int, int])

  • seeds (Sequence[int] | None)

  • seed_count (int)

  • base_seed (int)

  • split_seed (int)

  • steps (int)

  • dt (float)

  • save_every (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • psi_noise_amplitude (float)

  • observation_count (int)

  • write_figures (bool)

mhx.neural_ode.reproducibility.write_neural_ode_training_bundle(outdir, *, shape=(16, 16), seeds=None, seed_count=6, base_seed=20240511, split_seed=314159, steps=24, dt=0.01, save_every=1, resistivity=0.001, viscosity=0.001, perturbation_amplitude=0.001, psi_noise_amplitude=1e-08, observation_count=2, hidden_size=8, ridge=1e-08, model_seed=0, write_figures=True)

Write dataset, baselines, fitted latent ODE, predictions, and figures.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • shape (tuple[int, int])

  • seeds (Sequence[int] | None)

  • seed_count (int)

  • base_seed (int)

  • split_seed (int)

  • steps (int)

  • dt (float)

  • save_every (int)

  • resistivity (float)

  • viscosity (float)

  • perturbation_amplitude (float)

  • psi_noise_amplitude (float)

  • observation_count (int)

  • hidden_size (int)

  • ridge (float)

  • model_seed (int)

  • write_figures (bool)

Production campaign planning and checkpoint/resume contracts.

class mhx.campaigns.ProductionCampaignPlan(config, walltime_policy, diagnostics, validation, runbook_markdown, checkpoint_index, job_array)

A duration-guarded production campaign plan that does not run the solver.

Parameters:

  • config (RunConfig)

  • walltime_policy (WalltimePolicy)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

  • runbook_markdown (str)

  • checkpoint_index (dict[str, Any])

  • job_array (dict[str, Any])

class mhx.campaigns.ProductionExecutionResult(run_dir, start_step, end_step, target_step, completed_target, diagnostics, validation)

A completed walltime chunk from a Rutherford campaign executor.

Parameters:

  • run_dir (Path)

  • start_step (int)

  • end_step (int)

  • target_step (int)

  • completed_target (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.campaigns.ProductionPromotionAssessment(run_dir, promotion_ready, diagnostics, validation)

Reviewer-facing readiness assessment for promoting a run to production.

Parameters:

  • run_dir (Path)

  • promotion_ready (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.campaigns.ResumePlan(run_dir, checkpoint, start_step, target_step, remaining_steps, chunks_remaining, validation, command_contract)

Resume selection for a production campaign checkpoint index.

Parameters:

  • run_dir (Path)

  • checkpoint (dict[str, Any] | None)

  • start_step (int)

  • target_step (int)

  • remaining_steps (int)

  • chunks_remaining (int)

  • validation (dict[str, Any])

  • command_contract (dict[str, Any])

to_dict()

Return a JSON-compatible resume plan.

Return type:

dict[str, Any]

class mhx.campaigns.WalltimePolicy(max_walltime_hours=12.0, seconds_per_step_estimate=0.5, checkpoint_interval_minutes=30.0, preemption_margin_minutes=20.0, min_steps_per_job=1)

Walltime and checkpoint cadence for long nonlinear campaigns.

Parameters:

  • max_walltime_hours (float)

  • seconds_per_step_estimate (float)

  • checkpoint_interval_minutes (float)

  • preemption_margin_minutes (float)

  • min_steps_per_job (int)

checkpoint_every_steps()

Conservative step interval between checkpoint records.

Return type:

int

property checkpoint_interval_seconds: float

Target checkpoint cadence in seconds.

property max_walltime_seconds: float

Scheduler walltime budget in seconds.

steps_per_walltime_job()

Conservative number of steps in one scheduler allocation.

Return type:

int

to_dict()

Return JSON-compatible walltime policy values.

Return type:

dict[str, Any]

property usable_walltime_seconds: float

Walltime remaining after reserving the preemption margin.

validated()

Return a validated copy or raise with a precise configuration error.

Return type:

WalltimePolicy

mhx.campaigns.assess_rutherford_production_promotion(run_dir, *, convergence_dirs=(), seed_qi_dir=None, require_movies=True, min_history_samples=100, min_convergence_dirs=2, max_energy_budget_residual=1e-09, max_divergence_linf=1e-09, min_reconnected_flux_amplification=1.05, min_island_width_amplification=1.05)

Assess whether a Rutherford execution bundle is ready for production claims.

This is intentionally stricter than the chunk executor. The executor proves that a restartable path can advance and resume; this promotion gate requires completed target time, fixed-scale media, convergence artifacts, seed-QI evidence, current-sheet geometry, finite histories, and tolerances before a reviewer-facing nonlinear claim can be made.

Return type:

ProductionPromotionAssessment

Parameters:

  • run_dir (str | Path)

  • convergence_dirs (tuple[str | Path, ...])

  • seed_qi_dir (str | Path | None)

  • require_movies (bool)

  • min_history_samples (int)

  • min_convergence_dirs (int)

  • max_energy_budget_residual (float)

  • max_divergence_linf (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

mhx.campaigns.execute_rutherford_production_campaign(run_dir, *, max_steps=None, seed=0, noise_amplitude=1e-06, write_movies=False, allow_production_claim=False, max_relative_energy_growth=1e-09, max_divergence_linf=1e-09, walltime_elapsed_seconds=0.0)

Execute a real restartable Rutherford campaign chunk.

Return type:

ProductionExecutionResult

Parameters:

  • run_dir (str | Path)

  • max_steps (int | None)

  • seed (int)

  • noise_amplitude (float)

  • write_movies (bool)

  • allow_production_claim (bool)

  • max_relative_energy_growth (float)

  • max_divergence_linf (float)

  • walltime_elapsed_seconds (float)

mhx.campaigns.load_checkpoint_index(run_dir, *, create_if_missing=False)

Load a checkpoint index, optionally creating a minimal empty index.

Return type:

dict[str, Any]

Parameters:

  • run_dir (str | Path)

  • create_if_missing (bool)

mhx.campaigns.plan_rutherford_production_campaign(*, harris_growth_rate=0.0131, production_efolds=10.0, safety_factor=3.0, shape=(128, 128), dt=0.1, target_saved_frames=400, run_output_dir='outputs/production/rutherford_island', min_production_resolution=96, walltime_policy=None, equilibrium='cosine_tearing', width=0.4, amplitude=1.0, perturbation_amplitude=0.001, perturbation_mode=(1, 1), resistivity=0.001, viscosity=0.001)

Build a production Rutherford campaign plan without advancing the PDE.

Return type:

ProductionCampaignPlan

Parameters:

  • harris_growth_rate (float)

  • production_efolds (float)

  • safety_factor (float)

  • shape (tuple[int, int])

  • dt (float)

  • target_saved_frames (int)

  • run_output_dir (str | Path)

  • min_production_resolution (int)

  • walltime_policy (WalltimePolicy | None)

  • equilibrium (str)

  • width (float)

  • amplitude (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

mhx.campaigns.select_resume_checkpoint(run_dir, *, target_step=None)

Select the latest valid checkpoint and return a deterministic resume plan.

Return type:

ResumePlan

Parameters:

  • run_dir (str | Path)

  • target_step (int | None)

mhx.campaigns.write_checkpoint_metadata(run_dir, *, step, time, state_path, history_path=None, diagnostics_path=None, walltime_elapsed_seconds=0.0, metrics=None, completed=False)

Write a checkpoint metadata record and update checkpoint_index.json.

Return type:

Path

Parameters:

  • run_dir (str | Path)

  • step (int)

  • time (float)

  • state_path (str | Path)

  • history_path (str | Path | None)

  • diagnostics_path (str | Path | None)

  • walltime_elapsed_seconds (float)

  • metrics (dict[str, float] | None)

  • completed (bool)

mhx.campaigns.write_rutherford_production_execution(run_dir, *, max_steps=None, seed=0, noise_amplitude=1e-06, write_movies=False, allow_production_claim=False, max_relative_energy_growth=1e-09, max_divergence_linf=1e-09, walltime_elapsed_seconds=0.0)

Run one restartable Rutherford campaign chunk and write real artifacts.

The function consumes campaign_plan.json and checkpoints/ in run_dir. If no checkpoint is valid it starts from the deterministic initial condition; otherwise it resumes from the latest valid state. Small CI runs normally use max_steps and keep claim_level = validation. A completed target run can only emit claim_level = production when allow_production_claim is set and all execution gates pass.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • max_steps (int | None)

  • seed (int)

  • noise_amplitude (float)

  • write_movies (bool)

  • allow_production_claim (bool)

  • max_relative_energy_growth (float)

  • max_divergence_linf (float)

  • walltime_elapsed_seconds (float)

mhx.campaigns.write_rutherford_production_plan(outdir, *, harris_growth_rate=0.0131, production_efolds=10.0, safety_factor=3.0, shape=(128, 128), dt=0.1, target_saved_frames=400, run_output_dir=None, min_production_resolution=96, walltime_policy=None, equilibrium='cosine_tearing', width=0.4, amplitude=1.0, perturbation_amplitude=0.001, perturbation_mode=(1, 1), resistivity=0.001, viscosity=0.001)

Write production-plan artifacts and an initialized checkpoint index.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • harris_growth_rate (float)

  • production_efolds (float)

  • safety_factor (float)

  • shape (tuple[int, int])

  • dt (float)

  • target_saved_frames (int)

  • run_output_dir (str | Path | None)

  • min_production_resolution (int)

  • walltime_policy (WalltimePolicy | None)

  • equilibrium (str)

  • width (float)

  • amplitude (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

mhx.campaigns.write_rutherford_production_promotion_report(run_dir, *, outdir=None, convergence_dirs=(), seed_qi_dir=None, require_movies=True, min_history_samples=100, min_convergence_dirs=2, max_energy_budget_residual=1e-09, max_divergence_linf=1e-09, min_reconnected_flux_amplification=1.05, min_island_width_amplification=1.05)

Write a promotion-readiness report and manifest for a campaign bundle.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • outdir (str | Path | None)

  • convergence_dirs (tuple[str | Path, ...])

  • seed_qi_dir (str | Path | None)

  • require_movies (bool)

  • min_history_samples (int)

  • min_convergence_dirs (int)

  • max_energy_budget_residual (float)

  • max_divergence_linf (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

mhx.campaigns.write_rutherford_resume_plan(run_dir, *, target_step=None)

Write resume_plan.json for the latest valid checkpoint.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • target_step (int | None)

Production Rutherford-campaign planning, execution, and checkpoint metadata.

This module defines the reviewer-facing contract that a production executor must satisfy: duration gates, walltime chunking, checkpoint records, resume selection, histories, movies, and artifact manifests. The executor can run small validation chunks in CI and the same code path can continue a long campaign on a scheduler without changing schemas.

class mhx.campaigns.production.ProductionCampaignPlan(config, walltime_policy, diagnostics, validation, runbook_markdown, checkpoint_index, job_array)

A duration-guarded production campaign plan that does not run the solver.

Parameters:

  • config (RunConfig)

  • walltime_policy (WalltimePolicy)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

  • runbook_markdown (str)

  • checkpoint_index (dict[str, Any])

  • job_array (dict[str, Any])

class mhx.campaigns.production.ProductionExecutionResult(run_dir, start_step, end_step, target_step, completed_target, diagnostics, validation)

A completed walltime chunk from a Rutherford campaign executor.

Parameters:

  • run_dir (Path)

  • start_step (int)

  • end_step (int)

  • target_step (int)

  • completed_target (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.campaigns.production.ProductionPromotionAssessment(run_dir, promotion_ready, diagnostics, validation)

Reviewer-facing readiness assessment for promoting a run to production.

Parameters:

  • run_dir (Path)

  • promotion_ready (bool)

  • diagnostics (dict[str, Any])

  • validation (dict[str, Any])

class mhx.campaigns.production.ResumePlan(run_dir, checkpoint, start_step, target_step, remaining_steps, chunks_remaining, validation, command_contract)

Resume selection for a production campaign checkpoint index.

Parameters:

  • run_dir (Path)

  • checkpoint (dict[str, Any] | None)

  • start_step (int)

  • target_step (int)

  • remaining_steps (int)

  • chunks_remaining (int)

  • validation (dict[str, Any])

  • command_contract (dict[str, Any])

to_dict()

Return a JSON-compatible resume plan.

Return type:

dict[str, Any]

class mhx.campaigns.production.WalltimePolicy(max_walltime_hours=12.0, seconds_per_step_estimate=0.5, checkpoint_interval_minutes=30.0, preemption_margin_minutes=20.0, min_steps_per_job=1)

Walltime and checkpoint cadence for long nonlinear campaigns.

Parameters:

  • max_walltime_hours (float)

  • seconds_per_step_estimate (float)

  • checkpoint_interval_minutes (float)

  • preemption_margin_minutes (float)

  • min_steps_per_job (int)

checkpoint_every_steps()

Conservative step interval between checkpoint records.

Return type:

int

property checkpoint_interval_seconds: float

Target checkpoint cadence in seconds.

property max_walltime_seconds: float

Scheduler walltime budget in seconds.

steps_per_walltime_job()

Conservative number of steps in one scheduler allocation.

Return type:

int

to_dict()

Return JSON-compatible walltime policy values.

Return type:

dict[str, Any]

property usable_walltime_seconds: float

Walltime remaining after reserving the preemption margin.

validated()

Return a validated copy or raise with a precise configuration error.

Return type:

WalltimePolicy

mhx.campaigns.production.assess_rutherford_production_promotion(run_dir, *, convergence_dirs=(), seed_qi_dir=None, require_movies=True, min_history_samples=100, min_convergence_dirs=2, max_energy_budget_residual=1e-09, max_divergence_linf=1e-09, min_reconnected_flux_amplification=1.05, min_island_width_amplification=1.05)

Assess whether a Rutherford execution bundle is ready for production claims.

This is intentionally stricter than the chunk executor. The executor proves that a restartable path can advance and resume; this promotion gate requires completed target time, fixed-scale media, convergence artifacts, seed-QI evidence, current-sheet geometry, finite histories, and tolerances before a reviewer-facing nonlinear claim can be made.

Return type:

ProductionPromotionAssessment

Parameters:

  • run_dir (str | Path)

  • convergence_dirs (tuple[str | Path, ...])

  • seed_qi_dir (str | Path | None)

  • require_movies (bool)

  • min_history_samples (int)

  • min_convergence_dirs (int)

  • max_energy_budget_residual (float)

  • max_divergence_linf (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

mhx.campaigns.production.execute_rutherford_production_campaign(run_dir, *, max_steps=None, seed=0, noise_amplitude=1e-06, write_movies=False, allow_production_claim=False, max_relative_energy_growth=1e-09, max_divergence_linf=1e-09, walltime_elapsed_seconds=0.0)

Execute a real restartable Rutherford campaign chunk.

Return type:

ProductionExecutionResult

Parameters:

  • run_dir (str | Path)

  • max_steps (int | None)

  • seed (int)

  • noise_amplitude (float)

  • write_movies (bool)

  • allow_production_claim (bool)

  • max_relative_energy_growth (float)

  • max_divergence_linf (float)

  • walltime_elapsed_seconds (float)

mhx.campaigns.production.load_checkpoint_index(run_dir, *, create_if_missing=False)

Load a checkpoint index, optionally creating a minimal empty index.

Return type:

dict[str, Any]

Parameters:

  • run_dir (str | Path)

  • create_if_missing (bool)

mhx.campaigns.production.plan_rutherford_production_campaign(*, harris_growth_rate=0.0131, production_efolds=10.0, safety_factor=3.0, shape=(128, 128), dt=0.1, target_saved_frames=400, run_output_dir='outputs/production/rutherford_island', min_production_resolution=96, walltime_policy=None, equilibrium='cosine_tearing', width=0.4, amplitude=1.0, perturbation_amplitude=0.001, perturbation_mode=(1, 1), resistivity=0.001, viscosity=0.001)

Build a production Rutherford campaign plan without advancing the PDE.

Return type:

ProductionCampaignPlan

Parameters:

  • harris_growth_rate (float)

  • production_efolds (float)

  • safety_factor (float)

  • shape (tuple[int, int])

  • dt (float)

  • target_saved_frames (int)

  • run_output_dir (str | Path)

  • min_production_resolution (int)

  • walltime_policy (WalltimePolicy | None)

  • equilibrium (str)

  • width (float)

  • amplitude (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

mhx.campaigns.production.select_resume_checkpoint(run_dir, *, target_step=None)

Select the latest valid checkpoint and return a deterministic resume plan.

Return type:

ResumePlan

Parameters:

  • run_dir (str | Path)

  • target_step (int | None)

mhx.campaigns.production.write_checkpoint_metadata(run_dir, *, step, time, state_path, history_path=None, diagnostics_path=None, walltime_elapsed_seconds=0.0, metrics=None, completed=False)

Write a checkpoint metadata record and update checkpoint_index.json.

Return type:

Path

Parameters:

  • run_dir (str | Path)

  • step (int)

  • time (float)

  • state_path (str | Path)

  • history_path (str | Path | None)

  • diagnostics_path (str | Path | None)

  • walltime_elapsed_seconds (float)

  • metrics (dict[str, float] | None)

  • completed (bool)

mhx.campaigns.production.write_rutherford_production_execution(run_dir, *, max_steps=None, seed=0, noise_amplitude=1e-06, write_movies=False, allow_production_claim=False, max_relative_energy_growth=1e-09, max_divergence_linf=1e-09, walltime_elapsed_seconds=0.0)

Run one restartable Rutherford campaign chunk and write real artifacts.

The function consumes campaign_plan.json and checkpoints/ in run_dir. If no checkpoint is valid it starts from the deterministic initial condition; otherwise it resumes from the latest valid state. Small CI runs normally use max_steps and keep claim_level = validation. A completed target run can only emit claim_level = production when allow_production_claim is set and all execution gates pass.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • max_steps (int | None)

  • seed (int)

  • noise_amplitude (float)

  • write_movies (bool)

  • allow_production_claim (bool)

  • max_relative_energy_growth (float)

  • max_divergence_linf (float)

  • walltime_elapsed_seconds (float)

mhx.campaigns.production.write_rutherford_production_plan(outdir, *, harris_growth_rate=0.0131, production_efolds=10.0, safety_factor=3.0, shape=(128, 128), dt=0.1, target_saved_frames=400, run_output_dir=None, min_production_resolution=96, walltime_policy=None, equilibrium='cosine_tearing', width=0.4, amplitude=1.0, perturbation_amplitude=0.001, perturbation_mode=(1, 1), resistivity=0.001, viscosity=0.001)

Write production-plan artifacts and an initialized checkpoint index.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • outdir (str | Path)

  • harris_growth_rate (float)

  • production_efolds (float)

  • safety_factor (float)

  • shape (tuple[int, int])

  • dt (float)

  • target_saved_frames (int)

  • run_output_dir (str | Path | None)

  • min_production_resolution (int)

  • walltime_policy (WalltimePolicy | None)

  • equilibrium (str)

  • width (float)

  • amplitude (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

  • resistivity (float)

  • viscosity (float)

mhx.campaigns.production.write_rutherford_production_promotion_report(run_dir, *, outdir=None, convergence_dirs=(), seed_qi_dir=None, require_movies=True, min_history_samples=100, min_convergence_dirs=2, max_energy_budget_residual=1e-09, max_divergence_linf=1e-09, min_reconnected_flux_amplification=1.05, min_island_width_amplification=1.05)

Write a promotion-readiness report and manifest for a campaign bundle.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • outdir (str | Path | None)

  • convergence_dirs (tuple[str | Path, ...])

  • seed_qi_dir (str | Path | None)

  • require_movies (bool)

  • min_history_samples (int)

  • min_convergence_dirs (int)

  • max_energy_budget_residual (float)

  • max_divergence_linf (float)

  • min_reconnected_flux_amplification (float)

  • min_island_width_amplification (float)

mhx.campaigns.production.write_rutherford_resume_plan(run_dir, *, target_step=None)

Write resume_plan.json for the latest valid checkpoint.

Return type:

tuple[Path, dict[str, Any]]

Parameters:

  • run_dir (str | Path)

  • target_step (int | None)

Composable physics closures and source terms.

class mhx.physics.CosineTearingEquilibrium(perturbation_amplitude=0.001)

Periodic current-sheet-like equilibrium ψ₀=cos(y)+ε cos(x)cos(y).

Parameters:

perturbation_amplitude (float)

class mhx.physics.ElectronPressureTensorTerm(chi_x=0.0, chi_y=0.0)

Toy pressure-tensor Ohm’s-law closure using anisotropic current smoothing.

Parameters:

  • chi_x (float)

  • chi_y (float)

class mhx.physics.Equilibrium(*args, **kwargs)

Stable protocol for reduced-MHD initial-condition builders.

initial_state(grid)

Return the initial reduced-MHD state on grid.

Return type:

ReducedMHDState

Parameters:

grid (CartesianGrid)

class mhx.physics.EquilibriumMetadata(name, description, parameters)

Serializable metadata for an equilibrium builder.

Parameters:

  • name (str)

  • description (str)

  • parameters (dict[str, float])

class mhx.physics.EquilibriumRegistry

Registry for named reduced-MHD equilibrium builders.

create(name, parameters=None)

Create an equilibrium from a registered factory.

Return type:

Equilibrium

Parameters:

  • name (str)

  • parameters (Mapping[str, Any] | None)

metadata()

Return metadata for all registered equilibria.

Return type:

tuple[EquilibriumMetadata, ...]

names()

Return registered equilibrium names in deterministic order.

Return type:

tuple[str, ...]

register(name, factory)

Register a factory under a stable equilibrium name.

Return type:

None

Parameters:

  • name (str)

  • factory (Callable[[Mapping[str, Any]], Equilibrium])

class mhx.physics.HyperResistivityTerm(eta4=0.0, nu4=0.0)

Fourth-order diffusion term -η₄∇⁴ψ and -ν₄∇⁴ω.

Parameters:

  • eta4 (float)

  • nu4 (float)

class mhx.physics.PeriodicDoubleHarrisEquilibrium(width=0.4, amplitude=1.0, perturbation_amplitude=0.0, perturbation_mode=(0, 1))

Periodic double-Harris current sheet with an optional tearing seed.

The reconnecting field is

B_y = A[tanh((x-L_x/4)/a) - tanh((x-3L_x/4)/a) - 1].

The corresponding flux is shifted to zero mean and remains periodic to exponentially small boundary error when a << L_x. This is the periodic spectral analogue of the Harris-sheet geometry used by the direct tearing eigenvalue benchmarks; it is intended for nonlinear growth gates and production-campaign initial data, not as a replacement for the finite-domain FKR/Harris eigenproblem.

Parameters:

  • width (float)

  • amplitude (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

class mhx.physics.PhysicsRegistry

Registry for versioned physics-term factories.

create(name, parameters=None)

Create a term from a registered factory.

Return type:

PhysicsTerm

Parameters:

  • name (str)

  • parameters (Mapping[str, Any] | None)

metadata()

Return metadata for all registered terms.

Return type:

tuple[PhysicsTermMetadata, ...]

names()

Return registered names in deterministic order.

Return type:

tuple[str, ...]

register(name, factory)

Register a factory under a stable term name.

Return type:

None

Parameters:

  • name (str)

  • factory (Callable[[Mapping[str, Any]], PhysicsTerm])

class mhx.physics.PhysicsTerm(*args, **kwargs)

Stable v1 protocol for reduced-MHD RHS extension terms.

rhs_addition(state, params, *, lengths)

Return additive RHS contributions for psi and omega.

Return type:

ReducedMHDState

Parameters:

  • state (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

class mhx.physics.PhysicsTermMetadata(name, api_version, description, parameters)

Serializable metadata for a registered physics term.

Parameters:

  • name (str)

  • api_version (str)

  • description (str)

  • parameters (dict[str, float])

class mhx.physics.ToyHallOhmTerm(ion_skin_depth=0.0)

Reduced-state toy Hall Ohm’s-law term d_i [j,\psi].

Parameters:

ion_skin_depth (float)

class mhx.physics.VorticityDragTerm(rate=0.0)

Linear vorticity drag -αω.

Parameters:

rate (float)

class mhx.physics.ZeroEquilibrium

Zero-field reduced-MHD initial condition for plugin/unit tests.

mhx.physics.apply_physics_terms(base_rhs, terms, state, params, *, lengths)

Add all configured physics-term RHS contributions to a base RHS.

Return type:

ReducedMHDState

Parameters:

  • base_rhs (ReducedMHDState)

  • terms (tuple[PhysicsTerm, ...])

  • state (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

mhx.physics.build_equilibrium(name, parameters=None, *, registry=None)

Build a configured equilibrium by name.

Return type:

Equilibrium

Parameters:
mhx.physics.build_physics_terms(names, term_parameters, *, registry=None, plugin_modules=(), plugin_entry_point_groups=())

Build configured terms from names and per-term parameter mappings.

Return type:

tuple[PhysicsTerm, ...]

Parameters:

  • names (tuple[str, ...])

  • term_parameters (Mapping[str, Mapping[str, Any]])

  • registry (PhysicsRegistry | None)

  • plugin_modules (tuple[str, ...])

  • plugin_entry_point_groups (tuple[str, ...])

mhx.physics.default_equilibrium_registry()

Return the built-in reduced-MHD equilibrium registry.

Return type:

EquilibriumRegistry

mhx.physics.default_physics_registry()

Return the built-in physics-term registry.

Return type:

PhysicsRegistry

mhx.physics.load_physics_entry_points(registry, groups=('mhx.physics',))

Load installed physics plugins from Python package entry-point groups.

Each entry point must resolve either to a callable register(registry) hook or to an object exposing register_physics(registry). This keeps the public plugin contract independent of how third-party packages organize their modules.

Return type:

PhysicsRegistry

Parameters:
mhx.physics.load_physics_plugin_modules(registry, module_names)

Load user physics plugins that expose register_physics(registry).

Return type:

PhysicsRegistry

Parameters:

Configurable reduced-MHD equilibrium and initial-condition builders.

class mhx.physics.equilibria.CosineTearingEquilibrium(perturbation_amplitude=0.001)

Periodic current-sheet-like equilibrium ψ₀=cos(y)+ε cos(x)cos(y).

Parameters:

perturbation_amplitude (float)

class mhx.physics.equilibria.Equilibrium(*args, **kwargs)

Stable protocol for reduced-MHD initial-condition builders.

initial_state(grid)

Return the initial reduced-MHD state on grid.

Return type:

ReducedMHDState

Parameters:

grid (CartesianGrid)

class mhx.physics.equilibria.EquilibriumMetadata(name, description, parameters)

Serializable metadata for an equilibrium builder.

Parameters:

  • name (str)

  • description (str)

  • parameters (dict[str, float])

class mhx.physics.equilibria.EquilibriumRegistry

Registry for named reduced-MHD equilibrium builders.

create(name, parameters=None)

Create an equilibrium from a registered factory.

Return type:

Equilibrium

Parameters:

  • name (str)

  • parameters (Mapping[str, Any] | None)

metadata()

Return metadata for all registered equilibria.

Return type:

tuple[EquilibriumMetadata, ...]

names()

Return registered equilibrium names in deterministic order.

Return type:

tuple[str, ...]

register(name, factory)

Register a factory under a stable equilibrium name.

Return type:

None

Parameters:

  • name (str)

  • factory (Callable[[Mapping[str, Any]], Equilibrium])

class mhx.physics.equilibria.PeriodicDoubleHarrisEquilibrium(width=0.4, amplitude=1.0, perturbation_amplitude=0.0, perturbation_mode=(0, 1))

Periodic double-Harris current sheet with an optional tearing seed.

The reconnecting field is

B_y = A[tanh((x-L_x/4)/a) - tanh((x-3L_x/4)/a) - 1].

The corresponding flux is shifted to zero mean and remains periodic to exponentially small boundary error when a << L_x. This is the periodic spectral analogue of the Harris-sheet geometry used by the direct tearing eigenvalue benchmarks; it is intended for nonlinear growth gates and production-campaign initial data, not as a replacement for the finite-domain FKR/Harris eigenproblem.

Parameters:

  • width (float)

  • amplitude (float)

  • perturbation_amplitude (float)

  • perturbation_mode (tuple[int, int])

class mhx.physics.equilibria.ZeroEquilibrium

Zero-field reduced-MHD initial condition for plugin/unit tests.

mhx.physics.equilibria.build_equilibrium(name, parameters=None, *, registry=None)

Build a configured equilibrium by name.

Return type:

Equilibrium

Parameters:
mhx.physics.equilibria.default_equilibrium_registry()

Return the built-in reduced-MHD equilibrium registry.

Return type:

EquilibriumRegistry

Versioned physics-term plugin API.

class mhx.physics.terms.ElectronPressureTensorTerm(chi_x=0.0, chi_y=0.0)

Toy pressure-tensor Ohm’s-law closure using anisotropic current smoothing.

Parameters:

  • chi_x (float)

  • chi_y (float)

class mhx.physics.terms.HyperResistivityTerm(eta4=0.0, nu4=0.0)

Fourth-order diffusion term -η₄∇⁴ψ and -ν₄∇⁴ω.

Parameters:

  • eta4 (float)

  • nu4 (float)

class mhx.physics.terms.PhysicsRegistry

Registry for versioned physics-term factories.

create(name, parameters=None)

Create a term from a registered factory.

Return type:

PhysicsTerm

Parameters:

  • name (str)

  • parameters (Mapping[str, Any] | None)

metadata()

Return metadata for all registered terms.

Return type:

tuple[PhysicsTermMetadata, ...]

names()

Return registered names in deterministic order.

Return type:

tuple[str, ...]

register(name, factory)

Register a factory under a stable term name.

Return type:

None

Parameters:

  • name (str)

  • factory (Callable[[Mapping[str, Any]], PhysicsTerm])

class mhx.physics.terms.PhysicsTerm(*args, **kwargs)

Stable v1 protocol for reduced-MHD RHS extension terms.

rhs_addition(state, params, *, lengths)

Return additive RHS contributions for psi and omega.

Return type:

ReducedMHDState

Parameters:

  • state (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

class mhx.physics.terms.PhysicsTermMetadata(name, api_version, description, parameters)

Serializable metadata for a registered physics term.

Parameters:

  • name (str)

  • api_version (str)

  • description (str)

  • parameters (dict[str, float])

class mhx.physics.terms.ToyHallOhmTerm(ion_skin_depth=0.0)

Reduced-state toy Hall Ohm’s-law term d_i [j,\psi].

Parameters:

ion_skin_depth (float)

class mhx.physics.terms.VorticityDragTerm(rate=0.0)

Linear vorticity drag -αω.

Parameters:

rate (float)

mhx.physics.terms.apply_physics_terms(base_rhs, terms, state, params, *, lengths)

Add all configured physics-term RHS contributions to a base RHS.

Return type:

ReducedMHDState

Parameters:

  • base_rhs (ReducedMHDState)

  • terms (tuple[PhysicsTerm, ...])

  • state (ReducedMHDState)

  • params (ReducedMHDParams)

  • lengths (tuple[float, float])

mhx.physics.terms.build_physics_terms(names, term_parameters, *, registry=None, plugin_modules=(), plugin_entry_point_groups=())

Build configured terms from names and per-term parameter mappings.

Return type:

tuple[PhysicsTerm, ...]

Parameters:

  • names (tuple[str, ...])

  • term_parameters (Mapping[str, Mapping[str, Any]])

  • registry (PhysicsRegistry | None)

  • plugin_modules (tuple[str, ...])

  • plugin_entry_point_groups (tuple[str, ...])

mhx.physics.terms.default_physics_registry()

Return the built-in physics-term registry.

Return type:

PhysicsRegistry

mhx.physics.terms.load_physics_entry_points(registry, groups=('mhx.physics',))

Load installed physics plugins from Python package entry-point groups.

Each entry point must resolve either to a callable register(registry) hook or to an object exposing register_physics(registry). This keeps the public plugin contract independent of how third-party packages organize their modules.

Return type:

PhysicsRegistry

Parameters:
mhx.physics.terms.load_physics_plugin_modules(registry, module_names)

Load user physics plugins that expose register_physics(registry).

Return type:

PhysicsRegistry

Parameters:

Input/output helpers.

mhx.io.read_reduced_mhd_trajectory_npz(path)

Read a reduced-MHD v1 NPZ trajectory and diagnostics.

Return type:

tuple[ReducedMHDTrajectory, dict[str, Any]]

Parameters:

path (str | Path)

mhx.io.write_artifact_manifest(root, *, path=None)

Write a recursive artifact manifest with file sizes and SHA-256 hashes.

Return type:

dict[str, Any]

Parameters:

  • root (str | Path)

  • path (str | Path | None)

mhx.io.write_manifest(path, *, config, outputs, claim_level='unspecified', claim_scope='')

Write a JSON manifest with output file hashes.

Return type:

dict[str, Any]

Parameters:

  • path (str | Path)

  • config (dict[str, Any])

  • outputs (dict[str, str])

  • claim_level (str)

  • claim_scope (str)

mhx.io.write_reduced_mhd_trajectory_npz(path, *, trajectory, config, diagnostics)

Write a reduced-MHD trajectory using the stable v1 NPZ schema.

Return type:

Path

Parameters:

  • path (str | Path)

  • trajectory (ReducedMHDTrajectory)

  • config (dict[str, Any])

  • diagnostics (dict[str, Any])

Versioned public API and artifact-schema helpers.

class mhx.versioning.APIVersionInfo(package_version, public_api_version, supported_api_versions, physics_api_version, diagnostics_api_version, trajectory_schema, manifest_schema, artifact_manifest_schema, validation_suite_schema, claim_levels)

Serializable summary of the active MHX public API surface.

Parameters:

  • package_version (str)

  • public_api_version (str)

  • supported_api_versions (tuple[str, ...])

  • physics_api_version (str)

  • diagnostics_api_version (str)

  • trajectory_schema (str)

  • manifest_schema (str)

  • artifact_manifest_schema (str)

  • validation_suite_schema (str)

  • claim_levels (tuple[str, ...])

to_dict()

Return JSON-compatible API metadata.

Return type:

dict[str, object]

mhx.versioning.active_api_version()

Return the requested public API version.

MHX_API_VERSION is an explicit reproducibility override. It currently accepts only v1; setting any other value fails early instead of silently reading or writing artifacts with incompatible assumptions.

Return type:

str

mhx.versioning.api_version_info()

Return the active package/API/schema compatibility summary.

Return type:

APIVersionInfo

mhx.versioning.require_supported_api_version(version=None, *, context='MHX')

Validate and return a supported public API version.

Return type:

str

Parameters:

  • version (str | None)

  • context (str)

mhx.versioning.require_supported_claim_level(claim_level, *, context='MHX')

Validate and return a supported artifact claim level.

Return type:

str

Parameters:

  • claim_level (str)

  • context (str)