Project

General

Profile

Documentation of libsbsdig » History » Version 118

Eric Fuchey, 04/14/2023 05:01 PM

1 1 Eric Fuchey
h1. Documentation of libsbsdig
2
3 70 Eric Fuchey
{{toc}}
4
5 36 Eric Fuchey
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:
6
https://redmine.jlab.org/projects/sbs-software/wiki/Old_Doc_libsbsdig
7
8 1 Eric Fuchey
h2. Overview
9
10 112 Eric Fuchey
This page is maintained by the UConn group (Eric Fuchey + Andrew Puckett). 
11 113 Eric Fuchey
-As of February 14, 2020 is specific to the sbsdig_lw branch of libsbsdig on github.-
12 108 Eric Fuchey
As of April 2022, those instructions also apply to the master branch of libsbsdig on github.
13 1 Eric Fuchey
14
h2. Purpose
15
16 52 Eric Fuchey
This page documents the libsbsdig code, which purpose is to process the Monte Carlo simulations of the SBS experiments produced by G4SBS [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs] to produce ADCs or TDCs.
17 37 Eric Fuchey
It is a standalone program which can run with a limited number of outputs (see section on usage).
18 52 Eric Fuchey
These produce files which can be analyzed with SBS-offline [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline].
19 1 Eric Fuchey
20
h2. Getting the code and building the program
21
22
h3. Prerequisites
23
24 54 Eric Fuchey
* Working ROOT [https://root.cern.ch/drupal/] installation. ROOT 6 is strongly recommended.
25
* Working G4SBS [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs] installation.
26 1 Eric Fuchey
27
h3. Downloading the repository
28
29 104 Eric Fuchey
h4. for simple users
30
31 1 Eric Fuchey
The code is hosted on a github repository owned by JLab. To clone via ssh (preferred method on JLab batch farm), do: 
32 5 Eric Fuchey
33 1 Eric Fuchey
bq. git clone git@github.com:JeffersonLab/libsbsdig.git
34
35
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.)
36
37 113 Eric Fuchey
Cloning the repository defaults to the "master" branch. 
38 110 Eric Fuchey
As of April, 25th, 2022, the most up-to-date version of the code and the databases is located on the *master* branch.
39 113 Eric Fuchey
-As of August, 18th, 2020, the master branch still contains the old version of the code.-
40 110 Eric Fuchey
-Beware that the current version of libsbsdig is not on the "master" branch, but on the "sbsdig_lw".-
41 71 Eric Fuchey
42 104 Eric Fuchey
* Have an individual github account.
43
* On github.com: Fork the JeffersonLab libsbsdig to your account. Setup to “watch” Jlab libsbsdig
44
* git clone git@github.com:GithubUserName/libsbsdig.git (This is ssh access). 
45
** This will be the “origin” remote repo;
46
** Create your own branch: git checkout –b NewBranchName
47
* git remote –add upstream git@github.com:JeffersonLab/libsbsdig.git
48
** This will be the “upstream” remote repo
49 1 Eric Fuchey
* You can pull ( or fetch/merge) changes from the upstream (Jefferson Lab) repo.
50
* You can push commits in your branch to the origin (Personal Github) repo and then make pull requests.
51 108 Eric Fuchey
52 109 Eric Fuchey
The most up-to-date version of the code is now available on the master branch.
53 36 Eric Fuchey
-To obtain the new version of the code currently being developped on the "sbsdig_lw" branch, do:-
54 109 Eric Fuchey
-bq. git checkout sbsdig_lw-
55 1 Eric Fuchey
56
h3. Building and installing the library
57
58 92 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 "libsbsdig" directory in any case). 
59 2 Eric Fuchey
You also need to have setup an installation path e.g. /path/to/libsbsdig-install
60 93 Eric Fuchey
For instance, you can create it parallel to your libsbsdig directory (with the mkdir command), even though it is not strictly required
61
62 2 Eric Fuchey
*NB*: similarly to the build directory, the /path/to/libsbsdig-install directory shall '''not''' be the same as the source directory!
63
_The following instructions assume that "build" is parallel to "libsbsdig":_
64 9 Eric Fuchey
If successful, the libsbsdig library and several other files and folders will be created in the "build" and the "install" directory.
65 1 Eric Fuchey
66 2 Eric Fuchey
To build and install, the procedure needs to be completed. From scratch:
67
68
bq. mkdir build
69
cd build
70
cmake -DCMAKE_INSTALL_PREFIX=/path/to/libsbsdig-install ../libsbsdig
71
make install
72 1 Eric Fuchey
73 3 Eric Fuchey
Then, the following line should be added in the OS login configuration file to take advantage of this functionality:
74 91 Eric Fuchey
* source /path/to/libsbsdig-install/bin/sbsdigenv.sh (or source /path/to/libsbsdig-install/bin/sbsdigenv.csh on the batch farm)
75 1 Eric Fuchey
76 13 Eric Fuchey
h2. How to use the digitization library
77 1 Eric Fuchey
78 37 Eric Fuchey
When sbsdig is installed in your machine, you can run the program using up to 4 arguments:
79 1 Eric Fuchey
80 98 Eric Fuchey
bq. sbsdig db_gmn_conf.dat gmn13.5_elastic_ex.txt 100000
81 33 Eric Fuchey
82 1 Eric Fuchey
These arguments have to come in this sequence, and while not all arguments are mandatory to provide, one cannot skip an argument unless they want to skip all following arguments.
83 78 Eric Fuchey
*The first argument is a database containing the list of detectors to digitize, and the parameters for the digitization. An example of such parameters is attached (db_gmn_conf.dat)
84
*The second argument is a list of "signal" files to digitize. It is mandatory to provide. An example is provided in the files attached.
85 105 Eric Fuchey
This file contains a list of input files for the program to run on. Hence, it has to contain g4sbs files that you have permission to modify. 
86 115 Eric Fuchey
This file may also optionally contain the input for background superimposition (see next section). 
87
*The third argument is the number of events to  process. It has a default value of "-1" (=2^64-1) so it can be left unprovided.
88 1 Eric Fuchey
89 118 Eric Fuchey
_Note: it is strongly advised to never run the digitization twice on the same file, or the first tree extension produced by the digitization will "hide" all the following ones._ __
90 1 Eric Fuchey
91
h2. Input files documentation
92 115 Eric Fuchey
93
h3. List of data files
94
95
This file must contain the list of "signal" files first. In case one wants to add a background file, the list of signal files should be ended with the following line:
96
97
bq. endlist
98
99
Then the background information can be added:
100
101
bq. gmn13.5_beambkgdhistos.root 100000000 30.e-5 0
102
103
with: 1st parameter name of the file where the histograms are stored; 2nd parameter: total number of background events generated; 3rd parameter: beam current in A; 4th is a flag to switch on or off the digitization of the PMT detectors background.
104 116 Eric Fuchey
The following line can also be added after the background file:
105 115 Eric Fuchey
106 116 Eric Fuchey
bq. end_bkgdinfo
107
108
Note:
109
A script to generate the background histograms for GMn is available at:
110
https://github.com/JeffersonLab/libsbsdig/blob/master/scripts/GMnBeambkgdSample.C
111 115 Eric Fuchey
112 79 Eric Fuchey
113 80 Eric Fuchey
h3. Configuration file
114 1 Eric Fuchey
115 81 Eric Fuchey
This part describes the expected parameters for the configuration file (first argument for sbsdig). 
116 114 Eric Fuchey
These parameters are presented as follows: name (expected type)
117 1 Eric Fuchey
118 81 Eric Fuchey
* Rseed (int): seed for random number generator
119
* TriggerJitter (float): global trigger jitter for all detectors in ns
120 1 Eric Fuchey
121 81 Eric Fuchey
* detectors_list (strings, may take several arguments): list of detectors to digitize
122
Currently implemented:
123
hcal (hadron calorimeter, "pmt" type detector)
124
bbps (Big Bite calorimeter preshower, "pmt" type detector)
125
bbsh (Big Bite calorimeter shower, "pmt" type detector)
126
grinch (BigBite GRINCH cherenkov, "pmt" type detector)
127
bbhodo (BigBite timing hodoscope, "pmt" type detector)
128 1 Eric Fuchey
bbgem (BigBite GEM tracker, "gem" type detector)
129 96 Eric Fuchey
ecal (GEp electromagnetic calorimeter, "pmt" type detector)
130
cdet (coordinate detector for GEp electron arm, "pmt" type detector)
131
ft (GEp front tracker, "gem" type detector)
132
fpp1 (GEp focal plane polarimeter 1, "gem" type detector)
133
fpp2 (GEp focal plane polarimeter 2, "gem" type detector)
134 89 Eric Fuchey
135
GEnRP detectors being added...
136 79 Eric Fuchey
137 88 Eric Fuchey
h4. Parameters for "pmt" type detector (name "det")
138 83 Eric Fuchey
139 88 Eric Fuchey
* NChan_det (int) number of PMTs
140
* gatewidth_det (float) size of the data acquisition window in ns 
141
* gain_det (float) PMT gain
142
* ped_det (float) channel pedestal mean
143
* pedsigma_det (channel)  channel pedestal sigma
144
* trigoffset_det (float) trigger offset to have the signal centered properly around zero
145
* ADCconv_det (float) fC/ADC channels conversion factor
146
* ADCbits_det (int) number of bits to store the ADC value
147
* TDCconv_det (float) ns/TDC channels conversion factor
148
* TDCbits_det (int) number of bits to store the TDC value
149
* sigmapulse_det (float) full width half max of PMT pulse
150 84 Eric Fuchey
151 86 Eric Fuchey
h4. Parameters for "gem" type detector (of name "detgem")
152 1 Eric Fuchey
153 97 Eric Fuchey
* NPlanes_detgem (int): number of GEM modules x number of readout planes (usually 2) included in the tracker;
154 1 Eric Fuchey
* gatewidth_detgem (float): size data acquisition window for the in ns;
155 97 Eric Fuchey
* nlayers_detgem (int): number of GEM layers (ensemble of GEM modules at a same z)
156
* detgem_layer_z (array of floats): z value of each layer (should match number of layers); 
157 95 Eric Fuchey
* layer_detgem (int): layer to which the plane/module/readout belongs; _array needs to be same size as NPlanes_detgem_
158 90 Eric Fuchey
* nstrips_detgem (array of ints): number of strips for each plane/module/readout; _array needs to be same size as NPlanes_detgem_
159
* offset_detgem (array of floats): geometrical offset in transport coordinate for each plane/module in meters (alternatively x, y); _array needs to be same size as NPlanes_detgem_
160
* RO_angle_detgem (array of floats): angle of readout in degrees, with respect to transport coordinate x; _array needs to be same size as NPlanes_detgem_
161
* triggeroffset_detgem (array of floats): trigger offsets for all planes in ns _array needs to equal to NPlanes_detgem/2_
162
* ZsupThr_detgem (float): zero suppression threshold for GEMs in ADC channels;
163
* commonmode_array_detgem (float or array of floats) "common mode" (APV pedestal) value/array for BBGEMs in ADC channels; one can provide only one value which will be used for all strips or an array of values for a more realistic simulation
164 82 Eric Fuchey
165 1 Eric Fuchey
h2. Root output documentation
166 39 Eric Fuchey
167
The new digitization library will expand the TTree object from the input file to add ADC and TDC values.
168 55 Eric Fuchey
The input tree structure from G4SBS has already been described in detail in the G4SBS documentation [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs#ROOT_Tree_Structure].
169 56 Eric Fuchey
The basic idea is that for each detector in the input tree, a set of branches will be added.
170
171
There are several types of detectors in G4SBS (GEM, CAL, RICH), but there is not always a defined extension for a G4SBS detector type.
172
(NB: I'm voluntarilly omitting ECAL, 
173
For the purpose of the digitization, it is more convenient to define the following types of detectors:
174
* GEM: GEM trackers. Corresponds unambiguously to GEM detector type in G4SBS. Read out by MPD (sampling ADC) modules.
175
* Cher: Cherenkov detectors (example: GRINCH). Corresponds unambiguously to RICH detector type in G4SBS. Read out by TDC modules (with optional ADCs).
176
* Scint: Scintillator timing detectors (example: Timing Hodoscope). Corresponds to CAL detector type in G4SBS. Read out by TDC modules (with optional ADCs).
177
* Cal: Calorimeter (example: BBPS, BBSH). Corresponds to CAL detector type in G4SBS. Read out by ADC modules.
178
* HCal: Hadron Calorimeter. Corresponds to CAL detector type in G4SBS. Read out by FADC (sampling ADC) modules with TDCs.
179 57 Eric Fuchey
180 99 Eric Fuchey
h4. Data structure extension for "Cal" detector types:
181 57 Eric Fuchey
182
* nchan (int): number of channels (firing?)
183 66 Eric Fuchey
* chan (std::vector<int>) channel number
184 57 Eric Fuchey
* adc (std::vector<int>) unencoded pedestal subtracted ADC value
185
186 100 Eric Fuchey
h4. Data structure extension for "Scint", "Cher" detector types:
187 57 Eric Fuchey
188
* nchan (int): number of channels (firing?)
189 66 Eric Fuchey
* chan (std::vector<int>) channel number
190 57 Eric Fuchey
* adc (std::vector<int>) unencoded pedestal subtracted ADC value
191
* tdc_l (std::vector<int>) unencoded leading TDC value
192
* tdc_t (std::vector<int>) unencoded trailing TDC value
193
194 101 Eric Fuchey
h4. Data structure extension for "FADC" (HCal) detector types:
195 57 Eric Fuchey
196 67 Eric Fuchey
* nchan (int): number of channels (firing?)
197 102 Eric Fuchey
* chan (std::vector<int>) channel number
198 101 Eric Fuchey
* samp (std::vector<int>) sample number
199
* adc (std::vector<int>) unencoded pedestal subtracted ADC values for individual samples 
200 1 Eric Fuchey
* tdc (std::vector<int>) unencoded TDC value (optional: only for HCal at the moment)
201 100 Eric Fuchey
202 1 Eric Fuchey
h4. Data structure extension for "GEMs" detector types:
203
204 79 Eric Fuchey
* nstrips (int) number of strips (firing?)
205 66 Eric Fuchey
* module (std::vector<int>) module number
206 103 Eric Fuchey
* strips (std::vector<int>) strip number
207 1 Eric Fuchey
* samp (std::vector<int>) sample number
208 104 Eric Fuchey
* adc (std::vector<int>) unencoded pedestal subtracted ADC values for individual samples