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 "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 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 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 second 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 third 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 fourth 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. 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 (one per GEM plane):

* nstrips (int) number of strips (firing?)

* strips (std::vector<int>) strip number

* adc_i (i = 0 -> 5) (std::vector<int>) unencoded pedestal subtracted ADC values for sample i