The simplest way to simulate collider events and extract jet observables.

jetgo generates collider events with pythia8mc, clusters the particles into jets with 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

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, 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, 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

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, including how to write your own observable or your own flavor tagger. Runnable scripts are in examples/.

License

This project is licensed under the terms of the BSD 3-Clause License.

Citation

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

@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