Refactor quasistationary code into magnetics.core

[priyanshlunia]

Retire quasistationary.py; promote the SLCONTOUR pipeline into shim-free core/qs_*

Draft PR body for refactor-quasistationary → develop. Delete this file after copying.

Summary

Reverses the direction of #40: instead of finishing the half-built pure-numpy
core/quasistationary.py port, this retires that dead module and promotes the
actually-served SLCONTOUR quasi-stationary pipeline (_slcontour/) into core/ under a
unified qs_ namespace, deleting the omfit_compat OMFIT shim entirely. Net −356 lines
(635 insertions / 991 deletions).

Three commits, each self-contained:

1. refactor(core): promote SLCONTOUR pipeline into shim-free core/qs_* — the move + shim removal.
2. docs: relocate + modernize the QS reference notebook & README — reference-material cleanup.
3. Adjusted stale docstring references, clarified each script's context and role — docstring pass.

Why

An audit turned up two facts:

• core/quasistationary.py was dead weight — a partial pure-numpy port of only the fit step
  (sinusoidal only; no prep, no loader, no Gaussian/vertical geometry), not wired into
  production, and its reconstruct_grid used exp(+i(nφ+mθ)), which mirrors the toroidal
  phase / flips helicity and is wrong for any mode with a non-zero spatial phase. It even
  shipped a test that falsely certified it, because the test only exercised zero-phase modes
  where +i and −i happen to agree.
• The active pipeline is correct — _slcontour (io_data → prep → fit) driven through
  core/qs_bridge is what the service serves, and its −i reconstruction matches the original
  DIII-D SLCONTOUR reference.

So the maintainable move is to make the working pipeline first-class and delete the misleading port.

What changed

Retire the dead port

• Delete core/quasistationary.py and its degenerate test.

Promote _slcontour → core/qs_* (shim-free)

• _slcontour/{fit,prep,io_data,run,plots}.py → core/qs_{fit,prep,io_data,run,plots}.py.
• Delete omfit_compat.py, folding each symbol to its owner: printv/w/e → stdlib logging;
  OMFITexception → ValueError; delta_degrees → qs_fit; cornernote/uband → qs_plots.
