Warning, /pfRICH/README.md is written in an unsupported language. File is not indexed.
0001 pfRICH
0002 ======
0003
0004 Standalone ePIC pfRICH GEANT4 simulation codes
0005
0006 Content:
0007
0008 * [Introduction](#introduction)
0009 * [Prerequisites and basic installation](#prerequisites-and-basic-installation)
0010 * [Pre-installed example](#pre-installed-example)
0011 * [Full installation](#full-installation)
0012 * [Example scripts](#example-scripts)
0013 * [Environment customization](#environment-customization)
0014
0015 Introduction
0016 ------------
0017
0018 These codes were originally written for the ATHENA EIC detector proposal proximity focusing
0019 Ring Imaging CHerenkov detector (pfRICH) in Fall
0020 2021. Later on they were adapted for a standalone simulation of ePIC pfRICH, as well as
0021 interfaced to the latest (2.0) version if [IRT libraries](https://github.com/eic/irt).
0022
0023 The codes contain a complete ePIC pfRICH detector geometry description, including its IRT-style
0024 optics representation as a sequence of refractive and reflective boundaries between photon
0025 emisson and detection points. A custom [GEANT stepping function](g4irt/source/CherenkovSteppingAction.cc)
0026 allows one to fully record history of Cherenkov photon creation and propagation through
0027 the optical media, as well as keeps track of the daughter-parent relashionships between
0028 charged particles and produced optical photons, association between emission vertices and
0029 particular Cherenkov light radiators, etc.
0030
0031 As of February 2024, the source code is split into four partss: one related to a
0032 [complete ePIC pfRICH detector](epic) simulation, one for a
0033 [pfRICH mockup](ftbf) simulation for the 2024 Fermilab beam test, one for a BNL HRPPD
0034 [test stand](tstand), and a part which is [common](share) for all three different geometries.
0035
0036 <br/>
0037
0038 Prerequisites and basic installation
0039 ------------------------------------
0040
0041 It is assumed that a user is familiar with ROOT and GEANT, as well as with the basic
0042 concepts of Monte-Carlo simulations, Cherenkov ring imaging detector design and event
0043 reconstruction goals, as well as the basic principles of Ring Imaging CHerenkov (RICH)
0044 particle identification (PID) techniques.
0045
0046 It is assumed that ROOT and GEANT are installed on a host PC, where the codes are supposed to be
0047 installed, as well as that *thisroot.sh* and *geant4.sh* were sourced already. GEANT is
0048 not needed to just import already produced ROOT trees.
0049
0050 In the following the installation under /tmp/sandbox is assumed. Define SANDBOX
0051 environment variable accordingly if installing in a different directory.
0052
0053 Make sure 'cmake' is version 3.0 or higher.
0054
0055 The following combination is known to work: SL7, gcc 4.8.5, cmake 3.22.1, ROOT 6.18.04,
0056 GEANT 4.10.05.p01 .
0057
0058
0059 ```
0060 #
0061 # Define installation area
0062 #
0063 export SANDBOX=/tmp/sandbox
0064 export LD_LIBRARY_PATH=${SANDBOX}/lib:${SANDBOX}/lib64:${LD_LIBRARY_PATH}
0065 ```
0066
0067 ```
0068 #
0069 # Install IRT library
0070 #
0071 cd ${SANDBOX}
0072
0073 git clone -b pfrich https://github.com/eic/irt.git
0074 cd irt && mkdir build && cd build
0075 cmake -DCMAKE_INSTALL_PREFIX=${SANDBOX} -Wno-dev ..
0076 make -j8 install
0077 ```
0078
0079 ```
0080 #
0081 # Download pfRICH repository
0082 #
0083 cd ${SANDBOX}
0084
0085 git clone https://github.com/alexander-kiselev/pfRICH.git
0086 ```
0087
0088 This is sufficient to import and analyze ROOT trees already produced after pfRICH
0089 GEANT simulation pass elsewhere (as long as there were no drastic changes to the
0090 C++ class variable description):
0091
0092 <br/>
0093
0094 Pre-installed example
0095 ---------------------
0096
0097 ```
0098 # TODO: NEED TO UPLOAD NEW ONES
0099 #cd ${SANDBOX}/pfRICH
0100 # A pre-uploaded file with 500 events;
0101 #root -l './examples/pfrich.C("examples/pfrich.root")'
0102 #root -l './examples/multi-eval.C("examples/pfrich.root")'
0103 ```
0104
0105 <br/>
0106
0107 Full installation
0108 -----------------
0109
0110 Installation of the actual GEANT simulation environment requires few more steps (make sure
0111 *geant.sh* was sourced!):
0112
0113
0114 ```
0115 #
0116 # Install Xerces; YES, DO THIS EVEN IF YOU HAVE A SYSTEM ONE INSTALLED ALREADY
0117 #
0118 cd ${SANDBOX}
0119
0120 # Copy over xerces-c-3.2.4.tar.gz (or a similar version) from the Web, unpack;
0121 cd xerces-c-3.2.4 && mkdir build && cd build
0122 cmake -DCMAKE_INSTALL_PREFIX=${SANDBOX} -Wno-dev ..
0123 make -j8 install
0124 ```
0125
0126
0127 ```
0128 #
0129 # Install BeastMagneticField (optional, only needed for a full ePIC pfRICH simulation);
0130 #
0131 cd ${SANDBOX}
0132
0133 git clone https://github.com/eic/BeastMagneticField.git
0134 cd BeastMagneticField && mkdir build && cd build
0135 cmake -DCMAKE_INSTALL_PREFIX=${SANDBOX} -Wno-dev ..
0136 make -j8 install
0137 ```
0138
0139
0140 ```
0141 #
0142 # Install HepMC3 (optional, only needed for a full ePIC pfRICH simulation);
0143 #
0144 cd ${SANDBOX}
0145
0146 git clone https://gitlab.cern.ch/hepmc/HepMC3.git
0147 cd HepMC3 && mkdir build && cd build
0148 cmake -DCMAKE_INSTALL_PREFIX=${SANDBOX} -DHEPMC3_ENABLE_ROOTIO=ON -DHEPMC3_ENABLE_PYTHON=OFF ..
0149 make -j8 install
0150 ```
0151
0152
0153 ```
0154 #
0155 # Install pfRICH simulation codes themselves
0156 #
0157 cd ${SANDBOX}/pfRICH
0158
0159 # Create links to the default header files;
0160 pushd share/include && ln -s hrppd.default.h hrppd.h && ln -s share.default.h share.h && popd
0161 pushd epic/include && ln -s epic.default.h epic.h && popd
0162 pushd ftbf/include && ln -s ftbf.default.h ftbf.h && popd
0163 pushd tstand/include && ln -s tstand.default.h tstand.h && popd
0164
0165 mkdir build && cd build
0166 # 'BMF' and 'HepMC3' are optional;
0167 cmake -DCMAKE_INSTALL_PREFIX=${SANDBOX} -DIRT=${SANDBOX} -DBMF=${SANDBOX} -DHEPMC3=${SANDBOX} -DXERCES=${SANDBOX} -Wno-dev ..
0168
0169 make -j8 install
0170 ```
0171
0172 Example scripts
0173 ---------------
0174
0175 ```
0176 #
0177 # A full ePIC pfRICH detector
0178 #
0179 cd ${SANDBOX}/pfRICH
0180 # FIXME: may need to click on "Useful tips", then on "viewer-0" in a Qt display;
0181 ./build/pfrich-epic -m macro/vis-epic.mac
0182 ```
0183
0184 A GEANT Qt display will appear with a picture similar to the image below. Use a green button
0185 in the Qt display controls to generate more events.
0186
0187 
0188
0189
0190 ```
0191 # Generate a file *pfrich-epic.root* with 1000 7 GeV/c pions at eta = -2.5
0192 ./build/pfrich-epic -o pfrich-epic.root -s 1000
0193
0194 # See a hit map in the sensor plane;
0195 root -l 'scripts/hit-map-epic.C("pfrich-epic.root")'
0196 ```
0197
0198 
0199
0200 Consider to uncomment *#define PRIMARY_PARTICLE_PHI* in [epic/include/epic.default.h](epic/include/epic.default.h),
0201 recompile and rerun both commands, in order to see a clear ring.
0202
0203 ```
0204 # Run IRT reconstruction;
0205 root -l 'scripts/reco-epic.C("pfrich-epic.root")'
0206 ```
0207
0208 
0209
0210 Top row of plots: reconstructed single photon Cherenkov angle distribution, its equivalent representation as a
0211 cumulative chi^2 distribution with one degree of freedom, track-level cumulative chi^2 distribution with N degrees
0212 of freedom (over N photons associated with a given track), event-level cumulative chi^2 distribution which is of
0213 course identical to the track-level one because there was only one track per events generated. *Cumulative chi^2
0214 distributions are expected to be reasonably uniform, otherwise something must be fundamentally wrong with the
0215 reconstruction procedure*.
0216
0217 Middle row of plots: Cherenkov photon hit count associated with a given track (should look like a
0218 Poissonian distribution), pion/kaon (mis)identification rate, the same plot, Cherenkov photon timing resolution
0219 (ignore).
0220
0221 Bottom row of plots: Track-level reconstructed Cherenkov angle distribution, wavelength distribution of detected
0222 photons (a convolution of several effects), empty panel, truth refractive index in aerogel for the detected photons.
0223
0224
0225 ```
0226 #
0227 # A Fermilab mockup of a pfRICH detector
0228 #
0229 ./build/pfrich-ftbf -m macro/vis-ftbf.mac
0230
0231 # Will take quite some time because of the optical photon tracing in the lens radiator;
0232 ./build/pfrich-ftbf -o pfrich-ftbf.root -s 1000
0233
0234 root -l 'scripts/hit-map-ftbf-1x1.C("pfrich-ftbf.root")'
0235 root -l 'scripts/hit-map-ftbf-2x2.C("pfrich-ftbf.root")'
0236
0237 # This one is also time consuming; comment "#define _ZCOORD_ASPHERIC_LENS_" in ftbf.default.h",
0238 # recompile and re-run ./build/pfrich-ftbf if the lens is of no interest;
0239 root -l 'scripts/reco-ftbf.C("pfrich-ftbf.root")'
0240 ```
0241
0242 Environment customization
0243 -------------------------
0244
0245 The code should be started in a *${SANDBOX}/pfRICH* directory, or otherwise in any other one,
0246 where exists a link to a *database* subdirectory, which contains MARCO solenoid field map (may be
0247 obsolete!), some of the media refractive index tables, etc.
0248
0249 Per design, there are no other configuration files, either ASCII or XML ones, in this package.
0250 All of the configuration changes are made through editing C++ header files and recompiling the
0251 executable codes. The rationale behind this paradigm is to have as transparent environment as
0252 possible, where there is no convoluted path from e.g. changing the detector geometry and propagating
0253 this change to the actual simulation pass. Besides this, the optical description of a setup is
0254 saved in the output ROOT tree with the charged particle, optical photon information and hits, to simplify
0255 book-keeping (there is no way a reconstruction code can pick up an optical configuration which is
0256 inconsistent with the GEANT geometry used in this simulation pass). All in all, it is a *development*
0257 style package, limited in its functionality, and designed just to do the job of implementing and
0258 trying out changes in the detector geometry *by you* in as simple and efficient way as possible
0259 (on a time scale
0260 of minutes for a full edit-compile-run-reconstruct sequence for O(10k) events), rather than a
0261 versatile solid framework with a detector configuration being changed *by somebody else for you*
0262 on a time scale of weeks and months.
0263
0264 One downside of this approach is a necessity to keep track of *your own changes* and do not let them
0265 interfere (after a *pull* request) with other changes occasionally happening in the repository. There are
0266 presently five "default" C++ header files in the repository: one with an
0267 [HRPPD description](share/include/hrppd.default.h), one with [shared parameters](share/include/share.default.h),
0268 and one for each of the [epic](epic/include/epic.default.h), [Fermilab](ftbf/include/ftbf.default.h) and
0269 BNL [QA station](tstand/include/tstand.default.h) configurations.
0270
0271
0272 ```
0273 # Consider creating your local copies of the repository header files, which you may want to change,
0274 # and pointing links like share.h to them, like (for a person 'xx'):
0275 cd ${SANDBOX}/pfRICH
0276
0277 pushd epic/include && rm epic.h && cp epic.default.h epic.xx.h && ln -s epic.xx.h epic.h && popd
0278
0279 # Then you can edit epic.xx.h locally without being affected by possible changes in epic.default.h
0280 # which would overwrite your local changes after next pull
0281 ```
0282
0283 Feel free to store your private header files in the repository (ask for a write access if you do not have one),
0284 and push them to the repository often enough. One can of course just create a git branch where one can modify
0285 the default header files directly.
0286
0287 It may make sense to look through the above mentioned default header files, line by line. They have a certain
0288 amount of
0289 comments, which allow one to understand what is what. It makes sense to periodically check whether anything
0290 was changed in the default configuration header files as compared to your local custom copies.
0291
0292 ```
0293 #Automation
0294 #----------
0295 #
0296 #
0297 # TODO: UPDATE THIS SECTION
0298 #Inside pfRICH directory run
0299 #`bash ./scripts/cc/AutomatedSimulationChain.sh`
0300 #It will display all the features with an example.
0301 #
0302 ```
