Newer
Older
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.
* [Prerequisites and installation](#prerequisites-and-installation)
* [pfRICH example configuration](#pfrich-example-configuration)
* [No-juggler reconstruction pass](#no-juggler-reconstruction-pass)
* [Juggler reconstruction pass](#juggler-reconstruction-pass)
* [DRICH case](#drich-case)
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;
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;
git clone https://eicweb.phy.anl.gov/EIC/irt.git --branch irt-init-v01
cmake -DCMAKE_INSTALL_PREFIX=/tmp/ATHENA -DEVALUATION=YES ..
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:
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)
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")'
```