Skip to content
ammarphp
ravel
Public

About

Autonomous scientific computing and research system for HEP workflows, from open-physics interpretation to hypothesis generation and iterative experimentation to statistical fits and manuscript drafting.

Topics

agentic-aiarm64hepllm-agentsmadgraphpyhfreproducible-research

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

8 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Latest commit

 

History

9 Commits

Folders and files

NameName
Last commit message
Last commit date
.agents/skills
.agents/skills
 
 
.antigravity
.antigravity
 
 
.claude
.claude
 
 
.codex
.codex
 
 
.gemini
.gemini
 
 
.github/workflows
.github/workflows
 
 
.opencode
.opencode
 
 
.ravel
.ravel
 
 
addons/gpl/mcfm-amplitudes
addons/gpl/mcfm-amplitudes
 
 
docs
docs
 
 
environment
environment
 
 
native
native
 
 
scripts
scripts
 
 
src/ravel
src/ravel
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
AGENTS.md
AGENTS.md
 
 
CHANGELOG.md
CHANGELOG.md
 
 
CITATION.cff
CITATION.cff
 
 
CLAUDE.md
CLAUDE.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
DIRECTORY.md
DIRECTORY.md
 
 
GEMINI.md
GEMINI.md
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
NOTICE
NOTICE
 
 
README.md
README.md
 
 
THIRD-PARTY-NOTICES.md
THIRD-PARTY-NOTICES.md
 
 
distribution.json
distribution.json
 
 
export-provenance.json
export-provenance.json
 
 
hatch_build.py
hatch_build.py
 
 
pyproject.toml
pyproject.toml
 
 
requirements-full.txt
requirements-full.txt
 
 
requirements-replay.lock
requirements-replay.lock
 
 
requirements-replay.txt
requirements-replay.txt
 
 
requirements-site-wms.in
requirements-site-wms.in
 
 
requirements-site-wms.lock
requirements-site-wms.lock
 
 
requirements-site-wms.txt
requirements-site-wms.txt
 
 
requirements-site.txt
requirements-site.txt
 
 

Repository files navigation

RAVEL

RAVEL is a governed research system for high-energy physics. State a question, choose the inputs and budget, and follow a recorded path through planning, scientific tools, review and delivery.

Install

git clone https://github.com/ammarphp/ravel.git
cd ravel
bash scripts/setup/install.sh
.venv/bin/ravel doctor

The installer brings its own Python, needs no administrator rights and resumes a failed step where it stopped.

The default installation needs 63.1 GB of disk space.

It plans about 8 hours for the default toolchain; bash scripts/setup/install.sh --dry-run prints the size and time of each part before anything changes.

The symbolic tools use your Wolfram Engine or Mathematica licence. The installation guide covers the licence, analysis-facility installs and model-provider setup.

A first study

After model setup, start a controller run with a synthetic question and your supplied inputs:

source .venv/bin/activate
ravel ask "Fit the supplied signal and background model and report a 95% CLs limit." --input studies/inputs/model.json --rundir studies/first-fit
ravel status --run RUN_ID
ravel drive --resume RUN_ID

Use the run ID printed by the first command. CHECK-IN 1 presents the plan, assumptions and budget for approval. The controller reports the next step, retains failed attempts and reviews the result against the original question. Study guides cover each kind of work; scope states the available paths and their boundaries.

How it works

The controller owns the run's state, authority and delivery. Agents propose plans and perform scoped work; tools and independent reviewers provide evidence. See the architecture appendices, workflow diagrams and methodology.

What RAVEL covers

The table counts registered operations. Each study uses the selected adapter's contract and executed evidence. The complete inventory links every declared interface to its reference.

Family Operations Examples
Event generation and simulation 17 MadGraph generation with decays and named weights, Pythia showering, Delphes detector simulation, LHE rewrites, PDF variations
Analysis and reinterpretation 25 Rivet, SimpleAnalysis and MadAnalysis 5 routines, columnar selections, newly written analysis code, SModelS and Contur constraints, signal patches for published likelihoods
Statistics and limits 24 95% CLs limits with pyhf, statistics the request prescribes, Combine and RooFit likelihoods, profile fits, workspace combinations
Measurements and global fits 12 Higgs coupling and signal-strength fits, SFitter global fits, EFT responses and coefficient conventions, EasyScan parameter scans
Models and calculations 26 FeynRules and SARAH models, FlexibleSUSY and SPheno spectra, widths and decays, Feynman diagrams and amplitudes, loop integrals, EFT running, symbolic and numerical calculations
Machine learning 3 Classifier training against baselines with one held-out test, published ONNX classifiers on supplied events
Literature, comparison and reports 7 Literature census and published-limit overlays, figure digitisation and comparison, result comparisons, report delivery

