jetgo 0.1.0__tar.gz

jetgo-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+/venv
+/.venv
+/.idea
+/.claude
+/docs/_build

jetgo-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Maxence Larose
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

jetgo-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: jetgo
+Version: 0.1.0
+Summary: Jet Event Toolkit for Generating Observables: generate collider events, find jets, tag their generator-level flavor, and save the observable data.
+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/jetgo_banner.png" alt="jetgo" width="820">
+</p>
+
+<p align="center">
+  <i>The simplest way to generate collider events and measure their 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, clusters the particles into jets, 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.
+
+# 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
+
+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
+)
+
+observable = EEC(
+    bin_edges=np.geomspace(0.005, 0.8, 31),
+    charged_only=True,
+    use_pseudorapidity=True
+)
+
+jet_flavor_tagger = DescendancyTracing(
+    delta_r_max=0.4,
+    use_pseudorapidity=True
+)
+
+simulator = Simulator(
+    event_generator=event_generator,
+    particle_selector=particle_selector,
+    jet_finder=jet_finder
+)
+
+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)

jetgo-0.1.0/README.md

@@ -0,0 +1,116 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MaxenceLarose/jetgo/main/images/jetgo_banner.png" alt="jetgo" width="820">
+</p>
+
+<p align="center">
+  <i>The simplest way to generate collider events and measure their 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, clusters the particles into jets, 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.
+
+# 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
+
+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
+)
+
+observable = EEC(
+    bin_edges=np.geomspace(0.005, 0.8, 31),
+    charged_only=True,
+    use_pseudorapidity=True
+)
+
+jet_flavor_tagger = DescendancyTracing(
+    delta_r_max=0.4,
+    use_pseudorapidity=True
+)
+
+simulator = Simulator(
+    event_generator=event_generator,
+    particle_selector=particle_selector,
+    jet_finder=jet_finder
+)
+
+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)

jetgo-0.1.0/examples/README.md

@@ -0,0 +1,16 @@
+# Examples
+
+Each script is standalone and runnable. Install the package with the Pythia8 extra first:
+
+```bash
+pip install jetgo[pythia]
+```
+
+| script | what it shows |
+|---|---|
+| `ex01_minimal_eec.py` | the smallest useful run: generate events, cluster jets, fill one observable, save |
+| `ex02_flavor_tagged_run.py` | the same run split into quark-tagged and gluon-tagged jets, and how to read the result back |
+| `ex03_custom_observable.py` | writing your own `Observable` subclass and running it through the simulator |
+
+They are deliberately small, a few thousand events each, so they finish in under a minute. Real
+runs are the same code with a larger `n_events`.

jetgo-0.1.0/examples/ex01_minimal_eec.py

@@ -0,0 +1,63 @@
+"""
+    @Title:             Minimal energy-energy correlator run.
+
+    @Description:       The smallest useful jetgo run. Generate hard-QCD proton-proton events, keep the
+                        charged final-state particles inside a tracker-like acceptance, cluster them into
+                        anti-kT jets, accumulate the energy-energy correlator, and write everything to one
+                        JSON file.
+"""
+
+import numpy as np
+
+from jetgo.observables import EEC
+from jetgo.simulation import EventGenerator, JetFinder, ParticleSelector, Simulator
+
+if __name__ == "__main__":
+    # ---------------------------------------------------------------------------------------------------- #
+    #                                           The three pieces                                            #
+    # ---------------------------------------------------------------------------------------------------- #
+    event_generator = EventGenerator(
+        beam_1=2212,        # proton
+        beam_2=2212,        # proton
+        sqrt_s=5020,        # GeV
+        pt_min=80,          # partonic p̂T window, in GeV
+        pt_max=200,
+        random_seed=42,     # anything non-zero: 0 lets Pythia8 pick its own seed, and the run stops
+    )                       # being reproducible
+
+    jet_finder = JetFinder(
+        radius=0.4,
+        pt_min=120,
+        pt_max=140,
+        max_abs_pseudorapidity=1.6,
+    )
+
+    particle_selector = ParticleSelector(
+        max_abs_pseudorapidity=2.4,
+    )
+
+    # ---------------------------------------------------------------------------------------------------- #
+    #                                              The run                                                  #
+    # ---------------------------------------------------------------------------------------------------- #
+    simulator = Simulator(
+        event_generator=event_generator,
+        jet_finder=jet_finder,
+        particle_selector=particle_selector,
+    )
+
+    # The bin edges are required. Observables histogram at fill time, so the file size does not grow with
+    # the run length, and the edges have to be the ones the result will be read on.
+    observable = EEC(
+        bin_edges=np.geomspace(0.005, 0.8, 31),
+        pt_min=1,
+        energy_weight=1,
+        charged_only=True,
+        use_pseudorapidity=True,
+    )
+
+    simulator.simulate(
+        n_events=5_000,
+        observables=observable,
+        output_path="jet_eec.json",
+        verbose=True,
+    )

