TPC: Improve standalone dEdx calculation class

[tubagundem]

Changes

• Merge same-row clusters, then fix the traversal bug this introduced:
  Added handleSameRowClusters(), which merges clusters that fall in the same (sector, row) and are assigned to the same track into a single combined cluster — pad/time are a charge-weighted average, total charge is summed, max charge is the max across the merged clusters. Introducing this merge exposed a bug in the order clusters were traversed along the track; the second commit fixes it by walking clusters in the track's actual native cluster-reference order (rowOrder, recorded on first encounter) instead of assuming a fixed row order.

• 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.

• 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 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; the original single-settings calculatedEdx() is kept as a behaviorally-mirrored convenience overload.

• 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.

• New debug/monitoring counters:
  getNPropagationFailed()/getNRowsProcessed() tracks refit/propagation failure rate.
  getNSubThresholdFilledPerSettings() tracks subthreshold fills per dEdxSettings entry.
  resetDebugCounters() resets all three.

• 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. Runs one CalculatedEdx instance per worker thread for parallel processing, 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), and debug streamer files are named per-thread-per-setting (dEdxDebug_t<i>_s<j>.root) when more than one setting is requested. Also adds a maxEvents parameter to cap the number of processed events, 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.