Metadata-Version: 2.4
Name: pyamplicol
Version: 0.1.3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Zero-Clause BSD (0BSD)
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Dist: colorama==0.4.6
Requires-Dist: numpy==2.4.2
Requires-Dist: platformdirs==4.10.0
Requires-Dist: prettytable==3.18.0
Requires-Dist: progressbar2==4.5.0
Requires-Dist: six==1.17.0
Requires-Dist: symbolica==2.2.0
Requires-Dist: tomli-w==1.2.0
Requires-Dist: ufo-model-loader==0.1.7
Requires-Dist: pypdf>=5,<6 ; extra == 'docs'
Requires-Dist: build>=1.2,<2 ; extra == 'test'
Requires-Dist: jsonschema>=4.22,<5 ; extra == 'test'
Requires-Dist: maturin==1.14.1 ; extra == 'test'
Requires-Dist: mypy>=1.13,<2 ; extra == 'test'
Requires-Dist: pytest>=8.3,<9 ; extra == 'test'
Requires-Dist: ruff>=0.9,<1 ; extra == 'test'
Requires-Dist: twine>=6,<7 ; extra == 'test'
Requires-Dist: wheel>=0.45,<1 ; extra == 'test'
Provides-Extra: docs
Provides-Extra: test
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/GammaLoop-model-assets.txt
License-File: licenses/GammaLoop.txt
License-File: licenses/MadGraph5_aMCatNLO.txt
License-File: licenses/SymJIT.txt
License-File: licenses/Symbolica.txt
License-File: licenses/ufo-model-loader.txt
License-File: licenses/rust/ahash-0.8.12/LICENSE-APACHE
License-File: licenses/rust/ahash-0.8.12/LICENSE-MIT
License-File: licenses/rust/allocator-api2-0.2.21/LICENSE-APACHE
License-File: licenses/rust/allocator-api2-0.2.21/LICENSE-MIT
License-File: licenses/rust/anyhow-1.0.103/LICENSE-APACHE
License-File: licenses/rust/anyhow-1.0.103/LICENSE-MIT
License-File: licenses/rust/autocfg-1.5.1/LICENSE-APACHE
License-File: licenses/rust/autocfg-1.5.1/LICENSE-MIT
License-File: licenses/rust/bincode-2.0.1/LICENSE.md
License-File: licenses/rust/bincode_derive-2.0.1/LICENSE.md
License-File: licenses/rust/bitflags-1.3.2/LICENSE-APACHE
License-File: licenses/rust/bitflags-1.3.2/LICENSE-MIT
License-File: licenses/rust/block-buffer-0.10.4/LICENSE-APACHE
License-File: licenses/rust/block-buffer-0.10.4/LICENSE-MIT
License-File: licenses/rust/bytemuck-1.25.1/LICENSE-APACHE
License-File: licenses/rust/bytemuck-1.25.1/LICENSE-MIT
License-File: licenses/rust/bytemuck-1.25.1/LICENSE-ZLIB
License-File: licenses/rust/cfg-if-1.0.4/LICENSE-APACHE
License-File: licenses/rust/cfg-if-1.0.4/LICENSE-MIT
License-File: licenses/rust/cpufeatures-0.2.17/LICENSE-APACHE
License-File: licenses/rust/cpufeatures-0.2.17/LICENSE-MIT
License-File: licenses/rust/crossbeam-deque-0.8.7/LICENSE-APACHE
License-File: licenses/rust/crossbeam-deque-0.8.7/LICENSE-MIT
License-File: licenses/rust/crossbeam-epoch-0.9.20/LICENSE-APACHE
License-File: licenses/rust/crossbeam-epoch-0.9.20/LICENSE-MIT
License-File: licenses/rust/crossbeam-utils-0.8.22/LICENSE-APACHE
License-File: licenses/rust/crossbeam-utils-0.8.22/LICENSE-MIT
License-File: licenses/rust/crypto-common-0.1.7/LICENSE-APACHE
License-File: licenses/rust/crypto-common-0.1.7/LICENSE-MIT
License-File: licenses/rust/digest-0.10.7/LICENSE-APACHE
License-File: licenses/rust/digest-0.10.7/LICENSE-MIT
License-File: licenses/rust/either-1.16.0/LICENSE-APACHE
License-File: licenses/rust/either-1.16.0/LICENSE-MIT
License-File: licenses/rust/equivalent-1.0.2/LICENSE-APACHE
License-File: licenses/rust/equivalent-1.0.2/LICENSE-MIT
License-File: licenses/rust/fixedbitset-0.5.7/LICENSE-APACHE
License-File: licenses/rust/fixedbitset-0.5.7/LICENSE-MIT
License-File: licenses/rust/foldhash-0.1.5/LICENSE
License-File: licenses/rust/foldhash-0.2.0/LICENSE
License-File: licenses/rust/generic-array-0.14.7/LICENSE
License-File: licenses/rust/getrandom-0.3.4/LICENSE-APACHE
License-File: licenses/rust/getrandom-0.3.4/LICENSE-MIT
License-File: licenses/rust/hashbrown-0.15.5/LICENSE-APACHE
License-File: licenses/rust/hashbrown-0.15.5/LICENSE-MIT
License-File: licenses/rust/hashbrown-0.16.1/LICENSE-APACHE
License-File: licenses/rust/hashbrown-0.16.1/LICENSE-MIT
License-File: licenses/rust/hashbrown-0.17.1/LICENSE-APACHE
License-File: licenses/rust/hashbrown-0.17.1/LICENSE-MIT
License-File: licenses/rust/heck-0.5.0/LICENSE-APACHE
License-File: licenses/rust/heck-0.5.0/LICENSE-MIT
License-File: licenses/rust/hugepage-rs-0.1.1/LICENSE-APACHE
License-File: licenses/rust/hugepage-rs-0.1.1/LICENSE-MIT
License-File: licenses/rust/indexmap-2.14.0/LICENSE-APACHE
License-File: licenses/rust/indexmap-2.14.0/LICENSE-MIT
License-File: licenses/rust/itoa-1.0.18/LICENSE-APACHE
License-File: licenses/rust/itoa-1.0.18/LICENSE-MIT
License-File: licenses/rust/lazy_static-1.5.0/LICENSE-APACHE
License-File: licenses/rust/lazy_static-1.5.0/LICENSE-MIT
License-File: licenses/rust/libc-0.2.186/LICENSE-APACHE
License-File: licenses/rust/libc-0.2.186/LICENSE-MIT
License-File: licenses/rust/mach2-0.4.3/LICENSE-APACHE
License-File: licenses/rust/mach2-0.4.3/LICENSE-BSD
License-File: licenses/rust/mach2-0.4.3/LICENSE-MIT
License-File: licenses/rust/memchr-2.8.3/COPYING
License-File: licenses/rust/memchr-2.8.3/LICENSE-MIT
License-File: licenses/rust/memchr-2.8.3/UNLICENSE
License-File: licenses/rust/num-complex-0.4.6/LICENSE-APACHE
License-File: licenses/rust/num-complex-0.4.6/LICENSE-MIT
License-File: licenses/rust/num-traits-0.2.19/LICENSE-APACHE
License-File: licenses/rust/num-traits-0.2.19/LICENSE-MIT
License-File: licenses/rust/once_cell-1.21.4/LICENSE-APACHE
License-File: licenses/rust/once_cell-1.21.4/LICENSE-MIT
License-File: licenses/rust/petgraph-0.8.3/LICENSE-APACHE
License-File: licenses/rust/petgraph-0.8.3/LICENSE-MIT
License-File: licenses/rust/petgraph-0.8.3/assets/images/LICENSE.md
License-File: licenses/rust/ppv-lite86-0.2.21/LICENSE-APACHE
License-File: licenses/rust/ppv-lite86-0.2.21/LICENSE-MIT
License-File: licenses/rust/proc-macro2-1.0.106/LICENSE-APACHE
License-File: licenses/rust/proc-macro2-1.0.106/LICENSE-MIT
License-File: licenses/rust/pyo3-0.28.3/LICENSE-APACHE
License-File: licenses/rust/pyo3-0.28.3/LICENSE-MIT
License-File: licenses/rust/pyo3-0.28.3/pyo3-runtime/LICENSE-APACHE
License-File: licenses/rust/pyo3-0.28.3/pyo3-runtime/LICENSE-MIT
License-File: licenses/rust/pyo3-build-config-0.28.3/LICENSE-APACHE
License-File: licenses/rust/pyo3-build-config-0.28.3/LICENSE-MIT
License-File: licenses/rust/pyo3-ffi-0.28.3/LICENSE-APACHE
License-File: licenses/rust/pyo3-ffi-0.28.3/LICENSE-MIT
License-File: licenses/rust/pyo3-macros-0.28.3/LICENSE-APACHE
License-File: licenses/rust/pyo3-macros-0.28.3/LICENSE-MIT
License-File: licenses/rust/pyo3-macros-backend-0.28.3/LICENSE-APACHE
License-File: licenses/rust/pyo3-macros-backend-0.28.3/LICENSE-MIT
License-File: licenses/rust/quote-1.0.46/LICENSE-APACHE
License-File: licenses/rust/quote-1.0.46/LICENSE-MIT
License-File: licenses/rust/rand-0.9.5/COPYRIGHT
License-File: licenses/rust/rand-0.9.5/LICENSE-APACHE
License-File: licenses/rust/rand-0.9.5/LICENSE-MIT
License-File: licenses/rust/rand_chacha-0.9.0/COPYRIGHT
License-File: licenses/rust/rand_chacha-0.9.0/LICENSE-APACHE
License-File: licenses/rust/rand_chacha-0.9.0/LICENSE-MIT
License-File: licenses/rust/rand_core-0.9.5/COPYRIGHT
License-File: licenses/rust/rand_core-0.9.5/LICENSE-APACHE
License-File: licenses/rust/rand_core-0.9.5/LICENSE-MIT
License-File: licenses/rust/rayon-1.12.0/LICENSE-APACHE
License-File: licenses/rust/rayon-1.12.0/LICENSE-MIT
License-File: licenses/rust/rayon-core-1.13.0/LICENSE-APACHE
License-File: licenses/rust/rayon-core-1.13.0/LICENSE-MIT
License-File: licenses/rust/region-3.0.2/LICENSE
License-File: licenses/rust/safe_arch-1.0.0/LICENSE-APACHE.md
License-File: licenses/rust/safe_arch-1.0.0/LICENSE-MIT.md
License-File: licenses/rust/safe_arch-1.0.0/LICENSE-ZLIB.md
License-File: licenses/rust/serde-1.0.228/LICENSE-APACHE
License-File: licenses/rust/serde-1.0.228/LICENSE-MIT
License-File: licenses/rust/serde_core-1.0.228/LICENSE-APACHE
License-File: licenses/rust/serde_core-1.0.228/LICENSE-MIT
License-File: licenses/rust/serde_derive-1.0.228/LICENSE-APACHE
License-File: licenses/rust/serde_derive-1.0.228/LICENSE-MIT
License-File: licenses/rust/serde_json-1.0.150/LICENSE-APACHE
License-File: licenses/rust/serde_json-1.0.150/LICENSE-MIT
License-File: licenses/rust/serde_spanned-1.1.1/LICENSE-APACHE
License-File: licenses/rust/serde_spanned-1.1.1/LICENSE-MIT
License-File: licenses/rust/sha2-0.10.9/LICENSE-APACHE
License-File: licenses/rust/sha2-0.10.9/LICENSE-MIT
License-File: licenses/rust/spec_math-0.1.6/LICENSE-APACHE
License-File: licenses/rust/spec_math-0.1.6/LICENSE-MIT
License-File: licenses/rust/symjit-2.22.0/LICENSE
License-File: licenses/rust/syn-2.0.119/LICENSE-APACHE
License-File: licenses/rust/syn-2.0.119/LICENSE-MIT
License-File: licenses/rust/target-lexicon-0.13.5/LICENSE
License-File: licenses/rust/thiserror-2.0.18/LICENSE-APACHE
License-File: licenses/rust/thiserror-2.0.18/LICENSE-MIT
License-File: licenses/rust/thiserror-impl-2.0.18/LICENSE-APACHE
License-File: licenses/rust/thiserror-impl-2.0.18/LICENSE-MIT
License-File: licenses/rust/toml-1.1.3+spec-1.1.0/LICENSE-APACHE
License-File: licenses/rust/toml-1.1.3+spec-1.1.0/LICENSE-MIT
License-File: licenses/rust/toml_datetime-1.1.1+spec-1.1.0/LICENSE-APACHE
License-File: licenses/rust/toml_datetime-1.1.1+spec-1.1.0/LICENSE-MIT
License-File: licenses/rust/toml_parser-1.1.2+spec-1.1.0/LICENSE-APACHE
License-File: licenses/rust/toml_parser-1.1.2+spec-1.1.0/LICENSE-MIT
License-File: licenses/rust/toml_writer-1.1.2+spec-1.1.0/LICENSE-APACHE
License-File: licenses/rust/toml_writer-1.1.2+spec-1.1.0/LICENSE-MIT
License-File: licenses/rust/typenum-1.20.1/LICENSE
License-File: licenses/rust/typenum-1.20.1/LICENSE-APACHE
License-File: licenses/rust/typenum-1.20.1/LICENSE-MIT
License-File: licenses/rust/unicode-ident-1.0.24/LICENSE-APACHE
License-File: licenses/rust/unicode-ident-1.0.24/LICENSE-MIT
License-File: licenses/rust/unicode-ident-1.0.24/LICENSE-UNICODE
License-File: licenses/rust/unty-0.0.4/LICENSE-APACHE
License-File: licenses/rust/unty-0.0.4/LICENSE-MIT
License-File: licenses/rust/version_check-0.9.5/LICENSE-APACHE
License-File: licenses/rust/version_check-0.9.5/LICENSE-MIT
License-File: licenses/rust/virtue-0.0.18/LICENSE.md
License-File: licenses/rust/wasmtime-jit-icache-coherence-34.0.2/LICENSE
License-File: licenses/rust/wide-1.5.0/LICENSE-ZLIB.md
License-File: licenses/rust/winnow-1.0.4/LICENSE-MIT
License-File: licenses/rust/zerocopy-0.8.54/LICENSE-APACHE
License-File: licenses/rust/zerocopy-0.8.54/LICENSE-BSD
License-File: licenses/rust/zerocopy-0.8.54/LICENSE-MIT
License-File: licenses/rust/zmij-1.0.23/LICENSE-MIT
Summary: Generator using current recursion to build fast color-ordered matrix-element evaluators
Keywords: high-energy physics,matrix elements,UFO,Symbolica
Author-email: Rikkert Frederix <rikkert.frederix@thep.lu.se>, Valentin Hirschi <valentin.hirschi@gmail.com>, Timea Vitos <timea.vitos@thep.lu.se>
License-Expression: 0BSD
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://mg5amcnlo.github.io/pyamplicol/
Project-URL: Homepage, https://github.com/mg5amcnlo/pyamplicol
Project-URL: Issues, https://github.com/mg5amcnlo/pyamplicol/issues
Project-URL: Source, https://github.com/mg5amcnlo/pyamplicol

