The simplest way to simulate collider events and extract their 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.

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