Feynman diagrams from functional derivatives
a Mathematica package for perturbation theory, effective actions and many-body physics

Showcase · Manual · Guided tour · Installation

FunctionalDiagrams is a Mathematica package that derives Feynman diagrams the way one does on paper: from a generating functional and an interaction, by functional derivatives with respect to the sources and the propagators, with the fermion signs of the Grassmann algebra and the symmetry factors that the derivatives produce. It is meant for many-body physics and effective actions (Luttinger–Ward functionals, vertices, Bethe–Salpeter, parquet and Hedin's equations, GW, pairing), and also reaches relativistic field theory: φ⁴ theory and one-loop QED in dimensional regularization, and the diagrams of QCD.

The diagrams it produces can be compared up to relabelling, sorted into classes (connected, one- and two-particle irreducible, skeleton, reducible in a channel), differentiated again, checked against exact equations, evaluated in a few common cases, and drawn in Mathematica or exported as TikZ. Every step is worked out for φ⁴ theory and for the electron gas.

_{A preview of the demo video (an MP4 file, also in the repository as Media/demo.mp4): the first example below typed and run, then a few other results.}

Needs["FunctionalDiagrams`"]

(* free fermions, G0 = -<psi psibar>, and a two-body interaction V between densities *)
DeclareGrassmannSource[eta, etabar];
DeclareField[psi, etabar]; DeclareField[psibar, eta, -1];
Z0 = Exp[-IntegralOver[G0[x, y] etabar[x] ** eta[y], {x, y}]];
DeclareSymmetric[V]; DeclareInteractionLine[V]; DeclareDirectedPropagator[G0, G];
interaction =
  1/2 IntegralOver[V[x, y] psibar[x] ** psibar[y] ** psi[y] ** psi[x], {x, y}];

(* the Green function to second order: 1 + 2 + 10 diagrams, no vacuum bubbles *)
DiagramPlot[
  -PerturbativeCorrelationFunction[Z0, {psi[x], psibar[y]}, interaction, 2], {x, y}]

(* the Luttinger–Ward functional and its derivatives: Sigma(x, y) = dPhi/dG(y, x) and
   Gamma0(x1, x2; x3, x4) = dSigma(x1, x2)/dG(x4, x3), the irreducible vertex
   (the shortcuts SelfEnergy and IrreducibleVertex give the same) *)
Phi = LuttingerWardFunctional[Z0, interaction, 3, G0 -> G];
DiagramPlot[FunctionalDerivative[Phi, G[y, x]], {x, y}]
DiagramPlot[FunctionalDerivative[Phi, G[x4, x3], G[x2, x1]], {x1, x2, x3, x4}]

The output of the last three lines, up to second order: Φ[G] and its derivatives Σ and Γ⁰. A wavy line stands for −V, so that the number in front of a picture times the values of its lines is the term; (ph̄) and (pp) mark the diagrams of Γ⁰ reducible in those channels.

The guided tour (Examples.wl, the same as a script, can be read on GitHub) goes on from here in thirteen short sections: the effective actions, the Bethe–Salpeter and parquet equations, pairing, Hedin's equations and GW, and then linear response, Matsubara sums, phonons, disorder, dimensional regularization, QED and QCD. The showcase covers everything in more depth; every picture and number in it is computed by the package.

Each panel is drawn by the package from results it computes; the showcase derives and checks all of them.

Exact equations. Drawn with blobs and checked order by order against perturbation theory: Dyson, Bethe–Salpeter, the vertex Λ of the density, and the parquet decomposition of the full vertex F.

Screening. Hedin's equations (the double wavy line is the screened interaction W), and the 2PI functional Φ[G, W] of the dressed lines (here the wavy ones are W) with its derivatives: the first diagram gives the GW approximation, the next ones its vertex corrections.

Pairing. With the Nambu superfield (ψ, ψ̄) the anomalous propagators (lines with two arrows) are variables of Φ: the first order of Φ, the Gor'kov equations, and the Hartree–Fock self-energy and the BCS gap Δ.

Field theory. φ⁴ theory in dimensional regularization: the two-loop self-energy with its pole, and the β function. One-loop QED: the three 1PI functions, with δ₂, β(e) and the anomalous magnetic moment. QCD: the one-loop gluon self-energy.

The package needs Mathematica 12.1 or later (for the paclet manager that loads it). Install the paclet of a release, which also contains the showcase, the manual and the guided tour:

PacletInstall["https://github.com/n4sd4q/FunctionalDiagrams/releases/download/v2.3.0/FunctionalDiagrams-2.3.0.paclet"]   (* once *)
Needs["FunctionalDiagrams`"]

or download the .paclet file of the release and pass its path to PacletInstall. The latest release is 2.3.0, which this page and the documents describe (see the changelog).

A clone of the repository works as it is, with PacletDirectoryLoad["/path/to/FunctionalDiagrams"] and Needs["FunctionalDiagrams`"], or simply Get["/path/to/FunctionalDiagrams/FunctionalDiagrams.wl"]. ?FunctionalDiagrams`* lists the functions and ?Name explains each one.

Diagrams from a generating functional

• functional derivatives with bosonic and Grassmann sources, chain rule, implicit dependence; a canonical form in which equal diagrams are recognized (FunctionalDerivative, SimplifyDiagrams)
• Wick's theorem; Z[J] and W = log Z order by order, at zero or non-zero source; vacuum bubbles and the linked-cluster theorem (PerturbativeCorrelationFunction, ConnectedCorrelationFunction, ConnectedVacuumDiagrams)
• classes of diagrams: connected, one- and two-particle irreducible, skeleton, reducible in a channel; amputation; Dyson series (ParticleIrreducibleDiagrams, SkeletonDiagrams, IrreducibleDiagrams, AmputateExternalLegs)

Effective actions and exact equations

• 1PI vertices as derivatives of the 1PI action, and connected functions as trees of propagators and vertices, for bosons and fermions (ConnectedFunctionFromVertices; the shortcut PerturbativeFullVertex computes the vertices from the connected functions)
• the Luttinger–Ward functional Φ[G], with Σ = δΦ/δG and Γ⁰ = δΣ/δG taken by FunctionalDerivative, also for several propagators (LuttingerWardFunctional; the shortcuts SelfEnergy, IrreducibleVertex)
• the 2PI effective action Γ[G] and Γ[φ̄, G], the 1PI effective action Γ[φ̄] and Potthoff's self-energy functional as objects, with traces of operators, derivatives with respect to two-index objects, the grand potential and conserving responses evaluated in Matsubara frequency, and exact zero-dimensional checks (EffectiveAction2PI, EffectiveAction1PI, SelfEnergyFunctional, TraceLog, ZeroDimensionalValue)
• Bethe–Salpeter ladders and the parquet decomposition, for fermions (ph, ph̄, pp) and bosons (s, t, u): the fully irreducible vertex and the kernels of the channels as derivatives of the 2PI action, the classification by cutting lines as the check (BetheSalpeterLadder, ParquetDecomposition)
• superfields: the Nambu propagator of (ψ, ψ̄), anomalous parts included, as the variable of the 2PI functional, which gives the kernels of all three channels, is exact at finite means and yields Hartree–Fock–Bogoliubov and the BCS gap equation at first order ("Statistics" -> "Superfield", SuperfieldComponents)
• Dyson, Bethe–Salpeter, parquet, Schwinger–Dyson and Hedin's equations and the vertex of a one-body operator, drawn with blobs or checked order by order against perturbation theory (ExactEquation, CheckEquation, DeclareBlob)
• Hubbard–Stratonovich fields in both directions, and the functional Φ[G, W] whose first diagram is the GW approximation (HubbardStratonovich, IntegrateOutField)

Evaluating diagrams

• momenta and Matsubara frequencies routed through a diagram, frequency sums by residues with Fermi and Bose functions, analytic continuation, and the cutting rules at finite temperature (EvaluateMatsubara, MatsubaraSum, CheckCuttingRules)
• loop integrals in dimensional regularization, done one loop after the other (tadpoles, bubbles, G-functions), with the Laurent expansion in ε, MS-bar Z factors and renormalization-group functions; φ⁴ theory to two loops (DiagramLoopIntegral, IntegrateLoops, EpsilonExpand, BetaFunctionFromZ)
• QED at one loop: Dirac algebra in d dimensions, Feynman parameters and tensor reduction, the electron self-energy, the vacuum polarization and the vertex, with their renormalization constants and β(e) (QEDIntegrand, DiracSimplify, IntegrateOneLoop, VertexFormFactors)

The evaluation part is deliberately small: it covers the integrals that come up in the examples, not general loop calculations.

Pictures and formulas

• diagrams in the usual style of many-body papers (fermion lines straight, loops as circles, ladders as ladders, symmetric diagrams drawn symmetric), exact equations with blobs, and formulas as LaTeX (DiagramPlot, DiagramToTikZ, ExpressionToLaTeX); in a notebook the pictures follow its light or dark appearance

The theories are written in condensed notation, so the same functions work for real and complex bosons, fermions, phonons, disorder and QCD (quarks, gluons, ghosts).

The public functions by their role in a calculation: declare the symbols, write a functional, differentiate it, then classify, draw and evaluate the diagrams. The colour of a name is its group in the manual; dashed names are inert heads used as data. A name indented under another is built on it, and uses lists the other names it uses. The interactive version has every dependency: select a name to read its usage message and to see the lines to the names it uses and from the names that use it (the file is Documentation/function_map.html: GitHub shows only its source, so download it and open it in a browser).

The results are checked against each other, order by order, and the showcase reports every residual. For the electron gas and φ⁴ theory to third order these include the Dyson equation and the linked-cluster theorem, Σ[G] against the skeleton part of the perturbative Σ, the Ward identity, the Bethe–Salpeter and parquet equations in every channel, the Schwinger–Dyson, vertex and Hedin equations, and a Hubbard–Stratonovich theory against the original one. The evaluation is checked against numbers: frequency sums against brute-force sums, imaginary parts against the cutting rules, loop integrals against numerical integration in non-integer dimension, and the renormalization of φ⁴ theory and of one-loop QED against the textbook results (β functions, anomalous dimensions, the Ising exponents at the Wilson–Fisher fixed point, Z₁ = Z₂, the anomalous magnetic moment).

FeynArts and FeynCalc are the standard Mathematica tools for scattering amplitudes: FeynArts generates the diagrams of a process from a model's Feynman rules, and FeynCalc does the Dirac and colour algebra and the reduction of loop integrals. DoFun derives Dyson–Schwinger and functional renormalization group equations. FunctionalDiagrams starts from the generating functional instead, and is meant for the objects of many-body theory and effective actions: correlation and vertex functions, Φ[G] and its derivatives, channels and parquet equations, self-consistent approximations. Its evaluation tools are much more limited than FeynCalc's, so for real loop calculations the two are better used together.

wolfram -script Tests/RunTests.wl     # or: wolframscript -file Tests/RunTests.wl

If you use FunctionalDiagrams in published work, please cite it as described in CITATION.cff (GitHub shows a Cite this repository button), for example

@software{Africani_FunctionalDiagrams,
  author = {Africani, Nazzareno},
  title  = {{FunctionalDiagrams}: functional derivatives and {Feynman}
            diagrams in {Mathematica}},
  year   = {2026},
  url    = {https://github.com/n4sd4q/FunctionalDiagrams}
}

The history of the package is in CHANGELOG.md. Problems, questions and suggestions are welcome as issues: see CONTRIBUTING.md.

Released under the GNU General Public License, version 3 or later, with two additional terms: the attribution to the author must be kept, and modified versions must say that they are modified, by whom and when (see NOTICE, with the copyright and the terms). Author: Nazzareno Africani (SISSA).