SC Linac Physics — Documentation

sc_linac_physics is the controls, analysis, and display software for the SLAC Superconducting (SC) Linac. It provides operator GUIs, command-line tools, and a Python library for interacting with the 296-cavity RF system via EPICS/Channel Access.

New here? Start with Getting Started — it covers EPICS, PyDM, and Qt through three hands-on exercises before pointing you to the reference docs below.

How the codebase is organized

src/sc_linac_physics/
├── utils/          Shared infrastructure: hardware model, EPICS wrappers, Qt utilities
├── applications/   Standalone applications (auto_setup, q0, tuning, …)
├── displays/       PyDM operator displays (cavity_display, srfhome, …)
└── cli/            Unified entry-point launcher (sc-linac) and watcher management

Everything in applications/ and displays/ is built on top of utils/. Start there if you're new.

Documentation pages

Infrastructure

Page	What it covers
Linac Hardware Model	Machine → Linac → Cryomodule → Rack → Cavity class hierarchy, PV naming, cryomodule groupings, all constants
Shared Utilities	EPICS PV wrapper, PVBatch, archiver client, platform_paths, custom_logger, Qt helpers

Applications

Page	What it covers	Explainer
Auto Setup	Automated cavity turn-on: SSA calibration → auto-tune → characterization → RF ramp	How auto-tune works
RF Commissioning	Phase-gated acceptance workflow for newly-installed cavities	How auto-tune works
Q0 Measurement	Cavity quality-factor measurement under thermal load
Microphonics	Mechanical vibration noise acquisition and analysis
Quench Processing	Automated fake-quench reset and real-quench detection
Tuning	Cavity frequency control, state polling, and trend persistence	How auto-tune works
Field Emission	Cavity amplitude vs. decarad radiation for past runs

An explainer is the "how it works and why" for an app, or for a piece several apps share: data flow, decisions, how it fails, each claim cited to the code. The app's page is the short reference. An explainer is a docs page, and each interactive part is a small HTML widget shown inline. On GitHub a widget shows as a link; opened on its own it also works offline.

Displays

Page	What it covers
Cavity Display	Fault monitoring dashboard for all 296 cavities with heatmap and audio alerts
Fault Heatmap	Fault counts per cavity over a time window, as a heatmap
SRF Home	Top-level launcher panel and watcher management

Quick orientation

• The physical machine hierarchy is defined once in utils/sc_linac/ and reused by every application. Read Linac Hardware Model first.
• EPICS PV names follow a strict naming convention derived from linac/cryomodule/cavity numbers. See Linac Hardware Model § PV naming.
• All applications create a module-level Machine subclass singleton (e.g., SETUP_MACHINE, Q0_MACHINE) that eagerly builds the full object tree at import time.
• Background CLI scripts (quench_resetter, tune_status_poll) are managed as "watchers" from SRF Home or via sc-watcher.
• See AGENTS.md at the repo root for architectural conventions (PV wrappers to use, logging format, platform path standards).