Project

General

Profile

Old Doc libsbsdig » History » Version 4

Eric Fuchey, 08/19/2020 12:58 AM

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