Add Pythia8 nuclear modes: Cascade and Angantyr

.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Download all cache files if missing
         run: |
           mkdir -p ~/.cache/chromo
-          for file in qgsjet_v002 Pythia8_v006 eposlhcr_v001 eposlhc_v001 dpm3191_v001 dpm3_v001 ; do
+          for file in qgsjet_v002 Pythia8_v007 eposlhcr_v001 eposlhc_v001 dpm3191_v001 dpm3_v001 ; do
             if [ ! -f ~/.cache/chromo/$file.zip ]; then
               echo "Downloading $file.zip..."
               curl -L -o ~/.cache/chromo/$file.zip "https://github.com/impy-project/chromo/releases/download/zipped_data_v1.0/$file.zip"
@@ -97,7 +97,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, ubuntu-24.04-arm, macos-intel-latest, macos-latest] # windows-latest: Disable windows for now
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-15-intel, macos-latest] # windows-latest: Disable windows for now
         arch: [auto]
         py: [cp39, cp310, cp311, cp312, cp313]
     steps:
@@ -113,7 +113,7 @@ jobs:
 
       - name: Set macOS deployment target
         if: runner.os == 'macOS'
-        run: echo "MACOSX_DEPLOYMENT_TARGET=${{ matrix.os == 'macos-intel-latest' && '13.0' || '15.0' }}" >> $GITHUB_ENV
+        run: echo "MACOSX_DEPLOYMENT_TARGET=15.0" >> $GITHUB_ENV
 
       - name: Setup gfortran
         uses: awvwgk/setup-fortran@v1.6.1
@@ -122,7 +122,7 @@ jobs:
           compiler: gcc
           version: 13
 
-      - if: ${{ matrix.os != 'macos-intel-latest' }}
+      - if: ${{ matrix.os != 'macos-15-intel' }}
         uses: ts-graphviz/setup-graphviz@v2
         name: Install Graphviz
 
@@ -152,7 +152,7 @@ jobs:
           echo "Sleeping $delay seconds to stagger cibuildwheel downloads..."
           sleep $delay
 
-      - if: ${{ matrix.os == 'macos-intel-latest' }}
+      - if: ${{ matrix.os == 'macos-15-intel' }}
         name: cibuildwheel on macOS Intel
         uses: pypa/cibuildwheel@v3.4.0
         env:

.github/workflows/test.yml

@@ -11,6 +11,16 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  lint:
+    if: contains(github.event.pull_request.labels.*.name, 'skip CI') == false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: pre-commit/action@v3.0.1
+
   prepare-cache:
     if: contains(github.event.pull_request.labels.*.name, 'skip CI') == false
     runs-on: ubuntu-latest
@@ -23,7 +33,7 @@ jobs:
       - name: Download all cache files if missing
         run: |
           mkdir -p ~/.cache/chromo
-          for file in qgsjet_v002 Pythia8_v006 eposlhcr_v001 eposlhc_v001 dpm3191_v001 dpm3_v001 ; do
+          for file in qgsjet_v002 Pythia8_v007 eposlhcr_v001 eposlhc_v001 dpm3191_v001 dpm3_v001 ; do
             if [ ! -f ~/.cache/chromo/$file.zip ]; then
               echo "Downloading $file.zip..."
               curl -L -o ~/.cache/chromo/$file.zip "https://github.com/impy-project/chromo/releases/download/zipped_data_v1.0/$file.zip"
@@ -39,15 +49,12 @@ jobs:
 
   test:
     if: contains(github.event.pull_request.labels.*.name, 'skip CI') == false
-    needs: prepare-cache
+    needs: [prepare-cache, lint]
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         include:
           # Python version number must be string, otherwise 3.10 becomes 3.1
-          # Disable Windows for now, as long as numpy is buggy on Windows
-          # - os: windows-latest
-          #   python-version: "3.12"
           - os: macos-latest
             python-version: "3.12"
           - os: ubuntu-latest
@@ -100,13 +107,13 @@ jobs:
 
   cibuildwheel:
     if: contains(github.event.pull_request.labels.*.name, 'skip CI') == false
