Writing or importing a theory

TreeLevel knows no Feynman rule by heart: it derives them from the Lagrangian you give it. Two ways to give it — a .feyn file in a tiny language, or a UFO folder produced by FeynRules.

The principle

You declare the fields (spin, mass, width, charge, colour) and the parameters, then write the interaction Lagrangian term by term. Kinetic terms are not written: propagators follow from the declarations and the chosen gauge. Every term with three fields or more becomes a vertex:

V = i × Σ_{bijections legs ↔ fields} (term without its fields, ∂_μ → −i p_μ, all momenta incoming)

The sum over the ways of attaching the legs to the fields produces the combinatorial factors (−λ/4! φ⁴ gives −iλ), the symmetrisations of vertices with identical bosons, and for Majorana fermions or couplings with C the Denner combination Γ + Γ′.

The .feyn language

model QED
gauge feynman                       # feynman | unitary

param ee = 0.313451, Me = 0.000511  # parameters, numerical value optional
cparam V = 0.97                     # complex parameter; conj(V) is its conjugate

field e  : dirac, mass Me, charge -1, pdg 11, label "e"
field mu : dirac, mass MMU, charge -1, pdg 13, label "μ"
field A  : vector, pdg 22, label "γ"
field Z  : vector, mass MZ, width WZ  # the width enters the propagator
field u  : dirac, mass MU, charge 2/3, color 3
field G  : vector, color 8            # octet: gluon
field N  : majorana, mass MN          # its own antiparticle
field h  : scalar, mass MH
field Gp : scalar, mass MW, charge 1, goldstone

family lep = { e, mu }                # fields with the same structure
array  Q[lep] = { -1, -1 }            # parameters indexed by a family
define W3[mu] = cw Z[mu] + sw A[mu]   # macro; its dummy indices are renamed at each use

L += sum(i in lep) ee Q[i] lep[i]~[a] gamma[nu][a,b] lep[i][b] A[nu]
L += gs u~[a,k] gamma[nu][a,b] T[c,k,l] u[b,l] G[nu,c]
L += -gs f[a,b,c] (del[mu] G[nu,a]) G[mu,b] G[nu,c]
L += -lam/24 h h h h                 # −λ/4! φ⁴ → vertex −iλ

• Indices. An index name repeated within a term is contracted. Fields carry their indices in the order: spinor, then colour (u[a,k]); Lorentz, then adjoint colour (G[mu,c]). The kind of an index (Lorentz, spinor, triplet, octet) follows from its position.
• Conjugation. X~ is the conjugate of the field X: e~ is ē, W~ annihilates a W⁻ if W annihilates a W⁺. For a self-conjugate field (γ, Z, h, Majorana) the tilde is moot.
• Built-in tensors. g (metric), delta, gamma, gamma5, PL, PR, C (charge conjugation), T (Gell-Mann/2), f (structure constants), eps — the Lorentz Levi-Civita with four indices, the colour one with three.
• Derivatives and constants. del[mu] X; I; sqrt2; powers ^2 on parameters and numbers (a field is repeated: h h h h); conj(...).
• Fermions. Write bilinears in the natural order, ψ̄ Γ χ (the “row” field before the “column” field). majorana declares a self-conjugate spin-½ field: N̄ γ^μ γ⁵ N gives 2γ^μγ⁵ and N̄ γ^μ N vanishes, as it should.
• Conventions. Vertex = i × term, incoming momenta, del[mu] → -I p[mu]. The built-in Standard Model follows FeynRules' conventions (D = ∂ − i g T A, Φ = (−iG⁺, (v + h + iG⁰)/√2), Feynman gauge); its 129 vertices agree with those of MadGraph's sm UFO.

Syntax errors, index errors (one name used both as a spinor and a colour index) and structural errors (a C matrix that does not link two fermion fields) are reported with their line number in the Theory tab.

Example: adding a Z′ to the Standard Model

1. In the palette, model StandardModel, Duplicate button. The new model “StandardModel copie” is selected; rename it SM-Zprime.
2. Theory tab. Add below the parameters and fields:

   param gZp = 0.3, MZp = 3000, WZp = 30
   field Zp : vector, mass MZp, width WZp, label "Z′"
   # universal vector coupling to the charged leptons
   L += sum(i in lep) gZp lep[i]~[a] gamma[nu][a,b] lep[i][b] Zp[nu]

