Clarify the FLUKA comparison notes and point at the shipped NIEL weights

docs/scoring/README.md

@@ -88,9 +88,11 @@ Particle names are the Geant4 ones: `neutron`, `proton`, `anti_proton`, `pi+`,
 `pi-`, `kaon0L`, `gamma`, `e-`, `opticalphoton`, and so on.
 
 A scorer without a filter counts everything, **including optical photons**.
-Those dominate the total fluence around the FT0 and are not transported by
-FLUKA at all, so an unfiltered `cellFlux` is not a quantity you can compare
-between the two engines. Filter, or read the filtered scorers instead.
+Those come from the FT0 radiator and dominate the total fluence around it. FLUKA
+produces them too, but in different numbers (see
+[the same scoring in FLUKA](flukacomparison.md)), so an unfiltered `cellFlux` is
+not a quantity you can compare between the two engines. Filter, or read the
+filtered scorers instead.
 
 ## Output
 
@@ -139,20 +141,24 @@ The trailing `true` is the `scoreweighted` flag. It only exists for `cellFlux`.
 Switch the weights on with:
 
 ```bash
---configKeyValues "G4.g4scoring=true;G4.g4fluenceweight=true;G4.fluenceWeightFile=$PWD/rd50_niel.csv;G4.configMacroFile=$PWD/g4scoring.in"
+--configKeyValues "G4.g4scoring=true;G4.g4fluenceweight=true;G4.fluenceWeightFile=$O2_ROOT/share/Detectors/gconfig/data/rd50_niel.csv;G4.configMacroFile=$PWD/g4scoring.in"
 ```
 
+**The `true` flag alone does nothing.** Without `G4.g4fluenceweight=true` the
+scorer falls back to a weight of one for every step, so the map looks perfectly
+healthy and is plain fluence. There is no warning. If a `neq` map comes out
+equal to the unweighted one, this is why.
+
 The weight file is a CSV of PDG code, kinetic energy in MeV and damage weight:
 
 ```
 # pdg,ekin[MeV],weight
 2112,1.025000e-10,1.575000e-02
 ```
 
-The same curves ship with O2 as ROOT graphs in
-`$O2_ROOT/share/Detectors/gconfig/data/rd50_niel.root`, under the names
-`neutronDW`, `protonDW`, `pionDW` and `electronDW`. If you do not have the text
-file, write it out from there — the loader only accepts CSV.
+The file ships with O2 as
+`$O2_ROOT/share/Detectors/gconfig/data/rd50_niel.csv`, together with the same
+curves as ROOT graphs in `rd50_niel.root`. The loader only accepts CSV.
 
 Only four tables are read — neutron (2112), proton (2212), pion (211) and
 electron (11) — and they are applied like this:
@@ -166,7 +172,14 @@ electron (11) — and they are applied like this:
 | everything else | zero |
 
 Outside the tabulated energy range the weight is clamped to the first or last
-tabulated value.
+tabulated value. The electron table covers 0.3 to 200 MeV (Summers et al.,
+IEEE Trans. Nucl. Sci. 40 (1993) 1372, as compiled by RD50), so electrons below
+0.3 MeV get the lowest tabulated weight. O2 versions from before October 2026
+ship the file without the electron table; there e± weigh nothing, which is
+about half a percent of the inner-tracker n eq.
+
+The four tables are the RD50 compilation by A. Vasilescu and G. Lindström,
+https://rd50.web.cern.ch/NIEL/.
 
 The consequence for a comparison: **do not filter the NIEL scorer down to
 neutrons, protons and pions.** FLUKA's `SI1MEVNE` weights every hadron and
@@ -184,7 +197,7 @@ coarse one over the cavern, each with fluence, 1 MeV n eq, hadrons above
 cat $O2_ROOT/share/Detectors/gconfig/g4config.in g4scoring_alice.in > g4full.in
 
 o2-sim -e TGeant4 -g pythia8pp -n 1000 -j 8 \