jetgo-0.1.0/examples/ex02_flavor_tagged_run.py

@@ -0,0 +1,69 @@
+"""
+    @Title:             Splitting a run by generator-level jet flavor.
+
+    @Description:       The same run as ex01, with a flavor tagger attached. Every observable is filled three
+                        times over: once with all jets, once with the jets the tagger calls quark-initiated,
+                        and once with the ones it calls gluon-initiated. The second half of the script reads
+                        the file back and turns the saved histograms into normalized observables.
+"""
+
+import json
+
+import numpy as np
+
+from jetgo.observables import DoubleDifferentialJetCrossSection, EEC
+from jetgo.simulation import EventGenerator, JetFinder, ParticleSelector, Simulator
+from jetgo.taggers import DescendancyTracing
+
+OUTPUT_PATH = "flavor_tagged_run.json"
+EEC_BIN_EDGES = np.geomspace(0.005, 0.8, 31)
+CROSS_SECTION_BIN_EDGES = np.linspace(120.0, 140.0, 21)
+
+if __name__ == "__main__":
+    # ---------------------------------------------------------------------------------------------------- #
+    #                                              The run                                                  #
+    # ---------------------------------------------------------------------------------------------------- #
+    simulator = Simulator(
+        event_generator=EventGenerator(
+            beam_1=2212, beam_2=2212, sqrt_s=5020, pt_min=80, pt_max=200, random_seed=42
+        ),
+        jet_finder=JetFinder(radius=0.4, pt_min=120, pt_max=140, max_abs_pseudorapidity=1.6),
+        particle_selector=ParticleSelector(max_abs_pseudorapidity=2.4),
+    )
+
+    simulator.simulate(
+        n_events=5_000,
+        observables=[
+            EEC(bin_edges=EEC_BIN_EDGES, pt_min=1, charged_only=True, use_pseudorapidity=True),
+            DoubleDifferentialJetCrossSection(
+                bin_edges=CROSS_SECTION_BIN_EDGES, max_abs_pseudorapidity=1.6
+            ),
+        ],
+        # Pass a list here to run several taggers at once. The output metadata then also reports, for every
+        # pair, how often they agreed on the jets both of them tagged.
+        jet_flavor_taggers=DescendancyTracing(delta_r_max=0.4, use_pseudorapidity=True),
+        output_path=OUTPUT_PATH,
+        verbose=True,
+    )
+
+    # ---------------------------------------------------------------------------------------------------- #
+    #                                          Reading it back                                              #
+    # ---------------------------------------------------------------------------------------------------- #
+    result = json.loads(open(OUTPUT_PATH).read())
+
+    counts = result["metadata"]["flavor_taggers"]["descendancy_tracing"]
+    print(f"quark-tagged jets: {counts['n_quark']}")
+    print(f"gluon-tagged jets: {counts['n_gluon']}")
+    print(f"untagged jets:     {counts['n_untagged']}")
+
+    # finalize turns a saved histogram into the normalized observable. It is a classmethod, and it runs here,
+    # never during the simulation itself.
+    histograms = result["Energy-energy correlator"]["histograms"]
+    for label, saved in (
+        ("inclusive", histograms["inclusive"]),
+        ("quark", histograms["descendancy_tracing"]["quark"]),
+        ("gluon", histograms["descendancy_tracing"]["gluon"]),
+    ):
+        shape = EEC.finalize(saved["values"], EEC_BIN_EDGES, saved["metadata"])
+        peak = EEC_BIN_EDGES[:-1][int(np.argmax(shape))]
+        print(f"{label:>10} EEC peaks near ΔR = {peak:.3f}")

