docs(tuning): add an interactive auto-tune explainer

[lisazacarias]

What this changes

Adds an interactive, offline HTML explainer for Cavity._auto_tune() — the single convergence loop behind the tuning GUI, auto setup, and RF commissioning — plus a drift test that re-derives the page's numbers from the real Python on every pytest run.

Six sections: what tuning moves, the loop (with a drivable simulator), where the detune number comes from, tune states, the commissioning stages, and how it fails. The failure table's 7 Inject buttons drive the section 2 simulator so you can watch each fault play out.

Operator-visible

None. Documentation only — no PV writes, no application behavior changes, no launch changes. Docs HTML now ships in the sdist (MANIFEST.in), which does not affect the wheel or anything operators run.

Scope

Docs-only; no src/ changes. Purely additive — 5 files, no deletions.

Two supporting files ride along:

• MANIFEST.in gains one line (sdist only; the wheel is untouched).
• tests/docs/test_auto_tune_explainer.py asserts the page's constants against the real Python.

Over the 400-line target, but the page is a single document — splitting it would ship half an explanation. The bulk is one 2172-line self-contained HTML file with no runtime dependency on anything else in the repo. The working plan and design spec used to build it were dropped from this branch rather than shipped; they were process artifacts, not deliverables.

The find_chirp_range ±400 kHz cap bypass found while writing this was fixed separately in #286, which has since merged; §3 documents the fixed behaviour.

Decisions worth recording

Interactive rather than markdown. The loop's behaviour is hard to convey statically: whether it converges depends on the interaction of undershoot, calibration error and the tolerance budget. Section 2 lets the reader move those and watch the outcome flip, which prose cannot do.

Resynced against main after #270, #286 and #287 merged mid-review. Three passages went stale and were rewritten, not patched over:

• fix(sc_linac): cap chirp range on magnitude in find_chirp_range #286 fixed the chirp-range cap (abs(int(...)) at cavity.py:1196). §3 had documented that bypass as live behaviour; it now documents the fix.
• fix(sc-linac): raise instead of hanging when tuner step estimate rounds to zero #287 fixed the zero-step hang. §2's loop oracle asserted "in the real Python this spins indefinitely"; the guard at cavity.py:884-900 now raises. The JS port carries the same guard at the same position, with a new zero-step outcome, and the oracle case was changed accordingly.
• feat(rf-commissioning): add frequency tuning UI #270 landed the tuning UI. §5's caveat claimed the re-run gates and controller were "not on main" and deferred them. Both exist, so §5 names them and scopes them out deliberately instead.

The zero-step guard is drivable, not just described. #287's fix needed a demonstrable path, and the sliders cannot reach that state — it needs a detune below 0.11 Hz while also above the 5 Hz tolerance floor, and widening the scale slider far enough would put values no cavity has in front of the reader. So it is a bad_scale injection that rewrites SCALE mid-tune. That is also the honest route in: microsteps_per_hz is re-read every iteration, so a bad _apply_hz_per_step probe takes effect on the next move. It needed a mutable effective scale, kept separate from microstepsPerHz because expected_steps and the step budget are computed once before the first move — so a mid-tune SCALE change moves the estimate without moving the budget.

Starting-detune slider widened to −50 kHz…200 kHz (review feedback). A cavity off cooldown can sit hundreds of kHz out, so ±50 kHz understated the envelope tuning actually walks in from. This sharpens §2 rather than diluting it: the tolerance factor tightens from 1.369× at 5 kHz to 1.0369× at 200 kHz, so the calibration-error window visibly narrows as the detune grows. 400 kHz is the most worth offering at all, since that is where find_chirp_range's cap stops widening — past it the detune cannot be measured.

selfCheck() now binds each Inject button to its table row. The abort button sat on the StepperAbortError row while injecting the cavity path, which raises CavityAbortError and turns RF off — the exact distinction §6 exists to draw, so a reader clicking that row was shown the other path's outcome. Fixed, and the check asserts every button's row names the exception the simulator reports. Verified it fails if the old arrangement is restored.