Toolchain

The complete installer prepares the required tools and reports licence or site actions. See component inventory and tool status.

Toolchain groups
Toolchain Tools
Miniforge and the build compilers Miniforge
RAVEL's Python environments (.venv, .venv-smodels, .venv-sfitter)
Model-provider configuration for research and review roles
MadGraph5_aMC@NLO 2.9.27 and 3.7.0 with LHAPDF 6.5.6 MadGraph5_aMC@NLO, LHAPDF
LHAPDF parton-density sets in one shared data directory LHAPDF PDF sets
Rivet 4.1.3, Pythia 8.312, HepMC3 and RAVEL's shower programs Rivet and YODA, Pythia 8, HepMC3
MadGraph-Pythia 8 interface for MadGraph's own showering MG5aMC_PY8_interface
ROOT 6.40, FastJet 3.5.2 and Delphes 3.5.1 ROOT, FastJet, Delphes
MadAnalysis 5 v1.11.1 with SampleAnalyzer MadAnalysis 5
CheckMATE 2 with its own Pythia 8.244 and Delphes 3.5.1 CheckMATE, Delphes, Pythia 8
Container engine for the Linux-only tools Podman, vfkit and gvproxy
SimpleAnalysis (container) and mapyde 0.5.0 mapyde
RestFrames library and RAVEL's recursive-jigsaw program RestFrames
Analysis source catalogue Rivet
Combine 9.2.1 on ROOT 6.22 (container) ROOT, Combine
Wolfram kernel (your licence) with FeynRules, SARAH, FeynCalc, FeynArts and HEPTAPOD FeynRules, SARAH, FeynCalc, FeynArts, HEPTAPOD
FlexibleSUSY 2.9.0 (CMSSM, lowMSSM, NMSSM) and SPheno 4.0.5 FlexibleSUSY, SPheno
pySecDec 1.6.6 with FORM pySecDec and FORM
SModelS 3.2.1 database (3.1.1 kept runnable) SModelS database 3.2.1, SModelS database 3.1.1
Contur 3.1.5 with its data and Herwig 7.3.0 Contur, Herwig and ThePEG
CAMB, CLASS and Cobaya (in the main Python environment) CAMB, CLASS (classy), Cobaya
SFitterAgents source in .venv-sfitter SFitterAgents
EasyScan_HEP with GM2Calc 2.3.1 and PhaseTracer EasyScan_HEP, GM2Calc, PhaseTracer, ALGLIB
ServiceX client ServiceX, func-adl-servicex-xaodr25
Nyx 26.09 with AMReX 26.09 and SUNDIALS 7.6.0 Nyx and AMReX, SUNDIALS
PDF, graph and SVG tools for reports poppler, Graphviz, librsvg, pypdfium2, pypdf
Linux site analysis and Snakemake environments
Analysis-facility access: CVMFS, grid proxy, Kerberos, HTCondor, apptainer, agent CLI
MCFM per-point helicity amplitudes for interfering resonances MCFM
FeynGraph diagram generator (Rust build) FeynGraph
HEPTAPOD NDA and Diagrammatica EDA diagram tools HEPTAPOD
External agent sources (AgentRivet) AgentRivet
Machine-learning libraries: scikit-learn, PyTorch (CPU) and PyTorch Geometric scikit-learn, PyTorch (CPU), PyTorch Geometric
PDG 2026 offline database (data CC BY 4.0) and RAVEL's pinned subset PDG Review of Particle Physics data (2026 edition), pdg Python package
TeX manuscript compiler and class assets

Documentation

Citing RAVEL

Use CITATION.cff. Cite the upstream tools used in your study; Appendix B links their citation records.

Licence

RAVEL uses the Apache License 2.0. Upstream tools retain their own licences; see NOTICE and THIRD-PARTY-NOTICES.md.

Appendix A: Architecture

The architecture index covers the controller, research, providers, scientific execution, safety and provenance. Each appendix includes a diagram and legend.

Appendix B: Citing upstream tools