<!-- SPDX-License-Identifier: 0BSD -->

<p align="center">
  <img src="https://raw.githubusercontent.com/mg5amcnlo/pyamplicol/main/docs/assets/pyamplicol_logo.png" alt="pyAmpliCol" width="760">
</p>

<p align="center">
  <a href="https://pypi.org/project/pyamplicol/"><img src="https://img.shields.io/pypi/v/pyamplicol.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/pyamplicol/"><img src="https://img.shields.io/pypi/pyversions/pyamplicol.svg" alt="Python versions"></a>
  <a href="https://mg5amcnlo.github.io/pyamplicol/"><img src="https://img.shields.io/badge/docs-User%20Guide-2f81f7.svg?logo=githubpages" alt="pyAmpliCol documentation"></a>
  <a href="https://github.com/mg5amcnlo/pyamplicol/actions/workflows/tests.yml"><img src="https://github.com/mg5amcnlo/pyamplicol/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
  <a href="https://github.com/mg5amcnlo/pyamplicol/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-0BSD-blue.svg" alt="License: 0BSD"></a>
</p>

<p align="center"><strong>Fast color-ordered scattering amplitudes from Python and native APIs.</strong></p>

pyAmpliCol generates and evaluates color-ordered scattering amplitudes from
built-in, JSON, or UFO models. It provides a typed Python API and CLI, fast
Rust-backed execution, runtime helicity and color-flow selection, and generated
Python, C11, C++17, Fortran 2008, and Rust 2021 interfaces.