The drift test lives in tests/, not as an uncommitted audit script. The page restates Python constants in JavaScript so it works offline. Its in-page selfCheck() only proves the page agrees with itself. A page whose entire value is trustworthy numbers needs CI to catch the day a constant moves — so the test parses TOL_ORACLE out of the HTML and re-derives every row from the real imported stepper_tol_factor.

Deferred scope

Section 5 documents the commissioning backend only. The per-stage re-run gates (_check_state_for_stage_2/3/4) and the 1,700-line frequency_tuning_controller.py landed with #270, but they are out of scope for a page about the convergence loop. §5 names them and says so, rather than leaving the reader to notice the gap.

Learning reviewer

@RDPorter — this page was written for you. Worth reading §1 (why HZ_PER_STEP is not what production uses) and §3 (the chirp-range cap bypass). No approval needed.

To open it: GitHub will not render it — HTML in a repo is served as source, and there is no Pages site here. Either check the branch out:

gh pr checkout 288 --repo slaclab/sc_linac_physics && open docs/explainers/auto_tune.html

or just grab the one file:

curl -sL https://raw.githubusercontent.com/lisazacarias/sc_linac_physics/docs/auto-tune-explainer/docs/explainers/auto_tune.html -o ~/Downloads/auto_tune.html && open ~/Downloads/auto_tune.html

The URL tracks the branch rather than a pinned commit — an earlier pinned SHA was orphaned by a rebase and quietly served a stale page. Either works offline; the page has no external references at all. The docs index now says this too, so the next reader does not have to find out by clicking.

Testing

• pytest passes — 3154 passed, 3 skipped (rebased onto 9.34.0)
• Coverage still clears 80% — 85%
• Checked against simulation — n/a, docs only

black and flake8 both clean.

Browser pass: done. Served locally with python3 -m http.server to run the real JavaScript, since the page is a static file with no dev server.

1. Console reads SELF-CHECK PASSED (14 tol-factor cases, 12 loop cases, 7 fault cases), no failure banner above the <h1>.
2. All five sliders reach both extremes and restore.
3. All 7 Inject buttons produce a verdict, and each verdict names the same exception class as its own row (now asserted in selfCheck()).
4. No horizontal scroll at 1280 px.

All data-fault values cross-check against FAULT_ORACLE with no dead buttons either way; no external references, no innerHTML.

[github-actions]

🔴 PR size: 2180 lines — over the 800-line hard limit

+2179 / -1 in production code.
2 test and asset files excluded.

Largest files	Change
docs/explainers/auto_tune.html	+2176/-0
src/sc_linac_physics/applications/rf_commissioning/phases/frequency_tuning.py	+1/-1
docs/index.md	+1/-0
MANIFEST.in	+1/-0

_{Target is 400 lines excluding tests, hard stop around 800 — see
"Scope and shipping" in CLAUDE.md. If this PR is over, the description
should say why it could not be split. Advisory only; this check never
fails the build.}

[Copilot]

Pull request overview

Adds a new interactive, offline HTML explainer documenting the _auto_tune() convergence loop (shared by tuning GUI, auto setup, and commissioning), and introduces a drift test to keep the explainer’s hand-copied constants synchronized with the real Python implementation.

Changes:

• Add docs/explainers/auto_tune.html: a self-contained interactive simulator + narrative explainer for _auto_tune().
• Add tests/docs/test_auto_tune_explainer.py to re-derive the HTML oracle values from stepper_tol_factor() on every pytest run.
• Include docs/*.html in the sdist and link the explainer from docs/index.md.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/explainers/auto_tune.html	New interactive explainer + JS port/oracles + in-page self-check.
tests/docs/test_auto_tune_explainer.py	Drift test that parses TOL_ORACLE from the HTML and validates it against Python.
tests/docs/__init__.py	Marks tests/docs as a package (empty).
docs/index.md	Adds a docs index entry pointing to the explainer.
MANIFEST.in	Includes docs/*.html in the source distribution.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.