Introduction to the test beam software framework (tbsw)

The test beam software framework (tbsw) deals with the reconstruction and analysis of test beam data obtained with the EUDET/AIDA reference telescope. Test beams are all about learning about a device under test, or DUT, installed in the centre of the reference telescope. The device under test is position sensitive detector, typically a pixel or strip silicon sensor. The idea is to probe the device under test with charged tracks crossing the DUT at known times and precisely estimated kinematic parameters.

The tbsw framework is designed to run on local machines (Desktop / Laptop) to enable detector groups doing their own data analysis right during the beam test (or shortly afterwards). Some effort was invested to make this as smooth and simple as possible. The installation of the framework is covered in INSTALL.

A testbeam paper describing also the algorithms behind tbsw in some detail can be found here: https://doi.org/10.1016/j.nima.2020.164978

For the impatient reader: The text below is a step by step instruction how to run the code on raw data

After installation, the root directory of tbsw contains a 'workspace' folder. The first step to analyse data from a new beam test is to make a working copy of this folder. For example:

$ cp -r workspace ~/workspace-my-beam-test

The idea of the folder 'workspace-my-beam-test' is to collect all steering files and analysis results from a specific beam test. Please replace the 'my-beam-test' part with something more specific like 'desyoctober2016' or similar. For simplicity, we will call this folder just workspace in the following.

It is a good idea to copy the workspace to some place outside of the tbsw installation. In case you want to reprocess your data with a new (different) version of tbsw, you typically just have to make sure the environment variables in 'init_tbsw.sh' point to the desired installation.

Raw data files (.raw) should not be stored directly in your workspace folder. Again, this simplifies switching versions of tbsw. It is advised collect all raw data files in a seperate folder.

For example:

$ mkdir path-to-big-disk/rawdata-my-beam-test

Raw data from a one week beam test is typically ~1TB and fits on most Desktop PCs or laptops.

Next, go to your new workspace folder and setup all environment variables.

$ . init_tbsw.sh

A test beam with the EUDET/AIDA telescope results in a number of .raw files. Each raw file corresponds to a particular run having a specific test beam geometry, beam energy and DUT configuration. Before we can start with the reconstruction and analysis of data, we need to prepare a set of steering files to describe this situation.

In order to have an introductory example, we will perform a simulation experiment. In this way, we do not need access to real test beam data but generate the raw data for one run by our own. The added benefit of this approach is that we can compare the reconstructed data with the simulated truth data. The steerfiles folder 'workspace/steering-files/depfet-tb/' contains:

• geardesyW11OF2.xml: Telescope geometry file, describes a Belle II PXD sensor installed in the EUDET telescope (6x M26 planes and a FEI4 timing plane)
  

The Python script example.py runs us through all steps of the example which includes the generation of simulated data, the calibration of telescope data and the full reconstruction with final calibration constants.

You can run the script by typing:

$ python example.py

In case the script is working, your console should display messages like:

``` benjamin@benjamin-ThinkPad-T470s:~/Desktop/TBSW/tbsw/workspace$ python example.py [INFO] Misalign position of plane with ID 0 [INFO] Misalign position of plane with ID 1 [INFO] Misalign position of plane with ID 2 [INFO] Misalign position of plane with ID 3 [INFO] Misalign position of plane with ID 4 [INFO] Misalign position of plane with ID 5 [INFO] Misalign position of plane with ID 21 [INFO] Misalign position of plane with ID 7 [INFO] Misalign position of plane with ID 6 [INFO] Starting to simulate a test beam run ... [INFO] Marlin sim.xml is done ('[INFO] Created new caltag ', 'default') ('[INFO] Created new caltag ', 'simulation') [INFO] Starting to calibrate file /home/benjamin/Desktop/TBSW/tbsw/workspace/simrun.slcio ... [INFO] Marlin maskpath.xml is done [INFO] Marlin clusterizerpath.xml is done [INFO] Marlin correlatorpath.xml is done [INFO] Marlin prealignerpath.xml is done [INFO] Marlin alignerpath.xml is done [INFO] Marlin alignerpath.xml is done [INFO] Marlin alignerpath.xml is done [INFO] Marlin dqmpath.xml is done [INFO] Marlin preclustercalpath.xml is done [INFO] Marlin alignerdbpath.xml is done [INFO] Marlin alignerdbpath.xml is done [INFO] Marlin clustercalpath.xml is done [INFO] Marlin clustercalpath.xml is done [INFO] Marlin clustercalpath.xml is done [INFO] Marlin clustercalpath.xml is done [INFO] Marlin clustercalpath.xml is done [INFO] Marlin clustercalpath.xml is done [INFO] Marlin alignerdbpath.xml is done [INFO] Marlin alignerdbpath.xml is done [INFO] Marlin dqmdbpath.xml is done ('[INFO] Created new caltag ', 'simrun-test') [INFO] Done processing file /home/benjamin/Desktop/TBSW/tbsw/workspace/simrun.slcio [INFO] Starting to reconstruct file /home/benjamin/Desktop/TBSW/tbsw/workspace/simrun.slcio ... [INFO] Marlin recopath.xml is done [INFO] Done processing file /home/benjamin/Desktop/TBSW/tbsw/workspace/simrun.slcio

```

