Introduction
This software is designed to take raw data from the CAEN-CoMPASS digitizer DAQ and provide an event-built data set for use in further physics analysis. This code is intended to be used with the DAQ setup for the Super-Enge Split-Pole Spectrograph (SESPS) and Silicon Array for Branching Ratio Experiments (SABRE) at Florida State University. A more general skeleton code is given in the repository EventBuilder_Skeleton for use with other setups. This wiki will go through some of the concepts of event building, as well as outline some of the specific methods used in the code. Finally, it will also contain some commonly asked questions and answers for using the software.
Event Building
To this software, event-building refers to the organization of several detector events (or "hits") into a single event based on time correlations. This involved ordering data sets in time, combining several data sources, as well as identifying and correlating data from different sources. In general, time correlations are defined by a coincidence window. A coincidence window is the time interval that defines whether or not two hits were coincident.
Related to the concept of coincidence windows, is the concept of dead time. Dead time refers to any time interval over which either the physical detector, DAQ hardware, or DAQ software is blind to incoming data and data could potentially be lost. The goal with event building software is to accurately build events while minimizing the amount of dead time injected into the detection system. For more details on dead time, types of dead time, or dead time corrections see Knoll, Radiation Detection and Measurement. In the case of the event building software, the larger the coincidence window implemented the greater the potential dead time incursion can be, however this software takes several steps to avoid dead time penalties.
The pipeline for event building is as follows: time-shifting and time-ordering, followed by slow sorting, followed by fast sorting (optional), and finally basic analysis.
Time-Shifting and Time-Ordering
To minimize dead time, it is in general beneficial to minimize the width of coincidence windows. To this end, the event builder allows the user to apply shifts to the timestamps of hits on a channel by channel (or board by board) basis. In this way, a detector can be shifted so that the timestamps of two detectors can be synchronized, thus meaning that the coincidence window for the detectors needs only be wide enough to capture the timing distribution rather than the time offset as well as the distribution between two detectors. Typically, in the SESPS-SABRE setup, shifts are applied to anode data and SABRE data such that these events are synchronized with scintillator data, thus making the delay-line data the only significant timing event in the slow coincidence window.
Data from the CoMPASS DAQ system is typically given in a raw binary format for each individual digitizer channel (in the full SESPS-SABRE setup this results in around 145 files). Each individual file (detector channel) is sorted in time, but we need to combine them together into a complete time-ordered data set. This is done by taking the earliest (top) hit of each file and comparing their timestamps. The earliest hit across all files is then sent to the next stage of building.
Slow Sorting and Fast Sorting
Once the data is properly ordered in time, the data must be sorted in to built events. The most general attempt at this is referred to as slow sorting by this code. Slow sorting is where all data that falls within a coincidence window is taken and placed into a single built event. This coincidence window is often referred to as the slow window. "Slow" comes from the fact that this is the largest window used by the program, so this sorting takes place over the largest time-scales. There are a few important things to note about slow sorting in the program. Foremost is that it does not have a master trigger. That is, data from any detector channel can start an event. This is essentially a requirement for using the time-shifts outlined above, as well as optimizing the slow window size. The window stays open until a hit with a timestamp that occurs outside of the slow window is found. Then, that hit starts the new built event and the previous event is flushed out to the next stage of the pipeline. Also, the slow sort algorithm does not discard any data. The built event from slow sort is comprised of dynamically allocated arrays (read std::vector) thus meaning that in principle the slow sort incurs no intrinsic dead time other than from fragmentation of events.
Fast sorting is an optional secondary stage of coincidence analysis, aimed at resolving multi-hit events. In general, each coincidence event should contain at most a single hit from a given detector channel (there are cases where this is not true, however they are rare for the SESPS-SABRE setup), but if the slow window is significantly wider than the typical time correlation for two hits there is a possibility that two hits for a given channel may be put into a single built event. To resolve this hit degeneracy, the user may input additional time correlation information for specific channels. Fast refers to the fact that these windows must be shorter than the slow window. Specifically, for the SESPS-SABRE code, the fast sort provides the option to enforce a window on focal plane scintillator-anode data and then on focal plane scintillator-SABRE data, as the scintillator and SABRE tend to be much faster detectors than the focal plane ion chamber. These windows are referred to as the fast ion-chamber window and fast SABRE window respectively. It is important to note that fast sorting is optional and may need tweaking on an experiment by experiment basis, and is not recommended to be run until the time-shifts and the slow sorting method have been tested and run successfully. Additionally, it should be emphasized that the default fast sorting stage can dump data. It requires that an ion-chamber anode hit be present in order to be saved; in general this means that scintillator-only events (scintillator singles) or SABRE singles will be dumped if the fast sorting is done.
Basic Analysis
Technically speaking, after the sorting stages, the event building is complete and the next, much more complicated and experiment specific data analysis stage should take over. However, due to some limitations of the CoMPASS software with online data analysis, as well as to provide a method to test the success of event builder, the event builder can pass the data on to a very basic analysis class. This analysis is not meant to be used as a final analysis program; it does not have very many safety measures and is typically too simple and too difficult to modify for most experiments. There are some key features that outline both the use and drawbacks of this analysis. First is that any degeneracy in data must be resolved for use with the analysis. Consider the following scenario: the front left delay line signal is slightly noisy and inside the built event there are two front left delay line hits. To calculate a calibrated focal plane position one must subtract the timestamp of the left and right signal for a given delay line. How then is the analysis to select which front left delay signal goes with the single front right delay signal? To make the code generally applicable it employs a very simple solution of taking whichever hit occurred first, but there are many experiments where this is not the correct approach. This first-in selection scheme is employed for every detection channel that gets converted into analyzed data. In general, the only data member that continues to maintain the earlier policy of not dumping data is the SABRE array, however, a down-scaled version of the SABRE array is then required to be used with the online plotting. Additionally, due to the dynamic nature of the sorted data, checks must be made upon the validity of the data at analysis time. This in turn induces a performance penalty as more and more complicated analyses are performed, which reduces the usefulness of adding more analysis steps. Finally, the data analysis tends to bloat the file size. Each additional analyzed parameter induces an increase in the written data size, and ROOT does not support optional writing. That is: even if an event does not have a right scintillator hit, all of the right scintillator data member will still be written to the file with an illegal default value (typically something like -1). In a more specialized analysis, only relevant data would be written, but due to the general nature of this analysis along with its focus on providing sanity checks for the event building process, a lot of experimentally irrelevant data will be written.
Other Operations
Plotting
The main purpose of running the analysis is to then generate histograms which help indicate the quality of the data. To this end, the event builder has a plotting routine that uses ROOT tools to generate a file of histograms. This plotting tool can take in multiple analyzed files and generate a single plot file containing all of the data. Additionally, a list of cuts (called the CutList) can be given to the plotter tool, and they will be applied to the data. Cuts should be given in a cut list file, and should each be individually saved in ROOT files as TCutG objects named "CUTG". The cutlist file will ask the user to give a new name for the cut, as well as specify the name of the variables upon which the cut should be applied. There are a fixed number of keywords for variables which can be used, see the CutHandler class for more details.
Scalers
Sometimes there is data collected where the only thing of interest is the number of counts in that channel, or the channel generates so much data that it cannot be analyzed online without slowing down the event building to such a crawl that it becomes impractical. To address these cases, specific channels can be designated as scalers. When a channel is designated as a scaler, the associated binary data file is separated from the main event building pipeline and analyzed quickly by calculating the number of hits. This number is then saved to the output file with an associated name. Scalers are specified using a scaler list file, where the file contains a list of CoMPASS file names and a scaler name. The CoMPASS file name is a string which indicates the board and channel to be designated as a scaler, where in this case the specific board ID must be used.
Installation, Building, and Setting up the Workspace
The event builder uses CMake and requires CMake version greater than or equal to 3.16.
The only external dependence for this repository is the ROOT Data Analysis Package. Due to the large size and complexity of ROOT, ROOT is not included as a submodule, and rather the user is relied upon to properly install and setup their own ROOT package. Please note, the event builder uses C++17, and as such the ROOT used must also have been built using C++17. This can be check on MacOS or Linux using the root-config tool.
Building the code is fairly straightforward. Obtain the repository from GitHub using the command git clone --recursive https://github.com/sesps/SPS_SABRE_EventBuilder.git. After obtaining the repository from GitHub, use CMake to build the project. See the README for an example of running CMake.
Workspaces
The event builder needs to know where the CoMPASS binary data is stored and the relevant directories for writing event built data. The event builder can generate a workspace on its own. In the EventBuilderGui, simply select a workspace folder, and the event builder will generate all required directories in that workspace folder. (It can also generate the workspace folder itself if you enter a directory that does not already exist.)
All CoMPASS binary data should then be moved to the raw_binary directory and stored as .tar.gz files of all the individual .BIN files made by CoMPASS. The naming should follow run_#.tar.gz.
Also included in the bin directory is a bash script called archivist. This script will move data from CoMPASS projects to a workspace, tarring and zipping them appropriately.
Running the Code
The basics of running the code are mostly contained within the input file. The input files are YAML files which contain the location of a workspace, a channel map file which gives a list of the digitizer channels and the associated detector information, a board offset file which lists the time-shifts to be applied to specific channels, a scaler file which lists any digitizer channels to be taken as scalers, and a cut list file which lists any cuts to be used with the plotter tool. Examples of these files may be found in the etc directory. The SESPS-SABRE event builder will also ask for reaction information so that a kinematic correction can be applied to analyzed focal plane data. This includes specifying atomic numbers for use in looking up nuclear masses. Note that the code uses the 2017 AMDC mass evaluation data; if you input information which requests a nuclear mass not included in that data, an error will occur in the code. Finally, the input file asks for window sizes as well as a range of run numbers over which to the program will be run.
If the commandline executable (EventBuilder) is being used, format is the following:
./bin/EventBuilder <evb_operation> <your_input_file>
Where <evb_operation> should be a keyword which indicates to the program which type of event building operation (Slow sort, fast sort, slow sort with analysis, etc.) should be used. The file main.cpp located in the src directory contains the list of keywords.
If the gui executable (EventBuilderGui) is being used, format is simply:
./bin/EventBuilderGui
The input file can then be loaded using the File->Load menu, or the user can manually enter the input parameters to the GUI. The GUI also provides functionality for saving an input file for the currently set parameters using the File->Save menu. The event building operation is then selected using the drop down menu.
Note that both executables should be run from the top-level repository directory, not from the bin directory. This is to define the path to specific external data files, namely the workspace and nuclear mass datafile.