Project
Loading...
Searching...
No Matches
Clusterer.cxx
Go to the documentation of this file.
1// Copyright 2019-2026 CERN and copyright holders of ALICE O2.
2// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
3// All rights not expressly granted are reserved.
4//
5// This software is distributed under the terms of the GNU General Public
6// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
7//
8// In applying this license CERN does not waive the privileges and immunities
9// granted to it by virtue of its status as an Intergovernmental Organization
10// or submit itself to any jurisdiction.
11
14
15#include "Framework/Logger.h"
16
18
19#include <algorithm>
20#include <numeric>
21
22namespace o2::iotof
23{
24
25//__________________________________________________
26void Clusterer::process(gsl::span<const Digit> digits,
27 gsl::span<const DigROFRecord> digitROFs,
28 std::vector<o2::iotof::Cluster>& clusters,
29 std::vector<unsigned char>& patterns,
30 std::vector<o2::itsmft::ROFRecord>& clusterROFs,
31 const ConstDigitTruth* digitLabels,
32 ClusterTruth* clusterLabels,
33 gsl::span<const DigMC2ROFRecord> digMC2ROFs,
34 std::vector<o2::itsmft::MC2ROFRecord>* clusterMC2ROFs)
35{
36 LOG(info) << "RUNNING CLUSTERIZER ON " << digitROFs.size() << " ROFs, TOTAL DIGITS: " << digits.size();
37
38 if (!mThread) {
39 mThread = std::make_unique<ClustererThread>(this);
40 }
41
42 for (size_t iROF = 0; iROF < digitROFs.size(); ++iROF) {
43 LOG(debug) << "Processing ROF " << iROF << "/" << digitROFs.size();
44 const auto& digitsThisROF = digitROFs[iROF];
45 const auto nStoredCls = static_cast<int>(clusters.size());
46 const int first = digitsThisROF.getFirstEntry();
47 const int nDigits = digitsThisROF.getNEntries();
48
49 if (nDigits == 0) {
50 clusterROFs.emplace_back(digitsThisROF.getBCData(), digitsThisROF.getROFrame(), nStoredCls, 0);
51 continue;
52 }
53
54 // Sort digit indices within this ROF by (chipID, row, col, time)
55 // extended with time information from TRK.
56 mSortIdx.resize(nDigits);
57 std::iota(mSortIdx.begin(), mSortIdx.end(), first);
58 std::sort(mSortIdx.begin(), mSortIdx.end(), [&digits](int a, int b) {
59 const auto& da = digits[a];
60 const auto& db = digits[b];
61 if (da.getChipIndex() != db.getChipIndex()) {
62 return da.getChipIndex() < db.getChipIndex();
63 }
64 if (da.getRow() != db.getRow()) {
65 return da.getRow() < db.getRow();
66 }
67 if (da.getColumn() != db.getColumn()) {
68 return da.getColumn() < db.getColumn();
69 }
70 return da.getTime() < db.getTime();
71 });
72 LOG(debug) << "Found " << nDigits << " digits for ROF " << iROF;
73
74 // Process blocks of digits within the same chip (marked by chipID)
75 int iDigit = 0;
76 while (iDigit < nDigits) {
77 const int firstDigit = iDigit;
78 const uint16_t chipID = digits[mSortIdx[iDigit]].getChipIndex();
79
80 // Define the span of digits featuring the same chipID
81 while (iDigit < nDigits && digits[mSortIdx[iDigit]].getChipIndex() == chipID) {
82 ++iDigit;
83 }
84 const int nDigitsThisChip = iDigit - firstDigit;
85
86 LOG(debug) << "Processing chip " << chipID << " with " << nDigitsThisChip << " digits, next digit starts from index " << iDigit;
87 mThread->processChip(digits, firstDigit, nDigitsThisChip, &clusters, &patterns, digitLabels, clusterLabels);
88 }
89
90 LOG(debug) << "Finished processing digit ROF " << iROF << ", produced " << (clusters.size() - nStoredCls) << " clusters";
91 clusterROFs.emplace_back(digitsThisROF.getBCData(), digitsThisROF.getROFrame(),
92 nStoredCls, static_cast<int>(clusters.size()) - nStoredCls);
93 }
94
95 LOG(info) << "FINISHED PROCESSING ALL DIGIT ROFS, TOTAL CLUSTERS PRODUCED: " << clusters.size();
96 if (clusterMC2ROFs && !digMC2ROFs.empty()) {
97 clusterMC2ROFs->reserve(clusterMC2ROFs->size() + digMC2ROFs.size());
98 for (const auto& in : digMC2ROFs) {
99 clusterMC2ROFs->emplace_back(in.eventRecordID, in.rofRecordID, in.minROF, in.maxROF);
100 }
101 }
102
103 LOG(info) << "WRITING CLUSTER TOPOLOGY MAP TO FILE TF3ClusterTopologies.root";
104 mThread->writeTopologiesToFile("TF3ClusterTopologies.root");
105}
106
107//__________________________________________________
108void Clusterer::ClustererThread::processChip(gsl::span<const Digit> digits,
109 int firstDigitIdx, int nDigits,
110 std::vector<Cluster>* clustersOut,
111 std::vector<unsigned char>* patternsOut,
112 const ConstDigitTruth* labelsDigPtr,
113 ClusterTruth* labelsClusPtr)
114{
115 // firstDigitIdx and nDigits are relative to mSortIdx (i.e. mSortIdx[firstDigitIdx..firstDigitIdx+nDigits-1]
116 // are the global digit indices for this chip, already sorted by time, col then row).
117 // We use parent->mSortIdx to resolve the global index of each pixel.
118 const auto& sortIdx = mParent->mSortIdx;
119
120 if (nDigits == 1) {
121 findClustersSingleHit(digits, sortIdx[firstDigitIdx], labelsDigPtr, labelsClusPtr);
122 } else {
123 std::vector<uint32_t> digitIdxs(nDigits);
124
125 for (int i = 0; i < nDigits; ++i) {
126 digitIdxs[i] = sortIdx[firstDigitIdx + i];
127 }
128
129 findClustersMultipleHits(
130 digits,
131 gsl::span<const uint32_t>(digitIdxs),
132 labelsDigPtr,
133 labelsClusPtr);
134 }
135
136 // Flush per-thread output into the caller's containers
137
138 // Push-back cluster labels, dummy labels for clusters with
139 // empty labels, to ensure that the clusterLabels container
140 // WWhas the same size as the clustersOut container.
141 if (labelsClusPtr) {
142 const size_t base = clustersOut->size(); // before inserting this chip's clusters
143 // and store labels as you go, or copy from mLabels:
144 for (size_t i = 0; i < mClusters.size(); ++i) {
145 auto labels = mLabels.getLabels(i); // empty span if none
146 if (labels.empty()) {
147 labelsClusPtr->addNoLabelIndex(base + i);
148 } else {
149 for (const auto& l : labels) {
150 labelsClusPtr->addElement(base + i, l);
151 }
152 }
153 }
154 mLabels.clear();
155 }
156
157 if (!mClusters.empty()) {
158 clustersOut->insert(clustersOut->end(), mClusters.begin(), mClusters.end());
159 mClusters.clear();
160 }
161 if (!mPatterns.empty()) {
162 patternsOut->insert(patternsOut->end(), mPatterns.begin(), mPatterns.end());
163 mPatterns.clear();
164 }
165}
166
167//__________________________________________________
168void Clusterer::ClustererThread::findClustersSingleHit(gsl::span<const Digit> digits,
169 uint32_t digitIdx,
170 const ConstDigitTruth* labelsDigPtr,
171 ClusterTruth* labelsClusPtr)
172{
173 const auto& digitizerParams = o2::iotof::DPLDigitizerParam::Instance();
174 const auto& digit = digits[digitIdx];
175 const uint16_t chipID = digit.getChipIndex();
176 const uint16_t row = digit.getRow();
177 const uint16_t col = digit.getColumn();
178 // const time_t time = digit.getTime();
179 const uint64_t nbc = digit.getBc();
180 const float timeWrtBc = digit.getTdc() * digitizerParams.tdcBin;
181 const time_t time = timeWrtBc + nbc * o2::constants::lhc::LHCBunchSpacingNS;
182
183 if (labelsClusPtr) {
184 int nStoredLabels = 0;
185 fetchMCLabels(digitIdx, labelsDigPtr, nStoredLabels);
186 const auto nCls = static_cast<uint32_t>(mClusters.size());
187 for (int i = 0; i < nStoredLabels; i++) {
188 mLabels.addElement(nCls, mLabelsBuff[i]);
189 }
190 }
191
192 const uint16_t minRow = row;
193 const uint16_t minCol = col;
194 uint8_t rowSpan{1}, colSpan{1};
195 uint32_t clsTopology{0};
196 constexpr uint16_t firedDigitsMask = (1U << 0); // 0x0001 (1)
197 mClsTopoClassifier.getTopology(firedDigitsMask, minRow, rowSpan, minCol, colSpan, clsTopology);
198 // Bit 0 corresponds to (rowOffset=0, colOffset=0) in row-major order
199 Cluster cluster(row, col, rowSpan, colSpan, firedDigitsMask, clsTopology, chipID, time, nbc, timeWrtBc);
200
201 LOG(debug) << "Pushing back cluster with row: " << row << ", col: " << col
202 << ", rowSpan: " << static_cast<int>(rowSpan) << ", colSpan: " << static_cast<int>(colSpan)
203 << ", pattern: " << firedDigitsMask << ", topology: " << static_cast<int>(clsTopology)
204 << ", chipID: " << chipID << ", time: " << time;
205
206 mClusters.emplace_back(cluster);
207 mPatterns.emplace_back(static_cast<unsigned char>(firedDigitsMask));
208}
209
210std::vector<std::vector<uint32_t>> Clusterer::ClustererThread::buildPreclusters(gsl::span<const Digit> digits, gsl::span<const uint32_t> digitIdxs, int maxTimeDiffNSigma, float timeResolution)
211{
212 std::vector<std::vector<uint32_t>> preclusters;
213 std::vector<bool> used(digitIdxs.size(), false);
214
215 auto areNeighbours = [&](const Digit& a, const Digit& b) {
216 return std::abs(static_cast<int>(a.getRow()) - static_cast<int>(b.getRow())) <= 1 &&
217 std::abs(static_cast<int>(a.getColumn()) - static_cast<int>(b.getColumn())) <= 1 &&
218 std::abs(a.getTime() - b.getTime()) <= maxTimeDiffNSigma * timeResolution;
219 };
220
221 for (size_t i = 0; i < digitIdxs.size(); ++i) {
222 if (used[i]) {
223 continue; // already part of an earlier precluster
224 }
225
226 std::vector<uint32_t> precluster;
227 std::vector<size_t> toVisit{i};
228 used[i] = true;
229
230 while (!toVisit.empty()) {
231 const size_t cur = toVisit.back();
232 toVisit.pop_back();
233 precluster.push_back(digitIdxs[cur]);
234
235 // add every not-yet-used digit that touches the current one
236 for (size_t j = 0; j < digitIdxs.size(); ++j) {
237 if (!used[j] && areNeighbours(digits[digitIdxs[cur]], digits[digitIdxs[j]])) {
238 used[j] = true;
239 toVisit.push_back(j);
240 }
241 }
242 }
243
244 preclusters.push_back(std::move(precluster));
245 }
246 return preclusters;
247}
248
249//__________________________________________________
250void Clusterer::ClustererThread::findClustersMultipleHits(gsl::span<const Digit> digits,
251 gsl::span<const uint32_t> digitIdxs,
252 const ConstDigitTruth* labelsDigPtr,
253 ClusterTruth* labelsClusPtr)
254{
255
256 // Constraints on time resolution
257 const auto& digitizerParams = o2::iotof::DPLDigitizerParam::Instance();
258 float timeResolution = digitizerParams.timeResolution; // in ns
259 const auto& clustererParams = o2::iotof::ClustererParam::Instance();
260 int maxTimeDiffNSigma = clustererParams.maxTimeDiffNSigma; // in nsigma
261 int maxFiredDigitsForCls = clustererParams.maxFiredDigitsForCls; // max fired digits in a cluster
262
263 // Digits are ordered by (chipID, row, col, time) within the same chip,
264 // so we can group them into preclusters based on adjacency in row and column.
265 std::vector<std::vector<uint32_t>> preclusters = buildPreclusters(digits, digitIdxs, maxTimeDiffNSigma, timeResolution);
266 uint16_t chipID = digits[digitIdxs[0]].getChipIndex();
267
268 for (const auto& precluster : preclusters) {
269
270 const auto nStoredCls = static_cast<uint32_t>(mClusters.size());
271
272 // Single-digit cluster in chip with multiple fired digits
273 if (precluster.size() == 1) {
274 const auto& digit = digits[precluster[0]];
275 const uint16_t row = digit.getRow();
276 const uint16_t col = digit.getColumn();
277 // const time_t time = digit.getTime();
278 const uint64_t nbc = digit.getBc();
279 const float timeWrtBc = digit.getTdc() * digitizerParams.tdcBin;
280 const time_t time = timeWrtBc + nbc * o2::constants::lhc::LHCBunchSpacingNS;
281
282 if (labelsClusPtr) {
283 int nMcLabels = 0;
284 fetchMCLabels(precluster[0], labelsDigPtr, nMcLabels);
285 for (int i = nMcLabels; i--;) {
286 mLabels.addElement(nStoredCls, mLabelsBuff[i]);
287 }
288 }
289
290 const uint16_t minRow = row;
291 const uint16_t minCol = col;
292 uint8_t rowSpan{1}, colSpan{1};
293 uint32_t clsTopology{0};
294 // Bit 0 corresponds to (rowOffset=0, colOffset=0) in row-major order
295 constexpr uint16_t firedDigitsMask = (1U << 0); // 0x0001 (1)
296 mClsTopoClassifier.getTopology(firedDigitsMask, minRow, rowSpan, minCol, colSpan, clsTopology);
297 // Bit 0 corresponds to (rowOffset=0, colOffset=0) in row-major order
298 Cluster cluster(minRow, minCol, rowSpan, colSpan, firedDigitsMask, clsTopology, chipID, time, nbc, timeWrtBc);
299
300 LOG(debug) << "Pushing back cluster with row: " << row << ", col: " << col
301 << ", rowSpan: " << static_cast<int>(rowSpan) << ", colSpan: " << static_cast<int>(colSpan)
302 << ", pattern: " << firedDigitsMask << ", topology: " << static_cast<int>(clsTopology)
303 << ", chipID: " << chipID << ", time: " << time;
304
305 mClusters.emplace_back(cluster);
306 mPatterns.emplace_back(static_cast<unsigned char>(firedDigitsMask));
307 } else {
308 // Retrieve min row, min col of the precluster
309 uint16_t minRow = std::numeric_limits<uint16_t>::max();
310 uint16_t maxRow = std::numeric_limits<uint16_t>::min();
311 uint16_t minCol = std::numeric_limits<uint16_t>::max();
312 uint16_t maxCol = std::numeric_limits<uint16_t>::min();
313
314 int nMcLabels = 0;
315
316 // Compute average time for digits in the precluster
317 time_t clsTime = 0.0;
318 for (const auto& idx : precluster) {
319 const auto& digit = digits[idx];
320 minRow = std::min(minRow, digit.getRow());
321 minCol = std::min(minCol, digit.getColumn());
322 maxRow = std::max(maxRow, digit.getRow());
323 maxCol = std::max(maxCol, digit.getColumn());
324 const time_t time = digit.getTdc() * digitizerParams.tdcBin + digit.getBc() * o2::constants::lhc::LHCBunchSpacingNS;
325 clsTime += time;
326 fetchMCLabels(idx, labelsDigPtr, nMcLabels);
327 }
328 clsTime /= precluster.size();
329 const uint8_t rowSpan = maxRow - minRow + 1;
330 const uint8_t colSpan = maxCol - minCol + 1;
331
332 const uint64_t nbc = static_cast<uint64_t>(clsTime / o2::constants::lhc::LHCBunchSpacingNS);
333 const float timeWrtBc = clsTime - nbc * o2::constants::lhc::LHCBunchSpacingNS;
334
335 // Fired digits bitmask packed into a single 16-bit pattern variable
336 uint16_t firedDigitsMask = 0;
337
338 if (rowSpan * colSpan > maxFiredDigitsForCls) {
339 // Overflow precluster: pass InvalidPatternID (or 0) and kHuge topology flag
340 Cluster cluster(minRow, minCol, rowSpan, colSpan, Cluster::InvalidPatternID, Topologies::kHuge, chipID, clsTime, nbc, timeWrtBc);
341 mClusters.emplace_back(cluster);
342 mPatterns.emplace_back(Cluster::InvalidPatternID);
343 continue;
344 }
345
346 // Fill firedDigitsMask in Row-Major order (bit 0 = (minRow, minCol))
347 for (const auto& idx : precluster) {
348 const auto& digit = digits[idx];
349 const uint16_t rowOffset = digit.getRow() - minRow;
350 const uint16_t colOffset = digit.getColumn() - minCol;
351
352 // Single bit position calculation
353 const uint16_t bitIndex = rowOffset * colSpan + colOffset;
354
355 // Set bit in LSB-to-MSB order
356 if (bitIndex < ClusterInfo::NBitsPattern) {
357 firedDigitsMask |= (1U << bitIndex);
358 }
359 }
360
361 uint32_t clsTopology{0};
362 mClsTopoClassifier.getTopology(firedDigitsMask, minRow, rowSpan, minCol, colSpan, clsTopology);
363
364 // Construct and add cluster using scalar pattern mask
365 for (int i = 0; i < nMcLabels; i++) {
366 mLabels.addElement(nStoredCls, mLabelsBuff[i]);
367 }
368 Cluster cluster(minRow, minCol, rowSpan, colSpan, firedDigitsMask, clsTopology, chipID, clsTime, nbc, timeWrtBc);
369 LOG(debug) << "Pushing back cluster with row: " << minRow << ", col: " << minCol
370 << ", rowSpan: " << static_cast<int>(rowSpan) << ", colSpan: " << static_cast<int>(colSpan)
371 << ", pattern: " << firedDigitsMask << ", topology: " << static_cast<int>(clsTopology)
372 << ", chipID: " << chipID << ", time: " << clsTime;
373 mClusters.emplace_back(cluster);
374 mPatterns.emplace_back(static_cast<unsigned char>(firedDigitsMask));
375 }
376 }
377}
378
379//__________________________________________________
380void Clusterer::ClustererThread::fetchMCLabels(uint32_t digID, const ConstDigitTruth* labelsDig, int& nFilled)
381{
382 if (!labelsDig || digID >= labelsDig->getIndexedSize()) {
383 return;
384 }
385 auto sortBuffer = [this]() { std::sort(this->mLabelsBuff.begin(), this->mLabelsBuff.end(), [](Label const& a, Label const& b) { return a.getTrackID() < b.getTrackID(); }); };
386 for (const auto& label : labelsDig->getLabels(digID)) {
387 bool skip = false;
388 for (int ic = 0; ic < nFilled; ic++) {
389 if (mLabelsBuff[ic] == label) {
390 skip = true;
391 break;
392 }
393 }
394 if (!skip) {
395 if (nFilled < MaxLabels) {
396 mLabelsBuff[nFilled++] = label;
397 if (nFilled == MaxLabels) {
398 sortBuffer();
399 }
400 } else if (mLabelsBuff.back().getTrackID() > label.getTrackID()) {
401 mLabelsBuff.back() = label;
402 sortBuffer();
403 }
404 }
405 }
406}
407
408//__________________________________________________
409void Clusterer::ClustererThread::writeTopologiesToFile(const char* filename)
410{
411 mClsTopoClassifier.saveCacheToFile("TF3ClusterTopologies.root");
412}
413
414} // namespace o2::iotof
std::ostringstream debug
int16_t time
Definition RawEventData.h:4
unsigned short int uint16_t
int32_t i
Timeframe settings Average distance in cm of events merged into Randomize distance around average distance of merged events Simulate correct bunch interactions instead of placing only the average number of events A value[n] sets TFlen for[n] collisions in Number of bunches per trainsort Number of bunch trains Instantaneous interaction rate Do not simulate border Total number of collisions to be placed in the interior of all time Do not select random but walk over array of events in stride steps h Event generator settings h configStandalone Use CPU for GPU Force usage of the specified GPU device no CPU fallback Continue processing after an error First event to Number of events to Number of iterations to Number of iterations to Number of initial iterations excluded from const char Directory with events to Events directory is and not inside events Show standalone event Run event generator maximum time bin of continuous for triggered for automatic continuous for automatic continuous triggered uint64_t
std::vector< o2::MCCompLabel > labels
uint32_t j
Definition RawData.h:0
uint32_t col
Definition RawData.h:4
Definition of the IOTOF cluster finder.
gsl::span< const TruthElement > getLabels(uint32_t dataindex) const
void addNoLabelIndex(uint32_t dataindex)
adds a data index that has no label
void addElement(uint32_t dataindex, TruthElement const &element, bool noElement=false)
virtual void process(gsl::span< const Digit > digits, gsl::span< const DigROFRecord > digitROFs, std::vector< o2::iotof::Cluster > &clusters, std::vector< unsigned char > &patterns, std::vector< o2::itsmft::ROFRecord > &clusterROFs, const ConstDigitTruth *digitLabels=nullptr, ClusterTruth *clusterLabels=nullptr, gsl::span< const DigMC2ROFRecord > digMC2ROFs={}, std::vector< o2::itsmft::MC2ROFRecord > *clusterMC2ROFs=nullptr)
Definition Clusterer.cxx:26
std::vector< int > mSortIdx
reusable per-ROF sort buffer
Definition Clusterer.h:107
std::unique_ptr< ClustererThread > mThread
Definition Clusterer.h:106
GLint first
Definition glcorearb.h:399
GLboolean GLboolean GLboolean b
Definition glcorearb.h:1233
GLuint GLsizei const GLchar * label
Definition glcorearb.h:2519
GLboolean GLboolean GLboolean GLboolean a
Definition glcorearb.h:1233
std::string filename()
LOG(info)<< "Compressed in "<< sw.CpuTime()<< " s"
std::vector< Cluster > clusters
std::vector< Digit > digits
std::vector< int > row