All calibration data is collected in the folder 'workspace/localDB' and root files with reconstructed tracks and hits are collected in the folder 'workspace/root-files'. The structure of the root trees for tracks hits and evenst is explained in the next section. The example script creates two root files with simple residual histograms ('Example-Residuals.root') and DUT hit efficiency plots ('Example-Efficiency.root') to show what can be done using the hit and track trees.

What is the input/output data format of tbsw?

The tbsw framework uses Marlin[1] and LCIO[2] to organize the calibration and reconstruction of test beam data into a Path of small steps handled by so called Processors. In order to read in raw files from EUDAQ a part of the EUDAQ 1 code base [3] is hosted to read files and convert event raw data into LCIO collections for further processing. The reconstruction path from the example script can illustrate the situation:

```

!python

Create a path for full reconstruction of telescope data

recopath = Env.createpath('reco_path')

Read input data from simulated raw file in lcio format

The file contains zero suppressed digits for all sensor

recopath.setglobals(params={'GearXMLFile': gearfile , 'MaxRecordNumber' : nevents, 'LCIOInputFiles': rawfile })

Create a precessor for clustering of telescope data

m26clust = Processor(name="M26Clusterizer",proctype="PixelClusterizer")

Now you can set various parameters of the processor

You can obtain a full list of all processor types with

all their parameters and default values by executing

the following command in a shell:

$MARLIN/bin/Marlin -x

All parameters can be overriding from the python script

Set the path to the hotpixel mask (generated in the calibration before)

m26clust.param("NoiseDBFileName","localDB/NoiseDB-M26.root")

Set the name of the input collection containing the m26 digits

m26clust.param("SparseDataCollectionName","zsdata_m26")

Set the name of the output collection with with clusters

m26clust.param("ClusterCollectionName","zscluster_m26")

Add the processor to the path

recopath.addprocessor(m26clust)

Create a processor for clustering pxd data

pxdclust = Processor(name="PXDClusterizer",proctype="PixelClusterizer")
pxdclust.param("NoiseDBFileName","localDB/NoiseDB-PXD.root") pxdclust.param("SparseDataCollectionName","zsdatapxd") pxdclust.param("ClusterCollectionName","zsclusterpxd") recopath.addprocessor(pxdclust)

Create center of gravity hits from m26 clusters

m26hitmaker = Processor(name="M26CogHitMaker",proctype="CogHitMaker") m26hitmaker.param("ClusterCollection","zsclusterm26") m26hitmaker.param("HitCollectionName","hitm26") recopath.addprocessor(m26hitmaker)

Create center of gravity hits for pxd clusters

pxdhitmaker = Processor(name="PXDCogHitMaker",proctype="CogHitMaker") pxdhitmaker.param("ClusterCollection","zsclusterpxd") pxdhitmaker.param("HitCollectionName","hitpxd") recopath.addprocessor(pxdhitmaker)

Make similar steps for the data from the FEI4 timing plane.

You can easily extend to include more sensors.

Create (find/fit)tracks from M26 and FEI4 and extrapolate to PXD.

trackfinder = Processor(name="TrackFinder",proctype="FastTracker")

Use hits from the following collections. You can add additional collections

as needed.

trackfinder.param("InputHitCollectionNameVec","hitm26 hitfei4")

Set the file from which to take the alignment. Computed during calibration.

trackfinder.param("AlignmentDBFileName","localDB/alignmentDB.root")

PXD hits (plane 3 in geometry file) are explicitely from

the trackfinding to avoid bias in measuring PXD efficiency

resolution.

This is not strictly necessary here, because the PXD hits are not

in the input hit collection list. But one can use this to measure

a specific M26 plane, for example

trackfinder.param("ExcludeDetector", "3")

Add to path

recopath.addprocessor(trackfinder)

Create a processor to compute out root file for a specific device under

test (DUT). Here, the DUT is the Belle II sensor at plane 3.

pxdanalyzer = Processor(name="PXDAnalyzer",proctype="PixelDUTAnalyzer") pxdanalyzer.param("HitCollection","hitpxd")
pxdanalyzer.param("DigitCollection","zsdatapxd") pxdanalyzer.param("AlignmentDBFileName","localDB/alignmentDB.root") pxdanalyzer.param("DUTPlane","3") recopath.addprocessor(pxdanalyzer)

```

