Project

General

Profile

Documentation of libsbsdig » History » Version 32

Eric Fuchey, 07/09/2020 02:28 PM

1 1 Eric Fuchey
h1. Documentation of libsbsdig
2
3
h2. Overview
4
5
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.
6
7
h2. Purpose
8
9
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.
10
These produce files which can be analyzed with [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline SBS-offline].
11
12
h2. Getting the code and building the program
13
14
h3. Prerequisites
15
16
*Working [https://root.cern.ch/drupal/ ROOT] installation. '''libsbsdig is compatible with ROOT version 5 and ROOT version 6'''. '''''ROOT 6 is strongly recommended'''''
17
*Working [https://redmine.jlab.org/projects/podd/wiki analyzer] installation. '''libsbsdig is compatible with analyzer versions 1.6 and beyond'''.
18
*Working [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline SBS-offline] installation.
19
20
h3. Downloading the repository
21
22
The code is hosted on a github repository owned by JLab. To clone via ssh (preferred method on JLab batch farm), do: 
23
24 5 Eric Fuchey
bq. git clone git@github.com:JeffersonLab/libsbsdig.git
25 1 Eric Fuchey
26
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.)
27
28
Cloning the repository defaults to the "master" branch.
29
30
h3. Building and installing the library
31
32 2 Eric Fuchey
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). 
33
You also need to have setup an installation path e.g. /path/to/libsbsdig-install
34
*NB*: similarly to the build directory, the /path/to/libsbsdig-install directory shall '''not''' be the same as the source directory!
35
_The following instructions assume that "build" is parallel to "libsbsdig":_
36 9 Eric Fuchey
If successful, the libsbsdig library and several other files and folders will be created in the "build" and the "install" directory.
37 1 Eric Fuchey
38 2 Eric Fuchey
To build and install, the procedure needs to be completed. From scratch:
39
40
bq. mkdir build
41
cd build
42
cmake -DCMAKE_INSTALL_PREFIX=/path/to/libsbsdig-install ../libsbsdig
43
make install
44 1 Eric Fuchey
45 3 Eric Fuchey
Then, the following line should be added in the OS login configuration file to take advantage of this functionality:
46
* source /path/to/libsbsdig-install/bin/sbsdigenv.sh (or source /path/to/g4sbs_install/bin/sbsdigenv.csh on the batch farm)
47 1 Eric Fuchey
48 31 Eric Fuchey
h2. How to use the digitization library
49 13 Eric Fuchey
50 9 Eric Fuchey
A working example script of using the digitization library is available in the libsbsdig repository at
51
example/digi_gmn.C 
52
The input arguments for this scripts are explained in the script comments. 
53
It has to be executed with the Hall A analyzer:
54 10 Eric Fuchey
> analyzer
55
> > .L digi_gmn.C
56
> > digi_gmn("simdig_outfile.root", 1000, "gmn13.5_elastic_prod.txt")
57 1 Eric Fuchey
58 30 Eric Fuchey
h2. Root output documentation
59 1 Eric Fuchey
60 15 Eric Fuchey
For each detector, several structures are stored under the form of an ensemble of vectors of integers and doubles.
61
There are three types of structures:
62 24 Eric Fuchey
* the "trackmchits" storing the information of the Monte Carlo track intercepting the detector; 
63
* the "simhits" storing the true energy deposits and corresponding number of photoelectrons for each g4sbs hit processed by libsbsdig;
64
* the "hits", storing the adc and tdc information;
65 15 Eric Fuchey
66 30 Eric Fuchey
h3. "trackmchit" structure
67 16 Eric Fuchey
68 32 Eric Fuchey
The full name of such variables for a given detector is <detector_full_name>.trackmchit.<varname>, where <varname> can be:
69
70 26 Eric Fuchey
* nhits (int): number of entries stored for this structure and this detector
71 23 Eric Fuchey
* source (std::vector<short>): type of file where the MC track comes from (0 if signal, >0 if background)
72
* trid (std::vector<short>): track ID in G4SBS (mostly useful to distinguish primary tracks)
73
* pid  (std::vector<int>): track PDG PID
74 26 Eric Fuchey
* xhit (std::vector<double>) estimated point of intercept of the track at the detector surface, projected in the dispersive direction x (transport coordinates)
75
* yhit (std::vector<double>) estimated point of intercept of the track at the detector surface, projected in the non-dispersive direction y (transport coordinate)
76 1 Eric Fuchey
* thit (std::vector<double>) estimated time of intercept of the track at the detector surface
77
* e (std::vector<double>) track total energy
78 26 Eric Fuchey
* weight (std::vector<double>) weight of the event from which the track is issued (not implemented yet)
79 1 Eric Fuchey
80 32 Eric Fuchey
For the GEMs, the full track info is stored (but the intersect points with each of the GEM layers aren't).
81 1 Eric Fuchey
82 32 Eric Fuchey
The full name of such variables for a given detector is <detector_full_name>.mctrack.<varname>, where <varname> can be:
83
84
85 26 Eric Fuchey
mctrack_ntracks (int) number of tracks stored
86
* source (std::vector<short>): type of file where the MC track comes from (0 if signal, >0 if background)
87
* trid (std::vector<short>): track ID in G4SBS (mostly useful to distinguish primary tracks)
88
* pid  (std::vector<int>): track PDG PID
89
* x (std::vector<double>): track position x at z = 0 (transport coordinates)
90
* y (std::vector<double>): track position y at z = 0 (transport coordinates)
91
* t (std::vector<double>): track time  at z = 0
92
* p (std::vector<double>): track momentum
93
* dx (std::vector<double>): track slope projected in the dispersive direction x (transport coordinates)
94
* dy (std::vector<double>): track slope projected in the non-dispersive direction y (transport coordinates)
95
* xv (std::vector<double>): track vertex x at target (if applicable)
96
* yv (std::vector<double>): track vertex y at target (if applicable)
97
* zv (std::vector<double>): track vertex z at target (if applicable)
98
* pxv (std::vector<double>): track momentum x at target (if applicable)
99
* pyv (std::vector<double>): track momentum y at target (if applicable)
100
* pzv (std::vector<double>): track momentum z at target (if applicable)
101
* weight (std::vector<double>) weight of the event from which the track is issued (not implemented yet)
102
103 30 Eric Fuchey
h3. "simhit" structure
104 1 Eric Fuchey
105 32 Eric Fuchey
The full name of such variables for a given detector is <detector_full_name>.simhit.<varname>, where <varname> can be:
106
107 27 Eric Fuchey
* nhits (int) number of entries stored for this structure and this detector
108 24 Eric Fuchey
* src (std::vector<short>): type of file where the sim hit comes from (0 if signal, >0 if background)
109
* trid (std::vector<short>): ID of track responsible of hit in G4SBS (n. i. y.)
110
* pid (std::vector<int>): PDG PID of track responsible of hit in G4SBS (n. i. y.)
111
* chan (std::vector<short>): channel number in which the hit is recorded
112 1 Eric Fuchey
* edep (std::vector<double>): energy deposit recorded in g4sbs (in GeV)
113 24 Eric Fuchey
* npe (std::vector<int>): recorded or estimated number of photoelectrons detected
114 27 Eric Fuchey
* time (std::vector<double>): time of hit as recorded by g4sbs
115 24 Eric Fuchey
* t_lead(std::vector<double>): estimated time when the pulse rises over threshold (for detectors with TDCs) 
116
* t_trail(std::vector<double>): estimated time when the pulse falls under threshold (for detectors with TDCs) 
117 18 Eric Fuchey
118 1 Eric Fuchey
Note: 
119
for calorimeters without TDCs, t_lead and t_trail are not applicable and will not be stored;
120
for cherenkov detectors, edep is not applicable and will not be stored;
121 27 Eric Fuchey
122
The structure above is valid for all detectors except GEMs. The structure for GEMs sim hits is:
123
124
* nhits (UInt_t) number of entries stored for this structure and this detector
125
* src (std::vector<short>): type of file where the sim hit comes from (0 if signal, >0 if background)
126
* trid (std::vector<short>): ID of track responsible of hit in G4SBS (n. i. y.)
127
* pid (std::vector<int>): PDG PID of track responsible of hit in G4SBS (n. i. y.)
128
* plane (std::vector<short>): layer number of the GEM in which the hit is recorded
129
* module (std::vector<short>): module number of the GEM in whcih the hit is recorded
130
* edep (std::vector<double>): energy deposit recorded in g4sbs (in GeV)
131
* time (std::vector<double>): time of hit as recorded by g4sbs
132 28 Eric Fuchey
* xpos (std::vector<double>): x position of hit in GEM module (transport coordinates)
133
* ypos (std::vector<double>): y position of hit in GEM module (transport coordinates)
134
* px (std::vector<double>): x momentum of the track in transport coordinates
135
* py (std::vector<double>): y momentum of the track in transport coordinates
136
* pz (std::vector<double>): z momentum of the track in transport coordinates
137 29 Eric Fuchey
* sizex (std::vector<short>): number of strips on the x readout that receive _any_ signal from the GEM avalanche
138
* sizey (std::vector<short>): number of strips on the y readout that receive _any_ signal from the GEM avalanche
139
* startx (std::vector<short>): lowest x strip number that receive _any_ signal from the GEM avalanche
140
* starty (std::vector<short>): lowest y strip number that receive _any_ signal from the GEM avalanche
141 27 Eric Fuchey
142 29 Eric Fuchey
Notes: 
143
- the 4 last variables should be interpreted as such: the GEM avalanche will spread from strip #startx(y) to strip #startx(y)+sizex(y)
144
- 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).
145 27 Eric Fuchey
146 18 Eric Fuchey
147 1 Eric Fuchey
h3. "hit" structure
148 32 Eric Fuchey
149
The full name of such variables for a given detector is <detector_full_name>.hit.<varname>, where <varname> can be:
150 20 Eric Fuchey
151 25 Eric Fuchey
* nhits (int) number of entries for this structure and this detector
152
* chan (std::vector<short>) channel number in which the hit is recorded
153
* dataword (std::vector<unsigned int>) encoded data word containing the ADC/TDC; may also store headers (useful for simulation decoding)
154
* adc (std::vector<int>) unencoded pedestal subtracted ADC value
155
* tdc_l (std::vector<int>) unencoded leading TDC value
156
* tdc_t (std::vector<int>) unencoded trailing TDC value
157 19 Eric Fuchey
158 25 Eric Fuchey
*Particular case of detector read out by sampling ADCs (GEMs MPDs, HCal FADCs):*
159
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
160
 
161
* nsamps (std::vector<unsigned int>) number of ADC samples (number of elements in vector samps_adc, see note below)
162
* samps_adc (std::vector<vector<int> >) unencoded pedestal subtracted ADC values (samps_adc[i][j] = sample j for hit i)
163
* datawords (std::vector<vector<unsigned int> >) datawords containing the encoded GEMs. 
164
165
_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.