SBS Software

h1. Documentation of libsbsdig

This page concerns the new version of libsbsdig which is currently being developped. The documentation for the old version of libsbsdig has been saved at:

https://redmine.jlab.org/projects/sbs-software/wiki/Old_Doc_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 '''''sbsdig_lw''''' 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://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs G4SBS] 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. '''As of August, 18th, 2020, the master branch still contains the old version of the code'''.

To obtain the new version of the code currently being developped on the "sbsdig_lw" branch, do

bq. git checkout sbsdig_lw

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. How to use the digitization library

Working example scripts using the SBS-offline are available in the SBS-offline repository 

in the replay directory.

An example of script is replay_diggmn_test.C

h2. 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;

h3. "trackmchit" structure

The full name of such variables for a given detector is <detector_full_name>.trackmchit.<varname>, where <varname> can be:

* nhits (int): number of entries stored 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, projected in the dispersive direction x (transport coordinates)

* yhit (std::vector<double>) estimated point of intercept of the track at the detector surface, projected in the non-dispersive direction y (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)

For the GEMs, the full track info is stored (but the intersect points with each of the GEM layers aren't).

The full name of such variables for a given detector is <detector_full_name>.mctrack.<varname>, where <varname> can be:

mctrack_ntracks (int) number of tracks stored

* 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

* x (std::vector<double>): track position x at z = 0 (transport coordinates)

* y (std::vector<double>): track position y at z = 0 (transport coordinates)

* t (std::vector<double>): track time  at z = 0

* p (std::vector<double>): track momentum

* dx (std::vector<double>): track slope projected in the dispersive direction x (transport coordinates)

* dy (std::vector<double>): track slope projected in the non-dispersive direction y (transport coordinates)

* xv (std::vector<double>): track vertex x at target (if applicable)

* yv (std::vector<double>): track vertex y at target (if applicable)

* zv (std::vector<double>): track vertex z at target (if applicable)

* pxv (std::vector<double>): track momentum x at target (if applicable)

* pyv (std::vector<double>): track momentum y at target (if applicable)

* pzv (std::vector<double>): track momentum z at target (if applicable)

* weight (std::vector<double>) weight of the event from which the track is issued (not implemented yet)

h3. "simhit" structure

The full name of such variables for a given detector is <detector_full_name>.simhit.<varname>, where <varname> can be:

* nhits (int) number of entries stored for this structure and this detector

* 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

* 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;

The structure above is valid for all detectors except GEMs. The structure for GEMs sim hits is:

* nhits (UInt_t) number of entries stored for this structure and this detector

* 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.)

* plane (std::vector<short>): layer number of the GEM in which the hit is recorded

* module (std::vector<short>): module number of the GEM in whcih the hit is recorded

* edep (std::vector<double>): energy deposit recorded in g4sbs (in GeV)

* time (std::vector<double>): time of hit as recorded by g4sbs

* xpos (std::vector<double>): x position of hit in GEM module (transport coordinates)

* ypos (std::vector<double>): y position of hit in GEM module (transport coordinates)

* px (std::vector<double>): x momentum of the track in transport coordinates

* py (std::vector<double>): y momentum of the track in transport coordinates

* pz (std::vector<double>): z momentum of the track in transport coordinates

* sizex (std::vector<short>): number of strips on the x readout that receive _any_ signal from the GEM avalanche

* sizey (std::vector<short>): number of strips on the y readout that receive _any_ signal from the GEM avalanche

* startx (std::vector<short>): lowest x strip number that receive _any_ signal from the GEM avalanche

* starty (std::vector<short>): lowest y strip number that receive _any_ signal from the GEM avalanche

Notes: 

- the 4 last variables should be interpreted as such: the GEM avalanche will spread from strip #startx(y) to strip #startx(y)+sizex(y)

- the reconstructed hit size (i.e. after analysis/clustering) should not be expected to be the same as sizex (since strips receiving the slightest signals are counted in).

h3. "hit" structure

The full name of such variables for a given detector is <detector_full_name>.hit.<varname>, where <varname> can be:

* nhits (int) number of entries for this structure and this detector

* chan (std::vector<short>) channel number in which the hit is recorded

* dataword (std::vector<unsigned int>) encoded data word containing the ADC/TDC; may also store headers (useful for simulation decoding)

* adc (std::vector<int>) unencoded pedestal subtracted ADC value

* tdc_l (std::vector<int>) unencoded leading TDC value

* tdc_t (std::vector<int>) unencoded trailing TDC value

Note: when a "header" is stored in dataword, the channel number stored is -1. 

*Particular case of detector read out by sampling ADCs (GEMs MPDs, HCal FADCs):

In this case, storing each sample with the structure about would be too inefficient in terms of disk space. Hence, for this very specific case, we use vectors of evectors

* nsamps (std::vector<unsigned int>) number of ADC samples (number of elements in vector samps_adc, see note below)

* samps_adc (std::vector<vector<int> >) unencoded pedestal subtracted ADC values (samps_adc[i][j] = sample j for hit i)

* datawords (std::vector<vector<unsigned int> >) datawords containing the encoded GEMs. 

_Note_: for both MPDs and FADCs, two ADC values are encoded in a single 32 bits words. that means the actual number of ADC samples (nsamps) is twice the number elements in vector datawords. The number of elements in vector datawords is stored in variable dataword.