-  --configKeyValues "G4.g4scoring=true;G4.g4fluenceweight=true;G4.fluenceWeightFile=$PWD/rd50_niel.csv;G4.configMacroFile=$PWD/g4full.in"
+  --configKeyValues "G4.g4scoring=true;G4.g4fluenceweight=true;G4.fluenceWeightFile=$O2_ROOT/share/Detectors/gconfig/data/rd50_niel.csv;G4.configMacroFile=$PWD/g4full.in"
 ```
 
 {% include list.liquid all=true %}

docs/scoring/flukacomparison.md

@@ -82,14 +82,23 @@ So per event: `fluka_value * total_weight / nevents` against
 - **Same kinematics.** Generate once with `--noGeant`, then replay the same
   file in both engines with `-g extkinO2 --extKinFile o2sim_Kine.root`.
   Otherwise the comparison also contains the generator.
-- **Low-energy neutrons.** FLUKA transports neutrons down to thermal energies
-  by default. Geant4 does not, unless an HP physics list is used and the
-  neutron cut is lowered:
+- **Low-energy neutrons.** Whenever neutrons below 20 MeV matter, which is the
+  case for any 1 MeV n eq map, switch low-energy neutron transport on in both
+  engines. In FLUKA this is `FlukaParam.lowNeutron=true`; it is off by default
+  in `o2-sim`, and setting `FlukaParam.scoringFile` also switches it on. In
+  Geant4 use an HP physics list and lower the neutron cut:
   `G4.physicsmode=kFTFP_BERT_HP_optical;SimCutParams.lowneut=true;GlobalSimProcs.CUTNEU=5.e-12`.
-- **Optical photons.** Geant4 produces and transports Cherenkov photons in the
-  FT0; FLUKA in the ALICE setup does not. They show up in any unfiltered
-  fluence scorer and swamp it locally. Dose, 1 MeV n eq and hadron fluence are
-  unaffected.
+- **Optical photons.** O2 switches on Cherenkov production in the FT0 radiator
+  in both engines, and both count these photons in an unfiltered fluence
+  scorer (`ALL-PART` in FLUKA, a `cellFlux` without filter in Geant4). The
+  engines do not produce the same number: the absorption length and mirror
+  surfaces O2 defines for the FT0 are passed to Geant4 but not to FLUKA, so
+  FLUKA's photons are not absorbed and about six times more of them leave the
+  detector. In ALICE 2, with the MFT fix below applied, this makes the total
+  fluence differ by a factor two at R = 5–20 cm near the FT0 planes
+  (z = +335 cm and z = −84 cm). The photons carry a few eV, so dose,
+  1 MeV n eq and hadron fluence are unaffected.
+  Compare the species you need, never unfiltered total fluence.
 - **Same geometry.** `--detectorList` and `--skipModules` have to match, and
   hit creation should be switched off or on in both.
 
@@ -107,8 +116,10 @@ Check this in every FLUKA run directory before you trust a map:
 grep -c "ASSIGNMAT       -1.0" flukaMat.inp   # 0 when healthy
 ```
 
-This affected the ten MFT PEEK support disks in ALICE 2 and pulled the FLUKA
-fluence in the barrel down by up to a factor two — for a long time this was read
-as a physics disagreement between the two codes. The geometry is fixed by
-giving the support volume a name of its own; make sure your O2 version has that
-fix.
+In ALICE 2 this happened to the ten MFT PEEK support disks, which lowered the
+FLUKA fluence in the barrel by up to a factor two. The name clash exists in O2
+from February 2020 ([AliceO2 PR 2877](https://github.com/AliceO2Group/AliceO2/pull/2877)) until September 2026, when the support
+volume got a name of its own (`4f9072579a`). It concerns only TFluka runs with
+an O2 version from that period and the MFT in the geometry. The official ALICE
+FLUKA calculations predate it and are not affected, and neither are the FoCal
+calculations on the A side.

docs/scoring/g4scoring_alice.in

@@ -1,4 +1,6 @@
 # ALICE radiation scoring: two cylindrical meshes, phi averaged.
+# The neq scorers need G4.g4fluenceweight=true and G4.fluenceWeightFile, otherwise
+# they silently score unweighted fluence.
 # Append this to $O2_ROOT/share/Detectors/gconfig/g4config.in and pass the
 # result as G4.configMacroFile. The scorers mirror the FLUKA USRBIN cards
 # 201 (fluence), 236 (1 MeV n eq), 237 (hadrons > 20 MeV), 202 (charged)