Repository navigation
Conversation
pmoriano
marked this pull request as ready for review
November 11, 2026 16:12
anagainaru
reviewed
Nov 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a reproducible SLAC-FEL scientific example to current APEIRON, including a focused drift-adaptation tutorial, the existing pretrained model and scalers, a paper-style replay figure, documentation, and automated tests.
The tutorial uses 14 windows from the December 2025 FEL dataset and accepts the dataset location through
data.path, allowing the permanent hosting decision to be incorporated later without changing the workflow.Motivation & Context
The SLAC-FEL workflow was previously available on a historical development branch and was used for the original paper-reproduction work. This PR ports that workflow to current
mainand provides a smaller, documented tutorial suitable for new users.The permanent public dataset host is still being evaluated through AmSC. The implementation therefore uses a configurable local data path and does not commit dataset files.
Approach
5542efbb47fdfddbb0b3202beaa2ad4c68cc3bd2.slac-felthrough the existing example factory.data_730.pklthroughdata_743.pkl.The README-driven command-line workflow is canonical. A notebook can be added later as an optional presentation layer without duplicating the implementation.
Screenshots / Logs
The focused replay figure is included at:
examples/slac_fel/figures/focused_drift_adaptation.pngValidated focused-run result:
data_740.pkl, pipeline step 31Two independent seeded runs produced identical scientific metrics and bitwise-identical adapted checkpoint tensors.
API / CLI Changes
slac-felas a supporteddata.namein the example factory.examples/slac_fel/slac-fel-tutorial.toml.examples/slac_fel/test_tomls/dec2025.toml.botorchandpyyaml, plus thetypes-pyyamldevelopment dependency.seedconfiguration at application startup.Breaking Changes
Security & Privacy
No FEL dataset files are included in the repository. The model and scaler artifacts are retained from the existing historical APEIRON commit and were verified by Git object identity before the compatibility changes.
Users should run the example only with trusted model and dataset artifacts because the existing FEL workflow loads PyTorch and pandas serialized files.
Dependencies
Added:
botorch>=0.18.1pyyaml>=6.0.3types-pyyaml>=6.0.12.20261103in the development dependency groupuv.lockwas regenerated and validated with the repository-compatible uv version.Testing Plan
Validation completed:
uv lock --check: passed1.4e-7mJDocumentation
Documentation includes dataset expectations, configurable paths, execution instructions, expected results, figure reproduction, scientific interpretation, and implementation provenance.
AI / LLM Assistance
AI assistance was used during implementation, documentation, testing, validation design, and review. The contributor remains responsible for the submitted work. The second checkbox will be completed after the final human review.
Checklist
make lintmake type-checkmake testRisk & Rollback Plan
Risk is medium. Most changes are isolated to a new scientific example, but the PR also restores application-wide deterministic seeding and adds dependencies.
Rollback consists of reverting the PR. The FEL dataset is external and no data migration or persistent service state is introduced.
Notes for Reviewers
Suggested review focus:
The figure reports a paper-style offline segmented replay. It does not claim strict causal availability of the adapted checkpoint at the beginning of the trigger window.
The permanent public dataset URL is intentionally not hard-coded. Once the AmSC hosting option is clarified, the README can be updated without changing the tutorial implementation.