[PyTokMHD] Complete API and physics documentation

[callme-YZ]

Problem

v2.0 documentation incomplete

Currently exists:

• ✅ README (good overview)
• ✅ PHYSICS_VALIDATION_REPORT.md
• ✅ SCOPE_CLARIFICATION.md
• ✅ Docstrings in code

Missing:

• ❌ API documentation (Sphinx/ReadTheDocs)
• ❌ Physics model derivation
• ❌ Developer guide
• ❌ User tutorial

Impact

v3.0 development:

• New contributors cannot easily understand code
• Physics assumptions unclear
• Extension difficult

Publication:

• Supplementary material needed
• Reproducibility requires clear docs

Proposed Solution

1. API Documentation (High priority)

Use Sphinx + autodoc:

• Generate docs from docstrings
• Host on ReadTheDocs
• Include examples

Key modules:

• complete_solver.py - Main API
• toroidal_bracket.py - Physics operators
• ballooning_ic_v2.py - Initial conditions

2. Physics Derivation (High priority)

Document:

• Morrison bracket formulation
• Elsasser variables derivation
• Toroidal coupling (ε terms)
• Resistive + pressure terms
• Why 2D + Fourier is appropriate for ballooning

Format: Jupyter notebook or LaTeX supplement

3. Developer Guide (Medium priority)

Topics:

• Code structure
• Adding new physics
• Testing guidelines
• Contributing workflow

4. User Tutorial (Medium priority)

Examples:

• Basic usage (setup → run → analyze)
• Custom initial conditions
• Parameter scanning
• Integration with RL

Deliverables

• Sphinx documentation site
• Physics derivation document
• Developer guide (markdown)
• Tutorial notebooks (3-5 examples)

Effort Estimate

Documentation: 2-3 weeks

Success Criteria

• ✅ API docs online (ReadTheDocs)
• ✅ Physics derivation peer-reviewable
• ✅ New user can run example in <30 min
• ✅ Developer can add feature following guide

Priority

P2-medium 🟡 - Important for v3.0 collaboration/publication

---

Reported by: 小P ⚛️ + 小A 🤖
Date: 2026-03-23