README.md 9.1 KB
Newer Older
1
# EventLoaderEUDAQ2
2
3
**Maintainer**: Jens Kroeger (<jens.kroeger@cern.ch>), Simon Spannagel (<simon.spannagel@cern.ch>)  
**Module Type**: *DETECTOR*  
4
**Status**: Functional
5
6

### Description
7
8
This module allows data recorded by [EUDAQ2](https://github.com/eudaq/eudaq/) and stored in a EUDAQ2 binary file as raw detector data to be read into Corryvreckan.
For each detector type, the corresponding converter module implemented in EUDAQ2 is used to transform the data into the `StandardPlane` event type before storing the individual `Pixel` objects on the Corryvreckan clipboard.
9

10
The detectors need to be named according to the following scheme: `<detector_type>_<plane_number>` where `<detector_type>` is the type specified in the detectors file and `<plane_number>` is an iterative number over the planes of the same type.
11
12
13
14
15
16

If the data of different detectors is stored in separate files, the parameters `name` or `type` can be used as shown in the usage example below.
It should be noted that the order of the detectors is crucial.
The first detector that appears in the configuration defines the event window to which the hits of all other detectors are compared.
In the example below this is the CLICpix2.

17
If the data of multiple detectors is stored in the same file as sub-events, it must be ensured that the event defining the time frame is processed first.
18
This is achieved by instantiating two event loaders in the desired order and providing them with the same input data file.
19
The individual (sub-) events are compared against the detector type.
20

21
22
23
24
25
26
27
For each event, the algorithm checks for an event on the clipboard.
If none is available, the current event defines the event on the clipboard.
Otherwise, it is checked whether or not the current event lies within the clipboard event.
If yes, the corresponding pixels are added to the clipboard for this event.
If earlier, the next event is read until a matching event is found.
If later, the pointer to this event is kept and it continues with the next detector.

28
Data from detectors with both triggered readout and without timestamps are matched against trigger IDs stored in the currently defined Corryvreckan event.
29
30

If no timestamp is available for the individual pixels, the pixel timestamp is set as the centre of the EUDAQ2 event.
31

32
If no detector is capable of defining events, the `[Metronome]` module needs to be used.
33

34
35
Tags stored in the EUDAQ2 event header are read, a conversion to a double value is attempted and, if successful, a profile with the value over the number of events in the respective run is automatically allocated and filled.
This feature can e.g. be used to log temperatures of the devices during data taking, simply storing the temperature as event tags.
36

37
38
39
40
41
42
### Requirements
This module requires an installation of [EUDAQ2](https://eudaq.github.io/). The installation path needs to be set to
```bash
export EUDAQ2PATH=/path/to/eudaq2
```
when running CMake to find the library to link against and headers to include.
43

44
45
46
47
It is recommended to only build the necessary libraries of EUDAQ2 to avoid linking against unnecessary third-party libraries such as Qt5.
This can be achieved e.g. by using the following CMake configuration for EUDAQ2:

```bash
48
cmake -DEUDAQ_BUILD_EXECUTABLE=OFF -DEUDAQ_BUILD_GUI=OFF ..
49
50
51
```

It should be noted that individual EUDAQ2 modules should be enabled for the build, depending on the data to be processed with Corryvreckan.
52
For instance, to allow decoding of Caribou data, the respective EUDAQ2 module has to be built using
53
54

```bash
55
cmake -DUSER_CARIBOU_BUILD=ON ..
56
57
```

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
In this case, EUDAQ2 itself depends on [Peary](https://gitlab.cern.ch/Caribou/peary), which is the data acquisition software accompanying the Caribou readout system.
To switch off all interfaces that are not necessary when not operating devices, one can do:

```bash
cmake -DINTERFACE_EMULATION=ON ..
```

__Note:__ For an installatin on `lxplus` it is recommended to `source path/to/corryvreckan/etc/setup_lxplus.sh` not only before the installation of Corryvreckan but also before starting with the installation of EUDAQ2 to make sure the same compiler version is used for all libraries.
If also Peary is installed, the following order is recommended:

1. `source path/to/peary/.gitlab-ci.d/init_x86_64.sh`
2. install Peary as described [here](https://peary-caribou.web.cern.ch/peary-caribou/#compilation-installation)
3. `source path/to/corryvreckan/etc/setup_lxplus.sh`
4. install EUDAQ2 as described [here](https://github.com/eudaq/eudaq/)
5. install Corryvreckan

74
75
### Contract between EUDAQ Decoder and EventLoader

76
The decoder guarantees to
77

78
* return `true` only when there is a fully decoded event available and `false` in all other cases.
79
* not return any event before a possible T0 signal in the data. This is a signal that indicates the clock reset at the beginning of the run. It can be a particular data word or the observation of the pixel timestamp jumping back to zero, depending on data format of each the detector.
80
* return the smallest possible granularity of data in time either as even or as sub-events within one event.
81
* always return valid event timestamps. If the device does not have timestamps, it should return zero for the beginning of the event and have a valid trigger number set.
82
* provide the detector type via the `GetDetectorType()` function in the decoded StandardEvent.
83

84
85
86
87
### Configuring EUDAQ2 Event Converters

Some data formats depend on external configuration parameters for interpretation.
The EventLoaderEUDAQ2 takes all key-value pairs available in the configuration and forwards them to the appropriate StandardEvent converter on the EUDAQ side.
Simon Spannagel's avatar
Simon Spannagel committed
88
It should be kept in mind that the resulting configuration strings are parsed by EUDAQ2, not by Corryvreckan, and that therefore the functionality is reduced.
89
For example, it does not interpret `true` or `false` alphabetic value of a Boolean variable but will return false in both cases. Thus `key = 0` or `key = 1` have to be used in these cases.
90
91
Also, more complex constructs such as arrays or matrices read by the Corryvreckan configuration are simply interpreted as strings.

92
In addition, the calibration file of the detector specified in the geometry configuration is passed to the EUDAQ2 event decoder using the key `calibration_file` and its canonical path as value. Adding the same key to the module configuration will overwrite the file specified in the detector geometry.
93

94
### Parameters
95
* `file_name`: File name of the EUDAQ2 raw data file. This parameter is mandatory.
96
97
* `inclusive`: Boolean parameter to select whether new data should be compared to the existing Corryvreckan event in inclusive or exclusive mode. The inclusive interpretation will allow new data to be added to the event as soon as there is some overlap between the data time frame and the existing event, i.e. as soon as the end of the time frame is later than the event start or as soon as the time frame start is before the event end. In the exclusive mode, the frame will only be added to the existing event if its start and end are both within the defined event.
* `skip_time`: Time that can be skipped at the start of a run. All hits with earlier timestamps are discarded. Default is `0ms`.
98
99
* `get_time_residuals`: Boolean to change if time residual plots should be created. Default value is `false`.
* `get_tag_vectors`: Boolean to enable creation of EUDAQ2 event tag histograms. Default value is `false`.
100
* `ignore_bore`: Boolean to completely ignore the Begin-of-Run event (BORE) from EUDAQ2. Default value is `true`.
101
* `adjust_event_times`: Matrix that allows the user to shift the event start/end of all different types of EUDAQ events before comparison to any other Corryvreckan data. The first entry of each row specifies the data type, the second is the offset which is added to the event start and the third entry is the offset added to the event end. A usage example is shown below, double brackets are required if only one entry is provided.
102
* `buffer_depth`: Depth of buffer in which EUDAQ2 `StandardEvents` are timesorted. This algorithm only works for `StandardEvents` with well-defined timestamps. Setting it to `0` disables timesorting. Default is `0`.
Simon Spannagel's avatar
Simon Spannagel committed
103
* `shift_triggers`: Shift the trigger ID up or down when assigning it to the Corryvreckan event. This allows to correct trigger ID offsets between different devices such as the TLU and MIMOSA26.
104

105
### Plots produced
106
107
108
109
110
111
112
113
114
115
116
117
118

For all detectors, the following plots are produced:

* 2D histograms:
    * Hit map
    * Map of the pixel time minus event begin residual over time
    * Map of the difference of the event start and the pixel timestamp over time
    * Map of the difference of the trigger time and the pixel timestamp over time
    * Profiles of the event tag data
* 1D histograms:
    * Histograms of the pixel hit times, raw values, multiplicities, and pixels per event
    * Histograms of the eudaq/clipboard event start/end, and durations
    * Histogram of the pixel time minus event begin residual
119
120
121
122

### Usage
```toml
[EventLoaderEUDAQ2]
123
124
name = "CLICpix2_0"
file_name = /path/to/data/examplerun_clicpix2.raw
125

126
127
128
[EventLoaderEUDAQ2]
type = "MIMOSA26"
file_name = /path/to/data/examplerun_telescope.raw
129
adjust_event_times = [["TluRawDataEvent", -115us, +230us]]
130
buffer_depth = 1000
131
```