When you publish results from a study, cite the tools it used. Each entry gives the reference the tool asks for; where a tool names none, the entry gives its release paper or its home page. upstream.json records where each reference was found, and scripts/maintenance/render_citations.py renders this list from it. THIRD-PARTY-NOTICES.md lists the upstream code RAVEL redistributes and its licences.

References for each upstream tool

MadGraph5_aMC@NLO: event generation.

  1. arXiv:1405.0301, doi:10.1007/JHEP07(2014)079.
  2. For mixed-coupling or NLO electroweak computations, also: arXiv:1804.10017, doi:10.1007/JHEP11(2021)085.

Pythia 8: showering and hadronisation.

  1. arXiv:2203.11601, doi:10.21468/SciPostPhysCodeb.8.

Herwig 7: event generation and showering.

  1. arXiv:1512.01178, doi:10.1140/epjc/s10052-016-4018-8.

HepMC3: event records.

  1. arXiv:1912.08005, doi:10.1016/j.cpc.2020.107310.

Delphes: detector simulation.

  1. arXiv:1307.6346, doi:10.1007/JHEP02(2014)057.

FastJet: jet clustering.

  1. arXiv:1111.6097, doi:10.1140/epjc/s10052-012-1896-2.
  2. Optionally, also: arXiv:hep-ph/0512210, doi:10.1016/j.physletb.2006.08.037.

LHAPDF: parton densities.

  1. arXiv:1412.7420, doi:10.1140/epjc/s10052-015-3318-8.

MCFM: amplitudes for interfering resonances. Home page: https://mcfm.fnal.gov/.

Rivet: analysis routines.

  1. arXiv:2404.15984, doi:10.21468/SciPostPhysCodeb.36.

YODA: histograms.

  1. arXiv:2312.15070, doi:10.21468/SciPostPhysCodeb.45.

SimpleAnalysis: public event selections. Home page: https://gitlab.cern.ch/atlas-sa/simple-analysis.

RestFrames: recursive-jigsaw reconstruction. Home page: http://restframes.com/.

MAPyDE: card conventions and event conversion.

  1. doi:10.5281/zenodo.7796373.
  2. arXiv:2306.11055, doi:10.21468/SciPostPhysCodeb.27.

CheckMATE: reinterpretation.

  1. arXiv:2507.08565, doi:10.1140/epjc/s10052-026-15414-8.
  2. arXiv:1611.09856, doi:10.1016/j.cpc.2017.08.021.

MadAnalysis 5: reinterpretation.

  1. arXiv:1206.1599, doi:10.1016/j.cpc.2012.09.009.
  2. arXiv:1405.3982, doi:10.1140/epjc/s10052-014-3103-0.
  3. arXiv:1407.3278, doi:10.1140/epjc/s10052-014-3242-3.
  4. arXiv:1808.00480, doi:10.1142/S0217751X18300272.
  5. arXiv:1910.11418, doi:10.1140/epjc/s10052-020-8076-6.
  6. arXiv:2006.09387, doi:10.1140/epjc/s10052-021-09052-5.
  7. arXiv:2112.05163, doi:10.1140/epjc/s10052-022-10511-w.
  8. arXiv:2206.14870, doi:10.21468/SciPostPhys.14.1.009.
  9. arXiv:2303.03427, doi:10.1140/epjc/s10052-023-11779-2.

SModelS: simplified-model constraints.

  1. arXiv:2409.12942, doi:10.1007/JHEP11(2024)074.
  2. arXiv:2306.17676, doi:10.21468/SciPostPhys.15.5.185.
  3. arXiv:2112.00769, doi:10.1007/JHEP08(2022)068.
  4. arXiv:2009.01809, doi:10.1016/j.cpc.2021.107909.
  5. arXiv:1811.10624, doi:10.1016/j.cpc.2019.07.013.
  6. arXiv:1701.06586, doi:10.1016/j.cpc.2018.02.007.
  7. arXiv:1312.4175, doi:10.1140/epjc/s10052-014-2868-5.

Contur: constraints from measurements.

  1. arXiv:1606.05296, doi:10.1007/JHEP03(2017)078.
  2. arXiv:2102.04377, doi:10.21468/SciPostPhysCore.4.2.013.

AgentRivet: agent-built Rivet routines. Home page: https://gitlab.com/hepcedar/AgentRivet.

HEPData: published data tables. Home page: https://www.hepdata.net/.