3. Apply. The Z′ appears in the palette, the vertex list has three more entries.
4. Draw e⁺e⁻ → μ⁺μ⁻, Generate: three diagrams (γ, Z, Z′). Plot σ from 200 to 5,000 GeV on a log scale: the peak at 3 TeV has the width you declared. For a consistent width, draw Z′ → e⁺e⁻, read Γ in the Compute tab, and put it back (× the number of channels) into WZp.

Fermion-number-violating couplings

Diquarks, leptoquarks, the X and Y bosons of a grand-unified theory, Majorana-type terms with Dirac fields: these couplings link two fields “in the same direction” — two ψ or two ψ̄ — through the charge-conjugation matrix C = iγ²γ⁰ (Cᵀ = −C, Cγ^μᵀC⁻¹ = −γ^μ):

# ψᵀ C Γ χ  =  ψ̄ᶜ Γ χ           (ψᶜ = C ψ̄ᵀ, ψ̄ᶜ = ψᵀ C)
L += -g5/sqrt2 d[a,k] C[a,b] gamma[mu][b,c] PL[c,d] e[d] X[mu,k]
# ψ̄ Γ C χ̄ᵀ  =  ψ̄ Γ χᶜ          (its Hermitian conjugate)
L += -g5/sqrt2 e~[a] gamma[mu][a,b] PL[b,c] C[c,d] d~[d,k] X~[mu,k]
# diquark: colour ε, the same field twice → rule Γ + Γ′
L += -g5/sqrt2 eps[k,l,m] u~[a,l] gamma[mu][a,b] PL[b,c] C[c,d] u~[d,m] X[mu,k]

TreeLevel absorbs C into the vertex rule: the rule is Γ between the “row” leg (ψ, or ψ̄) and the “column” leg, and it is the fermion flow — oriented chain by chain after Denner, Eck, Hahn and Küblbeck — that carries the conjugation: Γ′ = CΓᵀC⁻¹ when a vertex is crossed against its orientation, S(−p) for a propagator run backwards, spinors u, v, ū, v̄ according to the position in the chain rather than particle/antiparticle. The result does not depend on the chosen orientation; the tests check it on every process.

Two identities the engine reproduces, and which serve as safeguards: ε_klm ū_l γ^μP_L C ū_mᵀ = ε_klm ū_l γ^μP_R C ū_mᵀ (the X diquark couples both chiralities, whence Γ(X → uu) = Γ(X → e⁺d̄)), and the axial diquark coupling ε ū γ^μγ⁵ C ūᵀ vanishes identically, like the vector coupling of a Majorana fermion.

Importing a UFO

The UFO format (Universal FeynRules Output) is the Python folder FeynRules produces for MadGraph and the other generators: particles.py, parameters.py, couplings.py, lorentz.py, vertices.py… TreeLevel reads it natively, without Python: a small reader of declarative Python evaluates the internal parameters (cmath functions, mixing matrices, complex expressions), recognises self-conjugate fermions as Majorana, and translates every Lorentz and colour structure into a rule.

1. Get a UFO folder: from a MadGraph installation (models/sm, models/MSSM_SLHA2…) or from the FeynRules model database.
2. Palette › Model › 📁 Import a UFO folder. The import takes a fraction of a second; the report gives fields, vertices, parameters and, if any, the skipped vertices and why.
3. The model is in My models, ready for the palette, generation, numerical and symbolic computations. The Theory tab gives its Import notes.

Conventions applied, established on MadGraph's sm UFO (129/129 vertices identical to the derived Standard Model): particle lists and momenta all outgoing, Gamma(mu,i,j) = (γ^μ)_ij with i on the ψ̄ side, ProjM = P_L, T(a,i,j) = (T^a)_ij, three-index colour Epsilon. The MSSM_SLHA2 imports entirely (50 fields, 1,572 parameters, 822 vertices); its neutralinos and gluino are handled as Majorana.

FeynRules, .fr, UFO, .feyn: who does what

Translating a .fr into a .feyn is done by hand today, often an hour's work for a model of reasonable size: the conventions (D_μ, projectors, normalisations) are the same. The recommended path for a large model remains .fr → UFO → import.