Skip to content

Pythia 8 hadronization: optional hadronization history in the event record - #562

Open
AdamAurisano wants to merge 2 commits into
GENIE-MC:masterfrom
AdamAurisano:feature/pythia8-hadronization-history
Open

AdamAurisano wants to merge 2 commits into
GENIE-MC:masterfrom
AdamAurisano:feature/pythia8-hadronization-history

Conversation

@AdamAurisano

@AdamAurisano AdamAurisano commented Nov 15, 2026 •

Copy link
Copy Markdown

Problem

Pythia8Hadro2019 and AGCharmPythia8Hadro2023 copy only two kinds of entries from the PYTHIA 8 event record: the
string ends (q, qq; PYTHIA status -23, GHEP status 12) and the undecayed particles. Every hadron that PYTHIA decays
during hadronization is dropped, and its decay products are attached to the leading quark. GENIE switches PYTHIA
decays off only for pi0, K0, K0bar, Lambda and Lambdabar, so the dropped hadrons include rho, omega, eta, eta', phi,
K*, Sigma0, Sigma+-, Xi, Omega- and Delta. Users cannot tell, for example, which photons came from an eta or a
Sigma0, or which pions came from a rho. The PYTHIA 6 interface imported the whole JETSET record, so this information
was lost in the port to PYTHIA 8.

Change

A new boolean parameter, KeepHadronizationHistory, added to Pythia8Hadro2019.xml and AGCharm2023.xml with
default false. When it is true:

  • Hadrons that PYTHIA decayed during hadronization (PYTHIA status -81..-89 and -91..-99) are added as
    kIStDecayedState (3) entries at their PYTHIA position.
  • Their decay products point to them through a PYTHIA-index to GHEP-index map. Primary hadrons keep their mothers
    (q, qq); in the charm remnant they point to the remnant quark.
  • The products of one PYTHIA decay are contiguous in PYTHIA's record, so the daughter lists stay compact.
  • A decayed hadron whose PDG code GENIE does not know is recorded as kPdgHadronicBlob, so that the links stay
    valid. This never happened in the validation samples.

Status 3 was chosen instead of 12 so that code that looks at status 12, 14 or 1 does not see the new entries. That
code includes the gst primary-hadron loop, INTRANUKE (status 14), the decayers (status 1 and 14) and the
energy-momentum check (status 1 and 15). gntpc's rootracker output copies the new rows; the t2k and nuance formats
drop them.

8 files, +110 / -4: Pythia8Hadro2019.cxx, PythiaBaseHadro2019.{h,cxx}, AGCharmPythia8Hadro2023.cxx,
AGCharmPythiaBaseHadro2023.{h,cxx} and the two XMLs.

Safety and defaults

  • The default is false. With the option off, the code path is the same as before (see the identity checks below).
  • The option adds no PYTHIA calls and draws no random numbers. With the option on, every status 1, 14 and 15 entry
    is the same as with it off; only the status-3 rows and the links that point to them are new.
  • GetParamDef is used, so configurations without the parameter keep working. This includes the tune-specific
    Pythia8Hadro2019.xml copies under config/G18_*/*_03_3[23]0/.

How to enable

In Pythia8Hadro2019.xml, and in AGCharm2023.xml for the charm remnant (or in a GXMLPATH override copy):

<param type="bool" name="KeepHadronizationHistory"> true </param>

Validation (master e2e04f1)

Setup: GENIE master e2e04f1 built with PYTHIA 8.313, ROOT 6.32, LHAPDF 6.3.0 and gcc 13.3; tune
AR23_20i_00_000. The cross sections come from the existing R-3_06_00 spline file. master accepts it: there are no
missing-spline messages, and a spot check of fresh master splines agrees for the keys that dominate (see the notes).
The numbers below are therefore identities and ratios, not absolute rates.

Samples use fixed seeds and the flux x*exp(-x/5) for 0.5-30 GeV:

Sample Target Events
numu Ar40 10k
numubar Ar40 10k
nue Ar40 5k
numu H 5k
numu, CharmCCDIS only Ar40 3k
numu, DIS only Ar40 10k

Every generation was run twice with the same seeds, and every comparison below was repeated on both passes with the
same result. Before any branch comparison, two stock master runs with the same seed were compared with each other on
numu Ar40 (10k events, four runs). All runs were identical.

Option off vs stock master. The comparison covers the GHEP record (every entry and field, plus event weight,
cross sections, kinematics and flags), all gRooTracker branches and all gst branches. All six samples were identical
in both passes (43k events per pass).

Option on vs off, same seed:

  • Final state. After the status-3 history rows are dropped, the GHEP records are identical in every sample (all
    remaining entries and fields; links compared after remapping). The gRooTracker status 1 / 14 / 15 rows are
    identical (131,821 rows in the numu Ar40 sample alone), and the gst output is unchanged.
  • New rows. History rows per event: numu Ar40 0.645, numubar 0.380, nue 0.648, numu H 0.662, charm 0.426,
    DIS-only 0.854. The most frequent are Delta+, rho+-, eta, Delta0, rho0, omega, Delta++, K*, Sigma0, Sigma*,
    eta', phi and Xi.
  • Consistency of the new rows.
    • The daughters of every history row sum to its 4-momentum within 1.3e-13 GeV.
    • Charge and baryon number are conserved in every decay (0 violations).
    • Every history row traces back to the leading quark.
    • All daughter lists are compact and contiguous: 0 link problems, and the record compactifier ran exactly as
      often as with the option off (2985 times per 10k numu Ar40 events in both cases).
    • No kPdgHadronicBlob fallback was needed.
  • Stock gntpc. A stock master gntpc reading files with history rows produces a gst file identical to the one
    from the option-off file.
  • Cost. No measurable change in generation time.
  • All three PRs together. With all three applied and every option on, the same identities hold relative to
    hyperons-on / history-off. In one of the two passes, the all-options run happened to be one of the rare divergent
    runs described in the hyperon PR; the other pass and the rerun agree.

Note on reproducibility: one rare, unexplained repeat-run difference was seen. It appeared only with the companion
option KeepLongLivedHyperons=true and is described in that PR. It was not seen in any run of this branch alone.

Notes

  • Cross sections. The R-3_06_00 spline file was used with master. For 15 keys (14 numu CC DIS keys on Ar40 and
    the numu CC Delta++ RES key on p in Ar40), fresh master splines (12-30 knots up to 30 GeV) were compared with the
    stored ones. The RES key agrees within 0.2%. Total CC DIS agrees within 0.6% between 1 and 30 GeV, within the
    precision of the knot interpolation. One difference: the two non-charm strange-sea DIS keys (q:3(s)) are up to 37%
    higher on master above about 4 GeV, but they are only about 0.1% of CC DIS. A CCQE spot check was too slow to
    finish. None of this affects the same-seed comparisons above.
  • Tune-specific XML copies. The new parameter is read with GetParamDef, so the tune-specific
    Pythia8Hadro2019.xml copies under config/G18_*/ do not need it. Users of those tunes add it there to enable the
    option.

