TWiki> LHCb Web>WebPreferences>TbUT (revision 23)EditAttachPDF

TbUT analysis software

This page provides information about the TbUT package. The software is a part of the Kepler project. The main aim of this software is to perform whole processing of the testbeam data using Gaudi framework.

Contact persons

Adam Dendek Mail


Follow these steps to setup TbUT in your working directory

  • Setup project and get source code from LHCb's SVN repository
    lb-dev Kepler v3r0
    cd ./KeplerDev_v3r0
    svn co svn+ssh://

  • Compile the source code
    make -j20
    make install

  • Mount EOS
    eosmount ~/eos

  • Prepare the running environment
    ./run bash

Running the TbUT software

The TbUT software can be run in two modes, Pedestal and Run. The description below contains instructions on how to run TbUT in standalone mode (no other Kepler stuff). You should also look at the Tools for the LHCb Software Environment TWiki page for a better understanding how to run Gaudi-like application.

Pedestal mode -- computing the pedestals

  • The aim of the pedestal training is to calculate the pedestals values, which will then be used in Run mode in order to subtract the pedestal from the raw data during execution of the Pedestal Subtraction algorithm.
  • In this mode only 2 algorithms are executed : Raw Data Reader and Pedestal Subtractor for more detailed description of this algorithms look to the developers section.
  • Preparation of the options. You just need to modify the file ( Tb/TbUT/options/ ):
    option name brief description
    app.inputData String, contains path to the input data (you have to set this, see NOTE below)
    app.isAType Boolean, choose if sensor is type A (true) or D (false)
    app.eventMax Integer, number of event to process String, contains path to the output file (contains pedestal values in a flat list).

  • NOTE: The input files are located on EOS. Currently, you either need to copy files from EOS to a local directory (you will run out of space fast) or you can mount eos temporarily
    • To mount EOS:
       eosmount ~/eos 
      If you do this, please add
      eosumount ~/eos
      to your ~/.logout file.
    • July 2015 testbeam files for board D9, for example, are located here: eos/lhcb/testbeam/ut/OfficialData/July2015/BoardD9/RawData/*.dat

  • Run the TbUT in Pedestal mode:
       cd Tb/TbUT options/
  • After the execution of the application, the output file contains pedestal values, one number per channel is output. The name of the file is specified in the options file ( line app.pedestalOutputData )

Run mode

  • In run mode the TbUT performs the whole processing of testbeam data.
  • In this mode all processing algorithms are executed.
    algorithm brief description
    Raw Data Reader Reads raw data from the DUT (Mamba board output) and saves the output into the TES
    Pedestal Subtractor Gets raw data from the TES, removes the calculated pedestals from the Pedestal mode run, and stores the output into theTES
    Common Mode Subtractor (CMS) Gets data after Pedestal Subtraction; removes the common mode noise, a single value per 32 Beetle channels (mean value of ADC); save the output into the TES
    Cluster Creator Gets data after CMS, create clusters and saves it information in the TES

Beyond the listed algorithms, a set of corresponding monitoring algorithms has been implemented. The detailed descriptions of processing and monitoring algorithms see developers section.

  • Preparation of the options. You just need to modify the file ( Tb/TbUT/options/ ):
    option name brief description
    app.inputData type of string, contains path to the input data (use an absolute path, e.g. "/afs/"
    app.isAType type of Boolean, choose if sensor is type A (true) or D (false)
    app..sensorType type of String, choose if sensor is P-type ("PType") or N-type ("NType") or both - calibration run ("Both")
    app.eventMax type of integer, number of event to process
    app.pedestalInputData type of string, contains path to pedestal file (created during execution TbUT in Pedestal mode)
    app.eventNumberDisplay type of integer, informs how many event snapshots will be saved (see section exemplary outputs )

  • Running TbUT in Run mode:
    cd Tb/TbUT options/
  • This needs to be run twice in order to properly determine clusters

DUT and Telescope analysis

  • These steps require running with a ROOT version 5, so it is helpful to type the following before running the combination of DUT and telescope data:
LbLogin -c x86_64-slc6-gcc48-opt
SetupProject LHCb v36r2
This ensures the proper root version will be used
  • After computing pedestal and CMS, the data from the DUT can be combined with the information from the telescope. Once in the Tb/TbUT directory, the script for appending the DUT data with the telescope data can be run by doing the following:

cd scripts/AddTrigTracks
./combDUTwithTrack -i ~/inputDUT_Tuple.root -t ~/eos/lhcb/testbeam/ut/TelescopeData/July2016/RootFiles/RunXXXX/Output/Kepler-tuple.root -n ~/inputDUT_noise.root -o outputFile.root
where inputDUT_Tuple.root is the file resulting from the the run mode, inputDUT_noise.root is the file containing the noise information (nominally the same as inputDUT_Tuple.root but without the 'Tuple' appendage), ~/Kepler-tuple.root is the data from the telescope, and outputFile.root is the desired output file name.

  • Once the track information has been appended to the DUT tuple file, the final set part of the analysis can be run. This includes calculation of various quantities (efficiency, correlation between DUT X and Track X, etc.).
  • Begin with supplying the output file from the previous step into ~/TbUT/scripts/ClusterWithTrackAna.h. This should be a string called "filename".
  • In ~Tb/TbUT/scripts/AnalysisBase_Inputs.h, one needs to specify various parameters given below
    parameter value description
    m_board "M1", "M3" or "M4" Board type
    m_bias e.g. 200 Bias voltage in volts
    m_sector "PA" or "C" Pitch adapter region or Central region
    m_scanType "Bias" or "Angle" Defines if this is a bias scan run or and angle scan run
    nChan e.g. 512 The total number of channels
    stripPitch e.g. 0.190 The strip pitch in mm
    isPtype true or false where this is n-in-p (p type) or p-in-n (n type)

Analyze DUT data with tracking

  • The final scripts can now be run using the following (if you are in ~Tb/TbUT/scripts/)
root [0]   .L TBrunClusterWithTrackAna.C 
root [1]   TBrunClusterWithTrackAna("the/full/path/Run_Angle_Scan-M1-FanIn-88-15046_Tuple_Tracks.root","M1","2","300")
The arguments of TBrunClusterWithTrackAna are the filename, the sensor ID, the sector and the bias voltage. A ROOT file will be written to the location specified in "AnalysisBase_Inputs.h" (currently $HOME/lhcb/testbeam/root_files/ )

* A pair of "summary" plots can then be produced using the *monitorPlots.C" macro:

root [0]   .L monitorPlots.C 
root [1]   monitorPlots("M1","2","300")     

Two canvases will be produced, one with Alignment information and one with Performance information. They should be hecked by the user. Below is an example for Run 15046, sensor M1, 300 V bias, 0 degree rotation angle

  • Alignment Plots


  • Performance Plots


Known issues

  • The TbUT cannot read eos files. *workaround: copy analyzed file into your work directory or use eosmount as shown above.
  • TbUT (run mode) need to be executed twice to correct calculate noise and extract clusters.
  • The tools should inherit from GaudTool class.
  • The unit test have to be implemented

Developers section

General overview

Every TbUT component class is a member of TbUT namespace.


The TbUT is a Gaudi based application. The application is separated into two sets of Gaudi algorithms. First group is responsible for processing the testbeam data. This algorithms inherit from GaudiAlgorithm class. The names of it contains string Algorithm for instanceTbUTRawDataReaderAlgorithm .

To understand TbUT source code, the algorithm classes should be treated as a starting point

The second group was designed to prepare monitoring plots. This classes inherit from base called TbUTDataMonitorAlgorithm ( see also implementation ). According to the file name convention it's names have to contains string DataMonitorAlgorithm in their's file names. E.g. TbUTPedestalSubtractorDataMonitorAlgorithm .


That kind of classes are responsible of performing the data modification. Each of this inherit from virtual interface called IProcessingEngine, therefore they have to implement processEvent method.

Tool's Factories

This kind of classes are responsible for dynamic, depend of options, creation of proper version of tools. This classes based on Factory design pattern (see also the beautiful explanation why is is so useful). See for example Raw Data Reader Factory and it implementation

Other types

  • Data structures (inherits from GaudiKernel/DataObject ) are used to be manipulated via the tools and be stored in TES. The TbUT package contains Raw Data and Clusters .
  • Additional data structures. Can be distinguished noise and pedestals. Their are used as a auxiliary structures by the tools.
  • Additional services. Used for manipulation of the additional data structures. See for instance Noise Calculator. Each of this services has own interface ( e.g. Noise calculator are based on INoiseCalculator).

TbUT high level architecture

TbUT high Level architecture

Description of the algorithms

Raw Data Reader

This algorithm is designed to read raw data from specific input file. Currently TbUT can work with files produced by Alibava and Mamba DAQs. The heart of this algorithm is tool inherit from interface IDataReader. This tool acts fascade for specific DAQ reader.

The execution of Raw Data Reader can be modified using options:

option name brief description
InputDataType type of string, choose one of DAQs data format (Mamba or Alibava)
inputData type of string, path to the input data.
standalone type of boolean, if is true the run is executed with Kepler (haven't been tested yet)

Pedestal Subtractor

The pedestal subtraction algorithm has two phases. In first, optional one, the pedestal values are calculated. This phase is also called training. During the second one the determined pedestal values are subtracted from the raw ADC data. From technical point of view the Pedestal Subtractor Algorithm calls two types of tools. One of them calculates or retrieves pedestals values( this classes inherit from I pedestal following ) and the second one remove pedestals values from the raw data. See data flow.


The execution of Pedestal Subtractor Algorithm can be modified using options:

option name brief description
FollowingOption type of string, choose type of execution (training or run)
treningEntry type of integer, number of training entry
ChannelMaskInputLocation type of string, location of the channel mask
PedestalInputFile type of string, path to the location where previously calculated pedestals are stored
PedestalOutputFile type of string, path to the location where calculated pedestal have to be stored
standalone type of boolean, if is true the run is executed with Kepler (haven't been tested yet)

Pedestal following

From the mathematical point of view the calculation of the pedestal can be described as a running average. In every training event then pedestal sum is updated. This update takes into account the previous value of the pedestal sum and the current ADC count. The pedestal sum is calculated for each channel separately. To be more precisely, the pedestal sum, $p_i(n)$, for channel $n$ and event $i$ can be expressed as follows:

$P_{i}^{sum}(n+1)=P^{sum}_{i}(n) + \frac{\Delta_{i}(n+1)}{N}$

Where the $\Delta_{i}(n+1)$ is a event to pedestal correction. This correction is expressed as:


To increase the suitability of the pedestal the limit for correction is applied. If the condition: $ \left| \Delta_{i}(n+1) \right| \leq 15  $ is not fulfilled the correction value is set to 15.

To determinate the pedestal values the pedestal sum should be normalized, so: $p_{i}=\frac{P^{sum}_{i}}{N}$

Pedestal removing algorithm

The second phase of the pedestal subtraction algorithm is subtraction determined pedestal values from the raw data. This procedure can be expressed as fallows:


where: $ADC_{i}$ is signal value after pedestal subtraction for event $i$, $ADC^{RAW}_{i}$ is a raw data and the $p_{i}$ is the pedestal value. Each of this quantities are in the unit of ADC counts.

Additional scripts

All scripts are stored in TbUT/scripts directory. (Not yet committed)
  • Noise monitor This script takes as an input noise file. The exemplary output:


-- AdamMateuszDendek - 2015-08-03

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng AlignmentPlots_M1_s2_vb300.png r1 manage 42.4 K 2016-05-13 - 22:19 UTTestbeamService  
PNGpng Landau_example.png r1 manage 0.9 K 2016-05-10 - 07:37 ChristopherBetancourt1 Example plots from runClusterWithTrackAna.C
PNGpng Pedestal_Subtrator.png r1 manage 53.7 K 2015-08-26 - 19:21 UnknownUser Pedestal Subtractor Data Flow
PNGpng PerformancePlots_M1_s2_vb300.png r1 manage 60.7 K 2016-05-13 - 22:19 UTTestbeamService  
PNGpng TbUT_Architecture.png r1 manage 103.6 K 2015-08-26 - 18:26 UnknownUser TbUT high level architecture
PNGpng Thresholds.png r1 manage 27.8 K 2015-08-26 - 13:59 UnknownUser  
PNGpng corr_example.png r1 manage 4.3 K 2016-05-10 - 07:39 ChristopherBetancourt1 Example plots from runClusterWithTrackAna.C
PNGpng profile_example.png r1 manage 0.9 K 2016-05-10 - 07:40 ChristopherBetancourt1 Example plots from runClusterWithTrackAna.C
PNGpng res_example.png r1 manage 0.8 K 2016-05-10 - 07:40 ChristopherBetancourt1 Example plots from runClusterWithTrackAna.C
Edit | Attach | Watch | Print version | History: r25 < r24 < r23 < r22 < r21 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r23 - 2016-05-13 - UTTestbeamService
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    LHCb All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback