Skip to content

Commit 044fe2c

Browse files
sawenzelclaude
andcommitted
Document Geant4 scoring and its FLUKA counterpart
This adds a Geant4 scoring section to the simulation documentation. - A page on the scoring macro, the o2-sim options, the output format and the 1 MeV neutron equivalent weighting. - A page translating USRBIN cards to Geant4 commands, with the normalisation and the settings to match before comparing. - A ready-to-use macro g4scoring_alice.in, the one used for the ALICE FLUKA/Geant4 radiation comparison. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 183b699 commit 044fe2c

4 files changed

Lines changed: 341 additions & 0 deletions

File tree

‎docs/scoring/README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
sort: 9
3+
title: Geant4 scoring
4+
---
5+
6+
# Geant4 scoring
7+
8+
Geant4 can accumulate radiation maps — fluence, dose, 1 MeV neutron equivalent
9+
fluence, hadron fluence above 20 MeV — on a mesh laid over the ALICE geometry,
10+
without any change to detector code. The mesh is configured with Geant4 macro
11+
commands, the same way FLUKA users configure `USRBIN` cards, and the result is
12+
written as a text file at the end of the run.
13+
14+
This page explains how to switch it on in `o2-sim`, how to write the macro, and
15+
how to read the output. The [FLUKA counterpart](flukacomparison.md) page gives
16+
the card-by-card translation and the differences you have to know about before
17+
comparing numbers.
18+
19+
## Quick start
20+
21+
Write a macro file `scoring.in`:
22+
23+
```
24+
/score/create/cylinderMesh fine
25+
/score/mesh/cylinderSize 10. 30. cm
26+
/score/mesh/nBin 100 60 1
27+
/score/quantity/cellFlux flux percm2
28+
/score/quantity/doseDeposit dose Gy
29+
/score/close
30+
```
31+
32+
Append it to the standard ALICE Geant4 configuration and run:
33+
34+
```bash
35+
cat $O2_ROOT/share/Detectors/gconfig/g4config.in scoring.in > g4scoring.in
36+
37+
o2-sim-serial -e TGeant4 -g pythia8pp -n 100 \
38+
--configKeyValues "G4.g4scoring=true;G4.configMacroFile=$PWD/g4scoring.in"
39+
```
40+
41+
The run writes `fine.worker<pid>.txt` into the working directory, one file per
42+
mesh.
43+
44+
`G4.configMacroFile` **replaces** the standard `g4config.in`, it does not add to
45+
it. Always concatenate, otherwise the run loses the ALICE physics settings
46+
(range cuts, PAI in the TRD, biasing, field steppers).
47+
48+
## Meshes
49+
50+
Each mesh is a block between `/score/create/...` and `/score/close`. Several
51+
meshes can coexist; they are parallel worlds and do not disturb the transport.
52+
53+
| Command | Meaning |
54+
|---|---|
55+
| `/score/create/cylinderMesh <name>` | cylindrical mesh, axis along z |
56+
| `/score/create/boxMesh <name>` | box mesh |
57+
| `/score/mesh/cylinderSize <R> <dz> <unit>` | outer radius and **half** length |
58+
| `/score/mesh/boxSize <dx> <dy> <dz> <unit>` | **half** lengths |
59+
| `/score/mesh/nBin <nR> <nZ> <nPhi>` | bins of a cylinder mesh |
60+
| `/score/mesh/nBin <nX> <nY> <nZ>` | bins of a box mesh |
61+
| `/score/mesh/translate/xyz <x> <y> <z> <unit>` | move the mesh off the origin |
62+
| `/score/close` | end the mesh definition |
63+
64+
A mesh is centred on the origin unless it is translated. Bins are equidistant.
65+
A single phi bin gives the phi-averaged map, which is what a radiation study
66+
normally wants.
67+
68+
## Quantities and filters
69+
70+
Inside a mesh, every `/score/quantity/...` line adds one scorer, and the
71+
`/score/filter/...` lines that follow apply to the scorer above them.
72+
73+
| Command | Quantity |
74+
|---|---|
75+
| `/score/quantity/cellFlux <name> percm2` | track length per cell volume, i.e. fluence |
76+
| `/score/quantity/doseDeposit <name> Gy` | absorbed dose |
77+
| `/score/quantity/energyDeposit <name> MeV` | deposited energy |
78+
| `/score/quantity/nOfStep <name>` | number of steps, useful for debugging |
79+
80+
| Filter | Selects |
81+
|---|---|
82+
| `/score/filter/particle <fname> <p1> <p2> ...` | those Geant4 particle names |
83+
| `/score/filter/particleWithKineticEnergy <fname> <emin> <emax> <unit> <p1> ...` | those particles in that kinetic energy range |
84+
| `/score/filter/charged <fname>` | all charged particles |
85+
| `/score/filter/neutral <fname>` | all neutral particles |
86+
87+
Particle names are the Geant4 ones: `neutron`, `proton`, `anti_proton`, `pi+`,
88+
`pi-`, `kaon0L`, `gamma`, `e-`, `opticalphoton`, and so on.
89+
90+
A scorer without a filter counts everything, **including optical photons**.
91+
Those dominate the total fluence around the FT0 and are not transported by
92+
FLUKA at all, so an unfiltered `cellFlux` is not a quantity you can compare
93+
between the two engines. Filter, or read the filtered scorers instead.
94+
95+
## Output
96+
97+
Each mesh is dumped at the end of the run to `<mesh>.worker<pid>.txt`:
98+
99+
```
100+
# mesh name: fine
101+
# primitive scorer name: flux
102+
# iZ, iPHI, iR, total(value) [percm2], total(val^2), entry
103+
0,0,0,1856.089717,405107.423708,10
104+
```
105+
106+
The columns are the bin indices, the sum over the whole run, the sum of
107+
squares, and the number of contributing steps. Two things to keep in mind:
108+
109+
- The value is summed over **all events of the run**, not per event. Divide by
110+
the number of events yourself.
111+
- `total(val^2)` is the sum of squares of the per-step contributions, so it is
112+
not the statistical error of the bin. Use several runs with different seeds
113+
if you need an uncertainty.
114+
115+
Parallel `o2-sim` writes one file per worker and merges them into `<mesh>.txt`
116+
at the end of the run. If a merge has to be redone by hand, for example after
117+
collecting dumps from several jobs:
118+
119+
```bash
120+
o2-sim-merge-g4scoring <directory> <expected number of workers>
121+
```
122+
123+
The second argument is optional; when given, the merger fails loudly if a
124+
worker file is missing, which is the common way to lose a few percent of the
125+
statistics without noticing.
126+
127+
## 1 MeV neutron equivalent fluence
128+
129+
Geant4 has no built-in NIEL scorer. The ALICE Geant4 build takes a per-step
130+
weight from a user function, and `o2-sim` feeds it with RD50 damage weights, so
131+
that a `cellFlux` scorer becomes a damage-weighted fluence:
132+
133+
```
134+
/score/quantity/cellFlux neq percm2 true
135+
```
136+
137+
The trailing `true` is the `scoreweighted` flag. It only exists for `cellFlux`.
138+
139+
Switch the weights on with:
140+
141+
```bash
142+
--configKeyValues "G4.g4scoring=true;G4.g4fluenceweight=true;G4.fluenceWeightFile=$PWD/rd50_niel.csv;G4.configMacroFile=$PWD/g4scoring.in"
143+
```
144+
145+
The weight file is a CSV of PDG code, kinetic energy in MeV and damage weight:
146+
147+
```
148+
# pdg,ekin[MeV],weight
149+
2112,1.025000e-10,1.575000e-02
150+
```
151+
152+
The same curves ship with O2 as ROOT graphs in
153+
`$O2_ROOT/share/Detectors/gconfig/data/rd50_niel.root`, under the names
154+
`neutronDW`, `protonDW`, `pionDW` and `electronDW`. If you do not have the text
155+
file, write it out from there — the loader only accepts CSV.
156+
157+
Only four tables are read — neutron (2112), proton (2212), pion (211) and
158+
electron (11) — and they are applied like this:
159+
160+
| Particle | Weight used |
161+
|---|---|
162+
| neutron | neutron table |
163+
| e+, e- | electron table, zero if the table is absent |
164+
| all other baryons and antibaryons | proton table |
165+
| all other mesons | pion table |
166+
| everything else | zero |
167+
168+
Outside the tabulated energy range the weight is clamped to the first or last
169+
tabulated value.
170+
171+
The consequence for a comparison: **do not filter the NIEL scorer down to
172+
neutrons, protons and pions.** FLUKA's `SI1MEVNE` weights every hadron and
173+
electron, so an ALICE inner-tracker map scored only on n, p and pi comes out
174+
about 18% low. Kaons alone account for most of it.
175+
176+
## A ready example
177+
178+
[`g4scoring_alice.in`](g4scoring_alice.in) is the macro used for the ALICE
179+
FLUKA/Geant4 radiation comparison: a fine mesh over the inner tracker and a
180+
coarse one over the cavern, each with fluence, 1 MeV n eq, hadrons above
181+
20 MeV, charged fluence, energy deposit and dose.
182+
183+
```bash
184+
cat $O2_ROOT/share/Detectors/gconfig/g4config.in g4scoring_alice.in > g4full.in
185+
186+
o2-sim -e TGeant4 -g pythia8pp -n 1000 -j 8 \
187+
--configKeyValues "G4.g4scoring=true;G4.g4fluenceweight=true;G4.fluenceWeightFile=$PWD/rd50_niel.csv;G4.configMacroFile=$PWD/g4full.in"
188+
```
189+
190+
{% include list.liquid all=true %}