The last processor in this reconstruction path create the output root data for studying the performance of the device under test. The root file Histos-PXD.root in workspace/root-files will contain three TTree's called Hit, Track and Event. These trees will be filled with reference tracks interpolated to the third plane along the beam line, i.e. the position of the DUT sensor in our example. The main advantage of this choice is that we can always work in the local uvw coordinates of our device under test.

• Origin of local coordinate system is center of the sensitive volume
• u,v,w positions are always in millimeters (mm)
• u axis points in direction of increasing ucells
• v axis points in direction of increasing vcells
• w axis completes a right handed cartesian coordinate system
• The interpolated track state does not include information from the DUT hit

The structure of the root trees is defined at the end of the document in Appendix 1.

A toy simulation example script for simulation, calibration (alignment), reconstruction and analysis of a depfet testbeam is part of the workspace folder.

The next script runs simulation, calibration and reconstruction:

python example.py

The output of this script is a root file root-files/Histos-PXD-simrun-test-reco.root containing flat tuples for further analysis. A simple way to get a pdf withplots is:

python histo-plotter.py --ifile=root-files/Histos-PXD-simrun-test-reco.root

The tbsw repo also ships a full script for processing of a depfet test beam November 2018 at Desy. This script shows the calibration and reconstruction process for testbeam data starting from .raw files.

An example .raw file from this test beam can be downloaded:

wget -O run001286.raw https://owncloud.gwdg.de/index.php/s/vphTqcJfwyyIHiZ/download

The steering files for in order to process this test beam is shipped with tbsw and can be found at steering-files/depfet-tb.

python depfet-reco.py python histo-plotter.py

Recently the option was added to read hit tables from different subdetectors in csv format as input into tbsw. A working example can be found here:

https://github.com/BenjaminSchwenker/tbswworkspacetjmp2_desy

Have fun with test beams ;)

benjamin.schwenker@phys.uni-goettingen.de

Bug Report / Feature Request / Question

Please use the issue tracker of the repository: https://github.com/BenjaminSchwenker/tbsw

Or contact me directly: benjamin.schwenker@phys.uni-goettingen.de

Phd theses

The software tbsw was develped and applied in the following (incomplete) list of Phd theses:

B. Schwenker, 2014 Development and validation of a model for the response of the Belle II vertex detector, Ph.D. thesis, http://cds.cern.ch/record/1967035 U. Göttingen, Göttingen, Germany

U. Stolzenberg, 2020 Radiation length measurements with high-resolution telescopes, Ph.D. thesis, http://cds.cern.ch/record/2690257, U.~Göttingen Göttingen, Germany

H. C. Beck, 2019 Development of Pixel Module Assembly Processes for the Phase 2 Upgrade of the ATLAS Detector and Test Beam Measurements with Diamond Pixel Detectors, Ph.D. thesis, https://ediss.uni-goettingen.de/handle/21.11130/00-1735-0000-0005-1337-8?locale-attribute=en , U.~Göttingen Göttingen, Germany

Proceedings and papers

