{"id":22753642,"url":"https://github.com/slaclab/sc_linac_physics","last_synced_at":"2026-05-27T20:00:52.489Z","repository":{"id":255244034,"uuid":"825938984","full_name":"slaclab/sc_linac_physics","owner":"slaclab","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-26T14:41:30.000Z","size":16291,"stargazers_count":2,"open_issues_count":17,"forks_count":8,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-05-26T16:33:38.534Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slaclab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-07-08T19:50:27.000Z","updated_at":"2026-05-26T14:55:33.000Z","dependencies_parsed_at":"2025-12-18T04:05:24.689Z","dependency_job_id":null,"html_url":"https://github.com/slaclab/sc_linac_physics","commit_stats":null,"previous_names":["slaclab/sc_linac_physics"],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/slaclab/sc_linac_physics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fsc_linac_physics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fsc_linac_physics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fsc_linac_physics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fsc_linac_physics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slaclab","download_url":"https://codeload.github.com/slaclab/sc_linac_physics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fsc_linac_physics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33581559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-11T06:12:19.467Z","updated_at":"2026-05-27T20:00:52.466Z","avatar_url":"https://github.com/slaclab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sc_linac_physics\n\nOperator displays, analysis tools, and command-line interface for the LCLS-II superconducting (SC) linac at SLAC.\n\n[![CI](https://github.com/slaclab/sc_linac_physics/actions/workflows/python-app.yml/badge.svg?branch=main)](https://github.com/slaclab/sc_linac_physics/actions/workflows/python-app.yml)\n[![Release](https://github.com/slaclab/sc_linac_physics/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/slaclab/sc_linac_physics/actions/workflows/release.yml)\n\nThe LCLS superconducting linac accelerates an electron beam through five sections (L0B–L4B) containing 60 cryomodules and 480 superconducting RF cavities. This package provides the software used by operators and physicists to control, monitor, and commission those cavities: PyDM-based GUIs, hierarchical setup automation, fault monitoring, and analysis tools for Q0 measurement, microphonics, and tuning.\n\nFor architecture documentation and per-application guides, see [`docs/`](docs/index.md).\n\n## Installation\n\nThis project requires Python 3.12+. The easiest way to get started:\n\n1. **Install conda** (if you don't have it): Follow the [conda installation guide](https://docs.conda.io/projects/conda/en/latest/user-guide/install/)\n\n2. **Create a Python environment:**\n\n```bash\nconda create -n sclp \"python\u003e=3.12\"\nconda activate sclp\n```\n\n3. **Install this package** from source (not published to PyPI):\n\nOptional: set up GitHub SSH first (recommended for contributors):\n\n```bash\nssh-keygen -t ed25519 -C \"your_email@example.com\"\neval \"$(ssh-agent -s)\"\nssh-add ~/.ssh/id_ed25519\ncat ~/.ssh/id_ed25519.pub\n```\n\nAdd the printed key to GitHub:\n\n- https://github.com/settings/keys\n\nThen verify SSH access:\n\n```bash\nssh -T git@github.com\n```\n\nClone with SSH:\n\n```bash\ngit clone git@github.com:slaclab/sc_linac_physics.git\n```\n\nOr clone with HTTPS (no SSH key setup required):\n\n```bash\ngit clone https://github.com/slaclab/sc_linac_physics.git\n```\n\nThen install:\n\n```bash\ncd sc_linac_physics\npip install -e \".[dev,test]\"\n```\n\nFor package-only installation (without development/testing dependencies), use:\n\n```bash\npip install -e .\n```\n\n\u003e Two dependencies (`edmbutton`, `lcls-tools`) install from `github.com/slaclab` and require network access.\n\n## Quick Start\n\n### Running displays locally\n\nTo run displays without live accelerator hardware, start the simulator in one terminal:\n\n```bash\nconda activate sclp\nsc-sim\n```\n\nThen launch any display in another terminal:\n\n```bash\nsc-srf-home\n```\n\n### Learning to develop\n\nNew to this codebase? Start with the [Getting Started Guide](docs/getting_started.md), which walks you through three hands-on exercises building displays from scratch. You'll learn EPICS, PyQt, and PyDM basics along the way. The guide uses `sc-sim` for live data and also includes a layout-only mode with `PYDM_DEFAULT_PROTOCOL=fake`.\n\n## Usage\n\nRun `sc-linac list` to see all available commands. Key entry points:\n\n| Command | Description |\n|---------|-------------|\n| `sc-srf-home` | Main operator dashboard |\n| `sc-cavity` | Real-time fault monitoring across all 296 cavities |\n| `sc-setup` | Automated cavity setup GUI |\n\nSetup commands (`sc-setup-all`, `sc-setup-linac`, `sc-setup-cm`, `sc-setup-cav`) automate cavity turn-on across hierarchy levels. Run any with `--help` for usage.\n\n## Development\n\n### Testing\n\n80% coverage is required and enforced in CI. Tests mock EPICS and do not require the simulator.\n\n```bash\npytest\npytest tests/test_cli.py -v   # single file\n```\n\n### Linting and formatting\n\nPre-commit hooks run `black` and `flake8` automatically on each commit (set up via `pre-commit install`). To run manually:\n\n```bash\nblack .\nflake8 . --count --max-complexity=10 --max-line-length=120 --show-source --statistics\n```\n\n### Architecture\n\n```\nsrc/sc_linac_physics/\n├── utils/          Shared infrastructure: hardware model, EPICS wrappers, Qt utilities\n├── applications/   Standalone applications (auto_setup, q0, tuning, …)\n├── displays/       PyDM operator displays (cavity_display, srfhome, …)\n└── cli/            Unified entry-point launcher and watcher management\n```\n\nThe hardware model (`utils/sc_linac/`) defines a `Machine → Linac → Cryomodule → Rack → Cavity` hierarchy reused by every application. See [`docs/`](docs/index.md) for detailed per-module documentation.\n\n### Releases\n\nReleases are automated via `python-semantic-release` on pushes to `main`. Commits must follow the Angular convention — the version bump and changelog entry are derived automatically.\n\n```\nfeat(q0): add automated calibration routine   → minor bump\nfix(display): prevent crash on PV disconnect   → patch bump\nBREAKING CHANGE: ...                           → major bump\n```\n\nThe latest tagged release is automatically deployed to production every Tuesday afternoon.\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| Displays show no data | Start the simulator with `sc-sim` |\n| Qt errors in headless environments | `export QT_QPA_PLATFORM=offscreen` or `xvfb-run -a ...` |\n| `ImportError` after cloning | Use editable install: `pip install -e .` |\n| CLI command not found | Run `conda activate sclp` and try again; if still missing, reinstall with `pip install -e .` |\n| `Invalid cryomodule` error | Use bare number (`01`, `H1`), not `CM01` |\n\n## Contributing\n\nPRs and issues are welcome. After cloning, install the pre-commit hooks:\n\n```bash\npre-commit install\n```\n\nThis runs `black` and `flake8` automatically on each commit. Add tests for new behavior and use conventional commit messages to keep the automated changelog accurate.\n\n## Authors\n\n- Lisa Zacarias (zacarias@slac.stanford.edu)\n- Sebastian Aderhold (aderhold@slac.stanford.edu)\n- Derikka Bisi (dabisi@slac.stanford.edu)\n- Haley Marts (hmarts@slac.stanford.edu)\n\nSee [CHANGELOG.md](CHANGELOG.md) for release notes.\n\n## License\n\nSee [LICENSE](LICENSE).\n\nCOPYRIGHT © SLAC National Accelerator Laboratory. This work is supported in part by the U.S. Department of Energy, Office of Basic Energy Sciences under contract DE-AC02-76SF00515.\n\nNeither the name of the Leland Stanford Junior University, SLAC National Accelerator Laboratory, U.S. Department of Energy nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslaclab%2Fsc_linac_physics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslaclab%2Fsc_linac_physics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslaclab%2Fsc_linac_physics/lists"}