Add Pythia8 nuclear modes: Cascade and Angantyr

[afedynitch]

Summary

• Adds two new Pythia8 model classes for nuclear interactions: Pythia8Cascade (PythiaCascade plugin for single-collision h+A mode) and Pythia8Angantyr (Glauber heavy-ion model for hA/AA with precomputed cross-section tables)
• Both models support CompositeTarget (e.g., Air), nuclear projectile decomposition, proper RNG state save/restore, and cosmic-ray slow-decay conventions
• C++ bindings extended with PythiaCascadeForChromo wrapper, set_may_decay support on both internal Pythia instances, and RNG state serialization
• Includes comprehensive tests (dedicated Cascade/Angantyr test suites, HepMC nuclear-target tests, updated generic generator tests), reference histograms, and a helper script for Angantyr table generation
• Bumps version to 0.11.0 and data to v007

Test plan

• python -m pytest tests/test_pythia8_cascade.py -v — Cascade-specific tests
• python -m pytest tests/test_pythia8_angantyr.py -v — Angantyr-specific tests
• python -m pytest tests/test_to_hepmc3.py -v — HepMC nuclear-target tests
• python -m pytest tests/test_generators.py -v -k "Cascade or Angantyr" — generic generator tests
• python -m pytest tests/test_cross_sections.py tests/test_mass_shell.py -v — cross-section and mass-shell tests
• Full test suite passes: python -m pytest -vv -n 16

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds dedicated Pythia8 nuclear-interaction models to chromo (Cascade single-collision h+A and Angantyr Glauber hA/AA), along with bindings, documentation, CI updates, and new/updated tests to validate HepMC conversion/IO, RNG state handling, and physics/regression outputs.

Changes:

• Introduce Pythia8Cascade and Pythia8Angantyr Python model classes and expose them via chromo.models.
• Extend the _pythia8 pybind module with a PythiaCascadeForChromo wrapper plus additional Pythia8/HIInfo bindings (RNG state, decay toggles, Glauber cross sections, settings IO, live beam/kinematics switching).
• Expand/adjust the test suite and reference artifacts for nuclear targets; bump packaged Pythia8 data to v007 and project version to 0.11.0.

Reviewed changes

Copilot reviewed 23 out of 52 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/chromo/models/pythia8.py	Adds Pythia8Cascade and Pythia8Angantyr, adjusts base Pythia8 scope, and implements nuclear-mode generation/cross sections/RNG handling.
src/cpp/_pythia8.cpp	Adds PythiaCascadeForChromo wrapper and exposes additional Pythia8 APIs needed by Cascade/Angantyr.
src/chromo/models/__init__.py	Exports new model classes via __all__.
scripts/generate_angantyr_tables.py	Adds helper script to generate Angantyr precomputed initialization tables.
tests/test_pythia8_cascade.py	New targeted unit tests for Cascade collisions/cross sections/projectile decomposition and event record consistency.
tests/test_pythia8_angantyr.py	New targeted unit tests for Angantyr collisions/cross sections/impact parameter/wounded nucleons and live kinematics switching.
tests/test_to_hepmc3.py	Skips nuclear-only models in generic tests and adds dedicated nuclear HepMC3 conversion + IO tests.
tests/test_hepmc_io.py	Refactors shared HepMC IO logic and adds nuclear-target round-trip coverage.
tests/test_generators.py	Adds probabilistic histogram regression tests for Cascade/Angantyr and adjusts expected “unsupported” assertions to include _ecm_min.
tests/test_rng_state.py	Uses nuclear targets for Cascade/Angantyr RNG-state tests.
tests/test_setstable.py	Adapts target choice for nuclear-only models; marks a known Cascade decay-mode limitation as xfail.
tests/test_final_state.py	Uses nuclear target kinematics for Cascade/Angantyr in final-state tests.
tests/test_cross_sections.py	Adds Angantyr-He skip and updates unsupported assertions to include _ecm_min.
tests/test_mass_shell.py	Adds Angantyr-He skip and updates unsupported assertions to include _ecm_min.
tests/test_decay_handler.py	Adds an Angantyr-specific fixed-target setup above the model’s minimum CMS energy.
tests/test_common.py	Marks known beam-record mismatches for Cascade/Angantyr as xfail and sets Angantyr kinematics to nuclear target.
tests/test_cli.py	Updates CLI ambiguity regex to include the new Pythia8 nuclear model names.
tests/test_pythia8.py	Removes an old (skipped) nuclear collision test.
tests/data/test_generators/Pythia8Cascade_pi-_O16_ft.pkl.gz	Adds reference histogram/covariance artifact for generator regression testing.
tests/data/test_generators/Pythia8Cascade_pi-_N14_ft.pkl.gz	Adds reference histogram/covariance artifact for generator regression testing.
tests/data/test_generators/Pythia8Cascade_p_O16_ft.pkl.gz	Adds reference histogram/covariance artifact for generator regression testing.
tests/data/test_generators/Pythia8Cascade_He_O16_ft.pkl.gz	Adds reference histogram/covariance artifact for generator regression testing.
tests/data/test_generators/Pythia8Angantyr_p_air_ft.pkl.gz	Adds reference histogram/covariance artifact for generator regression testing.
README.md	Updates model list to distinguish Pythia8 base vs Cascade vs Angantyr; updates citation instructions.
pyproject.toml	Bumps package version to 0.11.0.
CLAUDE.md	Documents the new Pythia8 nuclear mode split and where bindings live.
.github/workflows/test.yml	Adds a lint job and updates cached Pythia8 data bundle version to v007.
.github/workflows/release.yml	Updates cached Pythia8 data bundle version to v007 for releases.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

_merge_cascade_results returns the original next_coll tuple unchanged when len(results) == 1. Those arrays are views into the internal Pythia8 event buffer, so the returned event can be mutated/overwritten by the next generated collision. Consider always returning fully-copied arrays (e.g., np.array(..., copy=True)/.copy() for each element) even in the single-result case to keep event data stable across generator calls.

[Copilot]

The inline comment says slowDecays=False keeps mu/pi/K/K0L stable, but the actual call passes slowDecays=True. Please align the comment and the chosen setting (and ideally explain why this differs from the default), so readers don’t misinterpret the decay configuration.

[Copilot]

The wrapper comment claims next_coll returns numpy arrays that are already copied out of the internal Event, but _extract() currently exposes views into the Event storage (via pointer+stride). This is easy to misuse and can lead to surprising mutation once another collision is generated. Either update the comment to reflect the actual behavior, or switch to returning copied arrays from C++ (or enforce copying on the Python side for all cases).

Suggested change

	return _extract(ev);
	py::tuple extracted = py::cast<py::tuple>(_extract(ev));
	py::tuple copied(extracted.size());
	for (py::ssize_t i = 0; i < extracted.size(); ++i)
	copied[i] = extracted[i].attr("copy")();
	return copied;