TPC SCD: rename UnbinnedResid::pack to packToShort, document the fixed 0x7fff scale

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: matthias-kleiner

Detectors/TPC/calibration/SpacePoints/include/SpacePoints/TrackInterpolation.h

@@ -79,11 +79,11 @@ struct TPCClusterResiduals {
 struct UnbinnedResid {
   UnbinnedResid() = default;
   UnbinnedResid(float dyIn, float dzIn, float tgSlpIn, float yIn, float zIn,
-                unsigned char rowIn, unsigned char secIn, short chanIn = -1, bool rejFlag = false) : dy(pack(dyIn, param::MaxResid)),
-                                                                                                     dz(pack(dzIn, param::MaxResid)),
-                                                                                                     tgSlp(pack(tgSlpIn, param::MaxTgSlp, std::abs(tgSlpIn) < param::MaxTgSlp ? 0x7fff - 1 : 0x7fff)),
-                                                                                                     y(pack(yIn, param::MaxY)),
-                                                                                                     z(pack(zIn, param::MaxZ)),
+                unsigned char rowIn, unsigned char secIn, short chanIn = -1, bool rejFlag = false) : dy(packToShort(dyIn, param::MaxResid)),
+                                                                                                     dz(packToShort(dzIn, param::MaxResid)),
+                                                                                                     tgSlp(packToShort(tgSlpIn, param::MaxTgSlp, std::abs(tgSlpIn) < param::MaxTgSlp ? 0x7fff - 1 : 0x7fff)),
+                                                                                                     y(packToShort(yIn, param::MaxY)),
+                                                                                                     z(packToShort(zIn, param::MaxZ)),
                                                                                                      row(rowIn),
                                                                                                      sec(secIn),
                                                                                                      channel(chanIn),
@@ -98,10 +98,12 @@ struct UnbinnedResid {
   short channel{-1};    ///< extra channel info (ITS chip ID, TRD chamber, TOF main pad within the sector)
   bool rejected{false}; ///< residual is flagged as rejected in the validateTrack
 
-  /// value (|value| <= maximum) packed into a short, rounded to the nearest of the 0x7fff steps per maximum and limited to +-limit.
-  /// A plain cast would truncate towards zero, i.e. move every value towards zero by up to one step: the decoded cluster position
-  /// y + dy then depends on the sign of dy below the step size, which biases residuals binned by the cluster position on sub-pad scales
-  static short pack(float value, float maximum, int limit = 0x7fff)
+  /// value (|value| <= maximum) packed into a signed short, rounded to the nearest step. The scale is fixed at 0x7fff steps per maximum
+  /// (decoded everywhere as short * maximum / 0x7fff); limit only clips the result to +-limit (e.g. 0x7fff - 1 for an unclamped tgSlp, to
+  /// keep 0x7fff as the clamp marker), it does not change the scale. A plain cast would truncate towards zero, i.e. move every value
+  /// towards zero by up to one step: the decoded cluster position y + dy then depends on the sign of dy below the step size, which
+  /// biases residuals binned by the cluster position on sub-pad scales
+  static short packToShort(float value, float maximum, int limit = 0x7fff)
   {
     return static_cast<short>(std::clamp<long>(std::lround(value * 0x7fff / maximum), -limit, limit));
   }

Detectors/TPC/calibration/SpacePoints/src/TrackInterpolation.cxx

@@ -913,7 +913,7 @@ void TrackInterpolation::interpolateTrack(int iSeed)
           auto dy = yv - trkWorkITS.getY();
           auto dz = zv - trkWorkITS.getZ();
           if ((std::abs(dy) < param::MaxResid) && (std::abs(dz) < param::MaxResid) && (std::abs(trkWorkITS.getY()) < param::MaxY) && (std::abs(trkWorkITS.getZ()) < param::MaxZ) && std::abs(xv) < param::MaxVtxX) {
-            short compXV = UnbinnedResid::pack(xv, param::MaxVtxX);
+            short compXV = UnbinnedResid::packToShort(xv, param::MaxVtxX);
             mClRes.emplace_back(dy, dz, alpha / TMath::Pi(), trkWorkITS.getY(), trkWorkITS.getZ(), 190, -1, compXV);
             if (!gidTable[GTrackID::ITSTPC].isIndexSet()) {
               LOGP(fatal, "ITS-TPC seed index is not set for TOF track");
@@ -985,7 +985,7 @@ int TrackInterpolation::processTRDLayer(const o2::trd::TrackTRD& trkTRD, int iLa
   if (trkData) {
     auto slope = trdSP.getDy();
     if (std::abs(slope) < param::MaxTRDSlope) {
-      trkData->TRDTrkltSlope[iLayer] = UnbinnedResid::pack(slope, param::MaxTRDSlope);
+      trkData->TRDTrkltSlope[iLayer] = UnbinnedResid::packToShort(slope, param::MaxTRDSlope);
     }
   }
   if (trk64) {
@@ -1308,7 +1308,7 @@ void TrackInterpolation::extrapolateTrack(int iSeed)
           auto dy = yv - trkWorkITS.getY();
           auto dz = zv - trkWorkITS.getZ();
           if ((std::abs(dy) < param::MaxResid) && (std::abs(dz) < param::MaxResid) && (std::abs(trkWorkITS.getY()) < param::MaxY) && (std::abs(trkWorkITS.getZ()) < param::MaxZ) && std::abs(xv) < param::MaxVtxX) {
-            short compXV = UnbinnedResid::pack(xv, param::MaxVtxX);
+            short compXV = UnbinnedResid::packToShort(xv, param::MaxVtxX);
             mClRes.emplace_back(dy, dz, alpha / TMath::Pi(), trkWorkITS.getY(), trkWorkITS.getZ(), 190, -1, compXV);
             if (!gidTableFull[GTrackID::ITSTPC].isIndexSet()) {
               LOGP(fatal, "ITS-TPC seed index is not set for TOF track");