-    needs: prepare-cache
+    needs: [prepare-cache, lint]
     name: cibw ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, ubuntu-24.04-arm, macos-intel-latest, macos-latest]
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-15-intel, macos-latest]
     steps:
       - name: Restore chromo data cache
         uses: actions/cache@v4
@@ -121,15 +128,15 @@ jobs:
 
       - name: Set macOS deployment target
         if: runner.os == 'macOS'
-        run: echo "MACOSX_DEPLOYMENT_TARGET=${{ matrix.os == 'macos-intel-latest' && '13.0' || '15.0' }}" >> $GITHUB_ENV
+        run: echo "MACOSX_DEPLOYMENT_TARGET=15.0" >> $GITHUB_ENV
 
       - uses: awvwgk/setup-fortran@main
         id: setup-fortran
         with:
           compiler: gcc
           version: 13
 
-      - if: ${{ matrix.os != 'macos-intel-latest' }}
+      - if: ${{ matrix.os != 'macos-15-intel' }}
         uses: ts-graphviz/setup-graphviz@v2
         name: Install Graphviz
 
@@ -148,7 +155,7 @@ jobs:
           echo "Sleeping $delay seconds to stagger cibuildwheel downloads..."
           sleep $delay
 
-      - if: ${{ matrix.os == 'macos-intel-latest' }}
+      - if: ${{ matrix.os == 'macos-15-intel' }}
         name: cibuildwheel on macOS Intel
         uses: pypa/cibuildwheel@v3.4.0
         env:

CLAUDE.md

@@ -60,6 +60,16 @@ Run `pre-commit run -a` to apply all hooks to the codebase, and fix errors befor
 ### Model Implementations (`src/chromo/models/`)
 Each model file (e.g., `sibyll.py`, `qgsjet.py`, `pythia8.py`) subclasses `MCRun`/`MCEvent` and interfaces with compiled backends. Models can only be instantiated **once per process** due to Fortran global state — tests run each model in a separate subprocess. The relevant model classes are exposed in `src/chromo/models/__init__.py:__all__` for user access, extra models can be accessed through `src/chromo/models/_extra_models.py` if needed, whereas those with "_DEV" suffix are for development and testing only and are not located in the source code base.
 
+### Pythia8 Nuclear Modes (`src/chromo/models/pythia8.py`)
+
+Three Pythia8 model classes with distinct physics scopes:
+
+- **`Pythia8`** — Standard Pythia8 for hN, ee, γγ, γN collisions. Extended projectiles include strange/charm/bottom hadrons. No nuclear targets.
+- **`Pythia8Cascade`** — PythiaCascade plugin for single-collision h+A mode. Nuclear projectiles decomposed into Z protons + (A-Z) neutrons. Targets: nuclei with A>1. Uses `slowDecays=True` (cosmic-ray convention). RNG state save/restore via both internal Pythia instances (pythiaMain + pythiaColl). Supports `CompositeTarget` via `_composite_plan`.
+- **`Pythia8Angantyr`** — Glauber heavy-ion model for hA/AA with precomputed tables (20 GeV–20 PeV CMS, `_ecm_min=20 GeV`). Targets: nuclei only (no proton/neutron). Live target switching via `setBeamIDs` with lazy cross-section estimation. Supports `CompositeTarget`.
+
+C++ bindings in `src/cpp/_pythia8.cpp`: `PythiaCascadeForChromo` wraps `PythiaCascade` with numpy array extraction, `set_may_decay` on both internal Pythia instances, and `getRndmState`/`setRndmState` for RNG state serialization.
+
 ### Fortran/C++ Sources
 - `src/fortran/` — Fortran source for SIBYLL, QGSJet, DPMJET, EPOS, UrQMD, SOPHIA, PYTHIA6
 - `src/cpp/` — PYTHIA 8 C++ source with pybind11 bindings

README.md

@@ -60,15 +60,17 @@ To see the help of the command-line interface. If that does not work, just repla
 
 Please note that `chromo` only provides a user interface for the following models, and does not contain any particle physics models itself. When using any of these models in public-facing work, it is important to properly cite the original model reference by following the links below. Additionally, if you find `chromo` useful in your work, we would appreciate an acknowledgement, footnote, or link to `chromo`.
 
