MatchCosmics: TOF flight pair of the legs as selection criterion

New MatchCosmicsParams tofFlightSelection (default off, on in the preset
physics-v1; needs TOF clusters, the workflow then adds them to the
matcher's inputs): every pair of TPC-only legs accepted by checkPair is
tested for a top / bottom TOF cluster pair along the outward
continuations of its legs whose time difference matches the muon's
flight between them along the helix (tofFlightTolerance), with the mean
time in the pair's time window and both legs' y and z within tofRoad at
that time (the test of the cluster collector). A confirmed pair takes
the TOF time as its common time (error tofTimeError), so the winner is
refitted at it, and is put in front of all unconfirmed partners of both
legs (chi2 order within each group): the mutual-best selection prefers
it, and a random pair can no longer take a leg of a TOF-confirmed cosmic.

If the refit of a confirmed winner at the TOF time fails (in practice
chi2Match > maxChi2Match), it is refitted at the time it has without its
TOF flight pair (z-continuity time of legs on opposite sides, else the
centre of the overlap of the legs' time brackets): the winner selection
has already released the other candidates of both legs, so dropping the
winner loses both legs. PbPb 568041: 24 TOF-tagged same-side cosmics,
all real (legs on one line far from the beam line, TOF pair in the
physical order without a reversed-order alternative), mostly on the C
side nearer the readout at the TOF time; A-C cosmics show no TOF-TPC
time offset there. The refit loop body is a lambda refitting a winner at
a given time.

The TOF candidates of a leg are searched once per TF, in the time-sorted
TOF clusters of its time bracket and in the sector it points to and its
neighbours. Debug tree "match": tofScore.

Distorted cosmic MC (19 x 10 TFs, PbPb-like distortions, physics-v1
without the common-time refit, without -> with tofFlightSelection):
matched muons 6848 -> 6871 of 8639, 0 wrong pairs both, 2134 confirmed
pairs, 9 fallbacks.

PbPb 568041 reconstructed from CTF (310 CTFs, 16541 TFs, vs. the same
CTFs without the TOF selection, older code, before the fallback):
cosmics 4782 -> 4760, TOF-tagged 681 -> 697; A-C: 11 untagged pairings
replaced by 12 TOF-tagged ones. Matcher CPU 0.536 -> 0.545 s per TF.

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

Author: matthias-kleiner

Detectors/GlobalTracking/include/GlobalTracking/MatchCosmics.h

@@ -84,6 +84,19 @@ class MatchCosmics
     int next = MinusOne; ///< index of eventual next record
     float tCommon = 0.f; ///< common time [mus] fixed by z continuity of TPC-only legs on opposite TPC sides
     float tCommonErr = -1.f; ///< its 1 sigma error [mus]; < 0: not fixed, the refit uses the centre of the time-bracket overlap and the cosmic's time error is the overlap's half-width
+    float tofScore = -1.f;   ///< score of the top / bottom TOF hit pair matching the muon's flight (tofFlightSelection; < 0: none); a pair with one wins against pairs without
+    float tCommonNoTOF = 0.f;     ///< tCommon before a TOF flight pair replaced it: the refit falls back to it if the refit at the TOF time fails
+    float tCommonErrNoTOF = -1.f; ///< tCommonErr before a TOF flight pair replaced it
+  };
+
+  struct TOFCandidate { ///< TOF cluster along the outward continuation of a TPC-only seed
+    int index = -1;     ///< index of the TOF cluster
+    double timeNS = 0.; ///< its time since the start of the TF [ns]
+    float dy = 0.f;     ///< cluster - predicted y in the frame of the cluster's sector [cm]
+    float dz = 0.f;     ///< cluster - predicted z, the leg's z taken at its own reference time tRef [cm]
+    float gx = 0.f;     ///< global position of the cluster [cm]
+    float gy = 0.f;
+    float gz = 0.f;
   };
 
   struct TrackSeed : public o2::track::TrackParCov {
@@ -139,7 +152,10 @@ class MatchCosmics
   void updateTimeDependentParams();
   RejFlag checkPair(int i, int j);
   bool refitSeedAtTime(const TrackSeed& seed, float timeMUS, TrackSeed& out);
-  void registerMatch(int i, int j, float chi2, float tCommon = 0.f, float tCommonErr = -1.f);
+  void registerMatch(int i, int j, float chi2, float tCommon = 0.f, float tCommonErr = -1.f, float tofScore = -1.f, float tCommonNoTOF = 0.f, float tCommonErrNoTOF = -1.f);
+  void prepareTOFClusters(const o2::globaltracking::RecoContainer& data);
+  const std::vector<TOFCandidate>& getTOFCandidates(int iseed);
+  float findTOFFlightPair(int i, int j, float tMinMUS, float tMaxMUS, float& tofTimeMUS);
   void suppressMatch(int partner0, int partner1);
   void createSeeds(const o2::globaltracking::RecoContainer& data);
   bool validateMatch(int partner0);
@@ -169,6 +185,12 @@ class MatchCosmics
   const o2::globaltracking::RecoContainer* mRecoData = nullptr; ///< inputs of the TF being processed
   o2::gpu::GPUO2InterfaceRefit* mTPCRefitter = nullptr;         ///< TPC refitter of the TF being processed (owned by process())
   size_t mNRefitsCommonTime = 0;                                ///< seeds refitted at the common time of a same-side pair in this TF
+  std::vector<int> mTOFClusterOrder;                            ///< TOF clusters of the TF sorted in time (tofFlightSelection)
+  std::vector<float> mTOFClusterTimeMUS;                        ///< their times since the start of the TF [mus], same order
+  std::vector<std::vector<TOFCandidate>> mSeedTOFCandidates;    ///< TOF candidates per seed, filled on first use
+  std::vector<bool> mSeedTOFDone;                               ///< the TOF candidates of the seed are filled
+  size_t mNTOFConfirmed = 0;                                    ///< accepted pairs with a TOF flight pair in this TF
+  size_t mNTOFFallbacks = 0;                                    ///< TOF-confirmed winners refitted at their time without TOF in this TF
 
   std::vector<o2d::TrackCosmics> mCosmicTracks;
   std::vector<o2::MCCompLabel> mCosmicTracksLbl;

Detectors/GlobalTracking/include/GlobalTracking/MatchCosmicsParams.h

@@ -42,6 +42,10 @@ struct MatchCosmicsParams : public o2::conf::ConfigurableParamHelper<MatchCosmic
   bool constrainTPCOnlyZ = false; // TPC-only legs: test z at a common time (same side, or a leg with known time), else require the time implied by z continuity in both brackets
   bool vetoSameHalf = false;      // reject pairs whose two legs lie on the same side of the closest approach (two pieces of one leg)
   bool refitSameSideAtCommonTime = false; // TPC-only legs on the same side: compare them refitted at the centre of their brackets' overlap instead of at their own time0s
+  bool tofFlightSelection = false;        // needs TOF clusters: accepted pairs of TPC-only legs pointing to a top / bottom TOF hit pair with the muon's flight time win the selection, refit at that time (if that fails, at their time without TOF)
+  float tofRoad = 5.f;                    // half-width [cm] in y and z of the road at the TOF around the outward continuation of a TPC-only leg
+  float tofFlightTolerance = 2.f;         // max. deviation [ns] of the top / bottom TOF time difference from the flight time along the helix
+  float tofTimeError = 0.1f;              // error [mus] of the TOF time of a confirmed cosmic, for its refit and time window (covers TPC vs TOF offsets)
   float nSigmaTError = 4.f;    // number of sigmas on track time error for matching (except for TPC which provides an interval)
   float tpcExtraZError2 = 1.f; // extra error^2 on the TPC-only track Z coordinate
   float fiducialRIP = 1.0f;    // consider track having |Y@x=0|< this as passing DCA cut (if requested)