Documentation of libsbsdig » History » Revision 20
Revision 19 (Eric Fuchey, 07/09/2020 12:46 PM) → Revision 20/120 (Eric Fuchey, 07/09/2020 12:48 PM)
h1. Documentation of libsbsdig
h2. Overview
This page is maintained by the UConn group (Eric Fuchey + Andrew Puckett) and as of February 14, 2020 is specific to the '''''master''''' branch of libsbsdig on github.
h2. Purpose
This page documents the libsbsdig code, which purpose is to transform the output data from [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs G4SBS] to digital values such as ADCs or TDCs.
These produce files which can be analyzed with [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline SBS-offline].
h2. Getting the code and building the program
h3. Prerequisites
*Working [https://root.cern.ch/drupal/ ROOT] installation. '''libsbsdig is compatible with ROOT version 5 and ROOT version 6'''. '''''ROOT 6 is strongly recommended'''''
*Working [https://redmine.jlab.org/projects/podd/wiki analyzer] installation. '''libsbsdig is compatible with analyzer versions 1.6 and beyond'''.
*Working [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline SBS-offline] installation.
h3. Downloading the repository
The code is hosted on a github repository owned by JLab. To clone via ssh (preferred method on JLab batch farm), do:
bq. git clone git@github.com:JeffersonLab/libsbsdig.git
For this method to work, the ssh public key on the machine where you want to get the code must be added to your github account (see [https://help.github.com/articles/generating-ssh-keys/ Guide] to generating ssh keys and adding to your github.com account.)
Cloning the repository defaults to the "master" branch.
h3. Building and installing the library
Create a "build" directory that is parallel to the "libsbsdig" source directory (this is not strictly required, but the build directory must be separate from the "SBS-offline" directory in any case).
You also need to have setup an installation path e.g. /path/to/libsbsdig-install
*NB*: similarly to the build directory, the /path/to/libsbsdig-install directory shall '''not''' be the same as the source directory!
_The following instructions assume that "build" is parallel to "libsbsdig":_
If successful, the libsbsdig library and several other files and folders will be created in the "build" and the "install" directory.
To build and install, the procedure needs to be completed. From scratch:
bq. mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/path/to/libsbsdig-install ../libsbsdig
make install
Then, the following line should be added in the OS login configuration file to take advantage of this functionality:
* source /path/to/libsbsdig-install/bin/sbsdigenv.sh (or source /path/to/g4sbs_install/bin/sbsdigenv.csh on the batch farm)
h2. digitization library use
h3. how to use the digitization library
A working example script of using the digitization library is available in the libsbsdig repository at
example/digi_gmn.C
The input arguments for this scripts are explained in the script comments.
It has to be executed with the Hall A analyzer:
> analyzer
> > .L digi_gmn.C
> > digi_gmn("simdig_outfile.root", 1000, "gmn13.5_elastic_prod.txt")
h3. Root output documentation
For each detector, several structures are stored under the form of an ensemble of vectors of integers and doubles.
There are three types of structures:
- the "trackmchits" storing the information of the Monte Carlo track intercepting the detector;
- the "simhits" storing the true energy deposits and corresponding number of photoelectrons for each g4sbs hit processed by libsbsdig;
- the "hits", storing the adc and tdc information;
h4. "trackmchit" structure
nhits (int): number of entries for this structure and this detector
source (std::vector<short>): type of file where the MC track comes from (0 if signal, >0 if background)
trid (std::vector<short>): track ID in G4SBS (mostly useful to distinguish primary tracks)
pid (std::vector<int>): track PDG PID
xhit (std::vector<double>) estimated point of intercept of the track at the detector surface, in the dispersive direction (transport coordinates)
yhit (std::vector<double>) estimated point of intercept of the track at the detector surface, in the non-dispersive direction (transport coordinate)
thit (std::vector<double>) estimated time of intercept of the track at the detector surface
e (std::vector<double>) track total energy
weight (std::vector<double>) weight of the event from which the track is issued (not implemented yet)
h4. "simhit" structure
nhits (int)
src (std::vector<short>): type of file where the sim hit comes from (0 if signal, >0 if background)
trid (std::vector<short>): ID of track responsible of hit in G4SBS (n. i. y.)
pid (std::vector<int>): PDG PID of track responsible of hit in G4SBS (n. i. y.)
chan (std::vector<short>): channel number in which the hit is recorded
edep (std::vector<double>): energy deposit recorded in g4sbs (in GeV)
npe (std::vector<int>): recorded or estimated number of photoelectrons detected
time (std::vector<double>): time of hit as recorded by g4sbs or estimated by libsbsdig (if photons are estimated)
t_lead(std::vector<double>): estimated time when the pulse rises over threshold (for detectors with TDCs)
t_trail(std::vector<double>): estimated time when the pulse falls under threshold (for detectors with TDCs)
Note:
for calorimeters without TDCs, t_lead and t_trail are not applicable and will not be stored;
for cherenkov detectors, edep is not applicable and will not be stored;
h4. "hit" structure
nhits (int)
chan (std::vector<short>)
dataword (std::vector<unsigned int>)
adc (std::vector<int>)
tdc_l (std::vector<int>)
tdc_t (std::vector<int>)
std::vector<unsigned int> *sbs_hcal_hit_nsamps;
std::vector<vector<int> > *sbs_hcal_hit_samps_adc;
std::vector<vector<unsigned int> > *sbs_hcal_hit_samps_datawords;