U. Stolzenberg, A. Frey, B. Schwenker, P. Wieduwilt, C. Marinas and F. Lütticke, 2017, Radiation length imaging with high resolution telescopes, https://doi.org/10.1016/j.nima.2016.06.086 Nucl. Instrum. Meth. A 845 173 [1609.02402]

T. Obermanna, T. Hemperek, F. Hügging, H. Krüger, D.-L. Pohl, B. Schwenker and N. Wermes, 2017, Depleted Monolithic Pixels (DMAPS) in a 150 nm technology: lab and beam results, https://doi.org/10.1088%2F1748-0221%2F12%2F01%2Fc01062, JINST 2017

P. Wieduwilt,∗, B. Paschen,∗, H. Schreeck, B. Schwenker, Performance of production modules of the Belle II pixel detector in a high-energy particle beam, https://doi.org/10.1016/j.nima.2020.164978, Nucl. Inst. Meth. A 991 (2021) 164978

Further references

[1] F. Gaede, Marlin and LCCD: Software tools for the ILC, Nucl.Instrum.Meth. A559 (2006) 177–180.

[2] S. Aplin, J. Engels, F. Gaede, N. A. Graf, T. Johnson, et al., LCIO: A Persistency Framework and Event Data Model for HEP, SLAC-PUB-15296

[3] https://eudaq.github.io/

Appendix 1: Definition of output tuples