‎docs/scoring/flukacomparison.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
sort: 1
3+
title: The same scoring in FLUKA
4+
---
5+
6+
# The same scoring in FLUKA
7+
8+
FLUKA scores the same maps with `USRBIN` cards. In `o2-sim` the cards come from
9+
a file:
10+
11+
```bash
12+
o2-sim-serial -e TFluka -g pythia8pp -n 100 \
13+
--configKeyValues "FlukaParam.scoringFile=$PWD/scoring.inp"
14+
```
15+
16+
The file is appended to the FLUKA input that `o2-sim` generates, so it contains
17+
only the cards, in the fixed FLUKA column format:
18+
19+
```
20+
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7...+...8
21+
USRBIN 11. 201. 21. 10.0 0. 30.0fflux
22+
USRBIN 0. 0. -30.0 100. 1. 60.&
23+
USRBIN 11. 236. 22. 10.0 0. 30.0fneq
24+
USRBIN 0. 0. -30.0 100. 1. 60.&
25+
```
26+
27+
Each pair of cards is one binning: type, quantity, output unit, `Rmax`, x of the
28+
axis, `zmax`, name; then `Rmin`, y of the axis, `zmin`, `nR`, `nPhi`, `nZ`.
29+
30+
Two details worth spelling out:
31+
32+
- Type `11` is an r-phi-z mesh scored with the track-length apportioning
33+
algorithm. Type `1` uses the old point-wise algorithm and is **not allowed**
34+
for `SI1MEVNE` and `HADGT20M`.
35+
- A positive output unit writes formatted text to `fort.<unit>`, a negative one
36+
writes binary that has to go through `usbsuw`/`usbrea` first. Units below 21
37+
are reserved. Text output is easier to read back and costs nothing at ALICE
38+
mesh sizes.
39+
40+
## Translation table
41+
42+
| Quantity | FLUKA | Geant4 |
43+
|---|---|---|
44+
| all-particle fluence | `201` (ALL-PART) | `/score/quantity/cellFlux f percm2` |
45+
| charged fluence | `202` (ALL-CHAR) | `cellFlux` + `/score/filter/charged` |
46+
| neutral fluence | `203` (ALL-NEUT) | `cellFlux` + `/score/filter/neutral` |
47+
| neutron fluence | `8` (NEUTRON) | `cellFlux` + `/score/filter/particle f neutron` |
48+
| photon fluence | `7` (PHOTON) | `cellFlux` + `/score/filter/particle f gamma` |
49+
| deposited energy | `208` (ENERGY), GeV/cm3 | `/score/quantity/energyDeposit e MeV` |
50+
| dose | `228` (DOSE), GeV/g | `/score/quantity/doseDeposit d Gy` |
51+
| 1 MeV n eq (Si) | `236` (SI1MEVNE) | weighted `cellFlux`, see [Geant4 scoring](README.md) |
52+
| hadrons above 20 MeV | `237` (HADGT20M) | `cellFlux` + `particleWithKineticEnergy` filter |
53+
54+
`HADGT20M` has no Geant4 equivalent either, so the particle list has to be
55+
written out:
56+
57+
```
58+
/score/quantity/cellFlux had20 percm2
59+
/score/filter/particleWithKineticEnergy had20filter 20. 10000000. MeV proton anti_proton neutron anti_neutron pi+ pi- kaon+ kaon- kaon0L kaon0S lambda anti_lambda sigma+ sigma- xi- xi0 omega-
60+
```
61+
62+
Filtering works the other way round in the two codes. In FLUKA a binning scores
63+
one generalised particle and `AUXSCORE` can restrict it further, but not by
64+
energy. In Geant4 a scorer starts from everything and is narrowed by filters,
65+
including energy filters.
66+
67+
## Normalisation
68+
69+
This is the most common source of a wrong ratio.
70+
71+
- FLUKA normalises a `USRBIN` to **one unit of primary weight**. The text
72+
output carries the total weight of the primaries in its header; multiply by
73+
it to get the sum over the run.
74+
- Geant4 sums over the **whole run** and divides by nothing. Divide by the
75+
number of events yourself.
76+
77+
So per event: `fluka_value * total_weight / nevents` against
78+
`g4_value / nevents`.
79+
80+
## Settings to match before comparing
81+
82+
- **Same kinematics.** Generate once with `--noGeant`, then replay the same
83+
file in both engines with `-g extkinO2 --extKinFile o2sim_Kine.root`.
84+
Otherwise the comparison also contains the generator.
85+
- **Low-energy neutrons.** FLUKA transports neutrons down to thermal energies
86+
by default. Geant4 does not, unless an HP physics list is used and the
87+
neutron cut is lowered:
88+
`G4.physicsmode=kFTFP_BERT_HP_optical;SimCutParams.lowneut=true;GlobalSimProcs.CUTNEU=5.e-12`.
89+
- **Optical photons.** Geant4 produces and transports Cherenkov photons in the
90+
FT0; FLUKA in the ALICE setup does not. They show up in any unfiltered
91+
fluence scorer and swamp it locally. Dose, 1 MeV n eq and hadron fluence are
92+
unaffected.
93+
- **Same geometry.** `--detectorList` and `--skipModules` have to match, and
94+
hit creation should be switched off or on in both.
95+
96+
## Pitfall: black-hole regions in the FLUKA geometry
97+
98+
FLUKA gets one region per ROOT volume number. Two volumes that share a *name*
99+
share a number, and only one of them gets its material assigned. If the winner
100+
is a `TGeoVolumeAssembly`, its placeholder material index `-1` becomes
101+
`BLCKHOLE`, and a real piece of detector silently deletes every particle that
102+
enters it.
103+
104+
Check this in every FLUKA run directory before you trust a map:
105+
106+
```bash
107+
grep -c "ASSIGNMAT -1.0" flukaMat.inp # 0 when healthy
108+
```
109+
110+
This affected the ten MFT PEEK support disks in ALICE 2 and pulled the FLUKA
111+
fluence in the barrel down by up to a factor two — for a long time this was read
112+
as a physics disagreement between the two codes. The geometry is fixed by
113+
giving the support volume a name of its own; make sure your O2 version has that
114+
fix.