• New core/qs_device.py — the shared device-metadata leaf. It delegates to the data layer
  (data.devices, data.diiid_geometry) and keeps only the QS-specific extras: the derived
  theta/*_end1/2 sensor_geometry, the resolve_channel_filter semantics, and the
  "DIII-D" → diiid alias. data/ is left untouched.

Lock the reconstruction sign convention

• Invariant comments at the three reconstruction sites (qs_bridge._reconstruct_grid,
  qs_bridge.fit_to_phi_t_node, qs_plots.plot_slice) stating: fit basis exp(+i(nφ+mθ)) with a
  real/imag column split ⇒ reconstruction must use exp(−i(…)).
• New discriminating regression test in tests/test_qs_bridge.py (non-zero spatial phase δ)
  that fails against +i and passes against −i — the test the old one lacked.

Fixes a latent bug

• qs_device.load_wall now delegates to devices.feature_at("first_wall"); the old shim read a
  non-existent top-level wall key and returned (None, None) for every shipped device, so the QS
  sensor-map wall silently never rendered. It now returns the real outline (nodes.py threads shot).

Rewire + config + docs

• service/nodes.py → core.qs_run.run_steps and core.qs_device.load_wall.
• pyproject.toml → drop the ruff exclude (the qs_* files are ruff-clean); a targeted ty exclude
  is retained on the qs_* files as a documented follow-up (see below).
• qs_plots.py docstring reframed as standalone matplotlib (verified: nothing in the served path
  imports it — qs_bridge only ports its conventions).
• Reference notebook → examples/example_magnetics.ipynb, rewired onto magnetics.core.qs_*
  (no more sys.path/omfit_compat imports). README rewritten as
  docs/specs/quasistationary-mode-analysis.md (no OMFIT-magnetics plumbing).
• Module docstrings across qs_* recontextualized (OMFIT script provenance + pipeline step).

Verification

• uv run ruff format --check . — clean.
• uv run ruff check . — clean.
• uv run --extra service ty check src/magnetics — clean.
• uv run --extra service pytest — 209 passed, 1 skipped (the 3-test drop is the deleted
  degenerate quasistationary suite; the new sign-convention regression test is included).

Follow-ups (intentionally out of scope)

• Make the qs_* files ty-clean and drop their targeted ty exclude.
• Dedupe the pre-existing set-flattening copies in data/ against qs_device.
• Per-sensor σ / helicity from the data layer (the constant 2e-5 T σ inflates χ²); a device-agnostic
  pure-numpy core fit.
• docs/magnetics-code-architecture.md is still OMFIT-era and stale — later docs sweep.

Reviewer notes

• Reverses documented issue Quasi-stationary: two parallel QS codebases — kill the dead port or finish it #40 please sanity-check the direction.
• The load_wall fix lightly touches the Sensors/geometry surface (Data Streamers / Interfacers
  heads-up): it now returns a non-empty wall where it previously returned (None, None).
• No data/ files were modified; qs_device only imports from the data layer.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR consolidates the quasi-stationary (SLCONTOUR-style) analysis into magnetics.core under a qs_* namespace, retiring the unused pure-numpy quasistationary.py port and removing the _slcontour/omfit_compat shim, while updating the service, tests, and docs to point at the promoted core pipeline.

Changes:

• Promote the active SLCONTOUR pipeline into src/magnetics/core/qs_{io_data,prep,fit,run,device,plots}.py and keep qs_bridge as the service/GUI adapter.
• Remove the dead src/magnetics/core/quasistationary.py path and the _slcontour shim/docs.
• Rewire service + tests + docs to the new modules and adjust tooling excludes in pyproject.toml.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_slcontour_geometry.py	Update imports/docs to validate geometry via core.qs_device instead of _slcontour.omfit_compat.
tests/test_slcontour_fit.py	Point basis-function tests at core.qs_fit and update expected exception type.
tests/test_quasistationary.py	Remove tests for the retired core/quasistationary.py port.
tests/test_qs_pipeline.py	Update QS end-to-end test wiring to qs_* modules.
tests/test_qs_bridge.py	Add regression coverage for the reconstruction sign convention using a non-zero spatial phase.
src/magnetics/service/nodes.py	Switch QS pipeline orchestration to core.qs_run.run_steps and wall loading to core.qs_device.load_wall(device, shot).
src/magnetics/core/quasistationary.py	Delete the unused pure-numpy QS port.
src/magnetics/core/qs_run.py	Ensure QS orchestrator imports qs_fit/qs_prep/qs_io_data modules.
src/magnetics/core/qs_prep.py	Replace OMFIT shim prints with stdlib logging; keep prep logic in core.
src/magnetics/core/qs_plots.py	Replace OMFIT shim plot helpers with local matplotlib helpers; keep sign convention comments.
src/magnetics/core/qs_io_data.py	Repoint loader dependencies to qs_device and replace shim prints with logging.
src/magnetics/core/qs_fit.py	Replace OMFIT exception type + logging changes; (contains a Python-syntax issue noted in comments).
src/magnetics/core/qs_device.py	New device adapter delegating to magnetics.data.* for segment resolution/sets; (contains Python-syntax issues noted in comments).
src/magnetics/core/qs_bridge.py	Update docs/comments to reflect qs_fit provenance; pin reconstruction sign convention with invariant comments.
src/magnetics/_slcontour/README.md	Remove deprecated reference README.
src/magnetics/_slcontour/omfit_compat.py	Remove OMFIT compatibility shim (replaced by qs_device + logging).
src/magnetics/_slcontour/init.py	Remove deprecated _slcontour package init.
pyproject.toml	Drop ruff exclude for _slcontour; add targeted ty excludes for qs_* modules.
examples/example_magnetics.ipynb	Rewire notebook to import/run magnetics.core.qs_* directly (no sys.path hacks).
docs/specs/quasistationary-mode-analysis.md	Add updated pipeline spec, inputs, and explicit reconstruction sign convention documentation.

Comments suppressed due to low confidence (1)

src/magnetics/core/qs_fit.py:334

• Invalid Python exception syntax: except ValueError, np.linalg.LinAlgError: will raise a SyntaxError and prevent this module from importing. Use a tuple of exception types instead.