Metadata-Version: 2.4
Name: pyevtgen
Version: 0.0.1.dev24+g3c4f80f23
Summary: Python bindings for the EvtGen particle decay generator
Keywords: EvtGen,HEP,Monte Carlo,event generator,particle physics
Author-Email: Common Partial Wave Analysis <compwa-admin@ep1.rub.de>
Maintainer-Email: Unknown <compwa-admin@ep1.rub.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Project-URL: Changelog, https://github.com/ComPWA/pyevtgen/releases
Project-URL: EvtGen, https://gitlab.cern.ch/evtgen/evtgen
Project-URL: Issues, https://github.com/ComPWA/pyevtgen/issues
Project-URL: Source, https://github.com/ComPWA/pyevtgen
Requires-Python: >=3.11
Requires-Dist: numpy
Description-Content-Type: text/markdown

<!-- cspell:ignore direnv kpipi scikit -->

# pyevtgen

[![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)

Python bindings for [EvtGen](https://gitlab.cern.ch/evtgen/evtgen), the Monte Carlo generator for particle decays, in particular weak decays of heavy-flavor hadrons.

The wheels are self-contained: EvtGen 3.1.0, HepMC 3.3.1 and Pythia 8.318 are compiled statically into the extension module, and the package ships EvtGen's default decay table (`DECAY.DEC`), its particle table (`evt.pdl`) and the Pythia8 data that the `PYTHIA` decay model needs. No ROOT installation or environment variables are required.

> [!NOTE]
> This is an unofficial package that is not maintained by the EvtGen authors.

## Installation

```shell
pip install pyevtgen
```

Wheels are built for Linux (x86_64, aarch64) and macOS (arm64, x86_64) for Python 3.11 and newer: one wheel for Python 3.11 and one stable ABI (`abi3`) wheel for Python 3.12 and newer. There are also wheels for [Pyodide](https://pyodide.org), which runs Python in the browser through WebAssembly.

## Usage

```python
from pyevtgen import Generator, final_state_momenta

generator = Generator(seed=42)
event = generator.decay("B0")
for particle in event.final_state():
    print(particle.name, particle.pdg_id, particle.p4)
```

A `Particle` holds its EvtGen name, PDG ID, lab-frame four-momentum `p4` as (E, px, py, pz) in GeV, production `position` as (ct, x, y, z) in mm, and its `daughters`. Pass `p4=` to `decay()` or `generate()` to boost the parent; by default it decays at rest.

To study a single channel, override the default decay table with a user decay file and stack the events into a NumPy array of shape `(n_events, n_final_state, 4)`:

```python
generator = Generator(user_decay_file="D0_Kpipi0.dec", seed=0)
events = generator.generate("D0", n=10_000)
momenta = final_state_momenta(events)
```

To generate unweighted phase space for arbitrary masses, use `phase_space()`. It needs no `Generator` or decay table, and returns an array of shape `(n_events, n_daughters, 4)`:

```python
from pyevtgen import phase_space

momenta = phase_space(3.097, [0.135, 0.14, 0.14], n=10_000, seed=0)
```

Particle properties from the particle table are available by name or PDG ID:

```python
generator.properties("J/psi").mass
generator.properties(443).width
```

Final-state radiation can be simulated with Vincia's QED shower from Pythia8 by passing `fsr=True`. It applies to decay channels that carry the `FSR` (or legacy `PHOTOS`) flag in the decay file. PHOTOS++, Tauola++ and Sherpa are not included.

### Limitations

EvtGen stores its particle table, decay table and random engine in global state, so a process can create only one `Generator`. Reuse it, or call `read_user_decay_file()` to load additional decay files. EvtGen terminates the process on a malformed decay file, which Python cannot catch as an exception.

## Development

The project builds with [scikit-build-core](https://scikit-build-core.readthedocs.io) and [nanobind](https://nanobind.readthedocs.io). CMake downloads the pinned EvtGen, HepMC3 and Pythia8 sources on the first build, so building from source requires network access and a C++17 compiler.

[Pixi](https://pixi.sh) provides the compilers, CMake, Ninja and uv, while [uv](https://docs.astral.sh/uv) manages the Python environment in `.venv`. With [direnv](https://direnv.net), the `.envrc` file activates both when you enter the repository.

```shell
pixi run test     # build the package and run the tests
pixi run style    # formatters and linters
pixi run build    # source distribution and wheel in dist/
pixi run doc      # documentation with executed notebooks in docs/_build/html
pixi run upgrade  # upgrade lock files and pre-commit hooks
```

uv rebuilds the extension automatically when C++ or CMake sources change. You can also use uv directly with a system C++17 compiler, for instance `uv run pytest`.

The VS Code workspace recommends extensions for the Python and C++ tooling. For C++, [clangd](https://clangd.llvm.org) reads `build/compile_commands.json`, which the first local build creates. `src/pyevtgen/_core.pyi` is generated by nanobind on every build and committed, so that type checkers can resolve the extension module.

To update a dependency, change its version and SHA256 hash in `CMakeLists.txt`.

## Releases

Publishing a GitHub release triggers the `wheels.yml` workflow, which builds the source distribution and wheels with [cibuildwheel](https://cibuildwheel.pypa.io) and uploads them to PyPI through [trusted publishing](https://docs.pypi.org/trusted-publishers). The version is derived from the Git tag. Before the first release, register a pending trusted publisher for the `pyevtgen` project on PyPI with workflow `wheels.yml` and environment `PyPI`, and create that environment in the GitHub repository settings.

## Documentation and development builds

The [documentation](https://redeboer.github.io/pyevtgen-test) shows how to use all features through executed notebooks. It is hosted on GitHub Pages together with a package index of development wheels, which are built from `main` once the wheels pass their tests. The [installation page](https://redeboer.github.io/pyevtgen-test/install.html) explains how to install from that index.

## License

This package is distributed under the GNU General Public License v3.0 or later, because it links EvtGen (GPL-3.0-or-later), Pythia8 (GPL-2.0-or-later) and HepMC3 (LGPL-3.0-or-later). Their license texts are included in the wheels.