jetgo-0.1.0/examples/ex03_custom_observable.py

@@ -0,0 +1,102 @@
+"""
+    @Title:             Writing your own observable.
+
+    @Description:       Observables are the main extension point of jetgo. This example implements the jet
+                        constituent multiplicity, a quantity that separates quark and gluon jets, and runs it
+                        through the simulator exactly like a shipped observable.
+
+                        The contract is six methods. ``fill`` receives one event's jets and adds them to a
+                        histogram whose edges were fixed at construction; ``finalize`` is the classmethod that
+                        turns the saved histogram into the normalized quantity, downstream.
+"""
+
+import json
+from typing import Dict, List
+
+import fastjet as fj
+import numpy as np
+
+from jetgo.observables.base import Observable
+from jetgo.simulation import EventGenerator, JetFinder, ParticleSelector, Simulator
+from jetgo.taggers import DescendancyTracing
+
+BIN_EDGES = np.arange(0.5, 60.5, 2.0)
+OUTPUT_PATH = "constituent_multiplicity.json"
+
+
+class ConstituentMultiplicity(Observable):
+    """
+    Distribution of the number of constituents per jet, normalized to unit area.
+    """
+
+    N_JETS_KEY = "n_jets"
+    BIN_EDGES_KEY = "bin_edges"
+
+    def __init__(self, bin_edges: np.ndarray, pt_min: float = 1.0) -> None:
+        self._bin_edges = np.asarray(bin_edges, dtype=float)
+        self._counts = np.zeros(len(self._bin_edges) - 1, dtype=float)
+        self._pt_min = pt_min
+        self._n_jets = 0
+
+    @property
+    def identifier(self) -> str:
+        # Shipped observables use an ObservableIdentifier member, whose value is the HEPData keyword. Any
+        # hashable, unique value works: the simulator only uses it as this observable's key in the output.
+        return "constituent_multiplicity"
+
+    def fill(self, jets: List[fj.PseudoJet], cluster: fj.ClusterSequence) -> None:
+        for jet in jets:
+            self._n_jets += 1
+            multiplicity = sum(1 for c in jet.constituents() if c.pt() > self._pt_min)
+
+            index = int(np.searchsorted(self._bin_edges, multiplicity, side="right")) - 1
+            if 0 <= index < len(self._counts):
+                self._counts[index] += 1.0
+
+    def scale(self, scale_factor: float) -> None:
+        # Self-normalized, like the EEC: the generator's cross-section factor cancels in the shape.
+        pass
+
+    @classmethod
+    def finalize(cls, values, bin_edges: np.ndarray, metadata: Dict) -> np.ndarray:
+        counts = np.asarray(values, dtype=float)
+        return counts / counts.sum() / np.diff(np.asarray(bin_edges, dtype=float))
+
+    def _get_complementary_metadata(self) -> Dict:
+        return {self.N_JETS_KEY: self._n_jets, self.BIN_EDGES_KEY: self._bin_edges.tolist()}
+
+    def _get_binned_values(self) -> List[float]:
+        return self._counts.tolist()
+
+
+if __name__ == "__main__":
+    simulator = Simulator(
+        event_generator=EventGenerator(
+            beam_1=2212, beam_2=2212, sqrt_s=5020, pt_min=80, pt_max=200, random_seed=42
+        ),
+        jet_finder=JetFinder(radius=0.4, pt_min=120, pt_max=140, max_abs_pseudorapidity=1.6),
+        particle_selector=ParticleSelector(max_abs_pseudorapidity=2.4),
+    )
+
+    simulator.simulate(
+        n_events=5_000,
+        observables=ConstituentMultiplicity(bin_edges=BIN_EDGES),
+        jet_flavor_taggers=DescendancyTracing(delta_r_max=0.4, use_pseudorapidity=True),
+        output_path=OUTPUT_PATH,
+        verbose=True,
+    )
+
+    histograms = json.loads(open(OUTPUT_PATH).read())["constituent_multiplicity"]["histograms"]
+    centers = 0.5 * (BIN_EDGES[:-1] + BIN_EDGES[1:])
+
+    for label, saved in (
+        ("quark", histograms["descendancy_tracing"]["quark"]),
+        ("gluon", histograms["descendancy_tracing"]["gluon"]),
+    ):
+        shape = ConstituentMultiplicity.finalize(saved["values"], BIN_EDGES, saved["metadata"])
+        mean = float(np.sum(centers * shape * np.diff(BIN_EDGES)))
+        print(f"{label:>6} jets: mean constituent multiplicity = {mean:.1f}")
+
+    print("Gluon jets carry more constituents than quark jets: they radiate more, in the ratio of the")
+    print("color charges C_A/C_F. The measured ratio is well below that naive 9/4, since hadronization")
+    print("and the finite jet energy both dilute it.")