Explore the complete [pyAmpliCol documentation](https://mg5amcnlo.github.io/pyamplicol/)
for guided workflows, API examples, technical reference, and release support.

## Installation

Install the release from PyPI:

```console
python -m venv .venv
. .venv/bin/activate
python -m pip install pyamplicol
```

The binary wheels include the Rust runtime and native SDK; wheel users do not
need a Rust compiler. pyAmpliCol has no LHAPDF dependency.

To build the tagged source snapshot:

```console
git clone --branch v0.1.3 --depth 1 https://github.com/mg5amcnlo/pyamplicol.git
cd pyamplicol
python -m pip install .
```

A source build requires Python 3.11 or newer, Rust 1.89 or newer, and a C/C++
toolchain. A Fortran compiler is required only for Fortran consumers.

Contributor setup uses pinned source dependencies and produces explicitly
non-publishable candidate builds:

```console
nix develop  # optional on Nix/NixOS
just dev-install
PYTHON=.venv/bin/python just dev-test
```

The first `just dev-install` native build can take several minutes. Repeated
installs reuse the workspace-local Cargo cache and are substantially faster.

Full installation details are in the
[documentation](https://mg5amcnlo.github.io/pyamplicol/).

## Quick start

Copy the installed examples into an editable workspace:

```console
pyamplicol examples copy ./pyamplicol-examples --force
cd pyamplicol-examples
```

Keep the Python environment containing pyAmpliCol activated while using the
top-level CLI and Python examples, or invoke its executables by explicit path.
For a copy below a source checkout prepared by `just dev-install`, generated
artifact Python and native API drivers also find the nearest checkout `.venv`
automatically; explicit SDK overrides and an active environment take
precedence.

The primary example generates a multiprocess `p p > Z j j` artifact from the
packaged serialized Standard Model, then evaluates and profiles one concrete
subprocess. Its 19 ordered candidates collapse to eight side-permutation
classes; it stores the seven tree-level representatives and reports the
omitted loop-induced `g g > Z g g` class. The card inherits the portable JIT
O2 default, so its process artifact can be moved between supported 64-bit
little-endian macOS arm64, macOS x86_64, and Linux x86_64 hosts:

```console
pyamplicol generate_pp_zjj_from_ufo_sm.toml
pyamplicol evaluate_total.toml
pyamplicol evaluate_resolved.toml
pyamplicol benchmark.toml
```

For direct CLI use:

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

pyamplicol inspect ./artifacts/builtin_ddbar_to_zg
```

Process generation can also be steered directly from Python:

```python
from pyamplicol import GenerationConfig, Generator

generator = Generator(GenerationConfig(workers=4))
plan = generator.plan("d d~ > z g")  # Resolve without writing an artifact.
result = generator.generate(
    "d d~ > z g",
    "artifacts/builtin_ddbar_to_zg",
    mode="replace",
)
print(result.output)
```

The same runtime is available from Python:

```python
import json
from pathlib import Path

from pyamplicol import Runtime

momenta = json.loads(Path("data/pp_zjj_momenta.json").read_text())
runtime = Runtime.load("artifacts/pp_zjj", process="d d~ > g z g")
total = runtime.evaluate(momenta)
resolved = runtime.evaluate_resolved(momenta)
assert resolved.total() == total
```

Concrete process expressions may reorder particles within the incoming side or
within the outgoing side. Rusticol maps momenta, helicities, color flows, and
resolved metadata to that requested order; particles never cross the `>`
boundary. Stable process IDs remain available when more than one generated
representative could match an expression.

See the
[examples guide](https://github.com/mg5amcnlo/pyamplicol/blob/main/examples/README.md)
for complete cards, parameter updates, selector examples, and generated API
drivers.

## Models and execution

pyAmpliCol supports:

- the packaged built-in Standard Model;
- packaged serialized JSON and trusted UFO examples;
- user-supplied JSON or trusted UFO model paths;
- leading-color, contracted next-to-leading-color, and contracted full-color
  calculations;
- recurrence, compiled-DAG, and eager execution modes;
- JIT, C++, and assembly evaluator backends where supported;
- binary64 execution without importing Symbolica, plus precision-controlled
  Python evaluation when exact expressions are retained.

Generated artifacts preserve complete public helicity and color axes. Runtime
calls can select one flow or helicity globally or per phase-space point without
regenerating the artifact.

The public C ABI is version 1. Every generated artifact can include standalone
Python, C11, C++17, Fortran 2008, and dependency-free Rust 2021 drivers backed
by the wheel-owned static Rusticol SDK.

## Profiling campaigns

An installed wheel can populate a self-contained campaign workspace:

```console
pyamplicol profiling-campaign copy ./pyamplicol-profiling-campaign --force
cd ./pyamplicol-profiling-campaign
./steer_performance_campaign.py run \
  --workers 1 --table matrix --process-id 1 --multiplicity 1 \
  --color-approximation lc --generation-mode non-union-flow \
  --generation-engine recurrence --model built_in
```

That deliberately small real campaign measures only the final-state-
multiplicity-one `d d~ > Z` recurrence cell. Broader campaign selections are
intended for dedicated profiling hosts. The
[documentation](https://mg5amcnlo.github.io/pyamplicol/) covers selection,
continuation, optional original-AmpliCol comparisons, artifact retention, and
PDF generation.

The repository retains only two rendered performance snapshots. Raw JSON,
generated tables, attempts, and campaign workspaces stay untracked:

- [MacBook M3 report](https://github.com/mg5amcnlo/pyamplicol/blob/main/docs/performance_reports/macbook_M3_pyAmpliCol.pdf)
- [AMD EPYC report](https://github.com/mg5amcnlo/pyamplicol/blob/main/docs/performance_reports/EPYC_pyAmpliCol.pdf)

These are manual measurement snapshots rather than release-CI results; raw
campaign data remains local and the report format is reproducible from an
installed package.

## Documentation

Read the complete [pyAmpliCol documentation](https://mg5amcnlo.github.io/pyamplicol/).

## Dependencies and license

Release builds use pinned published dependencies plus SymJIT 2.22.0 from an
immutable revision of the official
[symjit-crate repository](https://github.com/siravan/symjit-crate).

pyAmpliCol is distributed under the 0BSD license. Third-party components and
model assets retain their own terms; see
[THIRD_PARTY_NOTICES.md](https://github.com/mg5amcnlo/pyamplicol/blob/main/THIRD_PARTY_NOTICES.md).

