PID/hpDIRC/README.md

0001 # Instructions for ePIC hpDIRC simulation and reconstruction
0002
0003 Please follow the [tutorial](https://eic.github.io/tutorial-setting-up-environment/02-eic-shell/index.html) on setting up the EIC environment first.
0004 The following assumes you're running in ```eic-shell```.
0005
0006 ## Detector geometry
0007
0008 The hpDIRC detector geometry is based on [DD4hep](https://github.com/AIDASoft/DD4hep). The following repository is a fork of [eic/epic](https://github.com/eic/epic) and has a branch that contains a version of hpDIRC geometry and all the material properties required for Cherenkov photon propagation. Get a copy of it using:
0009 ```bash
0010 git clone https://github.com/niwgit/epic.git
0011 cd epic
0012 git checkout box_envelope
0013 ```
0014 ## Compilation
0015 The following commands build and install the geometry to the ```install``` directory (can be replaced by any directory path).
0016 ```bash
0017 cmake -B build -S . -DCMAKE_INSTALL_PREFIX=install
0018 cmake --build build
0019 cmake --install build
0020 ```
0021 Load the geometry using
0022 ```bash
0023 source install/setup.sh
0024 ```
0025 ## Modifying detector geometry parameters
0026 The source code of hpDIRC geometry is located in ```src/DIRC_geo.cpp```. The parameters used in that file are defined in the compact file ```compact/pid/dirc.xml```. The wavelength-dependent properties such as refractive index and absorption length of the materials are defined in ```compact/optical_materials.xml```.
0027
0028 Use the following command to see a list of compact files with detector geometry configurations. The file ```epic_dirc_only.xml``` is used to include only the hpDIRC detector in the simulation.
0029 ```bash
0030 ls $DETECTOR_PATH
0031 ```
0032 ```${DETECTOR_PATH}/compact/pid/dirc.xml``` can be used to modify the parameters defining the hpDIRC geometry. For example, change the parameter ```DIRCBox_count``` to 1 to use only 1 bar box (default is 12 bar boxes).
0033
0034 ## Viewing the geometry
0035 ```bash
0036 dd_web_display --export $DETECTOR_PATH/epic_dirc_only.xml
0037 ```
0038 The above command creates an output ROOT file called ```detector_geometry.root```. Use [jsroot](https://root.cern/js/) to open the ROOT file and view the geometry.
0039
0040 ## Simulation
0041 Geant4 simulations with DD4hep are done via ```npsim```. For simulating events with one charged particle per event as the primary particle, we use a particle gun with ``-G`` flag. The number of events is specified with the ```-N``` flag. The paticle gun has options to set the momentum, vertex position and polar and azimuthal angles of the charged particle.
0042
0043 The following example is for running 100 events with 6 GeV/c pi+ track of polar angle 30 deg and azimuthal angle 355.334 deg. The azimuthal angle was selected such that the charged particle hits the center of one of the middle bars in the bar box when the magnetic field is included.
0044 ```bash
0045 npsim --runType batch --compactFile $DETECTOR_PATH/epic_dirc_only.xml -G -N 100  --gun.particle "pi+" --gun.momentumMin 6*GeV --gun.momentumMax 6*GeV --gun.phiMin 355.334*deg --gun.phiMax 355.334*deg --gun.thetaMin 30*deg --gun.thetaMax 30*deg --gun.distribution uniform --gun.position 0*cm,0*cm,0*cm --part.userParticleHandler='' --outputFile sim.edm4hep.root
0046 ```
0047 This will create an output ROOT file called ```sim.edm4hep.root```. The file name can be modified but it should contain the extension ```.edm4hep.root```. This file will contain all the hits on the DIRC sensitive detector (MCP plane) as ```DIRCBarHits```.  These are ```SimTrackerHit``` objects that are defined in the [EDM4hep](https://github.com/key4hep/EDM4hep/blob/main/edm4hep.yaml#L227) data model. The truth information of each particle simulated is saved in [MCParticle](https://github.com/key4hep/EDM4hep/blob/main/edm4hep.yaml#L158) objects. The primary particle can be selected using ```MCParticles.generatorStatus==1```.
0048
0049 To see the event display use ```--runType vis``` with a visualization macro file (e.g. ```--macroFile myvis.mac```) and ```--enableGun``` or ```-G``` option. Then in the Geant4 interactive mode run the event with ```/run/beamOn 1```.
0050 ![alt text](https://github.com/eic/snippets/blob/main/PID/hpDIRC/pic/event_display_myvis_box_envelope.png)
0051
0052 ## Applying quantum efficiency (QE) of sensors
0053 Currently, the ```npsim``` output file contains information on all the optical photons that hit the MCP plane. So the number of hits per event (track) can be high as 800-1000. But in reality, the detected number of photons will be much lower (50-150) due to the photon detection efficiency of the sensors. This efficiency is wavelength-dependent and ideally should be applied during the simulation to avoid tracking optical photons that are not detected. But at the moment these efficiencies are applied with the algorithm [PhotoMultiplierHitDigi](https://github.com/eic/EICrecon/blob/main/src/algorithms/digi/PhotoMultiplierHitDigi.cc) of ```eicrecon```. The configuration parameters of this algorithm for hpDIRC is set using https://github.com/eic/EICrecon/blob/main/src/detectors/DIRC/DIRC.cc and the quantum efficiencies for sensors are included in ```eicrecon``` with the default plugin ```DIRC```. This plugin creates collections ```DIRCRawHits``` and ```DIRCRawHitsAssociations```.
0054
0055 ## Using plugins with eicrecon
0056
0057  First you'll need to clone the repository EICrecon and follow the build instructions.
0058 ```bash
0059 git clone https://github.com/eic/EICrecon.git
0060 cd EICrecon
0061 cmake -B build -S . -DCMAKE_INSTALL_PREFIX=install
0062 cmake --build build
0063 cmake --install build
0064 ```
0065
0066 After that source the EICrecon environment.
0067 ```bash
0068 source install/bin/eicrecon-this.sh
0069 ```
0070
0071 Instructions on creating a plugin to make custom histograms/trees are given in the tutorial https://eic.github.io/tutorial-jana2/03-end-user-plugin/index.html. As an example,
0072 ```bash
0073 eicmkplugin.py  hpDIRCrawHits
0074 ```
0075
0076 For the hpDIRC, we use two plugins (https://github.com/eic/snippets/tree/main/PID/hpDIRC/plugins) with ```eicrecon```.
0077 - ```hpDIRCsimHits``` : This plugin is used to create histograms using simulated hits before applying sensor QE. For example, we can look at the wavelength distribution of Cherenkov photons.
0078 - ```hpDIRCrawHits``` : This plugin uses hits after applying QE. Additionally, it removes the hits that are in gaps between MCPs. The main purpose of this plugin is to save information such as the number of hits per event, time, mcp id and pixel id of each hit in a TTree called ```dirctree```.
0079
0080 The following shows how to build the plugin ```hpDIRCrawHits``` that will be installed in the directory ```EICrecon_MY```. The ```$EICrecon_MY$``` environment variable should be set to that directory so that when ```eicrecon``` runs the plugin will be identified. This assumes the files ```hpDIRCrawHitsProcessor.h```, ```hpDIRCrawHitsProcessor.cc``` and ```CMakelists.txt``` are within the source directory ```hpDIRCrawHits```.
0081 ```bash
0082 mkdir EICrecon_MY
0083 export EICrecon_MY=${PWD}/EICrecon_MY
0084 cmake -S hpDIRCrawHits -B hpDIRCrawHits/build
0085 cmake --build hpDIRCrawHits/build --target install
0086 ```
0087 To run the plugins with ```eicrecon``` over the simulation file ```sim.edm4hep.root``` which was created earlier using ```npsim``` do:
0088 ```bash
0089 eicrecon -Pplugins=hpDIRCsimHits,hpDIRCrawHits -Ppodio:output_collections=DIRCRawHits,DIRCRawHitsAssociations sim.edm4hep.root
0090 ```
0091 This will create two output files ```eicrecon.root``` and ```podio_output.root```. The file ```eicrecon.root``` should contain two directories ```hpDIRCsimHits``` and ```hpDIRCrawHits``` corresponding to the plugins we used. The histograms and trees defined in the plugins can be found in these directories. The ```dirctree``` in the ```hpDIRCrawHits``` directory will be used to obtain information required for the time imaging reconstruction.