Independence

This PR is independent of the two companion PRs: the gst primary-hadron fix (#563, bugfix/gst-pythia8-primary-hadrons)
and the optional long-lived hyperons (#564, feature/pythia8-long-lived-hyperons). Any of them can be merged alone. All
pairs, and all three in any of the six orders, apply to master without conflicts (cherry-pick and merge) and give
the same tree. The combination was validated with every option on (above).

🤖 Generated with Claude Code

https://claude.ai/code/session_01E3nCvREWPkWV3JvvxzenHN

Pythia8Hadro2019 and AGCharmPythia8Hadro2023 copy only the string ends
(q, qq) and the undecayed particles from the PYTHIA 8 event record; every
hadron PYTHIA decays during hadronization (rho, omega, eta, eta', phi, K*,
Sigma0, Sigma+-, Xi, Omega-, Delta) is dropped and its decay products are
attached to the leading quark. The Pythia 6 interface imported all entries.

New boolean parameter KeepHadronizationHistory (default false, in
Pythia8Hadro2019.xml and AGCharm2023.xml). When true, decayed hadrons
(PYTHIA status -81..-89 and -91..-99) are added as kIStDecayedState (3)
entries at their PYTHIA position, and their decay products point to them
via a PYTHIA-index -> GHEP-index map. Primary hadrons keep their mothers
(q, qq); in the charm remnant they point to the remnant quark. Decay
products of a PYTHIA decay are contiguous in PYTHIA's record, so daughter
lists stay compact and the new entries never trigger the compactifier. Decayed hadrons whose
PDG code GENIE does not know are kept as kPdgHadronicBlob so links stay
valid.

No extra PYTHIA calls or random numbers are used: the status 1 / 14 / 15
entries are identical with the option on or off, and with it off the
record is identical to before. Status 3 is used (not 12) so that the gst
primary-hadron loop, INTRANUKE (status 14) and the decayers (status 1, 14)
do not see the new entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E3nCvREWPkWV3JvvxzenHN
@nusense

nusense commented Nov 17, 2026

Copy link
Copy Markdown
Member

Adam, this look like a good improvement in keeping history. To the point that I lean towards making the default "true". It shouldn't disturb anything and it makes what went on much clearer.

I did have to lookup what Pythia8 meant by status code -23 which comes up several places; perhaps you could centralize the value to an explicit constant with an accompanying comment. I'm never very comfortable with "special numbers" floating amongst the code body.

Review of GENIE-MC#562: the PYTHIA 8 status codes used to select what is copied
into the GHEP record (-23 for the fragmented string ends, -81..-89 and
-91..-99 for hadrons PYTHIA decayed during the hadronization) were bare
numbers in Pythia8Hadro2019 and AGCharmPythia8Hadro2023. They are now
named constants, with a helper IsPythia8DecayedHadron(), in a small
shared header Physics/Hadronization/Pythia8StatusCodes.h that explains
what the codes mean.

No change in behaviour; KeepHadronizationHistory still defaults to false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E3nCvREWPkWV3JvvxzenHN
@AdamAurisano

AdamAurisano commented Nov 18, 2026 •

Copy link
Copy Markdown
Author

Thanks. Done in fb885f1: the PYTHIA 8 status codes now live as named constants in a new shared header, Physics/Hadronization/Pythia8StatusCodes.h, with a comment explaining what -23 (string ends of the hard process, flipped negative after fragmentation), -81..-89 (primary hadrons decayed during hadronization) and -91..-99 (decay products that decayed in turn) mean. Pythia8Hadro2019 and AGCharmPythia8Hadro2023 both use them via IsPythia8DecayedHadron(). Output is bitwise identical to before with the option off and on.

On the default: we are happy to flip KeepHadronizationHistory to true if the collaboration prefers. The physics output does not change (every status 1/14/15 entry and the gst tree are identical with it on), but the files do grow: about 3.5% for GHEP and rootracker in our samples (0.4-0.9 extra rows per event). We will defer to what you want.

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants