Documentation of libsbsdig » History » Revision 37
Revision 36 (Eric Fuchey, 08/18/2020 10:05 PM) → Revision 37/120 (Eric Fuchey, 08/18/2020 11:04 PM)
h1. Documentation of libsbsdig 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 transform the Monte Carlo simulations of the SBS experiments produced by output data from [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs G4SBS] to produce digital values such as 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 [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_SBS-offline SBS-offline]. h2. Getting the code and building the program h3. Prerequisites *Working [https://root.cern.ch/drupal/ ROOT] installation. '''libsbsdig is compatible with ROOT version 5 and ROOT version 6'''. '''''ROOT 6 is strongly recommended''''' *Working [https://hallaweb.jlab.org/wiki/index.php/Documentation_of_g4sbs 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'''. 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 Working example scripts using the SBS-offline are available in the SBS-offline repository in the replay directory. An example of script is installed in your machine, you replay_diggmn_test.C h2. Root output documentation For each detector, several structures are stored under the form of an ensemble of vectors of integers and doubles. There are three types of structures: * the "trackmchits" storing the information of the Monte Carlo track intercepting the detector; * the "simhits" storing the true energy deposits and corresponding number of photoelectrons for each g4sbs hit processed by libsbsdig; * the "hits", storing the adc and tdc information; h3. "trackmchit" structure The full name of such variables for a given detector is <detector_full_name>.trackmchit.<varname>, where <varname> can run be: * nhits (int): number of entries stored for this structure and this detector * source (std::vector<short>): type of file where the program using up MC track comes from (0 if signal, >0 if background) * trid (std::vector<short>): track ID in G4SBS (mostly useful to 4 arguments: distinguish primary tracks) * pid (std::vector<int>): track PDG PID * xhit (std::vector<double>) estimated point of intercept of the track at the detector surface, projected in the dispersive direction x (transport coordinates) * yhit (std::vector<double>) estimated point of intercept of the track at the detector surface, projected in the non-dispersive direction y (transport coordinate) * thit (std::vector<double>) estimated time of intercept of the track at the detector surface * e (std::vector<double>) track total energy * weight (std::vector<double>) weight of the event from which the track is issued (not implemented yet) bq. sbsdig gmn13.5_elastic_prod.txt 100000 gmn13.5_beambkgd_prod.txt 15 For the GEMs, the full track info is stored (but the intersect points with each of the GEM layers aren't). These arguments have The full name of such variables for a given detector is <detector_full_name>.mctrack.<varname>, where <varname> can be: mctrack_ntracks (int) number of tracks stored * source (std::vector<short>): type of file where the MC track comes from (0 if signal, >0 if background) * trid (std::vector<short>): track ID in G4SBS (mostly useful to come distinguish primary tracks) * pid (std::vector<int>): track PDG PID * x (std::vector<double>): track position x at z = 0 (transport coordinates) * y (std::vector<double>): track position y at z = 0 (transport coordinates) * t (std::vector<double>): track time at z = 0 * p (std::vector<double>): track momentum * dx (std::vector<double>): track slope projected in the dispersive direction x (transport coordinates) * dy (std::vector<double>): track slope projected in the non-dispersive direction y (transport coordinates) * xv (std::vector<double>): track vertex x at target (if applicable) * yv (std::vector<double>): track vertex y at target (if applicable) * zv (std::vector<double>): track vertex z at target (if applicable) * pxv (std::vector<double>): track momentum x at target (if applicable) * pyv (std::vector<double>): track momentum y at target (if applicable) * pzv (std::vector<double>): track momentum z at target (if applicable) * weight (std::vector<double>) weight of the event from which the track is issued (not implemented yet) h3. "simhit" structure The full name of such variables for a given detector is <detector_full_name>.simhit.<varname>, where <varname> can be: * nhits (int) number of entries stored for this sequence, structure and while this detector * src (std::vector<short>): type of file where the sim hit comes from (0 if signal, >0 if background) * trid (std::vector<short>): ID of track responsible of hit in G4SBS (n. i. y.) * pid (std::vector<int>): PDG PID of track responsible of hit in G4SBS (n. i. y.) * chan (std::vector<short>): channel number in which the hit is recorded * edep (std::vector<double>): energy deposit recorded in g4sbs (in GeV) * npe (std::vector<int>): recorded or estimated number of photoelectrons detected * time (std::vector<double>): time of hit as recorded by g4sbs * t_lead(std::vector<double>): estimated time when the pulse rises over threshold (for detectors with TDCs) * t_trail(std::vector<double>): estimated time when the pulse falls under threshold (for detectors with TDCs) Note: for calorimeters without TDCs, t_lead and t_trail are not applicable and will not be stored; for cherenkov detectors, edep is not applicable and will not be stored; The structure above is valid for all arguments are mandatory to provide, one cannot skip an argument unless they want to skip all following arguments. detectors except GEMs. The structure for GEMs sim hits is: * nhits (UInt_t) number of entries stored for this structure and this detector *The first argument * src (std::vector<short>): type of file where the sim hit comes from (0 if signal, >0 if background) * trid (std::vector<short>): ID of track responsible of hit in G4SBS (n. i. y.) * pid (std::vector<int>): PDG PID of track responsible of hit in G4SBS (n. i. y.) * plane (std::vector<short>): layer number of the GEM in which the hit is a list recorded * module (std::vector<short>): module number of "signal" files to digitize. It the GEM in whcih the hit is mandatory to provide. recorded *The second argument is * edep (std::vector<double>): energy deposit recorded in g4sbs (in GeV) * time (std::vector<double>): time of hit as recorded by g4sbs * xpos (std::vector<double>): x position of hit in GEM module (transport coordinates) * ypos (std::vector<double>): y position of hit in GEM module (transport coordinates) * px (std::vector<double>): x momentum of the track in transport coordinates * py (std::vector<double>): y momentum of the track in transport coordinates * pz (std::vector<double>): z momentum of the track in transport coordinates * sizex (std::vector<short>): number of process. It has a default value strips on the x readout that receive _any_ signal from the GEM avalanche * sizey (std::vector<short>): number of "-1" (=2^64-1) so it can strips on the y readout that receive _any_ signal from the GEM avalanche * startx (std::vector<short>): lowest x strip number that receive _any_ signal from the GEM avalanche * starty (std::vector<short>): lowest y strip number that receive _any_ signal from the GEM avalanche Notes: - the 4 last variables should be left unprovided, unless one wants interpreted as such: the GEM avalanche will spread from strip #startx(y) to provide argument 3 strip #startx(y)+sizex(y) - 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). h3. "hit" structure The full name of such variables for a given detector is <detector_full_name>.hit.<varname>, where <varname> can be: * nhits (int) number of entries for this structure and 4. this detector *The third argument * chan (std::vector<short>) channel number in which the hit is recorded * dataword (std::vector<unsigned int>) encoded data word containing the ADC/TDC; may also store headers (useful for simulation decoding) * 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 Note: when a list "header" is stored in dataword, the channel number stored is -1. *Particular case of "background" files (usually min-bias beam-on-target) to superimpose to detector read out by sampling ADCs (GEMs MPDs, HCal FADCs): In this case, storing each sample with the signal to digitize. It can structure about would be ignored if one seeks to digitize signal with no background. too inefficient in terms of disk space. Hence, for this very specific case, we use vectors of evectors * nsamps (std::vector<unsigned int>) number of ADC samples (number of elements in vector samps_adc, see note below) *The fourth argument * samps_adc (std::vector<vector<int> >) unencoded pedestal subtracted ADC values (samps_adc[i][j] = sample j for hit i) * datawords (std::vector<vector<unsigned int> >) datawords containing the encoded GEMs. _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 "background" files to superimposeto the signal to digitize. It's default value elements in vector datawords is zero, so it can be ignored if one seeks to digitize signal with no background. h2. Root output documentation stored in variable dataword.