-| Interaction model                                         | Supported proj/targ       | Comment                         | 
+| Interaction model (click for [iNSPIRE.HEP](https://inspirehep.net/) link)                          | Supported proj/targ       | Comment                         | 
 |------------------------------------------------------------|---------------------------|--------------------------------|
 | [DPMJET-III 3.0.7](https://inspirehep.net/literature/538940) & [PHOJET 1.12-36](https://inspirehep.net/literature/373339)      | *hN, γγ, γN, hA, γA, AA*  | |
 | [DPMJET-III & PHOJET 19.1 and 19.3](https://inspirehep.net/literature/1503512) [(repo on GitHub)](https://github.com/DPMJET/DPMJET) |  *hN, γγ, γN, hA, γA, AA* | |
 | [EPOS-LHC](https://inspirehep.net/literature/1236629)     | *hN, hA, AA*              | |
 | [EPOS-LHC-R](https://inspirehep.net/literature/2680791)     | *hN, hA, AA*              | |
 | [EPOS-LHC-R (w/ hadr. rescattering)](https://inspirehep.net/literature/2680791)     | *hN, hA, AA*              | | Version with explicit hadronic rescattering in UrQMD (slow!)
 | [PYTHIA 6.4](https://inspirehep.net/literature/712925)    | *hN, ee, γγ, γN*          | |
-| [PYTHIA 8.3](https://inspirehep.net/literature/2056998) (https://pythia.org/) | *hN, ee, γγ, γN* & *hA, AA* (Argantyr) | unavailable on Windows |
+| [PYTHIA 8.317](https://inspirehep.net/literature/2056998) (https://pythia.org/) | *hN, ee, γγ, γN* | unavailable on Windows |
+| [PYTHIA 8.317 Cascade](https://inspirehep.net/literature/3092823) | *hA* | unavailable on Windows |
+| [PYTHIA 8.317 Angantyr](https://inspirehep.net/literature/1680030) | *hA, AA* | unavailable on Windows, uses precomputed glauber tables for 20 GeV–20 PeV CMS by default |
 | [QGSJet-01](https://inspirehep.net/literature/460408)     | *hN, hA, AA*              | |
 | [QGSJet-II-03](https://inspirehep.net/literature/667881)  | *hN, hA, AA*              | |
 | [QGSJet-II-04](https://inspirehep.net/literature/872658)  | *hN, hA, AA*              | |
@@ -97,18 +99,28 @@ Advanced and developer installation instructions can be found [here](doc/dev_doc
 
 ## Citation
 
-If you use `chromo` in your research, please cite it using the following DOI:
-
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16562752.svg)](https://doi.org/10.5281/zenodo.16562752)
-
-You can also cite it in your bibliography as:
-
-```
-Fedynitch, A., Dembinski, H., Prosekin, A., El Hadri, S., & Watanabe, K. (2025). 
-CHROMO: Cosmic ray and HadROnic interactiOn MOnte-carlo frontend. 
-Zenodo. https://doi.org/10.5281/zenodo.16562752
+If you use `chromo` in your research, please cite the paper:
+
+> A. Fedynitch, H. Dembinski and A. Prosekin, *Chromo: A high-performance python interface to hadronic event generators for collider and cosmic-ray simulations*, [Comput.Phys.Commun. 321 (2026) 110031](https://doi.org/10.1016/j.cpc.2026.110031), [arXiv:2507.21856](https://arxiv.org/abs/2507.21856) [[INSPIRE](https://inspirehep.net/literature/2955234)]
+
+BibTeX:
+```bibtex
+@article{Fedynitch:2025mgj,
+    author = "Fedynitch, Anatoli and Dembinski, Hans and Prosekin, Anton",
+    title = "{Chromo: A high-performance python interface to hadronic event generators for collider and cosmic-ray simulations}",
+    eprint = "2507.21856",
+    archivePrefix = "arXiv",
+    primaryClass = "physics.comp-ph",
+    doi = "10.1016/j.cpc.2026.110031",
+    journal = "Comput. Phys. Commun.",
+    volume = "321",
+    pages = "110031",
+    year = "2026"
+}
 ```
 
+Software release: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16562752.svg)](https://doi.org/10.5281/zenodo.16562752)
+
 ## Authors
 
 - Anatoli Fedynitch