SBS Software

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). 

-As of February 14, 2020 is specific to the sbsdig_lw branch of libsbsdig on github.-

As of April 2022, those instructions also apply to the master 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

h4. for simple users

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 April, 25th, 2022, the most up-to-date version of the code and the databases is located on 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".-

* Have an individual github account.

* On github.com: Fork the JeffersonLab libsbsdig to your account. Setup to “watch” Jlab libsbsdig

* git clone git@github.com:GithubUserName/libsbsdig.git (This is ssh access). 

** This will be the “origin” remote repo;

** Create your own branch: git checkout –b NewBranchName

* git remote –add upstream git@github.com:JeffersonLab/libsbsdig.git

** This will be the “upstream” remote repo

* You can pull ( or fetch/merge) changes from the upstream (Jefferson Lab) repo.

* You can push commits in your branch to the origin (Personal Github) repo and then make pull requests.

The most up-to-date version of the code is now available on the master branch.

-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 "libsbsdig" directory in any case). 

You also need to have setup an installation path e.g. /path/to/libsbsdig-install

For instance, you can create it parallel to your libsbsdig directory (with the mkdir command), even though it is not strictly required

*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/libsbsdig-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

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. 

This file may also optionally contain the input for background superimposition (see next section). 

*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.

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.

h2. Input files documentation

h3. List of data files

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:

bq. endlist

Then the background information can be added:

bq. gmn13.5_beambkgdhistos.root 100000000 30.e-5 0

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.

The following line can also be added after the background file:

bq. end_bkgdinfo

Note:

A script to generate the background histograms for GMn is available at:

https://github.com/JeffersonLab/libsbsdig/blob/master/scripts/GMnBeambkgdSample.C

h3. Configuration file

This part describes the expected parameters for the configuration file (first argument for sbsdig). 

These parameters are presented as follows: name (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 (hadron calorimeter, "pmt" type detector)

bbps (Big Bite calorimeter preshower, "pmt" type detector)

bbsh (Big Bite calorimeter shower, "pmt" type detector)

grinch (BigBite GRINCH cherenkov, "pmt" type detector)

bbhodo (BigBite timing hodoscope, "pmt" type detector)

bbgem (BigBite GEM tracker, "gem" type detector)

ecal (GEp electromagnetic calorimeter, "pmt" type detector)

cdet (coordinate detector for GEp electron arm, "pmt" type detector)

ft (GEp front tracker, "gem" type detector)

fpp1 (GEp focal plane polarimeter 1, "gem" type detector)

fpp2 (GEp focal plane polarimeter 2, "gem" type detector)

GEnRP detectors being added...

h4. Parameters for "pmt" type detector (name "det")

* NChan_det (int) number of PMTs

* gatewidth_det (float) size of the data acquisition window in ns 

* gain_det (float) PMT gain

* ped_det (float) channel pedestal mean

* pedsigma_det (channel)  channel pedestal sigma

* trigoffset_det (float) trigger offset to have the signal centered properly around zero

* ADCconv_det (float) fC/ADC channels conversion factor

* ADCbits_det (int) number of bits to store the ADC value

* TDCconv_det (float) ns/TDC channels conversion factor

* TDCbits_det (int) number of bits to store the TDC value

* sigmapulse_det (float) full width half max of PMT pulse

h4. Parameters for "gem" type detector (of name "detgem")

* NPlanes_detgem (int): number of GEM modules x number of readout planes (usually 2) included in the tracker;

* gatewidth_detgem (float): size data acquisition window for the in ns;

* nlayers_detgem (int): number of GEM layers (ensemble of GEM modules at a same z)

* detgem_layer_z (array of floats): z value of each layer (should match number of layers); 

* layer_detgem (int): layer to which the plane/module/readout belongs; _array needs to be same size as NPlanes_detgem_

* nstrips_detgem (array of ints): number of strips for each plane/module/readout; _array needs to be same size as NPlanes_detgem_

* 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_

* 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_

* triggeroffset_detgem (array of floats): trigger offsets for all planes in ns _array needs to equal to NPlanes_detgem/2_

* ZsupThr_detgem (float): zero suppression threshold for GEMs in ADC channels;

* 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

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. 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. 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. Data structure extension for "FADC" (HCal) detector types:

* nchan (int): number of channels (firing?)

* chan (std::vector<int>) channel number

* samp (std::vector<int>) sample number

* adc (std::vector<int>) unencoded pedestal subtracted ADC values for individual samples 

* tdc (std::vector<int>) unencoded TDC value (optional: only for HCal at the moment)

h4. 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

* samp (std::vector<int>) sample number

* adc (std::vector<int>) unencoded pedestal subtracted ADC values for individual samples