Project

General

Profile

Documentation of libsbsdig » History » Version 89

Eric Fuchey, 09/30/2020 08:35 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 41 Eric Fuchey
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.
11 1 Eric Fuchey
12
h2. Purpose
13
14 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.
15 37 Eric Fuchey
It is a standalone program which can run with a limited number of outputs (see section on usage).
16 52 Eric Fuchey
These produce files which can be analyzed with SBS-offline [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline].
17 1 Eric Fuchey
18
h2. Getting the code and building the program
19
20
h3. Prerequisites
21
22 54 Eric Fuchey
* Working ROOT [https://root.cern.ch/drupal/] installation. ROOT 6 is strongly recommended.
23
* Working G4SBS [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs] installation.
24 1 Eric Fuchey
25
h3. Downloading the repository
26
27
The code is hosted on a github repository owned by JLab. To clone via ssh (preferred method on JLab batch farm), do: 
28 5 Eric Fuchey
29 1 Eric Fuchey
bq. git clone git@github.com:JeffersonLab/libsbsdig.git
30
31
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.)
32
33 51 Eric Fuchey
Cloning the repository defaults to the "master" branch. _As of August, 18th, 2020, the master branch still contains the old version of the code_.
34 72 Eric Fuchey
*Beware that the current version of libsbsdig is not on the "master" branch, but on the "sbsdig_lw".*
35 71 Eric Fuchey
36
To obtain the new version of the code currently being developped on the "sbsdig_lw" branch, do:
37 36 Eric Fuchey
38
bq. git checkout sbsdig_lw
39 1 Eric Fuchey
40
h3. Building and installing the library
41
42 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). 
43
You also need to have setup an installation path e.g. /path/to/libsbsdig-install
44
*NB*: similarly to the build directory, the /path/to/libsbsdig-install directory shall '''not''' be the same as the source directory!
45
_The following instructions assume that "build" is parallel to "libsbsdig":_
46 9 Eric Fuchey
If successful, the libsbsdig library and several other files and folders will be created in the "build" and the "install" directory.
47 1 Eric Fuchey
48 2 Eric Fuchey
To build and install, the procedure needs to be completed. From scratch:
49
50
bq. mkdir build
51
cd build
52
cmake -DCMAKE_INSTALL_PREFIX=/path/to/libsbsdig-install ../libsbsdig
53
make install
54 1 Eric Fuchey
55 3 Eric Fuchey
Then, the following line should be added in the OS login configuration file to take advantage of this functionality:
56
* source /path/to/libsbsdig-install/bin/sbsdigenv.sh (or source /path/to/g4sbs_install/bin/sbsdigenv.csh on the batch farm)
57 1 Eric Fuchey
58 13 Eric Fuchey
h2. How to use the digitization library
59 1 Eric Fuchey
60 37 Eric Fuchey
When sbsdig is installed in your machine, you can run the program using up to 4 arguments:
61 1 Eric Fuchey
62 78 Eric Fuchey
bq. sbsdig db_gmn_conf.dat gmn13.5_elastic_ex.txt 100000 gmn13.5_beambkgdhistos.root 1.0
63 33 Eric Fuchey
64 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.
65 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)
66
*The second argument is a list of "signal" files to digitize. It is mandatory to provide. An example is provided in the files attached.
67 77 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. In the example file sbsdig gmn13.5_elastic_ex.txt attached, you may want to 
68 78 Eric Fuchey
*The third argument is the number of process. It has a default value of "-1" (=2^64-1) so it can be left unprovided, unless one wants to provide argument 3 and 4.
69
*The fourth argument is a files containing the background histograms extracted from min-bias beam-on-target simulations Beware these histograms have to have a certain name. An example file and macros are attached
70 73 Eric Fuchey
It can be ignored if one seeks to digitize signal with no background. An example is provided in the files attached.
71 78 Eric Fuchey
*The fifth argument is the fraction of luminosity with respect to the experiment nominal luminosity, which determines the quantity of background to add to the signal. It's default value is zero, so it can be ignored if one seeks to digitize signal with no background.
72 25 Eric Fuchey
73 79 Eric Fuchey
h2. Input files documentation
74
75 80 Eric Fuchey
h3. Configuration file
76 1 Eric Fuchey
77 81 Eric Fuchey
This part describes the expected parameters for the configuration file (first argument for sbsdig). 
78
These parameters are presented as follows: name (expected type): nature of the 
79 1 Eric Fuchey
80 81 Eric Fuchey
* Rseed (int): seed for random number generator
81
* TriggerJitter (float): global trigger jitter for all detectors in ns
82 1 Eric Fuchey
83 81 Eric Fuchey
* detectors_list (strings, may take several arguments): list of detectors to digitize
84
Currently implemented:
85
hcal (hadron calorimeter, "pmt" type detector)
86
bbps (Big Bite calorimeter preshower, "pmt" type detector)
87
bbsh (Big Bite calorimeter shower, "pmt" type detector)
88
grinch (BigBite GRINCH cherenkov, "pmt" type detector)
89
bbhodo (BigBite timing hodoscope, "pmt" type detector)
90 1 Eric Fuchey
bbgem (BigBite GEM tracker, "gem" type detector)
91 89 Eric Fuchey
92
GEnRP detectors being added...
93 79 Eric Fuchey
94 88 Eric Fuchey
h4. Parameters for "pmt" type detector (name "det")
95 83 Eric Fuchey
96 88 Eric Fuchey
* NChan_det (int) number of PMTs
97
* gatewidth_det (float) size of the data acquisition window in ns 
98
* gain_det (float) PMT gain
99
* ped_det (float) channel pedestal mean
100
* pedsigma_det (channel)  channel pedestal sigma
101
* trigoffset_det (float) trigger offset to have the signal centered properly around zero
102
* ADCconv_det (float) fC/ADC channels conversion factor
103
* ADCbits_det (int) number of bits to store the ADC value
104
* TDCconv_det (float) ns/TDC channels conversion factor
105
* TDCbits_det (int) number of bits to store the TDC value
106
* sigmapulse_det (float) full width half max of PMT pulse
107 84 Eric Fuchey
108 86 Eric Fuchey
h4. Parameters for "gem" type detector (of name "detgem")
109 1 Eric Fuchey
110 87 Eric Fuchey
NPlanes_detgem (int): number of planes/modules/readout included in the tracker;
111
gatewidth_detgem (float): size data acquisition window for the in ns;
112
nstrips_detgem (array of ints): number of strips for each plane/module/readout; _array needs to be same size as NPlanes_detgem_
113
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_
114
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_
115
triggeroffset_detgem (array of floats): trigger offsets for all planes in ns _array needs to equal to NPlanes_detgem/2_
116
ZsupThr_detgem (float): zero suppression threshold for GEMs in ADC channels;
117
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
118 82 Eric Fuchey
119 1 Eric Fuchey
h2. Root output documentation
120 39 Eric Fuchey
121
The new digitization library will expand the TTree object from the input file to add ADC and TDC values.
122 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].
123 56 Eric Fuchey
The basic idea is that for each detector in the input tree, a set of branches will be added.
124
125
There are several types of detectors in G4SBS (GEM, CAL, RICH), but there is not always a defined extension for a G4SBS detector type.
126
(NB: I'm voluntarilly omitting ECAL, 
127
For the purpose of the digitization, it is more convenient to define the following types of detectors:
128
* GEM: GEM trackers. Corresponds unambiguously to GEM detector type in G4SBS. Read out by MPD (sampling ADC) modules.
129
* Cher: Cherenkov detectors (example: GRINCH). Corresponds unambiguously to RICH detector type in G4SBS. Read out by TDC modules (with optional ADCs).
130
* Scint: Scintillator timing detectors (example: Timing Hodoscope). Corresponds to CAL detector type in G4SBS. Read out by TDC modules (with optional ADCs).
131
* Cal: Calorimeter (example: BBPS, BBSH). Corresponds to CAL detector type in G4SBS. Read out by ADC modules.
132
* HCal: Hadron Calorimeter. Corresponds to CAL detector type in G4SBS. Read out by FADC (sampling ADC) modules with TDCs.
133 57 Eric Fuchey
134 62 Eric Fuchey
h4. (proposed) data structure extension for "Cal" detector types:
135 57 Eric Fuchey
136
* nchan (int): number of channels (firing?)
137 66 Eric Fuchey
* chan (std::vector<int>) channel number
138 57 Eric Fuchey
* adc (std::vector<int>) unencoded pedestal subtracted ADC value
139
140 62 Eric Fuchey
h4. (proposed) data structure extension for "Scint", "Cher" detector types:
141 57 Eric Fuchey
142
* nchan (int): number of channels (firing?)
143 66 Eric Fuchey
* chan (std::vector<int>) channel number
144 57 Eric Fuchey
* adc (std::vector<int>) unencoded pedestal subtracted ADC value
145
* tdc_l (std::vector<int>) unencoded leading TDC value
146
* tdc_t (std::vector<int>) unencoded trailing TDC value
147
148 61 Eric Fuchey
h4. (proposed) data structure extension for "HCal" detector types:
149 57 Eric Fuchey
150
* nchan (int): number of channels (firing?)
151 67 Eric Fuchey
* chan (std::vector<int>) channel number
152 57 Eric Fuchey
* adc_i (i = 0 -> 19) (std::vector<int>) unencoded pedestal subtracted ADC values for sample i
153 62 Eric Fuchey
* tdc (std::vector<int>) unencoded TDC value
154 1 Eric Fuchey
155 79 Eric Fuchey
h4. (proposed) data structure extension for "GEMs" detector types:
156 1 Eric Fuchey
157
* nstrips (int) number of strips (firing?)
158 79 Eric Fuchey
* module (std::vector<int>) module number
159 66 Eric Fuchey
* strips (std::vector<int>) strip number
160 69 Eric Fuchey
* adc_i (i = 0 -> 5) (std::vector<int>) unencoded pedestal subtracted ADC values for sample i