‎docs/scoring/g4scoring_alice.in‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# ALICE radiation scoring: two cylindrical meshes, phi averaged.
2+
# Append this to $O2_ROOT/share/Detectors/gconfig/g4config.in and pass the
3+
# result as G4.configMacroFile. The scorers mirror the FLUKA USRBIN cards
4+
# 201 (fluence), 236 (1 MeV n eq), 237 (hadrons > 20 MeV), 202 (charged)
5+
# and 208 (energy deposit).
6+
7+
# inner tracker region: R < 10 cm, |z| < 30 cm, 1 mm x 1 cm bins
8+
/score/create/cylinderMesh fine
9+
/score/mesh/cylinderSize 10. 30. cm
10+
/score/mesh/nBin 100 60 1
11+
/score/quantity/cellFlux flux percm2
12+
/score/quantity/cellFlux neq percm2 true
13+
/score/quantity/cellFlux had20 percm2
14+
/score/filter/particleWithKineticEnergy had20filter 20. 10000000. MeV proton anti_proton neutron anti_neutron pi+ pi- kaon+ kaon- kaon0L kaon0S lambda anti_lambda sigma+ sigma- xi- xi0 omega-
15+
/score/quantity/cellFlux charged percm2
16+
/score/filter/charged chargedfilter
17+
/score/quantity/energyDeposit edep MeV
18+
/score/quantity/doseDeposit dose Gy
19+
/score/close
20+
21+
# whole cavern: R < 5 m, |z| < 5 m, 2.5 cm x 5 cm bins
22+
/score/create/cylinderMesh coarse
23+
/score/mesh/cylinderSize 500. 500. cm
24+
/score/mesh/nBin 200 200 1
25+
/score/quantity/cellFlux flux percm2
26+
/score/quantity/cellFlux neq percm2 true
27+
/score/quantity/cellFlux had20 percm2
28+
/score/filter/particleWithKineticEnergy had20filter 20. 10000000. MeV proton anti_proton neutron anti_neutron pi+ pi- kaon+ kaon- kaon0L kaon0S lambda anti_lambda sigma+ sigma- xi- xi0 omega-
29+
/score/quantity/cellFlux charged percm2
30+
/score/filter/charged chargedfilter
31+
/score/quantity/energyDeposit edep MeV
32+
/score/quantity/doseDeposit dose Gy
33+
/score/close

‎docs/transport/engines.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Transport engines
77

88
## GEANT4
99

10+
Radiation maps (fluence, dose, 1 MeV n eq) can be scored on a mesh, see [Geant4 scoring](../scoring/).
11+
1012
### Scaling hadronic cross sections
1113

1214
Hadronic cross sections can be scaled by passing a specific Geant4 configuration to the transport simulation.
@@ -16,6 +18,8 @@ Hadronic cross sections can be scaled by passing a specific Geant4 configuration
1618

1719
Informtation about FLUKA.
1820

21+
For `USRBIN` scoring in `o2-sim` and how it maps to Geant4, see [the same scoring in FLUKA](../scoring/flukacomparison.md).
22+
1923
## GEANT3
2024

2125
Information about GEANT3.

0 commit comments

Comments
 (0)