Command-Line Interface

The pyamplicol command covers the complete user workflow: inspect or compile a model, plan or generate process artifacts, inspect their physics axes, evaluate phase-space points, and profile the optimized runtime. The same schema also drives the typed Python API.

[!TIP] Start with the four-card walkthrough in Quick Start. This page is a command map, not a requirement to configure every available switch.

Command map

Command	Purpose	Typical use
generate	Plan or write a process artifact	pyamplicol generate "d d~ > z g" artifacts/builtin_ddbar_to_zg --model built-in-sm
evaluate	Evaluate totals or resolved components	pyamplicol evaluate artifacts/builtin_ddbar_to_zg --momenta point.json
profile	Calibrate and measure the optimized total path	pyamplicol profile artifacts/builtin_ddbar_to_zg --target-runtime 1
benchmark	Compatibility alias for profile	Existing cards use action = "benchmark"
inspect	Show artifact and process metadata without running it	pyamplicol inspect artifacts/builtin_ddbar_to_zg
model inspect	Summarize a built-in, JSON, UFO, or compiled model	pyamplicol model inspect models/json/sm/sm.json
model compile	Compile portable model IR or a prepared kernel bundle	See Models and Processes
model processes	Expand and inspect a process request without generating it	pyamplicol model processes "p p > all all" --model built-in-sm
config template	Write the exhaustive schema-v1 TOML template	pyamplicol config template run.toml
config resolve	Show requested and effective settings	pyamplicol config resolve run.toml
examples list	List shipped card names, actions, and descriptions	pyamplicol examples list
examples copy	Create an editable, self-contained example workspace	pyamplicol examples copy ./pyamplicol-examples --force
examples run	Run one named packaged card in a private cache workspace	pyamplicol examples run evaluate_total
profiling-campaign copy	Create a self-contained performance campaign	See Profiling Campaigns
doctor	Diagnose the installed runtime and SDK	pyamplicol doctor
self-test	Run the installed-package smoke test	pyamplicol self-test

License-request helpers are documented in Symbolica and Licensing.

Run pyamplicol COMMAND --help for the options accepted by a command. For the model family, place --help after the second verb, for example pyamplicol model compile --help.

Cards, direct options, and overrides

There are three equivalent ways to supply configuration:

1. a schema-v1 TOML card;
2. dedicated command-line options;
3. repeated --set PATH=VALUE overrides.

Configuration precedence is:

defaults < TOML card < dedicated CLI options < repeated --set overrides

Any license or resource clamp is applied last and reported in the effective configuration. Unknown fields are errors rather than silently ignored.

Run a card directly:

pyamplicol generate_pp_zjj_from_ufo_sm.toml

Use an explicit action when the same card supplies shared settings:

pyamplicol generate --card qq_z6g_recurrence_jit_o2.toml
pyamplicol profile --card qq_z6g_recurrence_jit_o2.toml

Override one leaf without editing the card:

pyamplicol generate_pp_zjj_from_ufo_sm.toml \
  --set generation.workers=2 \
  --set generation.mode=replace

--set is deliberately repeatable and order-sensitive. For commonly used fields, prefer the readable dedicated form—for example --workers 2, --execution-mode eager, or --color-accuracy nlc.

For the complete field reference, see Configuration or create an annotated local template:

pyamplicol config template pyamplicol.toml

Generate

The shortest built-in-model command is:

pyamplicol generate "d d~ > z g" artifacts/builtin_ddbar_to_zg \
  --model built-in-sm

Useful generation options include:

• --process EXPRESSION to add another request;
• --name NAME to name a request;
• --multiparticle 'p=d,d~,g' to define a multiparticle label;
• --flavor-scheme N and --max-quark-lines N to constrain expansion;
• --color-accuracy {lc,nlc,full};
• --color-contraction {direct,symmetric-group-fft};
• --fft {trace,adjoint} as a shorthand selecting symmetric-group FFT and its basis;
• --correlators FILE.json to prepare named colour operators and allowed spin replacements for the Python and native correlated APIs;
• --lc-flow-layout {topology-replay,all-flow-union};
• --execution-mode {recurrence,compiled,eager,on-the-fly};
• --backend {jit,asm,cpp};
• --workers auto|N;
• --mode {error,append,replace} or the --force shortcut for replacement;
• --no-emit-api-bundle when standalone drivers are not wanted;
• --numerical-current-reuse to search for certified numerical current relations at generation time (off by default because the high-precision probes are costly);
• --post-build-validation for an optional immediate native total-versus- resolved smoke after writing the artifact.