```c // Hit Tree filled once per hit (potentially multiple times per event) rootHitTree = new TTree("Hit","Hit info"); _rootHitTree->Branch("iRun" ,&rootRunNumber ,"iRun/I"); // Run number from lcio file rootHitTree->Branch("iEvt" ,&rootEventNumber ,"iEvt/I"); // Event number from lcio file rootHitTree->Branch("sensorID" ,&rootSensorID ,"sensorID/I"); // DUT SensorID rootHitTree->Branch("nTelTracks" ,&rootNTelTracks ,"nTelTracks/I"); // Number of tracks in same event rootHitTree->Branch("nDutDigits" ,&rootNDUTDigits ,"nDutDigits/I"); // Number of DUT digits in the same event
rootHitTree->Branch("hasTestPixels" ,&rootDUTHasTestPixels, "hasTestPixels/O");// Flag if DUT sent test digits in event rootHitTree->Branch("isGoodEvent" ,&rootDUTGoodEvent, "isGoodEvent/O"); // Flag if DUT unpacking w/o errors
rootHitTree->Branch("clusterQuality" ,&rootHitQuality ,"clusterQuality/I"); // GoodCluster == 0, BadCluster != 0 rootHitTree->Branch("uhit" ,&rootHitU ,"uhit/D"); // Hit coordinate u from DUT cluster in mm
rootHitTree->Branch("vhit" ,&rootHitV ,"vhit/D"); // Hit coordinate v from DUT cluster in mm
rootHitTree->Branch("clusterCharge" ,&rootHitClusterCharge ,"clusterCharge/D");// Sum over all charges in the cluster rootHitTree->Branch("seedCharge" ,&rootHitSeedCharge ,"seedCharge/D"); // Highest charge in cluster rootHitTree->Branch("sizeU" ,&rootHitSizeU ,"sizeU/I"); // Number of hit pixels projected on u direction rootHitTree->Branch("sizeV" ,&rootHitSizeV ,"sizeV/I"); // Number of hit pixels projected on v direction rootHitTree->Branch("size" ,&rootHitSize ,"size/I"); // Number of hit pixels in cluster rootHitTree->Branch("pixeltype" ,&rootHitSeedPixelType ,"pixeltype/I"); // PixelType of seed pixel cell rootHitTree->Branch("cellUhit" ,&rootHitCellU ,"cellUhit/I"); // Hit u coordinate lies on this u cell rootHitTree->Branch("cellVhit" ,&rootHitCellV ,"cellVhit/I"); // Hit v coordinate lies on this v cell rootHitTree->Branch("cellUseed" ,&rootHitSeedCellU ,"cellUseed/I"); // Seed pixel has this u cell rootHitTree->Branch("cellVseed" ,&rootHitSeedCellV ,"cellVseed/I"); // Seed pixel has this u cell rootHitTree->Branch("hasTrack" ,&rootHitHasTrack ,"hasTrack/I"); // Hit can be matched to track (== 0)
rootHitTree->Branch("hasTrackWithRefHit", &rootHitHasTrackWithRefHit,"hasTrackWithRefHit/I"); // Number of tracks with hit on reference plane in same event rootHitTree->Branch("ufit" ,&rootHitFitU ,"ufit/D"); // Estimated track intersection u coordinate in mm, defautls to -1 when HasTrack!=0
rootHitTree->Branch("vfit" ,&rootHitFitV ,"vfit/D"); // Estimated track intersection v coordinate in mm, defautls to -1 when HasTrack!=0
rootHitTree->Branch("dudwfit" ,&rootHitFitdUdW ,"dudwfit/D"); // Estimated track slope du/dw in radians, defautls to -1 when HasTrack!=0
rootHitTree->Branch("dvdwfit" ,&rootHitFitdVdW ,"dvdwfit/D"); // Estimated track slope dv/dw in radians, defautls to -1 when HasTrack!=0
rootHitTree->Branch("momentum" ,&rootHitFitMomentum ,"momentum/D"); // Estimated track momentum from fit, defautls to -1 when HasTrack!=0 rootHitTree->Branch("ufiterr" ,&rootHitFitErrorU ,"ufiterr/D"); // Estimated 1x sigma uncertainty for track intersection u coordinate, defautls to -1 when HasTrack!=0 rootHitTree->Branch("vfiterr" ,&rootHitFitErrorV ,"vfiterr/D"); // Estimated 1x sigma uncertainty for track intersection v coordinate, defautls to -1 when HasTrack!=0 rootHitTree->Branch("pullresu" ,&rootHitPullResidualU ,"pullresu/D"); // Standardized residual in u direction, defautls to -1 when HasTrack!=0 rootHitTree->Branch("pullresv" ,&rootHitPullResidualV ,"pullresv/D"); // Standardized residual in v direction, defautls to -1 when HasTrack!=0 rootHitTree->Branch("cellUfit" ,&rootHitFitCellU ,"cellUfit/I"); // Estimated track intersection u coordinate lies on this u cell, defautls to -1 when HasTrack!=0
rootHitTree->Branch("cellVfit" ,&rootHitFitCellV ,"cellVfit/I"); // Estimated track intersection v coordinate lies on this v cell, defautls to -1 when HasTrack!=0
rootHitTree->Branch("cellUCenterfit" ,&rootHitFitCellUCenter ,"cellUCenterfit/D"); // Central coordinate of cell 'FitCellU' in mm, defautls to -1 when HasTrack!=0
rootHitTree->Branch("cellVCenterfit" ,&rootHitFitCellVCenter ,"cellVCenterfit/D"); // Central coordinate of cell 'FitCellV' in mm, defautls to -1 when HasTrack!=0
rootHitTree->Branch("trackChi2" ,&rootHitTrackChi2 ,"trackChi2/D"); // Chi2 value from fit of reference track, defautls to -1 when HasTrack!=0
rootHitTree->Branch("trackNdof" ,&rootHitTrackNDF ,"trackNdof/I"); // Number of degrees of freedom of track fit, defautls to -1 when HasTrack!=0
rootHitTree->Branch("trackNHits" ,&rootHitTrackNHits ,"trackNHits/I"); // Number of telescope hits used for track fitting, defautls to -1 when HasTrack!=0
rootHitTree->Branch("localChi2" ,&rootHitLocalChi2 ,"localChi2/D"); // Chi2 value from hit-track residual on device under test, defautls to -1 when HasTrack!=0

// Track Tree filled once per track (potentially multiple times per event) rootTrackTree = new TTree("Track","Track info"); _rootTrackTree->Branch("iRun" ,&rootRunNumber ,"iRun/I"); // Run number from lcio file rootTrackTree->Branch("iEvt" ,&rootEventNumber ,"iEvt/I"); // Event number from lcio file rootTrackTree->Branch("sensorID" ,&rootSensorID ,"sensorID/I"); // DUT SensorID rootTrackTree->Branch("nTelTracks" ,&rootNTelTracks ,"nTelTracks/I"); // Number of tracks in same event rootTrackTree->Branch("nDutDigits" ,&rootNDUTDigits ,"nDutDigits/I"); // Number of DUT digits in the same event
rootTrackTree->Branch("isGoodEvent" ,&rootDUTGoodEvent, "isGoodEvent/O"); // Flag if DUT unpacking w/o errors
rootTrackTree->Branch("hasTestPixels" ,&rootDUTHasTestPixels, "hasTestPixels/O"); // Flag if DUT sent test digits in event rootTrackTree->Branch("hasRefHit" ,&rootTrackWithRefHit ,"hasRefHit/I"); // Track has hit on reference plane (== 0) rootTrackTree->Branch("trackChi2" ,&rootTrackChi2 ,"trackChi2/D"); // Chi2 value from fit of reference track rootTrackTree->Branch("trackNdof" ,&rootTrackNDF ,"trackNdof/I"); // Number of degrees of freedom of track fit rootTrackTree->Branch("trackNHits" ,&rootTrackNHits ,"trackNHits/I"); // Number of telescope hits used for track fitting rootTrackTree->Branch("momentum" ,&rootTrackFitMomentum ,"momentum/D"); // Estimated track momentum from fit (GeV)
rootTrackTree->Branch("ufit" ,&rootTrackFitU ,"ufit/D"); // Estimated track intersection u coordimate in mm rootTrackTree->Branch("vfit" ,&rootTrackFitV ,"vfit/D"); // Estimated track intersection v coordimate in mm rootTrackTree->Branch("dudwfit" ,&rootTrackFitdUdW ,"dudwfit/D"); // Estimated track slope du/dw in radians rootTrackTree->Branch("dvdwfit" ,&rootTrackFitdVdW ,"dvdwfit/D"); // Estimated track slope dv/dw in radians, rootTrackTree->Branch("cellUfit" ,&rootTrackFitCellU ,"cellUfit/I"); // Estimated track intersection u coordinate lies on this u cell
rootTrackTree->Branch("cellVfit" ,&rootTrackFitCellV ,"cellVfit/I"); // Estimated track intersection v coordinate lies on this v cell
rootTrackTree->Branch("cellUCenterfit" ,&rootTrackFitCellUCenter ,"cellUCenterfit/D"); // Central coordinate of cell 'FitCellU' in mm rootTrackTree->Branch("cellVCenterfit" ,&rootTrackFitCellVCenter ,"cellVCenterfit/D"); // Central coordinate of cell 'FitCellV' in mm rootTrackTree->Branch("hasHit" ,&rootTrackHasHit ,"hasHit/I"); // Track can be matched to a DUT hit (== 0) rootTrackTree->Branch("localChi2" ,&rootTrackLocalChi2 ,"localChi2/D"); // Chi2 value from hit-track residual on device under test
rootTrackTree->Branch("seedCharge" ,&rootTrackSeedCharge ,"seedCharge/D"); // Highest charge in cluster, only filled if cluster matched rootTrackTree->Branch("pixeltype" ,&rootTrackPixelType ,"pixeltype/I"); // PixelType of pixel cell intersected by track rootTrackTree->Branch("maskedPixel" ,&rootTrackPixelMasked ,"maskedPixel/I"); // Track intersects a masked pixel (masked!=0) or unmasked pixel (masked=0)

// Event Summay Tree filled once per event rootEventTree = new TTree("Event","Event info"); _rootEventTree->Branch("iRun" ,&rootRunNumber ,"iRun/I"); // Run number from lcio file rootEventTree->Branch("iEvt" ,&rootEventNumber ,"iEvt/I"); // Event number from lcio file rootEventTree->Branch("sensorID" ,&rootSensorID ,"sensorID/I"); // DUT SensorID
rootEventTree->Branch("nTelTracks" ,&rootNTelTracks ,"nTelTracks/I"); // Number of tracks rootEventTree->Branch("nTelTracksWithRefHit" ,&rootNTelTracksWithRefHit ,"nTelTracksWithRefHit/I"); // Number of tracks with reference hit rootEventTree->Branch("nDutDigits" ,&rootNDUTDigits ,"nDutDigits/I"); // Number of DUT digits rootEventTree->Branch("hasTestPixels" ,&rootDUTHasTestPixels, "hasTestPixels/O"); // Flag if DUT sent test digits rootEventTree->Branch("isGoodEvent" ,&rootDUTGoodEvent, "isGoodEvent/O"); // Flag if DUT unpacking w/o errors

```