13. On-line Time-of-Flight calculator: `tofcalc` module

tofcalc analyses the processed events determining the time differences between events in temporal coincidence with a reference channel in a specified time-window. Time differences between events are normally regarded as Time-of-Flights (ToF).

13.1. Algorithm

The tofcalc module works on data packets generating groups of events in coincidence with the reference channels. Reference channels are selected by the user as the channels giving the reference timestamp for the time differences calculations. This algorithm is the similar to the one employed by the cofi module (see Section 12). The applied algorithm is:

Sort all the events in a packet according to the timestamps.
Select the events generated by reference channels. For each reference channel event then:
1. Search backward in the events array for events that did not originate from a reference channel. If the timestamps are outside the left time window stop the search. Use the timestamps of the selected events to determine the ToFs.
2. Search forward for events that did not originate from a reference channel. If the timestamps are outside the right time window, stop the search. Use the timestamps of the selected events to determine the ToFs.

Since the reference pulse is the time zero, it corresponds to a time offset. Time differences are calculated accordingly subtracting the time zero from the timestamps of the other channels.

In addition to the ToF histograms the tofcalc calculates also the energy vs ToF and energy vs energy histograms (see Fig. 3.8 for a screenshot of the user interface).

13.2. Coincidence windows

Listing 13.1 Diagram of the coincidence windows

              Events from           Event from a
              other channels        reference channel
              in the left           |
              coincidence           |
              window                |
              |                     |
              +----------+-----+    |
              |          |     |    |
              V          V     V    V

  3           2          2     1    0         1   1      3    2
------------------------------------|----------------------------> timestamps
          |                         t_0 <- Time zero of the    |
          |                         |      coincidence window  |
          |-------------------------|--------------------------|
          t_l <- Left edge                       Right edge -> t_r
                 of the window                of the window

Listing 13.1 shows a diagram of the coincidence windows defined by the module.

13.3. Time decay of spectra

It is possible to enable the time decaying of histograms. The histograms counts decay in time with an exponential decay with a user-supplied characteristic time. New statistics is added on top of the previously decayed counts. This feature allows to continuously see the evolution in time of the time difference between two detectors. For instance it is useful for optimizing detectors geometries or configurations, seeing in real time the effects.

The decay constant is calculated according to:

(13.1)\[d = \mathrm{e}^{-\Delta t / \tau}\]

Where \(d\) is the decay constant that is multiplied to the histograms counts at every publication. \(\Delta t\) is the time since the last publication and \(\tau\) is the user-supplied characteristic time.

13.4. Example configuration

Listing 13.2 Example configuration of the tofcalc module. This configuration is used in the example startup that replays example data.

{
    "module": "tofcalc",
    "ns_per_sample": 0.001953125,
    "time_decay": {
        "enable": false,
        "tau": 3,
        "counts_minimum": 0.0001
    },
    "channels": [
        {
            "id": 1,
            "reference": true,
            "note": "LaBr"
        },
        {
            "id": [6, 7],
            "reference": false,
            "bins_ToF": 200,
            "min_ToF": -80,
            "max_ToF": -30,
            "bins_E": 512,
            "min_E": 0,
            "max_E": 40960,
            "note": "CeBr"
        }
    ]
}

Listing 13.2 shows a configuration example. More examples can be found in the /usr/share/abcd/tofcalc/ folder. A detailed list of configurations follows:

ns_per_sample: Floating point value that is the conversion factor between the timestamp samples and nanoseconds. The conversion is applied only after the determination of difference in timestamps, in order not to lose numeric precision.
time_decay: Object value that contain the configuration of the time decaying of histograms (see Section 13.3). The object contains the values:
- enable: Bool value that enables the time decaying of histograms.
- tau: Floating point value is seconds that is the characteristic time of the decay.
- counts_minimum: Floating point value that sets a minimum value on the counts of the bins of the histograms. If the counts fall below this value they are set to zero. This is to avoid visualization artifacts.
channels: Array value of objects. This array contains the settings of the single channels. Each channel object has the settings:
- id: Integer value that indicates the channel to which these settings apply. It may be substituted with an array of integer values, indicating that these settings are to be replicated to all these channels.
- name: Just a mnemonic string for the user. The program actually ignores this setting.
- reference: Bool value to that sets the channel(s) as reference channels. If this setting is true then the other configurations of this channel are ignored, as they do not apply to reference channels.
- bins_ToF and bins_E: Integer value that sets the number of bins in the histograms.
- min_ToF and max_ToF: Floating point values in nanoseconds, that sets the extrema of the ToF histogram.
- min_E and max_E: Floating point values in ADC samples, that sets the extrema of the energy histogram (that are therefore not calibrated).

13.5. User interface

The tutorial has an extensive description of the web-based user interface (see Section 3.2.7).