docs: Add GEQDSK/geoflux implementation plan with 3D field support

[krystophny]

Summary

This PR adds a comprehensive implementation plan for tokamak GEQDSK support in SIMPLE using geoflux reference coordinates.

Key Additions

1. Complete GEQDSK Implementation Roadmap

• Geoflux coordinates: (s_tor, θ_geo, φ) as reference system
• Reuse field_divB0: Leverage libneo's battle-tested GEQDSK infrastructure
• Canonical coordinates: Meiss and Albert variants on geoflux reference
• Phased approach: Clear milestones from basic functionality to production-ready

2. 3D Field Superposition Documentation

• 4 perturbation modes: ipert=0/1/2/3 with detailed use cases
• Vacuum perturbations: RMPs, error fields via Biot-Savart (ipert=1)
• Plasma response: Linear MHD coupling with GPEC/MARS-F (ipert=2,3)
• Tool ecosystem: vacfield.x, coil_tools, coil_convert, Python interfaces
• Integration workflow: From coil geometry to perturbed field evaluation

3. Implementation References

• Simpson rule for q-profile integration: KAMEL fix-integration branch
• Plan to extract to libneo utility module for shared use

Architecture Highlights

Clean separation:

• libneo: Reference coordinates (geoflux) and field evaluation (field_divB0)
• SIMPLE: Canonical coordinates (Meiss/Albert) built on top

Key insight: Reference coordinates stay axisymmetric (based on equilibrium), while magnetic field can include 3D perturbations.

Reuse strategy: Leverage field_divB0 for all GEQDSK I/O and field evaluation, only add coordinate transformation layer.

Status

This is a documentation-only PR - no code changes yet. It provides:

• ✅ Complete technical specification
• ✅ Implementation phases with effort estimates
• ✅ Testing and validation strategy
• ✅ 3D field capability assessment (fully implemented but not regression tested)

Next Steps

1. Review and refine implementation plan
2. Begin Phase 1: Basic geoflux coordinates in libneo
3. Create test infrastructure for 3D field modes (currently missing)
4. Implement SIMPLE field classes for GEQDSK

Files Changed

• TODO.md: Comprehensive implementation plan (new file, ~1000 lines)

Related Issues

Addresses the need for tokamak equilibrium support alongside existing stellarator capabilities.