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
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
pip install feynman-engine
feynman setup # builds QGRAF, FORM, LoopTools, LHAPDF, OpenLoops 2 (10-20 min, one-time)
feynman serve # http://localhost:8000For platform-specific prerequisites, Docker, and troubleshooting, see INSTALLATION.md.
- 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 → ggK=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 isroughat √s<700 GeV,approximateabove) 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 | 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 |
| 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.
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% |
- 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_amplitudeextension API; seeexamples/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.
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 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.
Jupyter notebooks in examples/ cover different audiences and lead with runnable code:
getting_started.ipynb: install, first diagram, browser UIfor_undergrad_qft.ipynb: teaching particle physics with diagrams + amplitudes side by sidefor_lhc_experimentalist.ipynb: LHC observables, K-factors, dσ/dM_ll across the Z peakfor_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
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.
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.
- 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
- 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
vegasextra is installed): G. P. Lepage, "A new algorithm for adaptive multidimensional integration," Journal of Computational Physics 27, 192 (1978)
- 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.
- 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
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).