Warning, /EICrecon/src/detectors/DRICH/README.md is written in an unsupported language. File is not indexed.
0001 # dRICH
0002
0003 ## Algorithms and Data Flowchart
0004
0005 The following is a flowchart of algorithms and collections corresponding to **P**article **Id**entification (PID)
0006 from the **D**ual **R**ing **I**maging **Ch**erenkov (dRICH) detector.
0007
0008 ### Legend
0009 ```mermaid
0010 flowchart TB
0011 classDef alg fill:#ff8888,color:black
0012 classDef col fill:#00aaaa,color:black
0013 Algorithm[<strong>Algorithm Description</strong><br/>Algorithm Name<br/><i>Factory Name</i>]:::alg
0014 InputCollection(<strong>Input Collection Name</strong><br/>Input Collection Datatype):::col
0015 OutputCollection(<strong>Output Collection Name</strong><br/>Output Collection Datatype):::col
0016 InputCollection ==> Algorithm ==> OutputCollection
0017 ```
0018
0019 ### Flowchart
0020 ```mermaid
0021 flowchart TB
0022 classDef alg fill:#ff8888,color:black
0023 classDef col fill:#00aaaa,color:black
0024 classDef misc fill:#ff88ff,color:black
0025
0026 %%-----------------
0027 %% Nodes
0028 %%-----------------
0029
0030 subgraph Inputs
0031 direction LR
0032 SimHits(<strong>DRICHHits</strong><br/>MC dRICH photon hits<br/>edm4hep::SimTrackerHit):::col
0033 Trajectories(<strong>CentralCKFActsTrajectories</strong><br/>ActsExamples::Trajectories):::col
0034 MCParts(<strong>MCParticles</strong><br/>MC True Particles<br/>edm4hep::MCParticles):::col
0035 end
0036
0037 subgraph Digitization
0038 DigiAlg[<strong>Digitization</strong><br/>PhotoMultiplierHitDigi<br/><i>PhotoMultiplierHitDigi_factory</i>]:::alg
0039 RawHits(<strong>DRICHRawHits</strong><br/>includes noise<br/>edm4eic::RawTrackerHit):::col
0040 HitAssocs(<strong>DRICHRawHitsAssociations</strong><br/>no noise<br/>edm4eic::MCRecoTrackerHitAssociation):::col
0041 end
0042
0043 subgraph Charged Particles and Tracking
0044 PropagatorAlg[<strong>Track Projection</strong><br/>TrackPropagation<br/><i>RichTrack_factory</i>]:::alg
0045 subgraph rad1 [radiators]
0046 AerogelTracks(<strong>DRICHAerogelTracks</strong><br/>edm4eic::TrackSegment):::col
0047 GasTracks(<strong>DRICHGasTracks</strong><br/>edm4eic::TrackSegment):::col
0048 end
0049 MergeTracksAlg[<strong>Merge Tracks</strong><br/>MergeTrackSegments<br/><i>MergeTrack_factory</i>]:::alg
0050 MergedTracks(<strong>DRICHMergedTracks</strong><br/>edm4eic::TrackSegment):::col
0051
0052 %%MirrorTracks(<strong>DRICHMirrorTracks - TODO</strong><br/>edm4eic::TrackSegment):::col
0053 %%ReflectionsAlg[<strong>Track Reflections - TODO</strong><br/>RichTrackReflection<br/><i>RichTrackReflection_factory</i>]:::alg
0054 %%Reflections(<strong>DRICHTrackReflections - TODO</strong><br/>edm4eic::TrackSegment):::col
0055
0056 TrackingAlgos[(<strong>Tracking Algorithms</strong>)]:::alg
0057 TrackParameters(<strong>outputTrackParameters</strong><br/>edm4eic::TrackParameters):::col
0058 end
0059
0060 PIDInputs{{<strong>PID Algorithm Inputs</strong>}}:::misc
0061
0062 subgraph Particle Identification Algorithms
0063 IRT[<strong>IRT: Indirect Ray Tracing</strong><br/>IrtCherenkovParticleID<br/><i>IrtCherenkovParticleID_factory</i>]:::alg
0064 subgraph rad2 [radiators]
0065 IRTPIDAerogel(<strong>DRICHAerogelIrtCherenkovParticleID</strong><br/>edm4eic::CherenkovParticleID):::col
0066 IRTPIDGas(<strong>DRICHGasIrtCherenkovParticleID</strong><br/>edm4eic::CherenkovParticleID):::col
0067 end
0068
0069 AlternatePIDAlgo[<strong>Alternate PID Algorithm</strong><br/>TODO]:::alg
0070 AlternatePID(<strong>Alternate PID Output Collection<br/>TODO</strong><br/>edm4eic::CherenkovParticleID):::col
0071
0072 MergePID[<strong>Combine PID from radiators</strong><br/>MergeParticleID<br/><i>MergeCherenkovParticleID_factory</i>]:::alg
0073 IRTPIDMerged(<strong>DRICHIrtMergedCherenkovParticleID</strong><br/>edm4eic::CherenkovParticleID):::col
0074 end
0075
0076 PIDOutputs{{<strong>PID Algorithm Outputs</strong>}}:::misc
0077
0078 subgraph Particle Identification Linking
0079 ProxMatch[<strong>Proximity Matching</strong><br/>ParticlesWithPID<br/><i>ParticlesWithPID_factory</i>]:::alg
0080
0081 ReconParts(<strong>ReconstructedChargedParticles</strong><br/>edm4eic::ReconstructedParticle):::col
0082 ReconAssocs(<strong>ReconstructedChargedParticleAssociations</strong><br/>edm4eic::MCRecoParticleAssociation):::col
0083 ReconPIDs(<strong>ReconstructedChargedParticleIDs</strong><br/>edm4hep::ParticleID):::col
0084 end
0085
0086
0087 %%-----------------
0088 %% Edges
0089 %%-----------------
0090
0091 %% digitization
0092 SimHits ==> DigiAlg
0093 DigiAlg ==> RawHits
0094 DigiAlg ==> HitAssocs
0095 %%SimHits -.association.- HitAssocs
0096 %%SimHits -.association.- MCParts
0097
0098 %% tracking
0099 Trajectories ==> PropagatorAlg
0100 PropagatorAlg ==> AerogelTracks ==> MergeTracksAlg
0101 PropagatorAlg ==> GasTracks ==> MergeTracksAlg
0102 MergeTracksAlg ==> MergedTracks
0103
0104 %% track reflections
0105 %% PropagatorAlg ==> MirrorTracks
0106 %% MirrorTracks ==> ReflectionsAlg
0107 %% ReflectionsAlg ==> Reflections
0108 %% Reflections ==> PIDInputs
0109
0110 %% PID
0111 RawHits ==> PIDInputs
0112 HitAssocs ==> PIDInputs
0113 AerogelTracks ==> PIDInputs
0114 GasTracks ==> PIDInputs
0115 MergedTracks ==> PIDInputs
0116 PIDInputs ==> IRT
0117 IRT ==> IRTPIDAerogel ==> MergePID
0118 IRT ==> IRTPIDGas ==> MergePID
0119 MergePID ==> IRTPIDMerged ==> PIDOutputs
0120 PIDInputs ==> AlternatePIDAlgo ==> AlternatePID ==> PIDOutputs
0121
0122 %% linking
0123 Trajectories ==> TrackingAlgos ==> TrackParameters
0124 PIDOutputs ==> ProxMatch
0125 TrackParameters ==> ProxMatch
0126 MCParts ==> ProxMatch
0127 ProxMatch ===> ReconParts
0128 ProxMatch ==> ReconPIDs
0129 ProxMatch ==> ReconAssocs
0130 ReconParts -.1 to N.-> ReconPIDs
0131 %%ReconAssocs -.association.- MCParts
0132 ```
0133
0134 ## Data Model
0135
0136 ### Digitized Hits
0137 - All digitized hits, including noise hits, are stored as `edm4eic::RawTrackerHit` collections
0138 - Association `edm4eic::MCRecoTrackerHitAssociation` stores the 1-N link from a digitized hit to the MC truth hits
0139 - each MC truth hit has a 1-1 relation to the original MC `opticalphoton` (or whatever particle caused the hit)
0140 - digitized noise hits will not have associated MC truth hits, and therefore do not appear in `edm4eic::MCRecoTrackerHitAssociation` collections
0141 ```mermaid
0142 flowchart TB
0143 classDef col fill:#00aaaa,color:black
0144 classDef fn fill:#c3b091,color:black
0145
0146 %% nodes
0147 Association(<strong>DRICHRawHitsAssociation</strong><br/>edm4eic::MCRecoTrackerHitAssociation):::col
0148 RawHitFn[rawHit]:::fn
0149 subgraph Digitized
0150 RawHit(edm4eic::RawTrackerHit):::col
0151 end
0152 SimHitsFn[simHits]:::fn
0153 subgraph Simulated MC Truth
0154 direction TB
0155 SimHit1(edm4hep::SimTrackerHit):::col
0156 SimHit2(edm4hep::SimTrackerHit):::col
0157 SimHit3(... additional MC hits and corresponding photons ...):::col
0158 MCParticleFn1[MCParticle]:::fn
0159 MCParticleFn2[MCParticle]:::fn
0160 Photon1(edm4hep::MCParticle):::col
0161 Photon2(edm4hep::MCParticle):::col
0162 end
0163
0164 %% edges
0165 Association ==> RawHitFn ==> RawHit
0166 Association ==> SimHitsFn
0167 SimHitsFn ==> SimHit1 ==> MCParticleFn1 ==> Photon1
0168 SimHitsFn ==> SimHit2 ==> MCParticleFn2 ==> Photon2
0169 SimHitsFn ==> SimHit3
0170 ```
0171
0172 ### Expert-level PID Output
0173 - RICH-specific particle ID datatype `edm4eic::CherenkovParticleID`
0174 - From IRT: aerogel and gas results separated
0175 - Vector member of `edm4eic::CherenkovParticleIDHypothesis` components, one for each PID hypothesis, with members:
0176 - PDG
0177 - NPE
0178 - weight
0179 - Additional members:
0180 - Reconstructed Cherenkov (theta, phi) for each photon
0181 - NPE
0182 - MC: average photon energy and refractive index at emission point
0183 - Link to charged particle and hit-associations
0184 - 1-1 relation to corresponding charged particle `edm4eic::TrackSegment`
0185 - points to the _same_ `DRICHMergedTrack`, to facilitate merging aerogel and gas PID results
0186
0187 ```mermaid
0188 flowchart TB
0189 classDef col fill:#00aaaa,color:black
0190 classDef fn fill:#c3b091,color:black
0191 classDef comp fill:#8888ff,color:black
0192
0193 %% nodes
0194 CPIDAgl(<strong>DRICHAerogelIrtCherenkovParticleID</strong><br/>edm4eic::CherenkovParticleID):::col
0195 CPIDGas(<strong>DRICHGasIrtCherenkovParticleID</strong><br/>edm4eic::CherenkovParticleID):::col
0196 HypAglFn[hypotheses]:::fn
0197 HypGasFn[hypotheses]:::fn
0198
0199 subgraph <strong>hypotheses from aerogel</strong>
0200 direction TB
0201 HypAgl0([Electron]):::comp
0202 HypAgl1([Pion]):::comp
0203 HypAgl2([Kaon]):::comp
0204 HypAgl3([Proton]):::comp
0205 end
0206 subgraph <strong>hypotheses from gas</strong>
0207 direction TB
0208 HypGas0([Electron]):::comp
0209 HypGas1([Pion]):::comp
0210 HypGas2([Kaon]):::comp
0211 HypGas3([Proton]):::comp
0212 end
0213
0214 TrackAglFn[chargedParticle]:::fn
0215 TrackGasFn[chargedParticle]:::fn
0216 Track(<strong>DRICHMergedTracks</strong><br/>edm4eic::TrackSegment):::col
0217
0218 %% edges
0219 CPIDAgl ==> HypAglFn
0220 HypAglFn ==> HypAgl0
0221 HypAglFn ==> HypAgl1
0222 HypAglFn ==> HypAgl2
0223 HypAglFn ==> HypAgl3
0224 CPIDAgl ==> TrackAglFn ==> Track
0225 CPIDGas ==> HypGasFn
0226 HypGasFn ==> HypGas0
0227 HypGasFn ==> HypGas1
0228 HypGasFn ==> HypGas2
0229 HypGasFn ==> HypGas3
0230 CPIDGas ==> TrackGasFn ==> Track
0231 ```
0232
0233 ### User-level PID Output
0234 - Add `edm4hep::ParticleID` objects to `ReconstructedParticle`
0235 - `edm4hep::ParticleID` objects include a likelihood, PDG (and some index variables and `float` parameters for full generality)
0236 - Use 1-1 relation `ReconstructedParticle::particleIDUsed` to specify the most-likely `edm4hep::ParticleID` object;
0237 the diagram below exemplifies this for a pion
0238 - Use 1-N relation `ReconstructedParticle::particleIDs` to link all the `edm4hep::ParticleID` objects
0239 - User can then access PDG via:
0240 ```cpp
0241 ReconstructedParticleAssociation.getRec().getParticleIDUsed().getPDG(); // most likely PDG from PID
0242 ReconstructedParticleAssociation.getSim().getPDG(); // true PDG
0243 ```
0244 ```mermaid
0245 flowchart TB
0246 classDef col fill:#00aaaa,color:black
0247 classDef fn fill:#c3b091,color:black
0248 classDef comp fill:#8888ff,color:black
0249
0250 %% nodes
0251 ReconPart(<strong>ReconstructedChargedParticles</strong><br/>edm4eic::ReconstructedParticle):::col
0252 ReconAssoc(<strong>ReconstructedChargedParticleAssociations</strong><br/>edm4eic::MCRecoParticleAssociation):::col
0253 MCPart(<strong>MCParticles</strong><br/>MC True Particles<br/>edm4hep::MCParticles):::col
0254 RecFn[rec]:::fn
0255 SimFn[sim]:::fn
0256
0257 PDGReconFn[PDG]:::fn
0258 PDGMCFn[PDG]:::fn
0259
0260 PDGTrue([True PDG]):::comp
0261
0262 ParticleIDsFn[particleIDs]:::fn
0263 ParticleIDUsedFn[particleIDUsed]:::fn
0264
0265 subgraph <strong>Particle ID Objects</strong>
0266 direction LR
0267 Hyp0(edm4hep::ParticleID):::col ==> Pdg0Fn[PDG]:::fn ==> Pdg0([Electron]):::comp
0268 Hyp1(edm4hep::ParticleID):::col ==> Pdg1Fn[PDG]:::fn ==> Pdg1([Pion]):::comp
0269 Hyp2(edm4hep::ParticleID):::col ==> Pdg2Fn[PDG]:::fn ==> Pdg2([Kaon]):::comp
0270 Hyp3(edm4hep::ParticleID):::col ==> Pdg3Fn[PDG]:::fn ==> Pdg3([Proton]):::comp
0271 end
0272
0273 %% edges
0274 ReconAssoc ==> RecFn ==> ReconPart
0275 ReconAssoc ==> SimFn ==> MCPart
0276 ReconPart ==>|TO BE REMOVED| PDGReconFn ==> PDGTrue
0277 MCPart ==> PDGMCFn ==> PDGTrue
0278
0279 ReconPart ==> ParticleIDUsedFn ==> Hyp1
0280 ReconPart ==> ParticleIDsFn
0281
0282 ParticleIDsFn ==> Hyp0
0283 ParticleIDsFn ==> Hyp1
0284 ParticleIDsFn ==> Hyp2
0285 ParticleIDsFn ==> Hyp3
0286 ```