jetgo-0.1.0/jetgo/__init__.py

@@ -0,0 +1,20 @@
+"""
+    @file:              __init__.py
+    @Author:            Maxence Larose
+
+    @Creation Date:     09/2026
+    @Last modification: 09/2026
+
+    @Description:       This file defines package-level metadata (version, author, license, maintainer) for the
+                        ``jetgo`` package. It deliberately exposes no classes: the public API lives in the
+                        subpackages, so that importing ``jetgo`` never pulls in Pythia8 or FastJet.
+"""
+
+__version__ = "0.1.0"
+
+__author__ = "Maxence Larose"
+__credits__ = ["Maxence Larose"]
+__license__ = "BSD-3-Clause"
+__maintainer__ = "Maxence Larose"
+__email__ = "maxence.larose@stonybrook.edu"
+__status__ = "Production"

jetgo-0.1.0/jetgo/_pythia.py

@@ -0,0 +1,63 @@
+"""
+    @file:              _pythia.py
+    @Author:            Maxence Larose
+
+    @Creation Date:     06/2026
+    @Last modification: 09/2026
+
+    @Description:       This file resolves and re-exports the Pythia8 module, accounting for the different module
+                        name used by the pip-installed ``pythia8mc`` package versus a self-compiled ``pythia8``
+                        build.
+
+                        Pythia8 is an optional dependency of this package: only event generation and particle
+                        selection need it at runtime, so observables and taggers import without it. Importing
+                        this module on a machine without either build raises with an actionable message rather
+                        than a bare ModuleNotFoundError from somewhere deep in the import graph.
+"""
+
+import importlib
+
+# The module is named pythia8 when users compile it themselves, and pythia8mc when installed via pip.
+_CANDIDATE_MODULE_NAMES = ("pythia8mc", "pythia8")
+
+_NOT_INSTALLED_MESSAGE = (
+    "Pythia8 is required for event generation but is not installed. Install it with "
+    "`pip install jetgo[pythia]`, which pulls in the `pythia8mc` wheel, or compile Pythia8 yourself with its "
+    "Python interface enabled so that `import pythia8` works. Note that the `pythia8mc` wheels are Linux-only; "
+    "on another platform, a self-compiled build is the only option. The rest of jetgo, including every "
+    "observable and tagger, imports and runs without Pythia8."
+)
+
+
+class _Pythia8NotInstalled:
+    """
+    Stands in for the Pythia8 module when neither build is installed.
+
+    Importing a module must not fail merely because an optional dependency is absent, or nothing that
+    merely *mentions* Pythia8 could be imported either, including the modules whose only use of it is a
+    type annotation. Touching anything on this stand-in raises instead, so the error arrives when event
+    generation is actually attempted and names the way to fix it.
+    """
+
+    def __getattr__(self, name: str):
+        raise ModuleNotFoundError(_NOT_INSTALLED_MESSAGE)
+
+    def __bool__(self) -> bool:
+        return False
+
+
+def _resolve():
+    for name in _CANDIDATE_MODULE_NAMES:
+        try:
+            return importlib.import_module(name)
+        except ModuleNotFoundError:
+            continue
+
+    return _Pythia8NotInstalled()
+
+
+pythia8 = _resolve()
+
+#: Whether a working Pythia8 build was found. Lets callers branch on availability without having to
+#: import Pythia8 themselves, and lets the test suite skip what genuinely needs a generator.
+PYTHIA8_AVAILABLE = not isinstance(pythia8, _Pythia8NotInstalled)