Skip to content

Commit 83c6f4b

Browse files
mvishiu11andreasmolander
mvishiu11
authored and
andreasmolander
committed
doc: extend README
1 parent 00c5d67 commit 83c6f4b

1 file changed

Lines changed: 134 additions & 13 deletions

File tree

‎Modules/FIT/FT0/README.md‎

Lines changed: 134 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,141 @@ The schematics of the LCS is shown below. Per laser pulse, there will be two sig
1414

1515
More information about the LCS and the hardware side of the aging monitoring can be found [here](https://indico.cern.ch/event/1229241/contributions/5172798/attachments/2561719/4420583/Ageing-related%20tasks.pdf).
1616

17-
### `AgingLaserTask` configuration
17+
---
1818

19-
An example configuration can be found in `etc/ft0-aging-laser.json`. The task parameters are:
19+
### AgingLaserTask
2020

21-
- `detectorChannelIDs`: list of detector channels to be monitored. Omit this parameter to use all.
22-
- `referenceChannelIDs`: the reference channel IDs, should be: "208, 209, 210, 211".
23-
- `detectorAmpCut`: Lower cut on the detector amplitude in ADC ch, default "0". **TODO**: this has no effect at the moment.
24-
- `referenceAmpCut`: Lower cut on the reference channel amplitude in ADC ch to ignore cross talk, default "100".
25-
- `laserTriggerBCs`: list of BCs when the laser fires, should be "0, 1783".
26-
- `detectorBCdelay`: amount of BCs after the laser trigger BCs when the laser pulse is expected in the detector, should be "131".
27-
- `referencePeak1BCdelays`: amount of BCs after the laser trigger BCs when the first laser pulse is expected in the reference channels, should be "115, 115, 115, 115". One value per reference channel, even though they will be the same with the current LCS setup.
28-
- `referencePeak2BCdelays`: amount of BCs after the laser trigger BCs when the second laser pulse is expected in the reference channels, should be "136, 142, 135, 141". One value per reference channel.
29-
- `debug`: If true, an additional set of plots can be produced for debugging purposes, default "false".
21+
#### What it does (high level)
3022

31-
The channel ID and BC values delays are rather fixed and should not change unless the LCS changes significantly.
23+
* Selects laser events in specific bunch crossings (BCs).
24+
* Separately identifies:
3225

33-
**TODO**: should we apply the amplitude cuts in the SliceTrendingTask instead?
26+
* detector-channel laser signals,
27+
* reference-channel peak-1 and peak-2 signals (two per laser shot).
28+
* Fills per-channel **amplitude** and **time** histograms, split by ADC where relevant.
29+
* (Optional) Produces a rich set of debug histograms.
30+
31+
This task is the *producer* of the raw per-channel spectra used later by post-processing.
32+
33+
#### Inputs
34+
35+
* Digits and channel streams (from workflow config), e.g.
36+
37+
```
38+
digits: FT0/DIGITSBC/0
39+
channels: FT0/DIGITSCH/0
40+
```
41+
42+
#### Configuration
43+
44+
Example: `etc/ft0-aging-laser.json`.
45+
46+
| Key | Type | Default | Meaning |
47+
| ------------------------ | -----------: | ----------------: | -------------------------------------------------------------- |
48+
| `detectorChannelIDs` | list `uint8` | all `0–207` | Detector channels to monitor. |
49+
| `referenceChannelIDs` | list `uint8` | `208,209,210,211` | Reference (laser monitor) channels. |
50+
| `detectorAmpCut` | int | `0` | Minimum ADC for detector channels (**currently not applied**). |
51+
| `referenceAmpCut` | int | `100` | Minimum ADC for reference channels (suppress cross-talk). |
52+
| `laserTriggerBCs` | list `int` | `0,1783` | BCs where the laser is triggered. |
53+
| `detectorBCdelay` | int | `131` | BC shift from trigger to detector signal. |
54+
| `referencePeak1BCdelays` | list `int` | `115,115,115,115` | BC shifts for ref. peak-1 (per reference channel). |
55+
| `referencePeak2BCdelays` | list `int` | `136,142,135,141` | BC shifts for ref. peak-2 (per reference channel). |
56+
| `debug` | bool | `false` | Enable extra (heavy) debug histograms. |
57+
58+
> The BC delays and channel ID ranges are hardware-driven and stable; adjust only if the LCS timing changes.
59+
60+
#### Outputs (Monitor Objects)
61+
62+
Always produced (names correspond to *amplitude/time vs channel*; all TH2I unless noted):
63+
64+
* **Amplitude vs channel**
65+
66+
* `AmpPerChannel` - used by postprocessing task
67+
* `AmpVsChADC0` - detector + reference, ADC0
68+
* `AmpVsChADC1` - detector + reference, ADC1
69+
* `AmpVsChPeak1ADC0` / `AmpVsChPeak1ADC1` - reference peak-1
70+
* `AmpVsChPeak2ADC0` / `AmpVsChPeak2ADC1` - reference peak-2
71+
* **Time vs channel**
72+
73+
* `TimeVsCh` - detector + reference
74+
* `TimeVsChPeak1` - reference peak-1 (both ADCs)
75+
* `TimeVsChPeak2` - reference peak-2 (both ADCs)
76+
77+
Debug (enabled with `debug=true`; types indicated):
78+
79+
* **Reference-channel 1D spectra (per channel, TH1I)**
80+
amplitude: `mMapDebugHistAmp*` (for all/ADC0/ADC1/peak1/peak2/combos)
81+
time: `mMapDebugHistTimePeak{1,2}*`
82+
* **Time vs channel (TH2I)**: `DebugTimeVsChADC{0,1}`, `DebugTimeVsChPeak{1,2}ADC{0,1}`
83+
* **BC distributions (TH1I)**: `DebugBC*`, split by detector/reference, ADC and with/without amplitude cuts
84+
* **Amplitude vs BC (TH2I)** per reference channel: `mMapDebugHistAmpVsBC*`
85+
86+
> Note: the “time vs BC” debug maps are intentionally disabled in local-batch to avoid ROOT I/O size issues.
87+
88+
---
89+
90+
# AgingLaserPostProcTask
91+
92+
`o2::quality_control_modules::ft0::AgingLaserPostProcTask`
93+
94+
#### Purpose
95+
96+
Reduce the raw per-channel amplitude spectra to **one scalar per channel** representing the **weighted-mean amplitude**, normalized to the reference channels. Output is split into two histograms: A-side (channels 0–95) and C-side (channels 96–207).
97+
98+
#### Inputs
99+
100+
* From the QC repository path `FT0/MO/AgingLaser`:
101+
102+
* `AmpPerChannel` (TH2): amplitude (ADC) vs channel, aggregated by the task.
103+
*(If you renamed the source MO, adjust the retrieval in the task config.)*
104+
105+
#### Algorithm (per update)
106+
107+
1. **Reference normalization**
108+
109+
* For each configured reference channel:
110+
111+
* Project its slice `AmpPerChannel(ch)` → `TH1`.
112+
* In `[adcSearchMin, adcSearchMax]` find the maximum `x_max`.
113+
* Fit a Gaussian in `[(1−a)·x_max, (1+b)·x_max]` → mean `μ_ref`.
114+
* `norm = average(μ_ref)` over all successful fits.
115+
2. **Per-channel value**
116+
117+
* For **every** detector channel:
118+
119+
* Find the global maximum `x_max`.
120+
* In the same fractional window around `x_max`, compute **weighted mean**
121+
`⟨x⟩ = Σ w_i x_i / Σ w_i` with weights `w_i = bin content`.
122+
* Store `value = ⟨x⟩ / norm`.
123+
3. **Publish two TH1F MOs**
124+
125+
* `AmpPerChannelNormWeightedMeanA`: 96 bins, channels 0–95.
126+
* `AmpPerChannelNormWeightedMeanC`: 112 bins, channels 96–207.
127+
128+
> Tip: when booking the C-side histogram use upper edge **208** (exclusive) with 112 bins to avoid off-by-one bin widths.
129+
130+
#### Configuration (extendedTaskParameters)
131+
132+
| Key | Type | Default | Meaning |
133+
| --------------------- | -----------: | --------: | ---------------------------------------------- |
134+
| `detectorChannelIDs` | list `uint8` | `0–207` | Detector channels to process (subset allowed). |
135+
| `referenceChannelIDs` | list `uint8` | `208–210` | Reference channels used for normalization. |
136+
| `adcSearchMin` | double | `150` | Lower ADC for reference peak search. |
137+
| `adcSearchMax` | double | `600` | Upper ADC for reference peak search. |
138+
| `fracWindowA` | double | `0.25` | Low fractional window, `a` in `(1−a)·x_max`. |
139+
| `fracWindowB` | double | `0.25` | High fractional window, `b` in `(1+b)·x_max`. |
140+
141+
#### Output objects (names & types)
142+
143+
* `FT0/MO/AgingLaserPostProc/AmpPerChannelNormWeightedMeanA` (TH1F)
144+
* `FT0/MO/AgingLaserPostProc/AmpPerChannelNormWeightedMeanC` (TH1F)
145+
146+
#### Trending (example)
147+
148+
Having two output MOs, allows us to create two time series, one per side. An example workflow that accomplishes this is in `etc/ft0-aging-laser-postproc.json`.
149+
150+
#### Notes & gotchas
151+
152+
* **Off-by-one binning (C side)**: for channels `96–207` you need **112 bins** and an **exclusive** upper edge at `208`. Using `207` with 112 bins yields non-unit bin width and will trip histogram helpers.
153+
* **Reference fits**: if all Gaussian fits fail, the post-proc update exits early and publishes nothing for that cycle.
154+
* **Amplitude cuts**: `detectorAmpCut` is currently not used by the task’s filling logic; if you need a cut in the derived quantity, apply it in post-processing or trending.

0 commit comments

Comments
 (0)