pyhf: likelihood fits.

  1. doi:10.5281/zenodo.1169739.
  2. doi:10.21105/joss.02823.

ROOT: data handling and RooFit.

  1. doi:10.1016/S0168-9002(97)00048-X.

Combine: statistical combinations.

  1. arXiv:2404.06614, doi:10.1007/s41781-024-00121-4.

Spey: measurement likelihoods.

  1. arXiv:2307.06996, doi:10.21468/SciPostPhys.16.1.032.

iminuit: minimisation.

  1. doi:10.5281/zenodo.7695764.
  2. doi:10.1016/0010-4655(75)90039-9.

Wolfram Engine: symbolic kernel. Home page: https://www.wolfram.com/engine/.

FeynRules: model files from a Lagrangian.

  1. arXiv:1310.1921, doi:10.1016/j.cpc.2014.04.012.

SARAH: model files and spectrum generators.

  1. arXiv:1309.7223, doi:10.1016/j.cpc.2014.02.018.

FeynArts: diagram generation.

  1. arXiv:hep-ph/0012260, doi:10.1016/S0010-4655(01)00290-9.

FeynCalc: amplitude algebra.

  1. arXiv:2512.19858.
  2. arXiv:2312.14089, doi:10.1016/j.cpc.2024.109357.
  3. arXiv:2001.04407, doi:10.1016/j.cpc.2020.107478.
  4. arXiv:1601.01167, doi:10.1016/j.cpc.2016.06.008.
  5. doi:10.1016/0010-4655(91)90130-D.

HEPTAPOD: diagram estimates.

  1. arXiv:2512.15867.

Diagrammatica: code from diagrams.

  1. arXiv:2603.26990.

FeynGraph: feynman diagrams. Home page: https://github.com/jens-braun/feyngraph.

FlexibleSUSY: spectra and decays.

  1. arXiv:1406.2319, doi:10.1016/j.cpc.2014.12.020.
  2. arXiv:1710.03760, doi:10.1016/j.cpc.2018.04.016.

SPheno: spectra and decays.

  1. arXiv:hep-ph/0301101, doi:10.1016/S0010-4655(03)00222-4.
  2. arXiv:1104.1573, doi:10.1016/j.cpc.2012.05.021.

PySLHA: spectrum files.

  1. arXiv:1305.4194, doi:10.1140/epjc/s10052-015-3638-8.

pySecDec: loop integrals.

  1. arXiv:2305.19768, doi:10.1016/j.cpc.2023.108956.
  2. arXiv:2108.10807, doi:10.1016/j.cpc.2021.108267.
  3. arXiv:1811.11720, doi:10.1016/j.cpc.2019.02.015.
  4. arXiv:1703.09692, doi:10.1016/j.cpc.2017.09.015.

SymPy: symbolic evaluation.

  1. doi:10.7717/peerj-cs.103.

PDG: particle data.

  1. doi:10.1142/S0217751X26300115.

SFitterAgents: higgs and EFT fits.

  1. arXiv:2607.22813.
  2. arXiv:2601.21015.
  3. arXiv:2411.00942.

EasyScan_HEP: parameter scans.

  1. arXiv:2304.03636, doi:10.1016/j.cpc.2023.109027.
  2. arXiv:2606.31214, doi:10.1140/epjc/s10052-026-16358-9.

GM2Calc: muon g−2 predictions.

  1. arXiv:1510.08071, doi:10.1140/epjc/s10052-015-3870-2.
  2. arXiv:2110.13238, doi:10.1140/epjc/s10052-022-10148-9.

PhaseTracer: phase transitions.

  1. arXiv:2412.04881, doi:10.1140/epjc/s10052-025-14258-y.
  2. arXiv:2003.02859, doi:10.1140/epjc/s10052-020-8035-2.

WCxf: wilson-coefficient exchange format.

  1. arXiv:1712.05298, doi:10.1016/j.cpc.2018.05.022.

Wilson: running and matching.

  1. arXiv:1804.05033, doi:10.1140/epjc/s10052-018-6492-7.

flavio: flavour and precision observables.

  1. arXiv:1810.08132.

smelli: global EFT likelihood.

  1. arXiv:1810.07698, doi:10.1140/epjc/s10052-019-6977-z.

CAMB: cosmological power spectra.

  1. arXiv:2607.14854, doi:10.1088/1475-7516/2026/10/013.
  2. arXiv:astro-ph/9911177, doi:10.1086/309179.

