Ravel helps collider-physics researchers turn a reinterpretation question into a reviewable calculation: define the physics task, prepare a simulation plan, run the analysis, compute exclusion limits, and check the artifacts behind the result.
It connects MadGraph, Pythia, Delphes, Rivet or SimpleAnalysis, and pyhf through explicit task contracts, run state, provenance checks, and validation. Use the Python CLI for initiation, contract validation, and cached statistical replay. Full simulations use the separately installed native HEP toolchain and the physics workflow.
Installation · CLI reference · Supported analyses · Validation results · Documentation
A run produces machine-readable yields and limits, figures, provenance records, and a report explaining the comparison with published results. A mass-plane scan adds per-point coverage and an exclusion contour. Missing points, quality bounds, and failed comparisons remain visible.
Limits carry explicit observed/expected roles and distinguish resolved crossings from scan bounds. Result packs bind to their inference inputs, and resumed stages reuse outputs only while their recorded dependencies remain current. See the result contracts and execution and recovery guide.
Compressed-slepton example. This figure freshly re-renders a recorded 52-point scan against the published ATLAS upper-limit grid. Fifty points have exact reference matches; two legacy bounds are excluded from residuals and retained in the coverage count. The observed-limit comparison has a
24.9% median same-basis residual.These are historical interpolated limits, whose numerical precision is not certified. The RRR diagnosis compares three retained campaigns and exposes coarse limit interpolation, incomplete detector samples in a rescan, and confounded generator comparisons. A fixed-template refit removes the prominent low-mass red cell's numerical excess without retuning physics. The remaining disagreement is unresolved; this figure is not a general accuracy guarantee. The figure, inputs, and per-point JSON are available alongside the original scan record.
Fresh reproduction controls. A new 20,000-event four-state sample completed generation through all six numerical limit checks. Its matched inclusive limits were
48.83 fb observed and 54.69 fb median expected at 150/140 GeV,compared with the published 46.63 and 56.53 fb. Combining it with an independent 40,000-event replica gives
47.37 fb observed and 57.27 fb median expected from the 60,000-event pool at 150/140 GeV.The pooled primary-region MC errors are 4.03% and 4.53%, meeting the declared 5% criterion. The pool reuses its parents; it is one mass point, not a third replica.
Close limit agreement does not establish robust physics. Lowering the leading-parton generation cut from 50 to 20 GeV gives
a high-region rate ratio of 1.412 (conditional 95% interval 1.146–1.678).The interval includes the reported generator-integration uncertainty under an explicit independence assumption. This fails the ±10% equivalence criterion. The 50 GeV cut matches the RRR recipe; the control tests its approximation rather than selecting a cut by its agreement with the data. Detector response, particle-level acceptance, signal systematics and the fresh mass plane remain open. The new control bundle contains the comparison figures, all 38 likelihood channels, six control regions, matched official-model nuisance tests, retained failures and an offline verifier. The earlier waypoint preserves its likelihood inputs, response figures and physics cards. Large raw events remain local.
The event-identity study traces the lower-cut contribution back to exact original generated events and shows every channel, including sparse and zero-count bins. A fresh second mass point gives 210.00 fb observed and 169.09 fb median expected at 100/98 GeV, below the released reference. Its sparse selected population and remaining disagreement are reported alongside the successful controls. The controlled signal-model comparison shows that removing signal MC uncertainty or control-region signal strengthens these bounds further. These omissions are diagnostic tests and do not improve the physics model or repair its disagreement with the reference.
The new 50/45 point gives
615.63 fb observed and 755.34 fb median expected at 50/45 GeV,above the reference by 16.84% and 6.82%. Together, these are
3 of 52 nominal mass points with completed fresh native evidence.The three-anchor comparison provides all 18 limits, 114 channel rows, mass-specific normalization and six reconstructed-fraction comparisons, with a standalone verifier.
The lower panel shows histogram MC precision, not uncertainty bars on the limits. The low-mass samples remain sparse. Reconstructed-fraction differences also change sign across these points; missing reference errors and truth/migration definitions prevent an acceptance certificate or a fitted detector correction.
The evidence checks answer different questions:
| Check | Recorded evidence | What it establishes |
|---|---|---|
| Statistical recovery | 7 observed S95 comparisons within 8.6% (statistical layer) | Recovery from published statistical inputs, across four searches |
| Implementation comparison | 141/141 signal regions identical; final limit delta 0.51% | A bounded native/container comparison on recorded inputs |
| Selection fidelity | Six scorable historical cases: four PASS, one WARN, one FAIL; three additional cases unscorable | Agreement with published acceptance × efficiency where comparable evidence exists |
| Workflow guards | 30 constructed gate cases | Responses to specified invalid states; not an agent-task success rate |
See all nine benchmark cases for the complete population and validation results for provenance, limitations, and the distinction between regression floors and certification. Registered headline values in this README and the detailed results page are checked against the same claim registry.
The package is ravel-hep; the executable and Python import are ravel.
These commands install from the repository, without assuming a PyPI release.
Use Python 3.12 for the committed dependency lock:
git clone https://github.com/ammarphp/ravel.git
cd ravel
python3.12 -m venv .venv-replay
.venv-replay/bin/python -m pip install --require-hashes -r requirements-replay.lock
.venv-replay/bin/python -m pip install --no-deps .
.venv-replay/bin/ravel --help
.venv-replay/bin/ravel replay --out local-runs/replay-exampleThe lock verifies dependency hashes; --no-deps prevents the package installation
from replacing those dependencies. Alternative uv commands and development
setup are in the installation guide.
The examples keep generated outputs under ignored local-runs/.
A successful replay ends with GATE: OK. It writes:
local-runs/replay-example/
├── environment.json # Python, dependencies, platform, and bundle fingerprint
├── results.json # Fresh checks and their explicitly labeled scope
└── work/ # Statistical outputs and subprocess logs
The replay works outside the checkout after installation and needs no further network access. It freshly fits the bundled fast benchmark using cached simulation inputs; acceptance certification may come from the recorded baseline. It does not generate events. Choose a new output directory for each attempt; failed attempts are retained too.
To regenerate the scan demonstration from the checkout, using the same environment:
.venv-replay/bin/python benchmarks/plot_scan_demo.py --out local-runs/scan-exampleThis writes PNG/PDF figures, an exact-match comparison JSON, and input/output hashes. It re-renders recorded data without changing the original scan or running new physics inference.
Verify the fresh waypoint's saved evidence and signal-unit identities without rerunning simulation or fitting limits:
.venv-replay/bin/python evidence/audits/2026-09-06-rrr-waypoint/curate.py --unitsCheck the newer cut comparison and all 42 saved native/official limit roots using the standard library, without a simulation toolchain:
.venv-replay/bin/python -B evidence/audits/2026-09-06-rrr-cut-dependence/verify.pyVerify the second mass point and the original-event partition, including all sparse bins and complementary weight moments:
.venv-replay/bin/python -B evidence/audits/2026-09-06-rrr-event-identity/verify.pyCreate a draft contract and initial run state from your request:
.venv-replay/bin/ravel initiate \
--prompt 'Initiate: reproduce Figure 16a of arXiv:1911.12606 for a slepton-bino model' \
--out local-runs/slepton-study
.venv-replay/bin/ravel validate \
local-runs/slepton-study/inputs/task_contract.json --json
.venv-replay/bin/ravel status --rundir local-runs/slepton-studyThe local router records a draft interpretation; an agent can also supply a request-bound interpretation with literal supporting spans. Review it: a valid contract is a structural check, not approval, a resolved analysis implementation, or evidence that the requested result is feasible. Initiation does not launch simulation or call an LLM. See the CLI reference for the output files and failure behavior.
For an agent-assisted session, open the checkout in your coding agent and use the same “Initiate:” request. The repository's workflow instructions guide the agent through the analysis survey, input review, proposed figure, resource budget, and CHECK-IN 1 plan. Your approved plan is required before event generation. The workflow entry point explains the check-ins and how to resume from recorded state.
A full calculation follows generation → shower/detector simulation → event selection → statistical inference → validation → result artifacts. Provision its toolchain using the environment guide and native pipeline instructions. The replay installation alone does not install MadGraph, Pythia, or detector tools. For Intel and Apple Silicon Macs, use the native doctor and build helpers to check architecture, dependencies and explicit tool prefixes before provisioning. Check capabilities before choosing an analysis; backend and validation coverage differ by routine.
An isolated correction on retained events. The three-lepton eRJR selection previously evaluated the invisible momentum in a different frame from the leptons inside one boost-dependent quantity. Applying the ATLAS definition changes SRlow from 43 to 95 selected events on the same 200,000-event sample. Its acceptance shortfall falls from 65.2% to 23.1%; the ISR signal region remains at 19 events. The remaining mismatch still fails the existing acceptance threshold. This is cached reanalysis with one calculation changed, not a fresh end-to-end simulation. The differential audit records stage counts, changed event IDs, input hashes, and the published definition.
Ravel also checks numerical failure modes: nonfinite inputs, missing reference data, scan ceilings, CLs crossing accuracy, and unsupported interpolation. The hardening report describes these changes and their tests. The landscape review compares lessons from MadAgents, ColliderAgent, established recasting tools, and statistical tooling. Statistical superiority has not been established by a controlled comparison; inference correctness and detector fidelity need separate evidence.
The RRR diagnosis and research program separates numerical, likelihood, normalization and detector failures using retained inputs and controlled refits. The public HEP analysis survey maps 26 candidates to distinct reuse methods and required admission evidence. These are measured diagnostics and proposed extensions, not newly validated analyses.
Code lives in src/ravel/, native bridges in native/, reference workflows in
docs/, and test definitions in benchmarks/ and tests/. The public evidence/
collection retains selected results and their original source identities. See
repository layout for naming and contents.
Use CONTRIBUTING.md for tests and development setup, and GitHub Issues for reproducible problems. Ravel is research software; consult the limitations before applying it to a new analysis. Citation metadata is in CITATION.cff, with upstream acknowledgements. Licensed under Apache-2.0.