EIC code displayed by LXR master/​irt/​README.md	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

Warning, /irt/README.md is written in an unsupported language. File is not indexed.

 Indirect Ray Tracing code for ATHENA event reconstruction
 =========================================================
 
   A C++ ROOT-based software library to peform Cherenkov photon ray 
 tracing between a loosely defined emission point (which is typically 
 unknown in the experiment) and a detection point on a photosensor
 matrix, in a configuration with a pre-defined sequence of refractive 
 and reflective surfaces. Provides means to perform detailed microscopic 
 simulations of Cherenkov imaging detectors in a pure GEANT4 environment, 
 as well as an interface to the ATHENA software framework. Given a track 
 parameterization along a charged particle trajectory in a sequence of 
 Cherenkov radiators, and a collection of single photon hits, allows one 
 to perform probabilistic analysis of particle mass hypotheses. 
 
   Primary application are proximity focusing and / or mirror-focusing RICH 
 detectors, with a configurable combination of aerogel and / or gas radiators, 
 as well as a set of spherical and / or flat mirrors.  
 
  Content:
 
  * [Introduction](#introduction)
  * [Prerequisites and installation](#prerequisites-and-installation)
  * [pfRICH example configuration](#pfrich-example-configuration)
  * [Simulation pass](#simulation-pass)
  * [No-juggler reconstruction pass](#no-juggler-reconstruction-pass)
  * [Juggler reconstruction pass](#juggler-reconstruction-pass)
  * [DRICH case](#drich-case)
  * [HEPMC writer](#hepmc-writer)
 
 <br/>
 
 Introduction
 ------------
 
   A typical event reconstruction task in a setup with an imaging Cherenkov 
 detector is to associate single photon hits with the charged particle tracks, 
 and evaluate the Cherenkov light emission angle, which - provided particle 
 momentum is evaluated by other means (for instance via tracking) - gives one a probabilistic 
 estimate of a particle mass and therefore allows one to e.g. separate charged
 pions and kaon in data analysis.
 
   Current implementation uses MC truth information to associate photon hits and 
 tracks, and does not make an attempt to perform either ring finding or noise 
 hit suppression in multi-track configurations. Nowehere in the algorithmic
 part it tries to reconstruct either average Cherenkov ring radius or average 
 emission angle. Instead of that the algorithm just makes an attempt to associate 
 *any* detected photon hit with any track, and perform *mass hypothesis ranking* for 
 each track. This procedure is supposed to automatically handle random noise, and 
 in a typically low track multiplicity environment at the EIC would only require 
 a shared hit resolution procedure in addition, to work in an optimal way in case 
 of overlapping rings. Well, this needs to be verified of course.
 
   The CPU overhead is supposed to scale as [N tracks] x [M photon hits], and in 
 general can be substantial. Further optimization like detector partitioning in 
 independent sectors will be required.
 
   Output provides estimated photon count and estimated weights for a set of  mass 
 hytheses requested by a user.
 
 <br/>
 
 Prerequisites and installation
 ------------------------------
 
   It is assumed that a user ia familiar with the [ATHENA software](https://eic.phy.anl.gov/ip6) 
 environment, and a juggler singularity container "jug_xl" is running. It is also assumed 
 that dd4hep sources are available either via cvmfs or locally, and athena detector software 
 is installed. For the sake of completeness, the following sequence of commands installs all what is needed 
 under /tmp, assuming that eic-shell was just started, see [ATHENA software](https://eic.phy.anl.gov/ip6) 
 for further details:
 
 ```
 # In the following /tmp/ATHENA is supposed to be a *link* to a safe scratch directory
 # <your-safe-scratch-area> somewhere on a (local) filesystem:
 
 cd /tmp && ln -s <your-safe-scratch-area> ATHENA && cd ATHENA
 ```
 
   The rest of the commands in this README can be grabbed by mouse and executed 
 block by block.
 
 ```
 # Do not want to mess up with the initial software installation in the container;
 unset ATHENA_PREFIX
 
 export LD_LIBRARY_PATH=/tmp/ATHENA/lib:${LD_LIBRARY_PATH}
 
 # Install a particular branch of the EIC data model;
 cd /tmp/ATHENA
 git clone https://eicweb.phy.anl.gov/EIC/eicd.git --branch irt-init-v01
 cd eicd && mkdir build && cd build
 cmake -DCMAKE_INSTALL_PREFIX=/tmp/ATHENA ..
 make -j2 install
 ```
 
 ```
 # Install the IRT library itself;
 cd /tmp/ATHENA
 git clone https://eicweb.phy.anl.gov/EIC/irt.git --branch irt-init-v01
 cd irt && mkdir build && cd build
 cmake -DCMAKE_INSTALL_PREFIX=/tmp/ATHENA -DEVALUATION=YES ..
 make -j2 install
 ```
 
   This compiles the IRT library codes and the executables to be later on used to read the .root
 files with the GEANT hits after *npsim* simulation pass. 
 
 ```
 # Install "athena" detector description;
 git clone https://eicweb.phy.anl.gov/EIC/detectors/athena.git --branch irt-init-v01
 cd athena && mkdir build && cd build
 cmake -DCMAKE_INSTALL_PREFIX=/tmp/ATHENA ..
 make -j2 install
 
 # Install "ip6" description;
 cd /tmp/ATHENA
 git clone https://eicweb.phy.anl.gov/EIC/detectors/ip6.git
 cd ip6 && mkdir build && cd build
 cmake -DCMAKE_INSTALL_PREFIX=/tmp/ATHENA ..
 make -j2 install
 
 ```
 
   The rest of this README builds a minimalistic self-contained example of how to make use of the 
 IRT library in application to a basic ATHENA e-endcap proximity focusing aerogel RICH.
 
 
 <br/>
 
 Simulation pass
 ---------------
 
   Create a separate sandbox directory. Generate a minimal set of necessary links. Run *npsim*.
 
 ```
 cd /tmp/ATHENA && mkdir sandbox && cd sandbox
 
 # Links to the directories with the "official" .xml files (depend on your installation);
 ln -s /tmp/ATHENA/share/ip6/ip6 .
 ln -s /tmp/ATHENA/share/athena/compact .
 
 # These two just to simplify 'npsim' command line:
 ln -s /tmp/ATHENA/share/athena/compact/pfrich.xml .
 ln -s /tmp/ATHENA/share/athena/compact/subsystem_views/pfrich_only.xml .
 
 # Eventually run 'npsim' for 100 events with 8 GeV pions, in a pfRICH-only geometry;
 npsim --compactFile=./pfrich_only.xml --runType=run -G -N=100 --outputFile=./pfrich-data.root --gun.position "0.0 0.0 0.0" --gun.direction "0.2 0.0 -1.0" --gun.energy 8*GeV --gun.particle="pi+" --part.userParticleHandler='' --random.seed 0x12345678 --random.enableEventSeed
 
 ```
 
   A pair of ROOT output files is produced: pfRICH detector optics configuration and 
 a file with GEANT tracks and photon hits.
 
 <br/>
 
 No-juggler reconstruction pass
 ------------------------------
 
   A simplified executable, using the same IRT engine, but with hardcoded (optional) QE 
 and low wavelength cutoff.
 
 ```
 cd /tmp/ATHENA/sandbox
 # Loop through the events in the raw GEANT4 hit file. See [reader.cc](evaluation/reader.cc)
 /tmp/ATHENA/bin/reader pfrich-data.root pfrich-config.root
 
 ```
 
 Juggler reconstruction pass
 ---------------------------
 
   Install Juggler first:
 
 ```
 cd /tmp/ATHENA
 git clone https://eicweb.phy.anl.gov/EIC/juggler.git --branch irt-init-v01
 cd juggler && mkdir build && cd build
 cmake -DCMAKE_INSTALL_PREFIX=/tmp/ATHENA ..
 
 # Fix an issue with LD_LIBRARY_PATH in jugglerenv.sh; may be required more than once (?);
 sed -i.bak 's/\:\/usr\/local\/lib\:/\:/g' jugglerenv.sh && echo "export LD_LIBRARY_PATH=\${LD_LIBRARY_PATH}:/usr/local/lib && export PYTHONPATH=\${PYTHONPATH}:/usr/local/lib" >> jugglerenv.sh
 # Compile with a single thread unless have a plenty of memory;
 make -j1 install
 
 ```
 
 ```
 cd /tmp/ATHENA/sandbox
 # Run Juggler with a simplified pfrich-testIRT.py options file provided with IRT distribution; 
 xenv -x ../Juggler.xenv gaudirun.py ../irt/pfrich-testIRT.py
 
 # Loop through the events in the reconstructed file. See [evaluation.cc](evaluation/evaluation.cc)
 /tmp/ATHENA/bin/evaluation pfrich-reco.root
 
 ```
 
 DRICH case
 ----------
 
 It is assumed that 'athena/ip6/compact' links in /tmp/ATHENA/sandbox directory are created already.
 The rest is pretty much similar to the pfRICH case, except for perhaps a .C script usage instead 
 of a .cc executable:
 
 ```
 cd /tmp/ATHENA/sandbox
 ln -s /tmp/ATHENA/share/athena/compact/drich.xml .
 ln -s /tmp/ATHENA/share/athena/compact/subsystem_views/drich_only.xml .
 ```
 
 ```
 npsim --compactFile=./drich_only.xml --runType=run -G -N=500 --outputFile=./drich-data.root --gun.position "0.0 0.0 0.0" --gun.direction "0.27 0.0 1.0" --gun.energy 12*GeV --gun.particle="pi+" --part.userParticleHandler='' --random.seed 0x12345678 --random.enableEventSeed
 ```
 ```
 xenv -x ../Juggler.xenv gaudirun.py ../irt/drich-testIRT.py
 root -l '../irt/scripts/evaluation.C("drich-reco.root")'
 ```
 
 HEPMC writer
 ------------
 
 It is of course way more convenient to create a .hepmc file with a collection of events / tracks, 
 than to use a limited in functionality npsim command line interface. Here is an example:
 
 ```
 cd /tmp/ATHENA/sandbox
 root -l '../irt/scripts/drich-hepmc-writer.C("drich-data.hepmc", 300)'
 
 npsim --compactFile=./drich_only.xml --runType=run -G -N=300 --inputFiles ./drich-data.hepmc --outputFile=./drich-data.root --part.userParticleHandler='' --random.seed 0x12345678 --random.enableEventSeed
 
 xenv -x ../Juggler.xenv gaudirun.py ../irt/drich-testIRT.py
 root -l '../irt/scripts/evaluation.C("drich-reco.root")'
 ```

This page was automatically generated by the 2.3.7 LXR engine. The LXR team