Tutorials

Ten fully executed Jupyter notebooks, walking a worked model stage by stage with real (stored) output — plots, mass matrices, Feynman rules. They are tracked through the nbstripout --keep-output git filter (see the repo’s CLAUDE.md), so what you see below is exactly what re-running the notebook produces.

• How to compute a particle decay
• 2→2 scattering in feynlag: from Mandelstam invariants to a forward–backward asymmetry
• From Pauli matrices to any SU(N): gauge representations with feynlag
• Discrete symmetries: representations, characters, and the construction of invariants
• Feynman rules of the Standard Model with feynlag
• Vector-like fermions in feynlag: SM + a vector-like lepton doublet
• Extending the SM by a gauged U(1)\(_X\): a Z′ tutorial in feynlag
• Model building with feynlag: suggest + anomaly cancellation
• The type-I seesaw in feynlag: Majorana neutrino masses, step by step
• 3HDM with S₃ flavor symmetry: forcing the vacuum, not tuning it

Particle Decays Tutorial

How to get from a Lagrangian to a measured lifetime, for a student who has met Feynman rules and Dirac spinors but never carried a decay calculation through to a number. Derives everything by hand first — two-body phase space and the Källén function, the spin sums that turn \(|\mathcal{M}|^2\) into a Dirac trace, the trace theorems, polarisation sums — and only then reveals DecayCalculator as the automation of exactly those steps. Lands on \(\Gamma(h\to f\bar f) = N_c m_h m_f^2\beta^3/8\pi v^2\) (with the \(\beta^3\) explained as the P-wave signature of a CP-even scalar), \(\Gamma(Z\to\nu\bar\nu)\) and \(\Gamma(W\to\ell\nu)\) within ~1% of the PDG, and the familiar Higgs branching-ratio-versus-mass plot. Then completes the picture: the DiracParticle fermion sector, and the off-shell \(1\to3\) \(h\to WW^*/ZZ^*\) (a \(W^*\) line-shape figure showing the virtual \(W\) never reaches its mass shell, and the canonical Higgs BR chart — \(b\bar b\) 61%, \(WW^*\) 25%). Closes with the two mistakes that fail silently — forgetting that a Dirac fermion is two Weyl fields (an error that vanishes in the massless limit), and closed channels turning \(\sqrt\lambda\) imaginary — and then builds a \(Z'\) from scratch to show the same machinery on a new model.

Scattering Tutorial

The first native cross section, not a decay width: \(e^+e^-\to\mu^+\mu^-\) through a photon (Tier 1), matched against the Peskin & Schroeder closed form, then \(e^+e^-\to\mu^+\mu^-\) through the Z alone (Tier 2), where a real electron Z coupling is pulled straight out of a built SM Lagrangian rather than typed in as a textbook formula. Derives by hand why the \(\gamma_5\) (ε-tensor) term that vanishes in every decay this library computes — two independent momenta is never enough — survives for \(2\to2\), where two chiral currents meeting at one propagator give three, and walks the two derived (not quoted) identities in feynlag.pheno.epsilon that compute it: the trace coefficient \(\kappa=-4i\) and the Gram-determinant sign \(s_{\det}=-1\). Reproduces the LEP forward–backward asymmetry \(A_{FB}=\tfrac34A_eA_f\) from first principles, with a \(d\sigma/d\cos\theta\) figure showing the chiral tilt against a symmetric vector-coupling baseline, and closes with a total-cross-section sanity check showing the ε term is an angular effect only — it integrates away, so Tier 1’s QED benchmark is untouched.

SU(N) Groups Tutorial

A gentle, self-contained introduction to gauge representations for a reader new to particle physics (linear algebra + basic QM only). Builds up from “what is a generator?” through the Lie algebra and representations to feynlag’s dynamic any-SU(N)/any-irrep machinery: Dynkin labels and the Weyl dimension formula, a peek at the highest-weight/ladder (Gelfand–Tsetlin) construction (with the tell-tale √2 ladder entries of the 6 of SU(3)), conjugate representations T̄ = −T*, and anomaly coefficients — culminating in the SU(5) 5̄ + 10 anomaly cancellation and a gauge-invariance check of a scalar in the fundamental of SU(4).

Discrete Groups Tutorial

The discrete counterpart to the SU(N) notebook: the finite flavour symmetries (\(\mathbb{Z}_N\), \(S_3\), \(A_4\)) that model builders impose to forbid terms. Built around one practical question — how many free parameters does an invariant potential have, and can you know before writing a single term? — answered by deriving \(S_3\)’s character table from its generator matrices (nothing typed in), verifying orthogonality and \(\sum_r(\dim r)^2=|G|\), and then predicting invariant counts by group averaging and checking each against explicit Clebsch–Gordan construction. Covers the four traps that produce wrong counts: the antisymmetric \(\mathbf{1'}\) vanishing on a repeated multiplet; distinct legs versus one field (four doublets give 3 quartic invariants, one doublet gives 1 — characters versus the Molien series); basis conventions, where CG coefficients differ between the real and complex \(S_3\) bases but counts do not; and the conjugate leg \(X=(M^{-1})^{\mathsf T}\), which equals \(M\) only for real orthogonal irreps, so the \(S_3\) coincidence hides the \(\mathbb{Z}_N\) error. Lands on the 3HDM: imposing \(S_3\) cuts the potential from 33 operators to 10 (2 mass + 8 quartic), the number THDM_S3_Tutorial builds on. Closes by defining \(A_4\) — the workhorse flavour group, which the library does not ship — on top of DiscreteSymmetry, deriving its character table and running reynolds_project and check_discrete_invariance on it unchanged.

SM Feynman Rules Tutorial

Builds the full Standard Model (Higgs, electroweak gauge, leptons, QCD) from scratch and extracts its Feynman rules, mirroring examples/sm_scalar_gauge.py one pipeline stage at a time.

SM VLL Tutorial

Adds a vector-like lepton doublet to the SM and walks the biunitary diagonalization of the resulting mass matrix, including a standalone demo of why expand_bilinear is required for fermion mass-basis rotations to extract correctly.

SM U(1)_X Tutorial

Extends the SM by a second, symbolically-charged abelian gauge factor and walks the chained Weinberg → Z–Z′ rotation that results from tree-level kinetic/mass mixing.

Model Building Tutorial

Goes one step earlier than the others: instead of analyzing a hand-written Lagrangian, it shows the model-building tools. For a dark U(1)_D sector with symbolic charges it uses feynlag.anomalies to derive the anomaly-free charge assignment (forcing the dark fermion to be vector-like), feynlag.suggest to enumerate the invariant operator basis (and catch a mistuned charge that admits no mass term), and build_lagrangian to assemble a validated model before running the full pipeline to the dark-photon mass and Z_D χχ coupling.

SM Seesaw Tutorial

The Standard Model extended by right-handed neutrinos with a large Majorana mass — the type-I seesaw. Uses the Majorana machinery (diracC, MajoranaBilinear, majorana_mass_matrix) to build the [[0, m_D], [m_Dᵀ, M_R]] mass matrix, diagonalize_takagi for the light (sub-eV) + heavy (~M_R) spectrum, and the charge-conjugation-aware MajoranaRotation to extract the physical heavy-neutrino couplings — showing W ℓ̄ N = (g/√2)·V with the light–heavy mixing V ≈ m_D/M_R, and its decoupling as M_R → ∞.

3HDM with S₃ Tutorial

The library’s group-theory stress test: three Higgs doublets, with (H1, H2) forming an S3 doublet and HS an S3 singlet, and the potential built entirely from S3.doublet_product’s own \(2\otimes2=1\oplus1'\oplus2\) Clebsch–Gordan decomposition. Introduces the one genuinely new invariance concept in the whole tutorial set — a finite discrete-symmetry check (check_discrete_invariance, the exact group substitution) rather than the infinitesimal linearization every gauge check elsewhere relies on — and shows a model where the vacuum isn’t free to tune: with three VEVs but only two independent mass parameters, the third tadpole condition forces the alignment \(v_1^2=v_2^2/3\), derived directly from the symbolic tadpole system rather than assumed — matching, up to the basis swap, the tadpole solution of the literature S₃-3HDM model (Gómez-Bock, Mondragón & Pérez-Martínez, EPJC 81, 942 (2021)) this example follows. Builds the pseudoscalar and charged mass matrices alongside the CP-even one, then implements and verifies that paper’s geometric rotation ansatz: it exactly, symbolically diagonalizes the Goldstone-protected pseudoscalar/charged sectors for any couplings, while the CP-even sector needs one further dynamical mixing angle (reusing the same 2×2 tool thdm.py uses for the plain 2HDM) — closing with a numerical stability scan (mirroring the paper’s own) that turns a mostly tachyonic benchmark point into seven genuine physical scalar masses.