Planning is non-writing:

pyamplicol generate "p p > Z j j" artifacts/unused \
  --model models/json/sm/sm.json \
  --multiparticle 'p=d,d~,g' --multiparticle 'j=d,d~,g' \
  --flavor-scheme 2 --max-quark-lines 2 \
  --execution-mode compiled --dry-run

Adaptive --fft adjoint is the recommended starting point for exact FFT colour contraction. It selects certified DDM where valid and otherwise retains exact fundamental-chain or trace tensors. Select contracted colour and a supported execution lane (recurrence or on-the-fly) explicitly:

pyamplicol generate "g g > g g g" artifacts/ggg_adjoint_fft \
  --model built-in-sm --color-accuracy full \
  --fft adjoint --execution-mode recurrence

Use --execution-mode on-the-fly for the compact OTF counterpart. The same option works for quark processes, using their existing fundamental chains:

pyamplicol generate "d d~ > z g g" artifacts/quark_zgg_fft \
  --model built-in-sm --color-accuracy full \
  --fft adjoint --execution-mode recurrence

For a certified n-gluon tree, DDM fixes two gluon anchors and retains (n-2)! orderings instead of (n-1)!. Certified single-insertion HEFT also uses DDM: see examples/builtin_sm_heft.toml, which explicitly sets HIG = 1. Other interactions retain their exact trace representation; multi-quark-line processes retain fundamental-chain products, not a JO primitive basis. The saved fft_basis_selection states the requested and actual basis and the selection reason. --fft trace forces the original representation. Both requests preserve full or nlc accuracy; forced adjoint FFT rejects correlations. In the benchmarked pure-gluon family the adjoint basis was faster than trace for six or more external gluons (3.9x per sample and 4x faster generation at ten gluons); at lower multiplicity the two are comparable, so compare warmed evaluation and setup costs for other workloads. --color-contraction symmetric-group-fft remains valid and defaults to adjoint. Without an explicit contraction flag, NLC/full recurrence and on-the-fly generation automatically try adaptive adjoint FFT and fall back to direct if the FFT plan is unsupported. LC, compiled/eager, and correlated generation remain direct/trace. Use --color-contraction direct to opt out. Do not combine --fft and --color-contraction; use either spelling. Card settings are overridden by dedicated flags, then by ordered --set options as usual.

For the dedicated direct/FFT/reference scaling scan, see FullColor FFT Profiling.

--dry-run performs the operation exposed as Generator.plan(). It creates no artifact, output directory, or model-cache entry. A raw UFO or JSON source must already have a reusable compiled-model cache entry, or be compiled explicitly, because planning never compiles trusted model input as a side effect.

See Generation Modes and Evaluators before combining execution modes and prepared-model backends.

Correlated Born quantities

The Born Correlations guide gives the declaration format and complete runtime examples:

pyamplicol generate 'g g > g g' artifacts/gg_correlated \
  --model built-in-sm --color-accuracy full --correlators correlators.json

--correlators is a generation option, separate from the ordinary TOML colour settings. --color-accuracy lc|nlc|full selects the correlated approximation (the ordinary default is LC). Complete amplitudes are generated in all cases; direct contraction and generic compiled execution are selected, with those adjustments recorded in the effective configuration. Partial helicity/colour generation, append, and --dry-run are not supported on this path. Numerical spin-vector setting and correlated evaluation use Runtime.set_spin_correlation_vectors(...) and Runtime.evaluate_correlated(...) or Runtime.evaluate_correlated_many(...) in Python, or the corresponding native SDK calls, not the CLI evaluate command.

Inspect and select a process

List an artifact’s stable process IDs and coverage:

pyamplicol inspect artifacts/pp_zjj

Focus on one public process ordering:

pyamplicol inspect artifacts/pp_zjj --process 'd d~ > g z g'

The selector may be a stable process ID, an explicit alias ID, an exact stored expression, or a unique side-preserving permutation of one. See Process Selection and Permutations for the ordering contract.

