The truth graph in Ember: what is used, and what is missing¶
In Ember, "truth" means the CMSSW truth graph and nothing else:
truth::Graphand its hit index (truth::LogicalGraphHitIndex, PhysicsTools/TruthInfo);- the reco ↔ truth associations of SimGeneral/TruthGraphAssociatorProducers;
as NanoAOD tables. CaloParticle, SimCluster and SimTrackster are not used (the hgcal profile excludes their tables),
and should not be.
The tables come from one of two places:
- the truth tables: the CMSSW branch
truthgraph-nano-tables(TruthGraphFlatTableProducerandTruthGraphHitFlatTableProducerin PhysicsTools/TruthInfo, and the association tables of cms-sw/cmssw#52451, intruthGraphNanoTables_cff).ember_cfg.pyuses them when your release has them (CMSSW side). Their association tables are named<Key>ToTruthandTruthTo<Key>, each with a...Linkstable; - the earlier export: Ember's earlier whole-detector export, an unmerged CMSSW package that is no longer made. It
wrote the truth of the bundles made so far, such as the ttbar data sets of https://marriot-evd.web.cern.ch, and
every measurement on this page. Its association tables were named
<collection>ToTruthand<collection>FromTruth. The truth tables are its generic successor, with the same particle selection (keepLevelMask,keepMatchedBy,keepAncestors) and the same per-particle hit energies.
This page says:
- what the viewer shows from the truth graph;
- what the viewer works out itself where the graph has no answer;
- what is missing, so that each gap can be checked off as CMSSW adds it.
What a reco object is compared with, the measures (purity, completeness) and the colours are in Truth.
What the viewer shows¶
| in the viewer | from |
|---|---|
| Truth graph · Particles, Vertices; the Truth tab (parent → children) | TruthParticles, TruthVertices, TruthParticleChildren |
| a reco object's "best match"; the pair view's particle for a selected reco object | <Key>ToTruth (earlier export: <collection>ToTruth): the AdaptiveNominal working point, one particle per reco object, with sharedEnergy and score (0 is best) |
| a reco object's purity, and whether its match is clean (inspector, truth mode) | ToTruth.sharedEnergy over the object's own amount, as the relation's match hint says (Truth) |
| a truth particle's matched reco objects (its card's "Reconstructed as"), a match's completeness | TruthTo<Key> (earlier export: <collection>FromTruth), with sharedEnergyFraction (earlier export: sharedFraction) and score |
| "the particle" that colours everything below it in the truth colours; the levels in the lineage | TruthParticles.levelFlags (truth::LevelFlag; bit 2 StableDecayProducts, bit 3 CaloBoundary) |
| a hit's particle; "simulated energy in its hits, by particle" | TruthHGCalRecHits, TruthPFRecHits (earlier export: TruthHGCalHits, TruthSoAHits{EE,HSi,HSci}, and the barrel and forward ones of gap 12): per (particle, hit), the simulated energy of the particle's subgraph |
Choices in Ember. Ember derives no truth association where CMSSW has none: a layer cluster, a TICL candidate or a PF candidate is shown as a gap, not matched through its hits (until 2026-11, layer clusters took the particle with the most simulated energy in their hits; that stand-in is gone). What Ember does choose is how truth is grouped for the eye:
- One colour per generator particle (gap 2): a particle takes the colour of its highest ancestor in the profile's
particlelevel, the generator-level stable particles (identitiesin the same file; Truth). So a π⁺ that interacted in the tracker, its daughters' hits and its track share one colour. A shower secondary matched to a trackster has the colour of the shower's hits. The inspector still names the particle that was actually matched, and its lineage. - Small, faint grey hits mean that no exported particle left energy in them: noise, or a particle that was not exported (gaps 3 to 5). The export cannot tell which. The larger mid grey means something else: a particle beyond the seven that get a colour.
How truth reaches Ember¶
Sources: CMSSW_20_1_0_pre5 with the truth-graph developments and the earlier export. CMSSW paths are relative to src/
(SimDataFormats/TruthInfo as in the release). Numbers marked measured come from the bundles gun3_0PU.evdb (events
0 to 2) and ttbar_pu200.evdb (events 0 and 1), read with embertools.bundle. Checked on 2026-11-10.
- Graph and hit index, built at DIGI (
PhysicsTools/TruthInfo/python/truthGraphMixedDigi_cff.py). For every particle of the graph, the hit index holds its own calorimeterPCaloHitenergy per DetId ("direct"), and the set including its descendants ("subgraph"). The calorimeter channel covers HGCal EE/HEF/HEB, the ECAL barrel and HCAL (SimDataFormats/TruthInfo/interface/LogicalGraphHitIndex.h:20-25). By default the graph holds pile-up from the in-time bunch crossing only (truthGraphMixedDigi_cff.py:49,pileupBunchCrossings=[0]). A step2 customisation can add out-of-time crossings (the Ember reference samples have -3 to +3); thehgcalprofile then keeps crossing 0 only. - Associators (
SimGeneral/TruthGraphAssociatorProducers/python/truthGraphAssociators_cff.py), scheduled bycustomiseTruthGraphAssociators. Each one writes aRecoToTruth<WP>map per working point (Fixed, AdaptiveTight, AdaptiveNominal) and oneTruthToRecomap. TheTruthAssociationTraitsspecialisations list the reco types covered (plugins/AllRecoToTruthBranchAssociatorsProducer.cc:137-227):reco::Track,reco::Vertex,reco::PFCluster,ticl::Trackster,TICLCandidate. Notreco::CaloCluster. - The tables. The earlier export wrote
TruthParticles,TruthVertices,TruthParticleChildren,<coll>ToTruth(AdaptiveNominal),<coll>FromTruth(TruthToReco), andTruthHGCalHits/TruthSoAHits{EE,HSi,HSci}(particle → hit, simulated energy). The SoA ones are written only where SoA hit tables are written, which a stock release does not do (CMSSW side). The truth tables write the same particles, vertices and links, the association tables in both directions, and a hit table for any hit table with a DetId column. - The Ember profiles read all of these as relations:
truth.jsonfor the truth tables, andembertools/profiles/hgcal.json:64-114for the earlier export.sameRowsredirects the legacy CLUEstering relations to the SoA tracksters (hgcal.json:12,_resolve_relationsinembertools/converter.py).
Definitions the display inherits (shared energy, scores)¶
From PhysicsTools/TruthInfo/interface/BranchHitAssociator.h:66-108, and the producer at :820-866:
- A truth branch is a particle with its whole subgraph of descendants. A reco object is matched to branches, not to single particles. So an ancestor always shares at least as much energy as its descendants.
- The weight of a cell is the rechit energy of the cell (offline: the legacy
HGCalRecHitcollections, the default at:951-955). The branch ownssimE_branch / simE_cell_totalof it, and the reco object owns its hit fraction. The shared energy per cell is the smaller of the two. ToTruth.sharedEnergy[GeV, rechit scale] andToTruth.score: normalised to the reco object, "squared uncovered energy over squared self energy". 0 is best. It is not linear, so 1 − score is not a purity.FromTruth.sharedFraction= shared energy / branch energy in HGCal (denominatorDetectors, cff:127), andFromTruth.scoreis the reverse score, normalised to the branch.- AdaptiveNominal picks one branch per reco object, by minimising
score + reverseScoreover the "assignable" roots. Partons, beam particles, electroweak bosons and synthetic nodes are excluded (cff:38-44). So the match can be at any level: a shower secondary, a particle that entered the calorimeter, a π⁰, or a decaying hadron. - Candidate roots: every particle that is not a parton and not synthetic, with |η| < 4, with no pT cut, signal
and pile-up alike (
TruthBranchTargetsProducer.cc:126-150, cff:21-32).
Gap table¶
Where each gap is:
- G: not in the graph or the hit index;
- A: in the graph, but with no associator;
- X: an associator exists, but it is not exported;
- E: exported, but Ember does not read it, or reads it in a way that loses information.
"Exported" means written to NanoAOD by the truth tables or by the earlier export. The priority is for the viewer.
| # | What is missing | Class | Where | Priority |
|---|---|---|---|---|
| 1 | Layer cluster ↔ truth association | A | no TruthAssociationTraits<reco::CaloCluster>, no layerClusters domain in truthGraphRecoLabelsPSet (truthGraphAssociationLabels_cff.py:37-54), nothing in truthGraphAssociatorsSequence (cff :190-199), no layer-cluster validator in Validation/TruthInfo |
high |
| 2 | Hits of the particle that a reco object is matched to, when that particle is not the one entering the calorimeter | X | TruthGraphHitFlatTableProducer (as the earlier export's hit table) exports subgraph hits only for particles with LevelFlag::CaloBoundary (the default of its levelMask, 8) |
high |
| 3 | Total simulated energy per hit (all particles), to tell a grey hit apart as noise or as a particle that was not exported | X (the data is in the index, but not exported) | the hit tables have only (exported particle, hit) rows | high |
| 4 | Particles that deposit energy, but are neither signal nor matched by a calorimeter object, are not exported, so their hits have no particle. Fixed in the truth tables (and in the earlier export): keepLevelMask, opt-in, see 3–5. Unattributed energy. |
X | the selection of TruthGraphFlatTableProducer; with the default selection, particles that only deposit energy are not kept; pairs with particles that are not exported are dropped |
high at pile-up |
| 5 | Out-of-time pile-up has no particles at all (in the default configuration; where a sample has them, the hgcal profile drops them) |
G | truthGraphMixedDigi_cff.py:49 (pileupBunchCrossings=[0]) |
medium |
| 6 | First-stage tracksters of a non-v6 (CLUE3D) reconstruction. Fixed: the associator follows the scheduled labels (truthGraphAssociationLabels_cff.py:170-189), and so do the truth tables (they read truthGraphAssociationLabels_cff, so a stock release writes the association tables of ticlTrackstersCLUE3DHigh). The profile reads them (clue3dTruth, truthClue3d in hgcal.json), with the same match contract as the CLUEstering tracksters. |
X | done | |
| 7 | TICL candidate ↔ truth association. The release has no TruthAssociationTraits<TICLCandidate> (AllRecoToTruthBranchAssociatorsProducer.cc specialises only reco::Track, reco::Vertex, reco::PFCluster and ticl::Trackster). The tracksters domain does include the trackster collection that TICLCandidateProducer writes next to its candidates (truthGraphAssociationLabels_cff.py, tracksterProducerTypes), so each candidate's own trackster is matched, and a charged candidate's track is. An earlier development branch had a calorimeter-only candidate associator (RecoHitAdapters.h) |
A | AllRecoToTruthBranchAssociatorsProducer.cc:114-181 |
medium |
| 8 | Runner-up matches per reco object (Fixed working point: every branch that shares energy) | X | only RecoToTruthAdaptiveNominal was exported by the earlier export |
low |
| 9 | HLT tracksters, tracks and vertices (for offline vertices, see 14: exported) | X | allVertexToTruthBranchAssociators and hlt*Associators exist (cff :89-114, :167-184); the HLT ones are not exported |
low |
| 10 | SoA objects are never associated directly | A | covered only through legacy copies (HGCalTrackstersFromSoAProducer in tracksterProducerTypes, labels cff :26-33) and Ember's sameRows |
low (works while SoA == legacy) |
| 11 | Times of the simulated hits | X | LogicalGraphHitIndex::directHitTimes (LogicalGraphHitIndex.h:77-79,160-171), not exported |
low |
| 12 | Hit truth for the barrel and forward calorimeters (EB, HB, HF, HO). Fixed in the earlier export; the truth tables give it with one TruthGraphHitFlatTableProducer per hit table. |
X | earlier export: TruthEcalHits, TruthHBHEHits, TruthHFHits, TruthHOHits, drawn as facts (fact hint, pf.json). At 200 pile-up, before the in-time cut: 253k EB, 13k HB and 103k HF links per event (1.7, 0.09 and 0.34 MB in the NanoAOD) |
high |
| 13 | ECAL and HCAL PF-cluster associations. Fixed in the earlier export and in the truth tables. | X | earlier export: particleFlowCluster{ECAL,HCAL}{To,From}Truth, with the PFClusters{ECAL,HCAL} tables in collection order; match hints in pf.json. Truth tables: ParticleFlowCluster{ECAL,HCAL}ToTruth, TruthToParticleFlowCluster{ECAL,HCAL} |
high |
| 14 | Primary and secondary vertex associations (part of gap 9). Fixed in the earlier export and in the truth tables. The earlier export dropped pairs whose truth vertex was not an exported TruthVertices row, without counting them; the truth tables also keep every truth vertex that a vertex map matches (keepVerticesMatchedBy), so no vertex link is dropped. |
X | earlier export: offlinePrimaryVertices{To,From}Truth, inclusiveSecondaryVertices{To,From}Truth, joined to TruthVertices.graphIndex; truth tables: OfflinePrimaryVerticesToTruth, TruthToOfflinePrimaryVertices, and the same for InclusiveSecondaryVertices (written by ember_cfg.py when the associators run in the job); match hints with target interaction / decayVertex, measure pt2, and purity in physics.json |
medium |
| 15 | PF-cluster associator for HF and HO | A (CMSSW configuration) | truthGraphRecoLabelsPSet (truthGraphAssociationLabels_cff.py:37-54) has only pfClustersEcal/Hcal. Add pfClustersHF = particleFlowClusterHF, pfClustersHO = particleFlowClusterHO, and two module clones with denominatorDetectors=["Hcal"] and pfRecHits including particleFlowRecHitHF and particleFlowRecHitHO. The default list is ECAL + HBHE (AllRecoToTruthBranchAssociatorsProducer.cc:966); without the change, HF cells are weighted by simulated photoelectrons. |
medium |
| 16 | The muon channel is not keyed by cell | G | PSimHits are keyed by detUnitId only (LogicalGraphHitIndexProducer.cc:430-433): CSC layer, RPC roll, GEM partition (DT is per wire). Two particles in one CSC layer cannot be told apart per rechit. Ask for a cell key (strip or wire group, from the PSimHit entry and exit points), as the tracker channel has. The earlier export wrote muon-hit truth at the coarser unit (TruthMuonHits: every rechit of a unit gets the unit's energy; fact.unit names it). |
medium |
| 17 | Muon-segment association | A | no truth::recoHits for DTRecSegment4D, CSCSegment, GEMSegment (the sim-unit DetIds of their rechits), no traits, no muonSegments domain; metric SharedHits on the Muon channel; thresholds from MuonAssociatorByHits (purity 0.75, efficiency 0.5, Validation/RecoMuon/python/associators_cff.py:23-42) |
medium |
| 18 | Muon association (reco::Muon, standaloneMuons, globalMuons) | A + G | recoHits(reco::Track) keeps only TrackerSingleRecHit (PhysicsTools/TruthInfo/interface/RecoHitAdapters.h:46-90). So listing globalMuons in the tracks domain would match only its tracker stub (do not do this in Ember). Ask for a muon-hit adapter, a reco::Muon trait judged per stub (the tracker through the track map, the muon system through 17), and a graph level for "muon reaching the muon system" (the graph has only checkpoint 0, tracker → calorimeter; ParticleData.h:130-131). |
medium |
| 19 | MTD-cluster and track-time association; MTD truth for particles outside CaloBoundary subgraphs | A + X | The MTD channel is filled with cells and times (LogicalGraphHitIndexProducer.cc:436-471), but nothing in CMSSW uses it. Ask for recoHits(FTLCluster) → (module, cell), an mtdClusters domain, and the matched particle's simulated time at MTD for track-time validation. The truth tables would need a direct-hit mode and keepWithHits (40% of the MTD cells at 200 pile-up are outside CaloBoundary subgraphs, measured). ember_cfg.py writes the MTD rechits, RecHitBTL and RecHitETL (CMSSW branch nanoaod-mtd-rechits), keyed by DetId with row and column (an ETL DetId is the sensor's), without truth. The join on module and cell and a direct-hit mode are table-producer work. They would add about 0.4 MB and up to 17.5k particles per event at 200 pile-up. |
low |
| 20 | PF-candidate association | A | the producer's ConstituentBased strategy names it (AllRecoToTruthBranchAssociatorsProducer.cc:118-128); needs a reco::PFCandidate trait over the track map and the PF-cluster and TICL-candidate maps (target ReconstructableFinalState, bit 10) |
medium |
| 21 | Jet association and generator jets | G + A | no clustering of graph particles (StableDecayProducts ∩ isSignal ∩ visible) into a level or a product; then a constituent-based reco::PFJet trait over 20. Never GenJet. |
low |
| 22 | Truth MET | G | −ΣpT of the visible signal generator particles, as a graph product (neutrinos are in the graph, GEN-only status 1). Never GenMET. | low |
| 23 | e/γ association | A | GsfElectron and Photon traits (supercluster clusters + GSF track); a reco::GsfTrack trait that reuses the track adapter (GsfTrack derives from reco::Track; electronGsfTracks is in step3); SuperCluster and CaloCluster not covered (gap 1) |
low |
| 24 | τ association | A | a reco::PFTau trait over the signal constituents; target TauVisibleHadronic (bit 11, exists; 0.2 per event without pile-up) |
low |
| 25 | HF rechit energy without simulated energy without pile-up; ECAL barrel rechits between 0.5 and 1 GeV without simulated energy | open (not yet a gap) | HF: 20–50% of the HF rechit energy above 0.5 GeV in events without pile-up has no simulated hit in its cell, although the index holds all the g4SimHits HF energy (measured, hfcheck.py). The cause is digitisation or noise. It is shown as "no truth"; check with an HF expert before the viewer calls it noise. ECAL barrel, without pile-up: half of the rechits above 0.5 GeV have no simulated energy (0.5–1.1 GeV, median 0.55, times −34 to +16 ns); every rechit above 1 GeV has some. Only 52% of the ECAL PF clusters above 0.5 GeV have a truth match, and 98% above 1 GeV. This is likely noise, to be confirmed with ECAL experts. The calo and pf profiles cut EB hits and PF clusters at 1 GeV by default. |
— |
1. Layer clusters¶
- Graph: it has everything needed. A layer cluster is a list of (DetId, fraction), and the hit index has the simulated energy per particle per DetId.
- Associator: the hit adapter already exists,
truth::recoHits(reco::CaloCluster const&)(PhysicsTools/TruthInfo/interface/RecoHitAdapters.h:106-117).reco::PFClusteruses it through its base class. What is missing: the traits specialisation forreco::CaloCluster, aDEFINE_FWK_MODULEalias, alayerClusters=cms.vstring("hgcalMergeLayerClusters")domain, and a module in the sequence. Checked both in the local area and in the release (CMSSW_20_1_X_2026-11-17-2300): there is noLayerClusterdomain anywhere inSimGeneral/TruthGraphAssociatorProducersorValidation/TruthInfoof the release. - In Ember today: layer clusters have no truth of their own: the inspector and the Truth tab say so (gap 1), and the truth colours leave them neutral. Their hits carry the simulated energy per particle (facts), and the card's fact line on the hits' step lists the particles in them. The pair view draws a matched trackster's layer clusters as part of the match, with no truth statement of their own.
- Check: a producer alias such as
TruthBranchLayerClusterAssociatorsProducerappears (or alayerClusterskey intruthGraphRecoLabelsPSet), and the step3 file has*_truthBranchLayerClusterAssociators_*. The truth tables then need the layer-cluster maps in their configuration, and Ember needs one reco → truth and truth → reco relation pair fromHGCalLayerClusters. The existingsameRowsredirect moves it ontoHGCalSoALayerClusters.
2. Hits are exported at a different level from the matches¶
TruthHitTable gives hits only to exported particles with the CaloBoundary bit, that is, particles that crossed the
boundary between tracker and calorimeter outwards (TruthLevels.h:411-414). Each of these particles gets the hits of
its whole subgraph. But the associator may match a reco object to a particle below that level (a secondary made
inside the calorimeter), or above it (a π⁰, whose photons are not exported unless they are matched themselves).
Measured at 200 pile-up, ttbar: 284 of the 1852 distinct CLUEstering match targets (event 0), and 179 of 1219 (event 1), lack CaloBoundary. They are mostly γ and e±, and a few π⁰. 283 and 179 of them have no exported hit anywhere in their own subgraph. For interpretations: 373 of 2153. For candidates: 221 of 1284. Gun, without pile-up: 2 of 6 CLUEstering targets in event 1 (two photons).
The consequence: the trackster's best particle is not the particle that its hits are attributed to (the
CaloBoundary ancestor). The ancestor's hits are still drawn, because keepAncestors exports it. Ember works around
matches below CaloBoundary: a particle takes the colour of its generator particle (see above). A match above it
(for example a π⁰, whose photons own the hits) is shown as an object that merges the generator particles below it
(Truth).
Check: TruthGraphHitFlatTableProducer gets a mode that exports hits for every exported particle with its own
(non-inclusive) direct hits, or for the association targets themselves. Today the only setting is levelMask.
3–5. Unattributed energy¶
Measured.
- Gun without pile-up, CE-E: 99.5–100% of the hit energy above 35 MeV has a truth particle.
- Gun without pile-up, CE-H silicon: 18–78%. The hits without truth are spread over both endcaps (η from −2.8 to +2.8, the first CE-H layers), so they are noise.
- ttbar at 200 pile-up, event 0: CE-E 42% (53k of 157k hits), CE-H silicon 34%, CE-H scintillator 73%. 85k of the 140k SoA layer clusters have no hit with truth. 7741 particles are exported (2156 signal); 2683 of them own CE-E hits (122 signal).
Checked against the full graph. On the step3 file of ttbar at 200 pile-up, with FWLite, for every RECO rechit above 35 MeV: does any particle of the graph have simulated energy in its cell?
- In-time pile-up: 94–96% of the CE-E energy, and 84–93% of the CE-H silicon energy.
- Signal: 1–2%.
- No particle of the graph: 2–5% (CE-E) and 6–15% (CE-H silicon).
The graph holds 120–174k pile-up particles per event, and the export kept about 8k. So the sample is complete for in-time pile-up, and the loss came from the export's selection (gap 4). The rest is noise (gun without pile-up: about 250 CE-H silicon hits per event at E/σ ≈ 3, with no time), and, most likely, out-of-time pile-up (gap 5; about 7k such hits per event at 200 pile-up, far above the noise).
Gap 4 is addressed in the truth tables, as it was in the earlier export. TruthGraphFlatTableProducer has
keepLevelMask; the configuration's truthGraphCaloBoundaryTable sets it to CaloBoundary, so every particle that
enters the calorimeter is exported with its hits, pile-up included. For ttbar at 200 pile-up, measured with the
earlier export:
- 82–136k particles per event (ancestors included), instead of 7.7k;
- hit energy with a particle: 95–98% (CE-E) and 85–91% (CE-H silicon), as much as the full graph allows;
- NanoAOD 1.79 GB instead of 1.16 GB, and bundle 1.56 GB instead of 0.96 GB (+62%).
The export still cannot tell noise from out-of-time pile-up (gap 3). The total simulated energy per cell is computed
inside the associator (BranchHitAssociator.h:187-188, cellTotalEnergy), but never written out.
Check: a simEnergyTotal (or hasSim) column on the hit tables, or a TruthHitTable row for "all other
particles".
Per-hit simulated energy: what it is, exactly¶
- It is per (exported CaloBoundary particle, hit), summed over the particle's subgraph (the hit table's
simEnergy). It is thePCaloHitdeposited energy: sampling energy, not calibrated. Only ratios between particles are meaningful, not a comparison with the rechit energy. - It is not for all particles: only for exported particles (signal, matched, and their ancestors) that also have CaloBoundary.
- Overlap: a hit can have several owners. Measured: up to 4 owners at 200 pile-up, and 20 hits with several
owners in a gun event. The owners are always separate branches. Every level is an antichain:
fillLevelFlagskeeps the earliest member of each chain (PhysicsTools/TruthInfo/interface/TruthLevels.h:688-795), so no CaloBoundary particle is an ancestor of another. Hits with several owners are overlapping showers. - Pile-up: in-time pile-up particles appear only when they are matched, or as ancestors of matched particles.
isSignalseparates them. Out-of-time pile-up is absent by default (gap 5), and thehgcalprofile drops it where it is present.
6–11. Smaller gaps, briefly¶
- 6: fixed. The truth tables read the label registry instead of a hard-coded list of v6 labels,
so a TICL v5 / CLUE3D sample gets its
ticlTrackstersCLUE3DHigh*Truthtables. - 7: with the earlier development branch's candidate associator, measured at 200 pile-up: 1307 of 1910 candidates had a match (the others included track-only candidates). The current release has none: the card shows the candidate's trackster's match and its track's, each named as theirs.
- 8: Ember's reco → truth relations have at most one entry per object (measured: the number of entries equals the
number of matched objects in every relation). "Several truth matches" exists only in the truth → reco direction
(
FromTruth). - 9, 11: the associators and the data exist; only the export is missing.
- 10:
sameRowsdrops the legacy table, and raises an error if SoA and legacy ever differ (_check_same_rowsinembertools/converter.py). The truth for SoA tracksters is then lost unless the entry is removed. A direct SoA associator (TruthAssociationTraitson the SoA view) would remove this dependency.
Covered only by legacy simulation objects today¶
Layer cluster ↔ truth (gap 1) and runner-up particles per object (gap 8, partly) exist today only in the
SimCluster/CaloParticle associations of HGCalNanoAOD
(DPGAnalysis/HGCalNanoAOD/python/hgcalTracksters_cfi.py:166,183). The hgcal.json profile excludes them
("exclude": ["Sim*", "Reco*2Sim*", "ticlSim*", ...]), and should keep doing so.
Track association weights are hit counts¶
The track associator (AllRecoToTruthBranchAssociatorsProducer.cc:858-877) works with hits. Its payload is a number
of shared hits, and its score is 1 − shared hits / track hits (measured: exact for every track of the sample
without pile-up).
The earlier export wrote the count under the calorimeter names (generalTracksToTruth.sharedEnergy,
generalTracksFromTruth.sharedFraction, integers from 1 to 33). The viewer calls them "shared hits", from the
relations' match.measure. The truth tables name the column after the metric: nSharedHits.
The maps have no threshold. CMS tracking validation calls a track with less than 75% shared hits a fake (measured at 200 pile-up: 11% of the matched tracks are below 75%). This is why the truth mode colours a track by its particle only from 75%.
Check: done in the truth tables (nSharedHits).
What the bundles carry for truth, and what the viewer does not use¶
Measured on bundles of the earlier export (zlib, per event; 50 events without pile-up, events 0–2 at 200 pile-up, in-time cut applied): truth is 0.41 of 1.58 MB without pile-up (26%), and 13.6 of 31.0 MB at 200 pile-up (44%). At 200 pile-up: particles 5.2 MB (102k rows), truth hit relations 4.3 MB, TruthToReco 2.6 MB, vertices 1.0 MB.
What no profile, converter or viewer code uses, at 200 pile-up (the inspector lists every column, so nothing is invisible):
| what | MB / event | note |
|---|---|---|
TruthParticles pt, eta, phi, mass, t |
1.5 | can be derived from the momentum and the vertex |
TruthParticles x, y, z |
0.56 | the production vertex's position (used for drawing; could be read through truthProdVertex) |
legacy truth hits (TruthHGCalHits) |
2.1 | duplicate the SoA truth hits where SoA exists: no longer written there (one source per kind) |
TruthToReco entries with sharedFraction < 0.1 |
≈ 1.6 (62% of 2.6) | 56 particles per interpretation trackster |
| particles with neither HGCal hits nor matches | ≈ 3.5 (estimate) | 73k of 108k rows: CaloBoundary particles in the barrel and forward regions, kept for barrel truth hits that are not exported yet |
Only the legacy truth hits are dropped (where SoA hits exist). Each of the others is a choice to make when the bundle is split into parts. The leaner direction is to export what the truth display needs (per-particle direct hits, a total simulated energy per hit, barrel hits), and to drop what it does not need.
What to watch for in CMSSW¶
grep -n "reco::CaloCluster>" SimGeneral/TruthGraphAssociatorProducers/plugins/*.ccfinds a traits specialisation, andtruthGraphRecoLabelsPSethas a layer-cluster domain (gap 1).TruthGraphHitFlatTableProducerhas a mode that is not limited to CaloBoundary, or a column with the total simulated energy per hit (gaps 2, 3).keepMatchedByincludes tracks, or there is an option "keep every particle with HGCal hits above E" (gap 4).pileupBunchCrossingsis widened, or there is an out-of-time summary per hit (gap 5).- Done: the truth tables read their list of labels from
truthGraphAssociationLabels_cff(gap 6).