CLASS: cosmological power spectra.

  1. arXiv:1104.2933, doi:10.1088/1475-7516/2011/07/034.

Cobaya: cosmological inference.

  1. arXiv:2005.05290, doi:10.1088/1475-7516/2021/05/057.
  2. ascl:1910.019.

Nyx: cosmological simulation. Home page: https://amrex-astro.github.io/Nyx/.

AMReX: adaptive mesh refinement for Nyx.

  1. doi:10.21105/joss.01370.
  2. doi:10.1177/10943420211022811.
  3. With pyAMReX or more modern features of AMReX, also: doi:10.1177/10943420241271017.

SUNDIALS: differential-equation solvers for Nyx.

  1. doi:10.1145/3539801.
  2. doi:10.1145/1089014.1089020.
  3. With GPU features of SUNDIALS, also: doi:10.1016/j.parco.2021.102836.
  4. With its ARKODE package, also: doi:10.1145/3594632.

ServiceX: remote columnar data. Home page: https://servicex.readthedocs.io/.

func-adl-servicex-xaodr25: query translation for ServiceX. Home page: https://github.com/iris-hep/func_adl_servicex_xaodr25.

uproot: rOOT files in Python.

  1. doi:10.5281/zenodo.4340632.

Awkward Array: columnar arrays.

  1. doi:10.5281/zenodo.4341376.

XRootD: remote file access. Home page: https://xrootd.slac.stanford.edu/.

Snakemake: facility workflows.

  1. doi:10.12688/f1000research.29032.2.

LangGraph: research graph. Home page: https://github.com/langchain-ai/langgraph.

Podman: containers. Home page: https://podman.io/.

PyTorch: machine learning.

  1. doi:10.1145/3620665.3640366.

scikit-learn: machine learning.

  1. https://jmlr.csail.mit.edu/papers/v12/pedregosa11a.html.

ONNX Runtime: published classifiers.

  1. https://onnxruntime.ai/.

Matplotlib: figures.

  1. doi:10.1109/MCSE.2007.55.

mplhep: hEP figure style.

  1. doi:10.5281/zenodo.3766157.

Miniforge: bootstrap Python and conda environments. Home page: https://github.com/conda-forge/miniforge.

LHAPDF PDF sets: parton-density data sets. Home page: https://lhapdf.hepforge.org/pdfsets.html.

MG5aMC_PY8_interface: madGraph's own Pythia 8 showering. Home page: https://launchpad.net/mg5amcnlo.

vfkit: container virtual machine on macOS. Home page: https://github.com/crc-org/vfkit.

gvproxy: container virtual-machine networking. Home page: https://github.com/containers/gvisor-tap-vsock.

FORM: symbolic manipulation for loop integrals. Home page: https://github.com/form-dev/form.

SModelS database 3.2.1: simplified-model results database. Home page: https://github.com/SModelS/smodels-database-release.

SModelS database 3.1.1: simplified-model results database (earlier release). Home page: https://github.com/SModelS/smodels-database-release.

ThePEG: event-generator toolkit under Herwig. Home page: https://thepeg.hepforge.org/.

ALGLIB: numerical library for phase-transition scans. Home page: https://www.alglib.net/.

poppler: pDF rendering for reports. Home page: https://poppler.freedesktop.org/.

Graphviz: graph layout for reports. Home page: https://graphviz.org/.

librsvg: sVG rendering for reports. Home page: https://gitlab.gnome.org/GNOME/librsvg.

pypdfium2: pDF page rendering in Python. Home page: https://github.com/pypdfium2-team/pypdfium2.

pypdf: pDF reading and assembly in Python. Home page: https://github.com/py-pdf/pypdf.

PyTorch Geometric: graph neural networks. Home page: https://github.com/pyg-team/pytorch_geometric.

PDG Review of Particle Physics data: particle properties. Home page: https://pdg.lbl.gov/.

pdg Python package: offline access to PDG data. Home page: https://github.com/particledatagroup/api.

Appendix C: Glossary

The glossary defines the workflow terms and links to their contracts. The visual overview provides a compact reading aid.

About

Autonomous scientific computing and research system for HEP workflows, from open-physics interpretation to hypothesis generation and iterative experimentation to statistical fits and manuscript drafting.

Topics

agentic-aiarm64hepllm-agentsmadgraphpyhfreproducible-research

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

8 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages