Metadata-Version: 2.5
Name: jetgo
Version: 0.1.3
Summary: Jet Event Toolkit for Generator-level Observables (JETGO)
Project-URL: Homepage, https://github.com/MaxenceLarose/jetgo
Project-URL: Documentation, https://maxencelarose.github.io/jetgo
Project-URL: Repository, https://github.com/MaxenceLarose/jetgo
Project-URL: Issues, https://github.com/MaxenceLarose/jetgo/issues
Author-email: Maxence Larose <maxence.larose@stonybrook.edu>
Maintainer-email: Maxence Larose <maxence.larose@stonybrook.edu>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: energy-energy-correlator,fastjet,high-energy-physics,jet-flavor,jets,monte-carlo,pythia8,qcd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS
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: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: fastjet>=3.4
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: numpydoc>=1.6; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
Requires-Dist: sphinx>=7.2; extra == 'docs'
Provides-Extra: pythia
Requires-Dist: pythia8mc>=8.3; extra == 'pythia'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/MaxenceLarose/jetgo/main/images/banner.png" alt="jetgo" width="820">
</p>

<p align="center">
  <i>The simplest way to simulate collider events and extract jet observables.</i>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.11+-blue.svg?logo=python&logoColor=white" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/PYTHIA-8.3+-orange.svg" alt="PYTHIA 8.3+">
  <img src="https://img.shields.io/badge/FastJet-3.5+-9cf.svg" alt="FastJet 3.5+">
  <a href="https://github.com/MaxenceLarose/jetgo/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-BSD--3--Clause-green.svg" alt="BSD-3-Clause license"></a>
  <a href="https://pypi.org/project/jetgo/"><img src="https://img.shields.io/pypi/dm/jetgo?label=downloads&color=blue" alt="Downloads"></a>
</p>

`jetgo` generates collider events with [pythia8mc](https://pypi.org/project/pythia8mc/), clusters
the particles into jets with [fastjet](https://pypi.org/project/fastjet/), tags each jet with the
color charge of the parton that initiated it, and writes the observables out. You define the
simulator, the observables and the tagger, `jetgo` does the rest.

# Installation

```bash
pip install jetgo[pythia]
```

PYTHIA8 is an optional dependency, because its wheels are Linux-only. Plain `pip install jetgo`
works everywhere and gives you every observable and tagger; only event generation needs the extra.

There are two ways to get PYTHIA8, and `jetgo` accepts either:

- **The wheel.** The `[pythia]` extra above pulls in
  [pythia8mc](https://pypi.org/project/pythia8mc/), the PyPI distribution of PYTHIA's own Python
  bindings. Nothing to compile, but the wheels are built for Linux only.
- **Your own build.** Compile PYTHIA8 with its Python interface enabled, following
  [the PYTHIA manual](https://pythia.org/latest-manual/PythonInterface.html), so that
  `import pythia8` works. This is the route on macOS and Windows, and the one to take if you need a
  specific PYTHIA version or your own patches.

# Quick usage preview

```python
import numpy as np

from jetgo.observables import EEC
from jetgo.simulation import EventGenerator, JetFinder, ParticleSelector, Simulator
from jetgo.taggers import DescendancyTracing

####################################################################################################
#                                         Define simulator                                         #
####################################################################################################
event_generator = EventGenerator(
    beam_1=2212,
    beam_2=2212,
    sqrt_s=5020,
    pt_min=80,
    pt_max=200,
    random_seed=42
)

particle_selector = ParticleSelector(
    max_abs_pseudorapidity=2.4
)

jet_finder = JetFinder(
    radius=0.4,
    pt_min=120,
    pt_max=140,
    max_abs_pseudorapidity=1.6
)

simulator = Simulator(
    event_generator=event_generator,
    particle_selector=particle_selector,
    jet_finder=jet_finder
)

####################################################################################################
#                                        Define observables                                        #
####################################################################################################
observable = EEC(
    bin_edges=np.geomspace(0.005, 0.8, 31),
    charged_only=True,
    use_pseudorapidity=True
)

####################################################################################################
#                                          Define tagger                                           #
####################################################################################################
jet_flavor_tagger = DescendancyTracing(
    delta_r_max=0.4,
    use_pseudorapidity=True
)

####################################################################################################
#                                               Run                                                #
####################################################################################################
simulator.simulate(
    n_events=100_000,
    observables=observable,
    jet_flavor_taggers=jet_flavor_tagger,
    output_path="jet_eec.json"
)
```

That run writes one file holding the inclusive energy-energy correlator, its quark-tagged and
gluon-tagged counterparts, and the run metadata.

# Documentation

Full documentation lives at [maxencelarose.github.io/jetgo](https://maxencelarose.github.io/jetgo),
including how to write your own observable or your own flavor tagger. Runnable scripts are in
[`examples/`](examples).

# License

This project is licensed under the terms of the [BSD 3-Clause License](LICENSE).

# Citation

If you use `jetgo` in your work, please cite the paper it was written for:

```bibtex
@article{Bossi:2026colors,
  author        = {Bossi, Hannah and Larose, Maxence and Mehtar-Tani, Yacine},
  title         = {The Colors of Jet Quenching},
  year          = {2026},
  eprint        = {2609.05609},
  archivePrefix = {arXiv},
  primaryClass  = {hep-ph},
  url           = {https://arxiv.org/abs/2609.05609}
}
```

# Contact

Maxence Larose — [maxence.larose@stonybrook.edu](mailto:maxence.larose@stonybrook.edu)
