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

These parameters are presented as follows: name (expected type): nature of the 

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