diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..3171144 Binary files /dev/null and b/.DS_Store differ diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000..804324c Binary files /dev/null and b/docs/.DS_Store differ diff --git a/docs/source/.DS_Store b/docs/source/.DS_Store new file mode 100644 index 0000000..fae79c8 Binary files /dev/null and b/docs/source/.DS_Store differ diff --git a/docs/source/images/.DS_Store b/docs/source/images/.DS_Store index cbc174b..9c0e147 100644 Binary files a/docs/source/images/.DS_Store and b/docs/source/images/.DS_Store differ diff --git a/docs/source/images/trude/spectrum.png b/docs/source/images/trude/spectrum.png new file mode 100644 index 0000000..1794543 Binary files /dev/null and b/docs/source/images/trude/spectrum.png differ diff --git a/docs/source/images/trude/wf_intervals.png b/docs/source/images/trude/wf_intervals.png new file mode 100644 index 0000000..8869110 Binary files /dev/null and b/docs/source/images/trude/wf_intervals.png differ diff --git a/docs/source/trude.rst b/docs/source/trude.rst index 6afb3b0..a0e00af 100644 --- a/docs/source/trude.rst +++ b/docs/source/trude.rst @@ -1,5 +1,116 @@ Trude ========== -.. caution:: - This page is currently not created, we are working on it. If you would like to contribute on this documentation, reach `me `_! +*From Germanic, Gertrud, hypocorism: female friend.* + +This city produces the light and dark spectrum of SiPMs for dedicated calibration runs. This is achieved by selecting regions in the SiPM waveforms where LED pulses are expected and regions which end 2 microseconds before (this value is hardcoded to avoid the overlap with light pulses), respectively and integrating the content within each region. The regions before LED pulses should only contain electronics noise and dark counts giving the zero external light approximation whereas those in time with the pulses will contain one or more detected photoelectrons. The waveform integrals are split into two groups: those with expected photoelectrons (light) and those without expected photoelectrons (dark). Each group produces a different spectrum. + +.. _Trude input: + +Input +----- + + * ``/Run/events``: list of the ``evt_number`` and the correspondent ``timestamp``. + * ``/Run/runInfo``: stores the ``run_number``. + * ``/RD/sipmrwf``: stores the raw waveform itself. It indicates the number of :math:`ADCs` per time bin for each event and SiPM. + +.. _Trude output: + +Output +------ + +* ``/HIST/sipm_dark``: histogram values of the dark spectrum. +* ``/HIST/sipm_dark_bins``: bin values of the dark spectrum. +* ``/HIST/sipm_spe``: histogram values of the light spectrum. +* ``/HIST/sipm_spe_bins``: bin values of the light spectrum. + +.. _Trude config: + +Config +------ + +Besides the :ref:`Common arguments to every city`, *Trude* has the following arguments: + +.. list-table:: + :widths: 50 40 120 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + + * - ``min|max_bin`` + - ``float`` + - Lower/upper limit of the number of :math:`ADCs` of the waveform to be considered for the spectrum. + + * - ``bin_width`` + - ``int`` + - Width of the bins for the spectrum in :math:`\mu s`. + + * - ``proc_mode`` + - ``string`` + - Two options of subtracting the baseline: ``subtract_mode`` to subtract the mode and ``subtract_median`` to subtract the median. + + * - ``number_integrals`` + - ``int`` + - Number of integrals to be performed in the waveform's time window. Typically this value is selected depending on the number of LED pulses in the waveform. E.g. if the waveform has 5 pulses, the number of integrals will be 5. + + * - ``integral_start`` + - ``int`` + - Bin in :math:`\mu s` where the first integral of the set of ``number_integrals`` starts. The other integrals are performed using ``integrals_period`` assuming the same distance between the peaks. + + * - ``integral_width`` + - ``int`` + - Number of bins to be considered for the integral starting at ``integral_start``. With ``integral_start`` these values are ideally chosen to select the whole pulse of the LED. + + * - ``integrals_period`` + - ``int`` + - Period between integrals. This parameter won't be considered when ``number_integrals = 1``. + + +.. _Trude workflow: + +Workflow +-------- + +Trude performs the following operations to obtain the spectra: + + * :ref:`Selection of integration limits ` + * :ref:`SiPM waveforms baseline subtraction ` + * :ref:`Spectrum histogram ` + + +.. _Selection of integration limits: + +Selection of integration limits +:::::::::::::::::::::::::::::::: + +Given the config parameters, the first step in this city would be to select the dark and light bins to compute the dark and light spectra. + +The light bins will be centered in the light pulse(s) and the dark bins are chosen as an interval of ``integral_width`` bins which ends 2 :math:`\mu s` before the light pulse begins, as shown here: + + .. image:: images/trude/wf_intervals.png + :width: 850 + +Typically, the limits are set to ``min_bin = -49.5`` and ``max_bin = 4000.5`` ADCs since it is the range of the waveform window. + +.. _SiPM waveforms baseline subtraction: + +SiPM waveforms baseline subtraction +:::::::::::::::::::::::::::::::::::: + +Same procedure as described in :ref:`Baseline subtraction of SiPM waveforms` section of the :doc:`irene` documentation with the option of using the mean instead of the mode of the waveform for the baseline subtraction. + +.. _Spectrum histogram: + +Spectrum histogram +::::::::::::::::::: + +The last step would be the integration of the dark and light bins in order to obtain the respective spectrum histograms. + +For each of the regions it sums all the :math:`ADCs` in the intervals and adds an entry to the histogram. It repeats this for each waveform of the same sensor. + +The end result will be a h5 file with ``/HIST/sipm_dark`` and ``/HIST/sipm_spe`` with a table per time bin and an entry per sensor. In the following plot you will find a light spectrum for a given channel. + +.. image:: images/trude/spectrum.png + :width: 850