Project

General

Profile

Documentation of libsbsdig » History » Revision 80

Revision 79 (Eric Fuchey, 09/30/2020 04:51 PM) → Revision 80/120 (Eric Fuchey, 09/30/2020 05:03 PM)

h1. Documentation of libsbsdig 

 {{toc}} 

 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 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. 
 It is a standalone program which can run with a limited number of outputs (see section on usage). 
 These produce files which can be analyzed with SBS-offline [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline]. 

 h2. Getting the code and building the program 

 h3. Prerequisites 

 * Working ROOT [https://root.cern.ch/drupal/] installation. ROOT 6 is strongly recommended. 
 * Working G4SBS [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_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_. 
 *Beware that the current version of libsbsdig is not on the "master" branch, but on the "sbsdig_lw".* 

 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 

 When sbsdig is installed in your machine, you can run the program using up to 4 arguments: 

 bq. sbsdig db_gmn_conf.dat gmn13.5_elastic_ex.txt 100000 gmn13.5_beambkgdhistos.root 1.0 

 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. 
 *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) 
 *The second argument is a list of "signal" files to digitize. It is mandatory to provide. An example is provided in the files attached. 
 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  
 *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. 
 *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 
 It can be ignored if one seeks to digitize signal with no background. An example is provided in the files attached. 
 *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. 

 

 h2. Input files documentation 

 h3. Configuration file 
 This part describes the expected parameters for the configuration file (first argument for sbsdig), with the name, nature, and expected type: 

 Rseed (int): seed for random number generator 
 TriggerJitter (float): global trigger jitter for all detectors in ns 

 detectors_list (strings, may take several arguments): list of detectors to digitize 
 Currently implemented: 
 hcal 
  bbps bbsh grinch bbhodo prpolscint_bs  
 bbgem  


 



 h2. Root output documentation 

 The new digitization library will expand the TTree object from the input file to add ADC and TDC values. 
 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]. 
 The basic idea is that for each detector in the input tree, a set of branches will be added. 

 There are several types of detectors in G4SBS (GEM, CAL, RICH), but there is not always a defined extension for a G4SBS detector type. 
 (NB: I'm voluntarilly omitting ECAL,  
 For the purpose of the digitization, it is more convenient to define the following types of detectors: 
 * GEM: GEM trackers. Corresponds unambiguously to GEM detector type in G4SBS. Read out by MPD (sampling ADC) modules. 
 * Cher: Cherenkov detectors (example: GRINCH). Corresponds unambiguously to RICH detector type in G4SBS. Read out by TDC modules (with optional ADCs). 
 * Scint: Scintillator timing detectors (example: Timing Hodoscope). Corresponds to CAL detector type in G4SBS. Read out by TDC modules (with optional ADCs). 
 * Cal: Calorimeter (example: BBPS, BBSH). Corresponds to CAL detector type in G4SBS. Read out by ADC modules. 
 * HCal: Hadron Calorimeter. Corresponds to CAL detector type in G4SBS. Read out by FADC (sampling ADC) modules with TDCs. 

 h4. (proposed) data structure extension for "Cal" detector types: 

 * nchan (int): number of channels (firing?) 
 * chan (std::vector<int>) channel number 
 * adc (std::vector<int>) unencoded pedestal subtracted ADC value 

 h4. (proposed) data structure extension for "Scint", "Cher" detector types: 

 * nchan (int): number of channels (firing?) 
 * chan (std::vector<int>) channel number 
 * 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 

 h4. (proposed) data structure extension for "HCal" detector types: 

 * nchan (int): number of channels (firing?) 
 * chan (std::vector<int>) channel number 
 * adc_i (i = 0 -> 19) (std::vector<int>) unencoded pedestal subtracted ADC values for sample i 
 * tdc (std::vector<int>) unencoded TDC value 

 h4. (proposed) data structure extension for "GEMs" detector types: 

 * nstrips (int) number of strips (firing?) 
 * module (std::vector<int>) module number 
 * strips (std::vector<int>) strip number 
 * adc_i (i = 0 -> 5) (std::vector<int>) unencoded pedestal subtracted ADC values for sample i