Tutorial

This tutorial builds the GammaLoop command-line interface and uses the included one-loop g g -> h h h run card to create a state that can be inspected and resumed. Compilation and process generation can take longer than a --help smoke test.

For the shortest installation and first-run path, begin with Using GammaLoop from the command line. Then return here to create, inspect, and resume the larger bundled example.

What this example establishes
The card selects one fixed-helicity, one-loop amplitude contribution and supplies an explicit 1/8 color projector. It demonstrates software state creation, inspection, and resumption; it is not an unpolarized, automatically color-averaged cross section. Read the method and capability boundary and normalization conventions before interpreting either integration block as a physical result.

Prerequisites

Work from a GammaLoop source checkout. The supported development environment is the repository Nix shell; without Nix you need Rust 1.85 or newer, just, a recent GNU toolchain, and the dependencies described in the root README. The bundled Standard Model used below does not need the UFO loader. A Symbolica license may be required by your build and use case.

nix develop
just build-cli
./gammaloop --help

The last command should print the one-shot CLI options and command tree. The ./gammaloop wrapper selects the binary built under target/dev-optim/.

Verification scope and cost
The docs harness checks these shell blocks for syntax; it does not build or execute GammaLoop. Verify a clean checkout manually in nix develop. A cold CLI build and process generation are the high-resource path and can take tens of minutes, while reopening a valid state is normally much cheaper. The invariant for this tutorial is a resumable state with the files listed below, not a completed Monte Carlo integration.

Generate an example process

The run card declares a state folder, settings, and named command blocks. Run its generate block and persist the result on exit:

./gammaloop --clean-state \
  ./examples/cli/gg_hhh/1L/gg_hhh_1L.toml \
  run generate -c "quit -o"

--clean-state removes the resolved state first
Use it only for this first, reproducible run. Omit it when resuming work you want to keep. Its generated argument reference records the exact valueless-flag semantics. The example card resolves its state to examples/cli/gg_hhh/1L/state and requests ten worker cores; make a private copy of the card before changing either value.

The block imports sm-default.json, generates the selected one-loop pentagon amplitude contribution, applies the card’s explicit helicity and color choices, builds its integrand, saves DOT data, and writes the state. A successful run exits without an error and leaves at least run.toml, global_settings.toml, default_runtime_settings.toml, and processes/ in the state folder. run.toml records the commands and settings needed to replay the run; it is not merely a log file.

Resume the saved state

Load the saved state and ask the active session to display its processes:

./gammaloop -s ./examples/cli/gg_hhh/1L/state \
  run -c "display processes; quit -o"

Success means the display includes the generated gg_hhh process and the command exits while keeping the same state. You can now run the card’s integrate_euclidean or integrate_physical block, but those are deliberately beyond the first-success path because they request a substantial Monte Carlo integration and require a separate normalization and validation plan.

Inspect before expensive work

Reopen the state read-only and inspect both the generated structure and the effective integrator settings before launching either integration block:

./gammaloop --read-only-state \
  -s ./examples/cli/gg_hhh/1L/state \
  run -c "display integrand -p gg_hhh -i 1L; display settings process -p gg_hhh -i 1L integrator; quit"

display integrand reports the generation backend, compiled record size, graph and graph-group counts, and detailed orientation, loop-momentum-basis, cut, and threshold tables. The settings command resolves the values attached to this generated integrand, which may differ from the current defaults. Check these records together: an unexpected graph count points back to process generation, while an unexpected sample budget, target accuracy, or seed belongs to runtime settings.

Read-only inspection is not persistence
--read-only-state prevents commands from writing inside the active state directory and disables file logging there. It does not make the in-memory session immutable. This command intentionally exits without -o; change settings in a separate writable session or in the run card that reconstructs the state.

The exact fields and selectors are kept current in the generated integrand display and process-settings references.

Troubleshooting and next steps

If the wrapper cannot find a binary, rerun just build-cli and confirm that target/dev-optim/gammaloop exists.
If compilation or process generation exhausts local resources, copy the card and reduce the values under cli_settings.global.n_cores; do not edit a state midway through generation.
If startup reports a state fingerprint or settings mismatch, replay the card with a new state folder instead of transplanting only its processes/ directory.
Use ./gammaloop help generate to inspect the flags supported by your installed version, then continue with the process-generation guide and the generate-command reference.

Example run card
See the complete gg_hhh run card before adapting the process, state location, or resource settings for your own calculation.