analysis/HERWIG_UE/README.md

0001 # HERWIG (Nashville) vs STAR UE cross-check for sPHENIX
0002
0003 Truth-level Fun4All analysis that reproduces **Fig. 4 (top right)** of the
0004 HERWIG7 RHIC tune paper (Qureshi et al., arXiv:2411.16897 / PRD 112, 116019):
0005 mean charged-particle multiplicity density `<dNch/(deta dphi)>` in the
0006 **Transverse region** vs leading-jet pT, compared to STAR,
0007 **PRD 101, 052004 (2020)** (arXiv:1912.08187).
0008
0009 The selections are ported 1:1 from the Rivet reference implementation
0010 `STAR_2019_I1771348` (github.com/star-bnl/star-pythia8-tune), which is what
0011 both the Detroit (PYTHIA8) and Nashville/New Haven (HERWIG7) tune papers ran:
0012
0013 | item | selection |
0014 |---|---|
0015 | final-state particles | status == 1, pT > 0.2 GeV/c, \|eta\| < 1.0 |
0016 | jet finding | anti-kT, R = 0.6, clustered from **all** such particles (charged + neutral) |
0017 | leading jet | hardest jet with 5 < pT < 45 GeV/c and \|eta\| < 0.4 |
0018 | Toward / Transverse / Away | \|dphi\| < pi/3  /  pi/3 < \|dphi\| < 2pi/3  /  \|dphi\| > 2pi/3 |
0019 | density | Nch / (deta * dphi) = Nch / (2 x 2pi/3), per event, profiled vs leading-jet pT |
0020 | jet-pT binning | {5, 7, 9, 11, 15, 20, 25, 35, 45} GeV/c (STAR HEPData) |
0021
0022 Also filled for free: Toward/Away densities, Transverse density for
0023 pT > 0.5 GeV/c, and the `<pT_ch>` profiles (STAR Figs. 2-4 companions),
0024 plus cutflow / leading-jet / dphi diagnostics.
0025
0026 ## Build
0027
0028 ```
0029 cd src
0030 mkdir -p build && cd build
0031 ../autogen.sh --prefix=$MYINSTALL
0032 make -j4 install
0033 ```
0034
0035 (usual sPHENIX setup: `source /opt/sphenix/core/bin/sphenix_setup.sh -n` and
0036 `sphenix_setup_myinstall` or add `$MYINSTALL` to `LD_LIBRARY_PATH` /
0037 `ROOT_INCLUDE_PATH`.)
0038
0039 ## Run
0040
0041 ```
0042 ls /path/to/herwig/DST*.root > herwig_dst.list
0043 root -b -q 'macro/Fun4All_HerwigUE.C("herwig_dst.list","herwig_ue_check.root",0)'
0044 root -l 'macro/PlotUETransverse.C("herwig_ue_check.root")'
0045 ```
0046
0047 `PlotUETransverse.C` has the STAR Transverse-region data points (values,
0048 stat, asymmetric sys from HEPData d01-x01-y03) baked in and produces the
0049 two-panel figure (distribution + MC/data ratio with the data uncertainty
0050 band) plus a per-bin numerical table.
0051
0052 ## What "sufficient" looks like
0053
0054 From the tune paper, the Nashville curve tracks the STAR Transverse density
0055 within roughly the experimental systematics (~5-8%) across the full range,
0056 with mild low-pT (5-10 GeV/c) and high-pT (>~30 GeV/c) deviations. If the
0057 sPHENIX production reproduces MC/data ratios at that level, the UE modeling
0058 in the production is behaving as published.
0059
0060 ## Caveats to keep in mind
0061
0062 1. **pThat-binned / triggered productions.** The tune papers generated
0063    *minimum-bias inelastic* HERWIG. If the sPHENIX production has a hard
0064    pThat floor (e.g. a Jet10/Jet30-style sample), the leading-jet-pT bins
0065    near and below the floor are sculpted — only trust bins with leading-jet
0066    pT comfortably above pThat_min (rule of thumb: +5-10 GeV/c). If multiple
0067    weighted pThat bins are chained, the HepMC event weight is picked up
0068    automatically (`evt->weights().front()`), but check the normalization
0069    convention of the production.
0070 2. **Particle-level decay settings.** The tune comparisons used HERWIG's
0071    generator-level stable particles. If the sPHENIX production changed the
0072    stable-particle lifetime threshold (e.g. decaying K0s/Lambda for Geant),
0073    secondary charged particles will inflate the UE density at the few-%
0074    level. Check which strange hadrons appear with status 1 in the DSTs.
0075 3. **Neutrinos in jets.** The Rivet reference clusters a plain `FinalState`,
0076    i.e. neutrinos included; the module matches this by default
0077    (`set_include_neutrinos(false)` to flip). Effect is negligible.
0078 4. **Crossing-angle boost.** If the production applied the sPHENIX beam
0079    crossing boost via PHHepMCGenHelper, eta/phi are shifted by O(mrad) —
0080    irrelevant here, but it's why this module reads the HepMC record rather
0081    than assuming a CM frame.
0082 5. **Statistics.** STAR stat errors are per-mille; the comparison is
0083    systematics-limited (~5%). A few 10^5 accepted leading jets (see the
0084    `h_nevents` cutflow) gives MC stat errors well below that in all but the
0085    35-45 GeV/c bin.