A description of all (important) functions

• Initializes all necessary QDC and TDC arrays
• Initializes Time and Energy Calibration objects FATIMA_T_CALIB and FATIMA_E_CALIB
• Loads boardID + channel_num to detector_ID allocation file

• Check if first word is QDC or TDC related
• while(!TDC_Called){...} loop over QDC data until TDC header is reached
• if TDC is reached, analyze TDC data

• inside for(int j = 7;j >= 0;j--) identify fired channels (and amount of fired channels) on QDC board
• for(int i = 0;i < num_channels_fired;++i): get detector id and QDC related data (Qlong,time,...)
• Calibrate data

• while(!trail) check for data until TDC trailer is reached
• get TDC data and calibrate it
• Exception: detector Ids 50 and 51 belong to PLASTIC for timing!

• send important data to RAW object(QLong,QShort,QDC_Time_Coarse,QDC_Time_Fine,TDC_Time,QDC_hits,TDC_hits,...)

The Fatima MBS Stream can be seen in the picture below.

---

---

• the first five words belong to the White Rabbit Time Stamp (red)
• a000000x is the first FATIMA word. The first a is the FATIMA identifier and the last value the number of all QDC words (on the respective QDC). If it is 4, there is no data inside the QDC.
• 30000000 describes the fired channel ids and the board id. The first five bits (from left) form the boardID, the first 8 bits (from right) the fired channel ids (binary coded). Each QDC has 8 channels. Hence the maximum value would be xxxxxxff (x not important). This has to be read in binary. E.g. 38000003: the last two values 03 are 0000 0011 in binary, meaning channel 1 and 2 fired.
• 00000000 to 00000082 are skipped (at the moment)
• 000368ef all 32 bits form the QDC time
• 000000e7's first (from left) 16 bits are extra time, 6 bits for additional flags and 10 bits for fine time
• 10850baf's first (from left) 16 bits are Qlong, followed by an empty bit and 15 bits forming Qshort
• 4139e969 is the TDC header word. All QDC words (from all fired boards) come before this word.
• 0001d345 is one of the TDC channel words. Its first 5 bits (from left) are empty, followed by the trailing or leading bit (not used at the moment). The next 5 bits form the channel ID followed by 21 bits belonging to the time (has to be multiplied by 25 to get the time in picoseconds). Each fired TDC channel has its own word. The trailer is used as an "end of stream flag".
• 80000069 is the TDC trailer word. It's the last (meaningful) word in the FATIMA subevent MBS stream.

The FATIMA specific configuration files are:

• FATIMA_allocation.txt
• FATIMA_Energy_Calibration.txt
• FATIMA_QDC_Time_Calibration.txt
• FATIMA_Time_Calibration.txt
• FATIMA_Gain_Match_Files

This maps the geo address and channel number of the TDC and QDC modules to a given detector number. The file is formatted as:

Detector Number	QDC Geo Address	QDC Channel Number	TDC Geo Address	TDC Channel Number	Enabled?
0	6	3	9	5	1

So for example the line: 0 6 3 9 5 1, would mean that Channel 3 on the QDC with geo address 6 and channel 5 on the TDC with geo address 9 refer to detector 0, and that detector 0 is enabled (Enabled? = 1). The detector number refers to the physical detector inside FATIMA and allow the code to correlate QDC and TDC data to a single detector.

If this file is not set up correctly the data will be allocated incorrectly which will cause issues for calibrations and histogram building.

All the FATIMA calibration files are formatted with detector number in the left column, and coefficients/offsets are listed in the subsequent columns. The energy calibration is carried out as follows:

Calibrated Energy = a*raw_energy⁴ + b*raw_energy³ + c*raw_energy² + d*raw_energy + e

As this method requires multiple coefficients the coefficient columns are listed in alphabetical order (using the alphabetical allocation given above). Uncalibrated spectra are provided, but if no calibration is desired simply set d to 1.0 and all other coefficients in the file to 0.0.

Both FATIMA time calibrations (QDC and TDC) are simple offsets, i.e Calibrated Time = raw_time + time_offset, so these files are formatted as two columns; detector number and time offset. Where the time offset is calculated as the offset from a reference detector. If no time calibration is required simply set the offsets to 0.0.

If Gain Matching is required, firstly in FATIMA_Detector_System.cxx gain_match_used should be set to true, and if First_Test.cxx FAT_gain_match_used should be set to true.

The gain match files are stored in the Configuration_Files/FATIMA_Gain_Match_Files directory, and should be formatted in the same way as the Energy Calibration files, but with only d and e as coefficients (so three columns in total). The filenames for the gain match files should also match the filenames of the data but with the extension .gm as shown below:

Data Filename = FATIMA_datafile_06.lmd

Gain Match Filename = FATIMA_datafile_06.gm

This naming is independent of the path of the data file.

If the program cannot find a correctly named gain match file in the FATIMA_Gain_Match_Files directory it will produce an error message and the analysis will stop.