Getting Started

Install

pip install feynlag

feynlag depends on SymPy and NumPy at runtime (NumPy is used only by the numeric integration in feynlag.pheno). The optional numeric extra adds SciPy for adaptive quadrature in the off-shell decay widths.

For development, install from a clone:

pip install -e .[dev]
pytest

The dev extra adds pytest, SciPy, matplotlib (for authoring the tutorial notebooks) and nbstripout (notebook diff hygiene — see the repo’s CLAUDE.md).

Quick tour

import sympy as sp
from feynlag import (ExternalParameter, InternalParameter, SU2, U1, Scalar,
                     Lagrangian, Model, Dmu, dag)

gw  = ExternalParameter("gw", 0.6535, positive=True)
g1  = ExternalParameter("g1", 0.3580, positive=True)
SU2L, U1Y = SU2("SU2L", coupling=gw), U1("U1Y", coupling=g1)

v   = ExternalParameter("v", 246.0, positive=True, unit_dim=1)
lam = ExternalParameter("lam", 0.129)
mu2 = InternalParameter("mu2", unit_dim=2)      # defined by the tadpole

H = Scalar("H", reps={SU2L: 2, U1Y: sp.Rational(1, 2)},
           component_names=["Gp", "H0"])
H.expand_vev({H.components[1]: v})              # H0 -> (v + h + i G0)/sqrt(2)

HdH = (dag(H) * H.mat)[0]
DH  = Dmu(H)
L = Lagrangian()
L.add((dag(DH) * DH)[0], sector="kinetic")
L.add(mu2.s * HdH - lam.s * HdH**2, sector="potential")

m = Model("SM", gauge_groups=[SU2L, U1Y],
          fields=[H, SU2L.bosons("W"), U1Y.bosons("B")],
          parameters=[gw, g1, v, lam, mu2], lagrangian=L)

m.check_invariance()          # gauge invariance, hermiticity, dim <= 4
m.solve_tadpoles([mu2])       # {mu2: lam v^2}, registered as internal

h = sp.Symbol("H0_r", real=True)
m.mass_matrix([h])            # Matrix([[2 lam v^2]])
m.feynman_rules([h])          # {(h,h,h): -6i lam v, (h,h,h,h): -6i lam}

Every stage above corresponds to one chapter of the Algorithms Manual. For a complete worked model, read examples/sm_scalar_gauge.py alongside 1. The Pipeline, or run the SM tutorial notebook.

Reusable SM scaffolding

Building a BSM model usually means “the Standard Model, plus something”. The feynlag.models module ships the electroweak scaffold — the SU(2)×U(1) gauge groups, the Higgs doublet with its potential, and the physical-basis rotations (Weinberg angle → Z/γ, then W±) — so an extension file writes only its new physics:

from feynlag import electroweak_scaffold, to_physical_basis, standard_model

ew = electroweak_scaffold()          # groups + Higgs + parameters
L = Lagrangian(); ew.add_higgs(L)    # kinetic + potential
# ... add your own fermions / Yukawas / extension to L ...
model = Model("my_bsm", gauge_groups=ew.gauge_groups,
              fields=ew.fields + [...], parameters=ew.parameters + [...],
              lagrangian=L)
phys = to_physical_basis(model, ew)  # Z, A, W±, Goldstones, conjugate map

sm = standard_model(generations=1)   # or the whole vanilla SM in one call

Composable primitives (electroweak_gauge, higgs_doublet, weinberg_rotation, charged_current_rotation) cover non-standard cases — e.g. a U(1)_X model whose Weinberg step feeds a chained Z–Z′ rotation. Every examples/sm_*.py uses these helpers.

Validation

The test suite pins the physics, not just the code (dual verification: symbolic difference and random-point numeric checks — see 10. Verification Philosophy):

  • SM Higgs: mu^2 = lam*v^2, m_h^2 = 2*lam*v^2, h^3 = -3i m_h^2/v, h^4 = -3i m_h^2/v^2

  • SM gauge: m_W = g*v/2, Weinberg rotation, hWW = i g m_W g^{mu nu}, gamma*W+*W- = e, Z*W+*W- = g cos(theta_W), scalar-QED Goldstone vertices

  • SM leptons: h*l*l = -i m_l/v, W*l*nu = i g/sqrt(2) gamma^mu P_L, Z couplings proportional to T^3 - Q sin^2(theta_W)

  • 2HDM: tadpoles, all three mass matrices and rotation angles vs the Gunion-Haber/Branco expressions

  • 3HDM+S3: invariant potential from the library’s CG products; the tadpole system forces the sqrt(3) alignment

  • UFO: generated model imports cleanly; parameters resolve in dependency order; hWW coupling pinned numerically

Status / roadmap

Working: scalars, gauge bosons, chiral fermions (bilinear track), tadpoles, mass matrices (real/charged/gauge blocks), orthogonal/SVD/Takagi diagonalization, momentum-space vertices for the closed catalog (SSS SSSS VSS VVS VVSS VVV VVVV FFS FFV), LaTeX tables, UFO export (including full SU(3) color-tensor strings).

Deferred (v2): R_xi gauge fixing and ghosts, four-fermion operators, NLO/UFO 2.0 extensions.