TPC: Improve standalone dEdx calculation class

[tubagundem]

Changes

• Merge same-row clusters (redesigned into a configurable, proximity-gated method), then fix the traversal bug the original merge exposed:
  The first two commits add handleSameRowClusters(), which unconditionally merged every cluster falling in the same (sector, row) and assigned to the same track into one combined cluster; pad/time a charge-weighted average, total charge summed, max charge the max across the group; and fixed a traversal bug this merge exposed by walking clusters in the track's actual native cluster-reference order (rowOrder, recorded on first encounter) instead of assuming a fixed row order. This was later redesigned: a same-row group is now only eligible for merging if it passes a pad/time proximity gate (setSameRowMaxPadDiff()/setSameRowMaxTimeDiff(), default 3 pad / 4 time bins); a group that fails it (e.g. the two legs of a low-p looper crossing the same row) is always kept as one independent sample per cluster, since merging those was biasing the low-p OROC3 dE/dx tail. For groups that do pass the gate, the new dEdxSettings::sameRowClusterMethod selects how: 0 = don't merge (one sample per raw cluster), 1 = merge and sum (the original charge-weighted-average/sum behavior), 2 (default) = merge by taking the single dominant (largest qTot) fragment.

• Fixed frequent track-propagation failures, plus a faster propagation option:
  Track propagation (mPropagateTrack) previously left the track state corrupted if rotate() or PropagateToXBxByBz failed partway through a step, causing every later row's propagation to fail too. Both now snapshot the track state first and roll back to it on failure, so one bad row no longer poisons the rest. Also added setPropagateParams() / mPropagateParams, a cheaper alternative that propagates only the track parameters (no material corrections) instead of the full track.

• Added a GPU-refit-to-propagation fallback for stalled refits:
  GPUTPCGMTrackParam::MoveToReference() and GPUTrackingRefit::RefitTrack() (and its RefitTrackAsGPU/RefitTrackAsTrackParCov overloads) now report through an output reachedReferenceOut flag whether the fit actually reached the requested reference X, instead of silently leaving the track at a stale/wrong position when it couldn't; this mainly affected low p tracks whose fitted helix falls short of an outer row. CalculatedEdx's refit path uses this: the first time a track's refit fails to reach a row, it permanently switches that track to plain propagation (new propagateTrackToX(), the same fallback ladder as mPropagateTrack/mPropagateParams) chained from its pristine pre-refit seed, instead of continuing to call a refit that will keep failing on later rows too.

• Excluded clusters no longer bias the subthreshold fill:
  Minimum-charge tracking and missing-cluster counting used to run over every cluster, including ones that would later be excluded (dead region, edge, failed propagation, etc.). Now they only run over clusters that are actually accepted into the dE/dx calculation.

• New cluster-exclusion:

  • ExcludeSplitCl split into ExcludeSplitPadCl and ExcludeSplitTimeCl for finer-grained control (bit values renumbered).
  • ExcludeSamePadRowCl — exclude clusters that were merged from the same pad row.
  • Stack-boundary exclusion via new isInStackBoundaries() and a mStackBoundaries table (row ranges per GEM stack), controlled by a new stackBoundaryMethod parameter (0 = disabled, 1 = exclude boundary row, 2 = also exclude the adjacent row).
  • Dead-channel exclusion: a dead channel map is now loaded from CCDB (loadCalibsFromCCDB()) and clusters in dead regions are excluded.

• Per-region occupancy output:
  Added an AverageOccupancy struct (IROC/OROC1-3) and a new output parameter on calculatedEdx() returning average track occupancy per TPC region.

