Research software documentation
GammaLoop
Differential cross-sections with Local Unitarity
Overview
GammaLoop is alpha-stage research software that computes numerical amplitude integrands and uses Local Unitarity for differential partonic cross sections. Its current external-kinematics path uses fixed momenta and a unit PDF factor; it does not yet provide hadronic PDF convolution or a factorization scale. Begin with the physics scope and method before translating a desired collider observable into a run card.
The primary manual path is written for perturbative-QFT and collider physicists. GammaLoop is an application rather than a thin numerical library: model import, process generation, integrand construction, integration, observables, persistence, and diagnostics meet in one stateful workflow. Rust and Python details become relevant only when structured automation is needed.
The command-line interface is the primary user interface. A run card creates a state, executes commands, and leaves a reusable working directory. The Rust and Python APIs load the same persisted state and expose selected structured operations; they do not define a second, independent execution model.
Choose a task
- To build or install the CLI and evaluate a compact one-loop scalar graph, follow the command-line guide.
- To decide whether an initial state, contribution, mass/spin choice, subtraction, and observable are supported, read physics scope and Local Unitarity.
- To define momentum flow, helicity and color ownership, flux, units, and sample weights, use the scientific conventions.
- To follow a maintained run card through the complete persistence lifecycle, use the first-state tutorial.
- To adapt a process specification or generation filters, use the process-generation guide with the generated
generatereference. - To inspect concrete cut events, selectors, and histogram snapshots without a full integration, follow the events and observables guide.
- To automate a loaded state or diagnose a long run, choose the Rust/Python interface guide or logging and diagnostics guide.
A stateful run
A typical source checkout is built and exercised from the repository root:
just build-cli-release
./gammaloop ./examples/cli/gg_hhh/1L/gg_hhh_1L.tomlThe run card imports a model, generates the requested process, executes its command blocks, and records the resulting state. Resume that directory explicitly for subsequent work:
./gammaloop -s ./examples/cli/gg_hhh/1L/state \
run integrate_physical -c "quit -o"The persisted run.toml records how to replay the run. The settings files describe global and default runtime configuration, while processes/ contains process-specific state. Ordinary runs create gammaloop_state/ unless a different state path is supplied.
The maintained
gg_hhh card is useful because it exercises model loading, generation, integration settings, and persistence. It selects a fixed-helicity amplitude contribution with an explicit color projector; running it does not by itself produce an unpolarized, color-averaged cross section or validate a published observable.Installation and external tools
For ordinary CLI use, begin with using GammaLoop from the command line. It recommends the packaged Nix application when Nix is available, but does not require it: a copy-and-paste Cargo route is provided for a standard Rust toolchain. Neither installation path requires a source checkout.
A source checkout is still needed to change GammaLoop or to work through repository-owned run cards. Its supported development path is the repository’s Nix shell, or a local Rust toolchain together with just, a recent GNU toolchain, and Python 3.11 or newer when building bindings. FORM 4.2.1 or newer is needed for analytical integration of integrated UV counterterms. UFO model import also needs the Python ufo-model-loader package.
Diagram rendering is a separate concern and uses Clinnet and Typst. Building the CLI does not imply that these drawing tools are installed. Use the Clinnet DOT-rendering guide for their independent versions, templates, and cache boundary.
Related crates
Linnet provides the half-edge graph model and graph algorithms. Spenso provides typed tensors, tensor structures, and network execution. Idenso handles symbolic tensor identities and algebraic simplification. Vakint matches and evaluates vacuum-integral topologies. GammaLoop combines these components into a collider-calculation workflow.
For a deeper view of how the command layer, state, integrands, and external components fit together, see the GammaLoop implementation architecture.
Where to begin
- Use built-in
--helpfor the CLI options supported by your installed version. - Start with the included
gg_hhhrun card for a complete state lifecycle, not as a substitute for a physical normalization and validation plan. - Record the method scope and every factor from the normalization checklist before launching a production run.
- Use the Rust or Python API only when a program needs structured access to loaded state or sample-evaluation results.
- Check prerequisites before starting an expensive integration; some workflows require a Symbolica license or external tools such as FORM.