.. _ch-tofcalc: ===================================================== 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). 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 :numref:`ch-cofi`). The applied algorithm is: 1. **Sort** all the events in a packet according to the timestamps. 2. **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 :numref:`fig-ABCD-ToF-calculator` for a screenshot of the user interface). Coincidence windows ------------------- .. code-block:: none :name: tab-diagram-coincidence-windows-tofcalc :caption: 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 :numref:`tab-diagram-coincidence-windows-tofcalc` shows a diagram of the coincidence windows defined by the module. .. _sec-tofcalc-time-decay: 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: .. math:: d = \mathrm{e}^{-\Delta t / \tau} :label: eq-tofcalc-time-decay Where :math:`d` is the decay constant that is multiplied to the histograms counts at every publication. :math:`\Delta t` is the time since the last publication and :math:`\tau` is the user-supplied characteristic time. .. _sec-tofcalc-config: Example configuration --------------------- .. code-block:: JSON :name: tab-tofcalc-configuration-example :caption: 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" } ] } :numref:`tab-tofcalc-configuration-example` 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 :numref:`sec-tofcalc-time-decay`). 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). User interface -------------- The tutorial has an extensive description of the web-based user interface (see :numref:`sec-tutorial-tof-calculator`).