pyAmpliCol

PyPI Python versions Tests License: 0BSD

Fast color-ordered scattering amplitudes from Python and native APIs.

pyAmpliCol generates portable process artifacts from built-in, JSON, and UFO models, then evaluates them through a fast Rust runtime. It supports a typed Python API and CLI, runtime helicity and color-flow selection, and generated Python, C11, C++17, Fortran 2008, and Rust 2021 interfaces.

Start here

I want to… Read
follow a physicist-friendly, MadGraph-style walkthrough Get started: a gentle walkthrough
install pyAmpliCol and verify it Installation
generate and evaluate my first process Quick Start
choose a model, process, color approximation, or evaluator Configuration and Models and Processes, including the packaged scalar HEFT workflow
check whether my UFO model is supported UFO Model Coverage, the exact list of accepted, conditional and rejected model features
call pyAmpliCol from Python Python API
prepare and evaluate tree-level spin and colour correlations Born Correlations and Correlation Conventions, LC/NLC/full colour and grouped Python evaluation
use C, C++, Fortran, Rust, or generated Python drivers Native APIs
benchmark, reproduce, or view performance reports Profiling and Benchmarking, FullColor FFT Profiling, and published performance reports
diagnose an error Troubleshooting

Install and try it 

python -m venv .venv
. .venv/bin/activate
python -m pip install pyamplicol
pyamplicol self-test

Generate a small built-in Standard Model process and inspect the artifact:

pyamplicol generate "d d~ > z" ./artifacts/ddbar_z \
  --model built-in-sm
pyamplicol inspect ./artifacts/ddbar_z

The generated process appears in the inspection table as:

+---------+-------------+------------------+-------+--------------+---------------+
| default | stable ID   | concrete process | color | helicities  | color outputs |
+---------+-------------+------------------+-------+--------------+---------------+
|    *    | d_dbar_to_z | d d~ > z         | lc    | 12 (6 eval.) | 1             |
+---------+-------------+------------------+-------+--------------+---------------+

The CLI uses color automatically on an interactive terminal; the plain capture above remains readable in logs and documentation.

One artifact, several interfaces 

model + process request
          │
          ▼
generated process artifact
          ├── Python Runtime
          ├── C / C++ / Fortran / Rust APIs
          ├── selectors and arbitrary precision
          └── benchmarking and profiling

Ordinary Python evaluation uses the same runtime as the native interfaces:

import math

from pyamplicol import Runtime

runtime = Runtime.load("artifacts/ddbar_z", process="d d~ > z")
energy = 91.188 / 2.0
momenta = [[
    [energy, 0.0, 0.0, energy],
    [energy, 0.0, 0.0, -energy],
    [2.0 * energy, 0.0, 0.0, 0.0],
]]
value = runtime.evaluate(momenta)
resolved = runtime.evaluate_resolved(momenta)
for optimized, explicit in zip(value, resolved.total(), strict=True):
    assert math.isclose(optimized.real, explicit.real, rel_tol=1e-12, abs_tol=1e-15)
    assert math.isclose(optimized.imag, explicit.imag, rel_tol=1e-12, abs_tol=1e-15)

Process expressions may reorder particles within the incoming side or within the outgoing side. pyAmpliCol consistently permutes momenta, helicities, color flows, and resolved metadata; particles never cross the > boundary. See Process Selection and Permutations.

Explore the documentation

This site is the authoritative user documentation for the current main branch. Release and Support records the published platform and validation boundary, while public API stability is defined by the API contract.