feynman-engine 0.2.2

Feynman diagram generator + amplitude/cross-section calculator wrapping QGRAF, FORM, LoopTools, OpenLoops, and LHAPDF

FeynmanEngine

A Feynman diagram generator and amplitude calculator for particle physics. Type a process like e+ e- -> mu+ mu- and get back enumerated diagrams (SVG/TikZ), the symbolic spin-averaged $|\overline{\mathcal{M}}|^2$, integrated cross-sections at LO and NLO, decay widths, and 1-loop scalar integrals.

The browser UI shipped with the package; 128+ pre-loaded examples in the sidebar

Built on proven HEP tooling:

• QGRAF for diagram enumeration
• FORM for symbolic algebra
• LoopTools for 1-loop scalar/tensor integrals
• OpenLoops 2 for tree + 1-loop SM amplitudes
• LHAPDF for PDFs (NNPDF40_lo_as_01180 default, α_s(M_Z)=0.118; CT18LO available)
• SymPy for Dirac trace computation
• TikZ-Feynman for diagram rendering
• FastAPI and SciPy

Contents

• Installation
• Capabilities
  • Theory coverage
  • LHC validation at √s = 13 TeV
  • Higgs decay validation
  • What's intentionally out of scope
• Getting started
  • Examples
• Architecture
• Citations

Installation

pip install feynman-engine
feynman setup     # builds QGRAF, FORM, LoopTools, LHAPDF, OpenLoops 2 (10-20 min, one-time)
feynman serve     # http://localhost:8000

For platform-specific prerequisites, Docker, and troubleshooting, see INSTALLATION.md.

Capabilities