Inspection does not execute evaluator state. Human output uses compact colored tables; machine output is available with --json.

Evaluate

Evaluate a momenta file with optional parameter updates:

pyamplicol evaluate artifacts/pp_zjj \
  --process 'd d~ > g z g' \
  --model-parameters data/model_parameters.json \
  --momenta data/pp_zjj_momenta.json

Request all physical components rather than only the optimized sum:

pyamplicol evaluate artifacts/pp_zjj \
  --process 'd d~ > g z g' \
  --momenta data/pp_zjj_momenta.json \
  --resolved

Global selectors may be repeated:

pyamplicol evaluate artifacts/pp_zjj \
  --process p_p_to_z_j_j_4 \
  --helicity 'h:-1,+1,-1,+1,+1' \
  --color-flow 1 \
  --momenta data/pp_zjj_momenta.json

--color-flow accepts either a stable flow ID or the one-based ordinal shown by inspect. Flow selection is LC-only; NLC and full-color artifacts expose a contracted color output and accept helicity selection only. More examples are in Runtime and Selectors.

Profile

The profiler measures the same optimized total path as Runtime.evaluate():

pyamplicol profile artifacts/pp_zjj \
  --process 'd d~ > g z g' \
  --momenta data/pp_zjj_momenta.json \
  --target-runtime 1.0 \
  --batch-size 128 \
  --color-flow 1 \
  --precision 16

It calibrates repetitions, keeps at least the requested independent sample count, and reports uncertainty. Ctrl-C during sampling preserves completed blocks and prints a result marked partial. See Profiling and Benchmarking for metric meanings and selector-aware profiling. If both profile selector axes are omitted, the stored LC layout supplies a deterministic optimized selector; explicit non-hot shapes are retained and produce at most one pre-loop warning per loaded process.

Models

Inspect a trusted UFO directory without generating a process:

pyamplicol model inspect models/ufo/sm

Compile portable model IR:

pyamplicol model compile models/ufo/sm models/sm.pyAmplicol-model.json

Prepare a reusable JIT-O2 kernel bundle for eager or recurrence execution:

pyamplicol model compile \
  models/json/sm/sm.json models/ufo-sm-jit-o2.pyamplicol-model \
  --backend jit --jit-optimization-level 2

Enumerate a broad request without writing a process artifact:

pyamplicol model processes "p p > all all" \
  --model built-in-sm --flavor-scheme 1 --max-quark-lines 0

The distinction between portable model IR and prepared kernel bundles is explained in Models and Processes.

Examples and installed workspaces

List the available names before running one:

pyamplicol examples list
pyamplicol examples run generate_pp_zjj_from_ufo_sm

The list uses a colored table on a terminal. Add --json for stable, uncolored machine-readable output.

examples run accepts the stem of a shipped .toml card. all_options is a reference template, not a runnable example. Unknown names fail with the full available-name list.

For an editable and inspectable workspace, copying is usually clearer:

pyamplicol examples copy ./pyamplicol-examples --force
cd pyamplicol-examples
pyamplicol generate_pp_zjj_from_ufo_sm.toml

See Examples Gallery for the complete card inventory and recommended sequences.

Output, color, progress, and logging

The common presentation options are:

Option	Values	Meaning
--json	flag	Emit stable machine-readable stdout instead of the human-facing table
--color	auto, always, never	Detect a terminal, force ANSI color, or disable it
--progress	auto, tty, log, off	Select live bars, rate-limited log progress, or silence
--log-level	debug, info, warning, error	Control diagnostic verbosity

JSON mode keeps stdout machine-readable; progress and diagnostics use stderr. This makes pipelines predictable:

pyamplicol inspect artifacts/pp_zjj --json > artifact.json

Use --color always only when the consumer understands ANSI escapes. The default auto mode produces colored terminal tables and plain redirected output.

Diagnostics

Start with the two installed-package checks:

pyamplicol doctor
pyamplicol self-test

Then inspect the relevant artifact and effective configuration:

pyamplicol inspect artifacts/pp_zjj --json > inspect.json
pyamplicol config resolve run.toml --json > config.json

For common failures and the information to include in a bug report, see Troubleshooting and Release and Support.

Next steps

• Configuration
• Models and Processes
• Generation Modes and Evaluators
• Runtime and Selectors
• Native APIs