MagnetoHydroDynamic Research

A research-oriented MHD repository that combines:

• a practical Python toolkit for closures, diagnostics, divergence control, and residual experiments
• a symbolic closure program centered on Euler-potential exactness and non-closure results

The GitHub repository now presents the project as MagnetoHydroDynamic Research. The installable Python package name remains mhd_toolkit / mhd-toolkit.

Current Release

• Release notes: docs/releases/v1.0.0.md
• Changelog: CHANGELOG.md
• Start here: docs/overview/start-here.md

This repository's core identity is now:

• theory / closure research first
• tooling and numerical baselines second
• Topological Adam bridge work third and clearly separated

What This Repository Studies

The main question is whether resistive MHD fields written through Euler potentials admit exact or controlled closure formulas, and where that story breaks.

In plain English:

• when does the closure residual vanish exactly?
• when can the residual be written in an analytically controlled way?
• when does variable resistivity destroy that exactness?
• which parts of the project are theorem-level, and which are still exploratory?

Strongest Current Results

Symbolically verified exact families under constant resistivity

Within the cylindrical framework implemented in this repository, the following families are exact:

1. alpha = f(r), beta = r*theta
2. alpha = f(r), beta = z
3. alpha = r*theta, beta = g(z)

These are broader and cleaner than the earlier power-family memo alone.

Conditional exact family

For alpha = f(r), beta = theta, the residual vanishes exactly only when f(r) = a*r^2 + b.

So the quadratic case survives, but the family is not generically exact.

Variable resistivity obstruction

For nonconstant eta(r), the broad smooth exact families above are generically broken. In the tested cylindrical classes, exactness survives only in trivial or singular cases once eta'(r) != 0.

That makes variable resistivity the main mathematical boundary in the current program.

Sharpened boundary under variable resistivity

The obstruction result is now sharper than “everything breaks.”

For nonconstant eta(r):

• alpha = f(r), beta = r*theta stays exact only on the annular/singular family f(r) = a*sqrt(r) + b
• alpha = f(r), beta = z stays exact only on the annular/singular family f(r) = a*log(r) + b
• alpha = r*theta, beta = g(z) has only trivial constant-g survivors when eta'(r) is nonzero on an interval

These are kept as restricted positive results on annular domains and not promoted as smooth axis-touching exact families.

Exact vs Symbolic vs Numerical vs Experimental

• Theorem / derivation-level:
  • exact cylindrical family identities listed above
  • conditional exactness for alpha = f(r), beta = theta
  • explicit variable-resistivity residual formulas for the tested families
• Symbolically verified:
  • power-family samples inside the larger radial class
  • obstruction formulas generated by the symbolic report
• Numerically verified toolkit behavior:
  • solver smoke tests
  • closure comparison commands
  • divergence-cleaning demos
  • residual-optimization demo
• Experimental bridge work:
  • Topological Adam connection and optimizer-facing interpretation

Best User Path

Start with the research layer

pip install -e .[dev,research]
python scripts/validate/run_research_checks.py

Then reproduce the symbolic report through the CLI

python -m mhd_toolkit research symbolic-checks

Then run the numerical toolkit baselines

python -m mhd_toolkit compare closures --problem brio-wu --closures ideal,resistive --steps 20 --nx 128
python -m mhd_toolkit divfree demo --problem orszag-tang --nx 64 --ny 64
python -m mhd_toolkit opt residual-demo --steps 80

Start Here Documents

• docs/overview/start-here.md
• docs/overview/strongest-results.md
• docs/overview/reproduce-key-checks.md
• docs/theorems/proof_status.md

Repository Map

• RESEARCH_MAP.md: high-level structure
• STATUS.md: current result classification
• FILE_INDEX.md: important files and what they do
• docs/discoveries/non_bilinear_exact_families.md
• docs/discoveries/variable_resistivity_obstructions.md
• docs/discoveries/annular_variable_resistivity_exact_families.md
• docs/discoveries/topological_adam_bridge.md
• papers/drafts: current draft PDFs

Relationship to Topological Adam

This repository is the theory and closure source layer. The sibling repository RRG314/topological-adam is the applied optimizer branch.

Research Program Layer

• FINAL_REPORT.md
• SYSTEM_REPORT.md
• docs/research-program/branch-audit.md
• docs/research-program/open-problem-program.md
• docs/research-program/novelty-assessment.md

That relationship matters, but it is intentionally secondary here.

Project Status

• core symbolic closure program: active and stronger than before
• variable-resistivity theory: the main current obstruction
• toolkit baselines: usable and tested
• Topological Adam bridge: experimental and clearly separated

License

MIT. See LICENSE.