• Debug streamer overhaul:
  Replaced the old per-track parallel debug vectors with two linked trees: dEdxDebugTrack (one row per track: pristine track, output, average occupancy, summary counts) and dEdxDebugCl (one row per cluster, with the track's propagated/refit parameters at that cluster). Rows are matched via a new running mDebugTrackIndex. setStreamer() also now keeps a map of streamers keyed by output filename, so different calculatedEdx() calls writing to different debug files each get their own independent tree.

• Simplified subthreshold cluster filling:
  Removed the Landau-based method (method=2) from fillMissingClusters(), keeping only minimum-charge and minimum-charge/2.

• getOccupancy() signature change:
  Now takes a cluster time (float) instead of a ClusterNative, and is only valid when the refit method (not propagation) is used, since the occupancy map is only filled by setRefit().

• Evaluate multiple dE/dx settings per track without repeating propagation:
  New dEdxSettings struct bundles a full configuration (truncation range, correction mask, cluster mask, subthreshold/stack-boundary/same-row-cluster method, per-call debug file, subthreshold charge caps). Per-track work is split into gatherRowClusterData() (refit/propagation, run once per track) and calculatedEdxFromRowData() (settings-dependent charge computation, run once per dEdxSettings entry against the shared row data). New calculatedEdxMultipleSettings() entry point ties the two together and returns one dEdxInfo per settings entry.

• Legacy calculatedEdx() no longer duplicates the implementation:
  The standalone single-settings calculatedEdx() overloads are now thin wrappers that build a dEdxSettings and delegate to the shared gatherRowClusterData()/calculatedEdxFromRowData() path used by calculatedEdxMultipleSettings().

• Subthreshold charge cap reintroduced as a per-region value clamp instead of an all-or-nothing gate:
  The old mMinChargeTotThreshold/mMinChargeMaxThreshold gated whether a gap got filled at all, track-wide across all regions: if the track's weakest accepted cluster anywhere exceeded the threshold, no gap on that track was filled in any region, undercounting subthreshold clusters relative to online tracking. Removed those members entirely; subthreshold gaps are now always filled (unless excluded), using a per-region running minimum charge, optionally clamped per settings entry via new dEdxSettings::maxSubthresholdChargeTot/maxSubthresholdChargeMax (default effectively uncapped) applied only to the fill value, never to whether/how many gaps get filled. fillMissingClusters() now takes per-region (float[4]) minimum-charge arrays instead of one track-wide scalar.

• Fixed a correction-map crash/inaccuracy from mutating an already-flattened transform in place:
  CalculatedEdx built its refit correction map as a TPCFastTransformPOD and then mutated that same flattened buffer directly (setTPCCorrMap()/vDrift updates); not a supported use of the POD form, and a source of heap corruption under production load. Fixed by keeping a regular, exclusively-owned TPCFastTransform (mTPCCorrMapFull) as the only object ever mutated, and re-flattening it into the POD buffer the GPU refitter reads via a new rebuildTPCCorrMapPOD() after every change. Along the way, loadCalibsFromCCDB() (and the matching local-snapshot loader) gained a loadVDriftForRefit option (default on) that fetches TPC/Calib/VDriftTgl and applies it to the refit transform via new setTPCVDrift()/setVDriftFromFile(); previously the refit transform carried no calibrated drift velocity/t0 at all, biasing the local z coordinates the refit sees.

• New debug/monitoring counters:

  • getNPropagationFailed()/getNRowsProcessed() track refit/propagation failure rate.
  • getNRefitFallback() tracks how often a row recovered via the new refit-to-propagation fallback.
  • getNSubThresholdFilledPerSettings() tracks subthreshold fills per dEdxSettings entry.
  • resetDebugCounters() resets all of them.

• Added macro/calculatedEdx.C:
  Example macro demonstrating standalone use of CalculatedEdx: reads TPC tracks and native clusters (data or MC), optionally restricting to TPC tracks matched to an ITS track, driven by a single settingsList vector parameter so multiple dE/dx settings can be evaluated per track in one run. The output tree gains one dEdx<i> branch per settingsList entry (instead of a single dEdx branch). Processes each event's tracks sequentially through a single CalculatedEdx instance — an earlier version ran one instance per worker thread for parallel processing, but mPropagateTrack was observed to give different results depending on nThreads, so multithreading was removed to keep this a reliable, simple usage example rather than a thread-count-dependent one (root cause of that discrepancy not yet identified); debug streamer files are now named per-setting only (dEdxDebug_s<j>.root) when more than one setting is requested, instead of per-thread-per-setting. Also adds a maxEvents parameter to cap the number of processed events, options to feed space-charge/drift-velocity calibration into the refit transform, and per-event logging of the refit/propagation failure rate and subthreshold-fill counts broken down per settings entry.

[shahor02]

Is this relevant for the pb26 production?

[tubagundem]

Is this relevant for the pb26 production?

No, this is just to improve the dE/dx calculation class if we want to use it later or if we want to debug things locally.

[alibuild]

Error while checking build/O2/fullCI_slc9 for d990619 at 2026-09-19 02:19:

## sw/BUILD/lhapdf-latest/log
collect2: error: ld returned 1 exit status


## sw/BUILD/VecGeom-latest/log
CMake Error at /container/bits/sw/BUILD/4b902089e8ae3e1235b16cffffe5b41003a490dd/VecGeom/buildExternals/VecCore-0.8.0/build/external/stamp/VecCore-0.8.0-configure-RELWITHDEBINFO.cmake:49 (message):
ninja: build stopped: subcommand failed.
CMake Error at cmake/modules/BuiltinVecCore.cmake:36 (add_custom_command):
CMake Error at CMakeLists.txt:222 (find_package):

Full log here.

[shahor02]

Why is this needed? Just return false if the loop is completed w/o returning true.

[shahor02]

Not sure this r formatting is correct. Also, it is quite sporadic.Was it imposed by the clang-format?

[davidrohr]

This is a bug in clang-format. You can leave it in or not, it will not break the code. But I will most probably revert such bogus formatting with my next PR.

[davidrohr]

Please do not unconditionally add parameters only for the debug streamers.
Please use GPUCA_DEBUG_STREAMER_CHECK(, int32_t iTrk, uint8_t flags).

[davidrohr]

This is a bug in clang-format. You can leave it in or not, it will not break the code. But I will most probably revert such bogus formatting with my next PR.

[davidrohr]

Do we really need this additional return value? Can't you just check at the end if the track x position is at the reference?