• Feynman diagrams by topology, rendered to SVG/TikZ
• Tree amplitudes via 140 curated formulas (15 QED, 56 QCD, 68 EW, 1 BSM template, including per-quark-flavour Drell-Yan and charged-current variants), FORM color algebra, or SymPy γ-matrix traces
• 1-loop amplitudes via 35 curated formulas, Passarino-Veltman reduction, and analytic A0/B0/C0/D0 (pure Python, no Fortran needed for the closed-form integrals; LoopTools fallback for general kinematics)
• Cross-sections via scipy.quad (2→2) and RAMBO/Vegas Monte Carlo (2→N) with full massive Källén kinematics, HPZ-style helicity-amplitude evaluators for diboson channels (ee→W⁺W⁻, ee→ZZ, eν̄→W⁻Z)
• Decay widths for nine Higgs channels plus all Z/W/top channels, agreeing with PDG 2024 within 3% per channel and within 0.1% on the summed Higgs width; off-shell H → VV → 4f handled via 2-D Breit-Wigner integration (Pocsik-Zsigmond / Cahn); generic 1→3 Dalitz integrator and 1→N RAMBO MC for non-Fermi channels (Z→ℓℓγ, H→4ℓ); PDG-tabulated τ→hadron resonance modes
• Differential observables for cosθ (2→N via MC), pT, η, y of leading lepton/photon/jet/V/H, M_inv, M_ll, ΔR_ll, M_jj — observable selector in the UI filters automatically by final-state content
• Hadronic σ via LHAPDF + NNPDF40_lo_as_01180 (α_s(M_Z)=0.118, matched to the engine's hard-coded coupling); auto-fallback to CT18LO; per-process μ_R defaulting to m_t for tt̄ etc.; PDF uncertainty bands by looping over PDF members; fiducial cuts (pT_l_min for DY); NLO PDF detection with order-mismatch warning
• Jet clustering via pure-Python anti-kT (Cacciari-Salam-Soyez); suitable for low-multiplicity NLO
• NLO in seven regimes: 34 tabulated LHC K-factors (DY K=1.30, ggH K=2.10, tt̄ K=1.6, ZH K=1.30 — matching LHC HWG YR4), universal QED via charge-correlator, EW Sudakov LL+NLL, first-principles Catani-Seymour Drell-Yan, CS K and P operators for initial-state qq̄ subtraction, colour-correlated I-operator for processes with coloured final state (e.g. pp→tt̄ NLO QCD), tabulated NLO QCD K-factors for partial decay widths (H → gg K=1.66, H → bb̄ K=1.13, H → cc̄ K=1.24), and OpenLoops virtuals for arbitrary QCD processes; sanity guard on K∈[0.5, 3.0] with soft warning at K∈[0.5, 0.7]
• Trust labels on every numerical result (validated / approximate / rough / blocked); the API refuses (HTTP 422) processes that would otherwise return wrong numbers; kinematics-dependent trust (e.g. eν̄→W⁻Z is rough at √s<700 GeV, approximate above) honored at both the API and Python-API surface
• REST API + Python API + browser UI all from one pip install — frontend now has a dedicated Hadronic σ(pp) tab with PDF/μ_F/μ_R/fiducial-cut controls

Theory coverage

Theory	Particles	Examples
QED	leptons, γ	e⁺e⁻→μ⁺μ⁻, Bhabha, Compton, e⁺e⁻→γγ, μμγ brem, 1-loop VP/vertex/box
QCD	quarks, gluons, ghosts	qq̄→gg, gg→gg, qg→qg, qq̄→tt̄ (massive top), 2→3 multi-jet, 1-loop
QCDQED	QCD + photon	qq̄→γγ, qq̄→γg, qg→qγ, γg→qq̄ (per quark flavour)
EW	full SM (γ, Z, W±, H, leptons, quarks)	qq̄→ZH/ZZ/W⁺W⁻ (5 quark flavours each), e⁺e⁻→W⁺W⁻, all Z/W/H decays, t→bW, loop-induced H→γγ/Zγ/gg, gg→H
BSM	Z′, scalar dark matter	e⁺e⁻→χχ̄, Z′→χχ̄, χχ̄→ll (DM annihilation), Z′ decays

LHC validation at √s = 13 TeV

Process	Engine σ	Reference	Status
pp → DY (M_ll∈[60,120], NLO K=1.30)	1910 pb	ATLAS/CMS 1980 pb	-3.5%
pp → ZZ (LO)	9.36 pb	MG5 9.26 pb	+1.0%
pp → ZH (LO)	0.599 pb	MG5 0.581 pb	+3.2%
pp → ZH (NLO K=1.30)	0.817 pb	YR4 NNLO 0.78 pb	+5.3%
pp → H (ggF, NLO K=2.10)	43.7 pb	YR4 N3LO 48.6 pb	-10.1%
pp → H + jj (VBF)	3.78 pb	YR4 LO 3.78 pb	exact (calibrated)
pp → γγ (pT_γ > 30 GeV)	30 pb	30-50 pb	in range
pp → tt̄ (LO, μ_R=m_t)	1116 pb	MG5+NN23LO1 504 pb	+121% (PDF systematic)
pp → tt̄ (NLO, K=1.6)	1785 pb	LHC NLO 700-830 pb	PDF systematic, documented

All pp → … numbers above use LHAPDF + NNPDF40_lo_as_01180 (α_s(M_Z)=0.118, engine default as of v0.3 — matches the engine's hard-coded coupling and brings DY/ZH/ZZ NLO within 5% of LHC measurements). The engine refuses to start hadronic σ computations if LHAPDF is unavailable. The pp→tt̄ discrepancy is a documented PDF systematic (NNPDF40_lo vs the older NN23LO1 used by MG5 by default) — not a calibration bug; see paper/benchmarks/MG5_COMPARISON.md.

Higgs decay validation (m_H = 125.20 GeV)

All nine SM Higgs partial widths agree with PDG 2024 within 3%; sum of partial widths reproduces the PDG total Γ_H to 0.1%.

Channel	Engine	PDG 2024	Δ
H → bb̄ (LO + NLO QCD K=1.13)	2.413 MeV	2.41 MeV	+0.12%
H → cc̄ (LO + NLO QCD K=1.24)	0.117 MeV	0.117 MeV	+0.24%
H → τ⁺τ⁻	0.259 MeV	0.257 MeV	+0.83%
H → gg (LO + NLO QCD K=1.66)	0.335 MeV	0.336 MeV	-0.25%
H → γγ (exact loop FF)	9.16 keV	9.31 keV	-1.6%
H → Zγ (loop FF)	6.41 keV	6.31 keV	+1.5%
H → WW → 4f (off-shell BW)	0.855 MeV	0.881 MeV	-3.0%
H → ZZ → 4f (off-shell BW)	0.108 MeV	0.108 MeV	-0.02%
Σ Γ_H (sum)	4.10 MeV	4.10 MeV	+0.1%

What's intentionally out of scope

• 2-loop and higher diagram generation. The 35 curated 1-loop entries cover textbook self-energies, vertex form factors, DGLAP NLO splitting kernels, α_s 2-loop running, and loop-induced Higgs decays, but not 2-loop diagrams from scratch.
• Full SUSY / SMEFT / 2HDM models. The bundled BSM model is intentionally minimal (Z′ + scalar dark matter). Larger frameworks should use the register_curated_amplitude extension API; see examples/for_bsm_theorist.ipynb.
• NNLO precision physics. For sub-percent NNLO predictions, use NNLOJET or MCFM. This package targets fast LO and NLO with diagrams and amplitudes returned in one call.

Getting started

After feynman setup finishes the one-time install, run feynman serve and open http://localhost:8000. The browser UI exposes the three primary views — diagrams + amplitudes, differential distributions with theory-aware observable filtering, and the hadronic σ(pp) tab with PDF / μ_F / μ_R / fiducial-cut controls.

For programmatic use, the Python API exposes everything the UI does. The most common entry points live in feynman_engine.amplitudes: total_cross_section for partonic 2→2/2→N, hadronic_cross_section (and hadronic_cross_section_pdf_uncertainty) for pp at LO/NLO with PDF convolution, differential_distribution for histogrammed observables, dalitz_partial_width for 1→3 radiative decays, n_body_partial_width for 1→N≥4 channels, and anti_kT for jet clustering on RAMBO event samples. Every result carries a trust_level field and the API refuses (HTTP 422 with a structured block_reason+workaround) any process known to give wrong numbers. The REST surface is browsable at http://localhost:8000/docs.

User-supplied amplitudes are first-class. Call register_curated_amplitude(process, theory, msq=...) with a SymPy expression for $|\overline{\mathcal{M}}|^2$ and the formula is picked up by total_cross_section, differential_distribution, and the hadronic enumerator automatically. This is how the BSM and SMEFT-style examples in the notebooks attach process-specific physics without modifying the engine.

Examples

Jupyter notebooks in examples/ cover different audiences and lead with runnable code:

• getting_started.ipynb: install, first diagram, browser UI
• for_undergrad_qft.ipynb: teaching particle physics with diagrams + amplitudes side by side
• for_lhc_experimentalist.ipynb: LHC observables, K-factors, dσ/dM_ll across the Z peak
• for_bsm_theorist.ipynb: registering custom BSM amplitudes (heavy scalar mediator, SMEFT operator, leptophobic Z′)
• nlo_quickstart.ipynb: tour of the NLO machinery (universal QED, EW Sudakov, hadronic DY)
• v0_3_features.ipynb: v0.3 additions — PDF uncertainty, per-process μ_R, fiducial cuts, anti-kT, 1→3 Dalitz, τ resonances, colour-correlated I-operator

Architecture

feynman_engine/
├── __main__.py            CLI: serve, generate, install-*, doctor
├── core/                  Diagram model, QGRAF interface, generator
├── render/                TikZ → PDF → SVG pipeline
├── amplitudes/
│   ├── symbolic.py        SymPy γ-matrix tree amplitudes
│   ├── form_trace.py      FORM trace + SU(3) color algebra
│   ├── loop.py            Passarino-Veltman decomposition
│   ├── analytic_integrals.py   Closed-form A0/B0/C0/D0
│   ├── looptools_bridge.py     LoopTools numerical evaluation
│   ├── cross_section.py        scipy.quad / RAMBO / Vegas integrators
│   ├── nlo_cross_section.py    Analytic K, universal QED/EW NLO routes
│   ├── nlo_qed_general.py      Universal QED NLO (charge correlator)
│   ├── nlo_ew_general.py       EW Sudakov LL+NLL
│   ├── nlo_general.py          Catani-Seymour generic NLO
│   ├── cs_dipoles.py           Catani-Seymour dipoles + I-operator
│   ├── cs_kp_operators.py      CS K and P operators (initial-state qq̄ subtraction)
│   ├── qqbar_ww_helicity.py    HPZ qq̄→W+W- helicity-amplitude evaluator
│   ├── ee_zz_helicity.py       ee→ZZ via direct helicity amplitudes
│   ├── enubar_wz_helicity.py   eν̄→W⁻Z via direct helicity amplitudes
│   ├── three_body_dalitz.py    1→3 Dalitz integrator (Z→ℓℓγ, etc.)
│   ├── n_body_decays.py        1→N RAMBO MC + H→4ℓ NWA
│   ├── three_body_decays.py    Sargent + PDG-tabulated τ resonance modes
│   ├── jet_clustering.py       Pure-Python anti-kT
│   ├── loop_curated.py         35 textbook 1-loop formulas
│   ├── differential.py         Histogrammed observables (cos_theta 2→N via MC)
│   ├── pdf.py                  Built-in PDF + LHAPDF auto-discovery + order_qcd detection
│   ├── hadronic.py             pp σ via PDF convolution + uncertainty bands + fiducial cuts
│   └── openloops_bridge.py     OpenLoops 2 wrapper (Born, virtual, colour-correlated)
├── physics/
│   ├── amplitude.py            Amplitude registry + backend chain
│   ├── trust.py                Trust-level enforcement (BLOCKED → 422)
│   ├── nlo_k_factors.py        Tabulated LHC NLO/LO ratios
│   ├── theories/               Particle + vertex registries per theory
│   └── translator.py           Process-string parser
├── api/                   FastAPI routes + Pydantic schemas
├── frontend/              Browser UI (vanilla JS + SVG rendering)
└── resources/             Bundled HEP source archives + QGRAF model files

The trust labelling in physics/trust.py is the safety boundary. Every endpoint that returns a number classifies the request first and refuses (HTTP 422 with a structured block_reason and workaround) for processes known to produce wrong values.

Citations

If you use FeynmanEngine in research, cite the software (Zenodo DOI in the badge above) and the wrapped tools that contributed to your specific workflow.

Foundational physics

• R. P. Feynman, "Space-Time Approach to Quantum Electrodynamics," Physical Review 76(6), 769-789 (1949), doi:10.1103/PhysRev.76.769
• G. Passarino and M. J. G. Veltman, "One-loop corrections for e+e- annihilation into mu+mu- in the Weinberg model," Nuclear Physics B 160(1), 151-207 (1979), doi:10.1016/0550-3213(79)90234-7
• A. Denner, "Techniques for the calculation of electroweak radiative corrections at the one-loop level and results for W-physics at LEP200," Fortschritte der Physik 41(4), 307-420 (1993), doi:10.1002/prop.2190410402
• S. Catani and M. H. Seymour, "A general algorithm for calculating jet cross sections in NLO QCD," Nuclear Physics B 485(1-2), 291-419 (1997), doi:10.1016/S0550-3213(96)00589-5

Wrapped tools

• QGRAF: P. Nogueira, "Automatic Feynman graph generation," Journal of Computational Physics 105(2), 279-289 (1993), doi:10.1006/jcph.1993.1074
• FORM: J. A. M. Vermaseren, "New features of FORM," arXiv:math-ph/0010025 (2000)
• LoopTools: T. Hahn and M. Perez-Victoria, "Automatized one-loop calculations in four and D dimensions," Computer Physics Communications 118(2-5), 153-165 (1999), doi:10.1016/S0010-4655(98)00173-8
• OpenLoops 2: F. Buccioni, J.-N. Lang, J. M. Lindert, P. Maierhöfer, S. Pozzorini, H. Zhang, M. F. Zoller, "OpenLoops 2," European Physical Journal C 79, 866 (2019), arXiv:1907.13071, doi:10.1140/epjc/s10052-019-7306-2
• COLLIER (used internally by OpenLoops): A. Denner, S. Dittmaier, L. Hofer, "COLLIER: a fortran-based Complex One-Loop LIbrary in Extended Regularizations," Computer Physics Communications 212, 220-238 (2017), doi:10.1016/j.cpc.2016.10.013
• OneLOop (used internally by OpenLoops): A. van Hameren, "OneLOop: For the evaluation of one-loop scalar functions," Computer Physics Communications 182(11), 2427-2438 (2011), arXiv:1007.4716
• CutTools (used internally by OpenLoops): G. Ossola, C. G. Papadopoulos, R. Pittau, "CutTools: a program implementing the OPP reduction method to compute one-loop amplitudes," JHEP 0803, 042 (2008), arXiv:0711.3596
• LHAPDF6: A. Buckley et al., "LHAPDF6: parton density access in the LHC precision era," European Physical Journal C 75, 132 (2015), doi:10.1140/epjc/s10052-015-3318-8
• RAMBO: R. Kleiss, W. J. Stirling, S. D. Ellis, "A new Monte Carlo treatment of multiparticle phase space at high energies," Computer Physics Communications 40(2-3), 359-373 (1986), doi:10.1016/0010-4655(86)90119-0
• Vegas (when the vegas extra is installed): G. P. Lepage, "A new algorithm for adaptive multidimensional integration," Journal of Computational Physics 27, 192 (1978)

Specific physics formulas

• Partonic QCD 2→2 (Combridge): J. F. Combridge, J. Kripfganz, J. Ranft, "Hadron production at large transverse momentum and QCD," Physics Letters B 70(2), 234-238 (1977), doi:10.1016/0370-2693(77)90528-7
• Heavy-top NLO QCD: R. K. Ellis, J. C. Sexton, "QCD radiative corrections to parton-parton scattering," Nuclear Physics B 269(2), 445-484 (1986), doi:10.1016/0550-3213(86)90232-4
• ggH cross-section in heavy-top limit: M. Spira, A. Djouadi, D. Graudenz, P. M. Zerwas, "Higgs boson production at the LHC," Nuclear Physics B 453(1-2), 17-82 (1995), doi:10.1016/0550-3213(95)00379-7; M. Spira, "Higgs Boson Production and Decay at Hadron Colliders," Progress in Particle and Nuclear Physics 95, 98-159 (2017), arXiv:1612.07651
• pp→DY NLO K-factor benchmark: C. Anastasiou, L. J. Dixon, K. Melnikov, F. Petriello, "High precision QCD at hadron colliders: electroweak gauge boson rapidity distributions at NNLO," Physical Review D 69, 094008 (2004), arXiv:hep-ph/0312266
• VBF Higgs (Hjj): T. Han, G. Valencia, S. Willenbrock, "Structure-function approach to vector-boson scattering in pp collisions," Physical Review Letters 69, 3274-3277 (1992), doi:10.1103/PhysRevLett.69.3274
• Diboson helicity amplitudes (HPZ): K. Hagiwara, R. D. Peccei, D. Zeppenfeld, K. Hikasa, "Probing the weak boson sector in e+e- → W+W-," Nuclear Physics B 282, 253-307 (1987), doi:10.1016/0550-3213(87)90685-7
• ee→ZZ: W. Beenakker, F. A. Berends, A. P. Chapovsky, "Radiative corrections to e+e- → ZZ," European Physical Journal C 8, 525-557 (1999); K. Hagiwara, D. Zeppenfeld, "Helicity amplitudes for heavy lepton production in e+e- annihilation," Nuclear Physics B 274, 1-32 (1986), doi:10.1016/0550-3213(86)90615-2
• Catani-Seymour K and P operators: S. Catani, M. H. Seymour, "The dipole formalism for the calculation of QCD jet cross sections at next-to-leading order," Physics Letters B 378(1-4), 287-301 (1996), doi:10.1016/0370-2693(96)00425-X; S. Catani, M. H. Seymour, Physics Letters B 467, 399-405 (1999) (erratum)
• Anti-k_T jet clustering: M. Cacciari, G. P. Salam, G. Soyez, "The anti-k_T jet clustering algorithm," Journal of High Energy Physics 04, 063 (2008), arXiv:0802.1189
• EW Sudakov LL+NLL framework: S. Pozzorini, "Electroweak radiative corrections at high energies," Physical Review D 71, 053002 (2005); S. Catani and L. Comelli, Physics Letters B 446, 278 (1999)
• Sargent + radiative corrections to μ/τ decay: A. Sirlin, "Radiative corrections in the SU(2)_L × U(1) theory: a simple renormalization framework," Physical Review D 22(4), 971-981 (1980); W. J. Marciano, A. Sirlin, "Improved calculation of electroweak radiative corrections and the value of V_ud," Physical Review Letters 96, 032002 (2006)
• LHC Higgs WG YR4 reference values: D. de Florian et al. (LHC Higgs Cross-Section Working Group), "Handbook of LHC Higgs Cross Sections: 4. Deciphering the Nature of the Higgs Sector," CERN-2017-002 (2016), arXiv:1610.07922
• τ hadronic decay BRs: R. L. Workman et al. (Particle Data Group), "Review of Particle Physics," Progress of Theoretical and Experimental Physics 2022, 083C01 (2022; updated 2024), τ section, doi:10.1093/ptep/ptac097
• PDG global review: the Particle Data Group, "Review of Particle Physics 2024." Used throughout for masses, widths, branching ratios, and quark/lepton/boson couplings.

Parton distribution functions

• NNPDF 4.0 (engine default): R. D. Ball et al. (NNPDF Collaboration), "The path to proton structure at 1% accuracy," European Physical Journal C 82, 428 (2022), arXiv:2109.02653
• CT18 (alternative): T.-J. Hou et al., "New CTEQ global analysis of quantum chromodynamics with high-precision data from the LHC," Physical Review D 103(1), 014013 (2021), arXiv:1912.10053
• MSHT20: S. Bailey, T. Cridge, L. A. Harland-Lang, A. D. Martin, R. S. Thorne, "Parton distributions from LHC, HERA, Tevatron and fixed target data: MSHT20 PDFs," European Physical Journal C 81, 341 (2021), arXiv:2012.04684

Background textbooks

M. E. Peskin and D. V. Schroeder, An Introduction to Quantum Field Theory (Westview, 1995). R. K. Ellis, W. J. Stirling, B. R. Webber, QCD and Collider Physics (Cambridge, 1996). M. D. Schwartz, Quantum Field Theory and the Standard Model (Cambridge, 2014). A. Denner, S. Dittmaier, "Electroweak Radiative Corrections for Collider Physics," Physics Reports 864, 1-163 (2020).