CbmKFV0FinderTask.h

Go to the documentation of this file.

/* Copyright (C) 2025 GSI Helmholtzzentrum fuer Schwerionenforschung, Darmstadt
   SPDX-License-Identifier: GPL-3.0-only
   Authors: Sergei Zharko [committer] */

 
// TODO: Provide a configurator to the class
 
#pragma once
 
#include "CbmEnumArray.h"
#include "CbmKFParticleFinder.h"  // for the CbmKFParticleFinder::InverseChi2Prob()
#include "CbmKFVertex.h"
#include "CbmVertex.h"
#include "FairTask.h"
#include "KFParticle/KFParticleTopoReconstructor.h"
#include "algo/kfp/KfpV0FinderCutter.h"
#include "algo/kfp/KfpV0FinderDefs.h"
 
#include <memory>
 
class CbmEvent;
class CbmGlobalTrack;
class CbmStsTrack;
class CbmTofHit;
class TClonesArray;
class FairTrackParam;
class KFPTrackVector;
class KFVertex;
class KFParticleFinder;
class CbmEventTriggers;
 
 
namespace cbm::kfp
{
  using namespace cbm::algo::kfp;

  class V0FinderTask : public FairTask {
   public:
    using Cutter_t = V0FinderCutter<EV0Type::Lambda>;

    enum class ECounter : uint8_t
    {
      TracksTotal,                //< Total number of tracks
      TracksSelected,             //< Tracks, which satisfy topology PID applicability
      TracksInfiniteParam,        //< Tracks, which have infinite parameters
      TracksWoTofHits,            //< Tracks, which have no TOF hits
      TracksWNegativeTofHitTime,  //< Tracks, the last TOF hit of which has a negative time (it's time is less then the t0)
      TracksWoStsHits,            //< Tracks, which have no STS hits
      TracksWoPid,                //< Tracks, which has undefined PID
      TracksWoMomentum,           //< Tracks, which has undefined PID
      TracksWAtLeastOneTofHit,   //< Tracks with at least one tof hit
      TracksWAtLeastTwoTofHits,  //< Tracks with at least two tof hits
      TracksWithUnphysicalBeta,  //< Tracks with beta > 1
      TracksW2Sts2Tof,           //< Tracks with at least two STS hits and two TOF hits
      Pions,                     //< Number of pion-candidates
      Protons,                   //< Number of proton-candidates
      EventsTotal,               //< Total number of events
      EventsWoTzero,             //< Number of events with undefined t-zero
      EventsLambdaCand,          //< Events with at least one pion and one proton candidate
      KfpEventsLambdaCand,       //< Events with lambda-candidates in KF-particle
      KfpLambdaCandidates,       //< Number of lambda-candidates
      END
    };

    enum class EPidApproach : uint8_t
    {
      Topo,  //< Topological PID (DCA calculation for a track)
      Mc     //< MC-truth PID
    };

    enum class EProcessingMode : uint8_t
    {
      TimeBased,  //< Time based simulation or real data
      EventBased  //< Event based simulation
    };

    enum class EPvUsageMode : uint8_t
    {
      Target,               //< Use target center as a primary vertex
      Reconstructed,        //< Use reconstructed primary vertex
      ReconstructSingle,    //< Reconstruct a single PV from given track vectors
      ReconstructMultiple,  //< Reconstruct multiple PVs (in case of pile-up)
      Mc                    //< Use MC-true primary vertex
    };

    struct DcaVector {
      double fAbs{std::numeric_limits<double>::quiet_NaN()};  
      double fX{std::numeric_limits<double>::quiet_NaN()};    
      double fY{std::numeric_limits<double>::quiet_NaN()};    
    };

    struct TrackInfo {
      double dca{std::numeric_limits<double>::quiet_NaN()};   
      double beta{std::numeric_limits<double>::quiet_NaN()};  
      const CbmTofHit* pTofHit{nullptr};                      
    };

    struct ParticleInfo {
      double dca{std::numeric_limits<double>::quiet_NaN()};   
      double beta{std::numeric_limits<double>::quiet_NaN()};  
      const CbmTofHit* pTofHit{nullptr};                      
      int32_t eventID{-1};                                    
    };

    explicit V0FinderTask(int verbose = 1) : FairTask("V0FinderTask", verbose){};

    ~V0FinderTask() = default;
 
    // Eliminate copy and move
    V0FinderTask(const V0FinderTask&) = delete;
    V0FinderTask(V0FinderTask&&)      = delete;
    V0FinderTask& operator=(const V0FinderTask&) = delete;
    V0FinderTask& operator=(V0FinderTask&&) = delete;
 
 
    //* FairTask overriden methods

    void Exec(Option_t*) override;

    void Finish() override;

    InitStatus Init() override;
 
 
    //* Accessors

    KFParticleFinder* GetKFParticleFinder() { return fpTopoReconstructorTs->GetKFParticleFinder(); }

    const KFParticleFinder* GetKFParticleFinder() const { return fpTopoReconstructorTs->GetKFParticleFinder(); }

    const auto& GetTrackDcaToOrigin() const { return fvTrackDca; }

    std::shared_ptr<const KFParticleTopoReconstructor> GetTopoReconstructor() const { return fpTopoReconstructorTs; }

    std::shared_ptr<const Cutter_t> GetCutter() const { return fpCutter; }

    const std::vector<DcaVector>& GetTrackDca() const { return fvTrackDca; }

    const std::vector<TrackInfo>& GetTrackInfo() const { return fvTrackInfo; }

    const std::vector<ParticleInfo>& GetParticleInfo() const { return fvParticleInfo; }
 
    //* Task logic and preliminary selection cut setters

    void SetConfigName(const TString& fileName) { fsConfigName = fileName; }

    void SetCutsConfigName(const TString& fileName) { fsCutsConfigName = fileName; }

    void SetProcessingMode(EProcessingMode mode) { fProcessingMode = mode; }

    void SetPidApproach(EPidApproach pid) { fPidApproach = pid; }

    void SetPvFindingMode(EPvUsageMode mode) { fPvUsageMode = mode; }

    void SetUseMc(bool bUseMc) { fbUseMc = bUseMc; }

    void SetMinPionDca(double dca) { fMinPionDca = dca; }

    void SetMinProtonDca(double dca) { fMinProtonDca = dca; }

    void SetQaOutputFileName(const TString& fileName) { fsQaOutputName = fileName; }

    void SetQpAssignedUncertainty(double uncertainty) { fQpAssignedUncertainty = uncertainty; }

    void SetTzeroOffset(double offset) { fTzeroOffset = offset; }

    // NOTE: The KFParticleFinder has its internal mixed-event analysis mode, but was not used in mCBM Lambda-analysis
    //       the internal mixed-event mode can be selected using the following method:
    //          fpTopoReconstructorTs->SetMixedEventAnalysis()
    void SetMixedEventMode(bool bMixedEvent) { fbMixedEventMode = bMixedEvent; }
 
 
    //* KFParticleFinder setters

    void AddDecayToReconstructionList(int pdg) { GetKFParticleFinder()->AddDecayToReconstructionList(pdg); }
 
    //* Static helper methods

    static std::string ToString(EProcessingMode mode);

    static std::string ToString(EPidApproach pid);

    static std::string ToString(EPvUsageMode pvMode);

    static std::string ToString(const FairTrackParam* pParam);

    static bool CheckTrackParam(const FairTrackParam* pParam);
 
   private:
    //* Auxilary internal methods

    void ApplyConfiguration();

    template<int PdgCode>
    void AssignMomentum(CbmGlobalTrack* pTrack, double beta);

    void AssignMomentum(CbmGlobalTrack* pTrack, double qp, double qpVar);

    DcaVector EstimateDcaToOrigin(const CbmStsTrack* pTrack) const;

    double EstimateBeta(const CbmTofHit* pTofHit) const;

    TrackInfo CollectTrackInfo(const CbmGlobalTrack* pTrack) const;

    KFPTrackVector MakeKfpTrackVector(const std::vector<const CbmGlobalTrack*>& vpTracks,
                                      const std::vector<int>& vTrackIds, const std::vector<float>& vChi2ToPv,
                                      bool bAtFirstPoint) const;

    KFVertex MakeKfpPrimaryVertex(float x, float y, float z) const;

    cbm::algo::kfp::ETrackPid InferTrackPidTopo(double dca) const;

    template<bool UseEvent>
    bool ProcessEvent(const CbmEvent* pEvent);

    double ShiftTofHitsToTzero(const CbmEvent* pEvent);

    void StoreParticles(const CbmEvent* pEvent);
 
   public:
    //* Task constants (To be moved to a configuration)
    static constexpr int kPrimaryPdg{321};        
    static constexpr int kUndefPdg{-2};           
    static constexpr float kChi2PvPrimThrsh{3.};  
 
    //* Physical constants
    static constexpr double kPionMass{0.13957039};      
    static constexpr double kProtonMass{0.938272088};   
    static constexpr double kSpeedOfLight{29.9792458};  
 
   private:
    //* Different run-time cuts and flags
    double fTzeroOffset{0.};             
    double fMinPionDca{1.5};             
    double fMinProtonDca{0.5};           
    double fQpAssignedUncertainty{0.1};  
    int fPrimaryAssignedPdg{321};        
    double fMinBetaProton{0.};           
    double fMaxBetaProton{1.};           
    double fMinBetaPion{0.};             
    double fMaxBetaPion{1.};             
 
    //* Cutter
    std::shared_ptr<Cutter_t> fpCutter{std::make_shared<Cutter_t>()};
 
    //* Input data branches
    TClonesArray* fpBrRecoEvents{nullptr};
    TClonesArray* fpBrGlobalTracks{nullptr};
    TClonesArray* fpBrStsTracks{nullptr};
    TClonesArray* fpBrTrdTracks{nullptr};
    TClonesArray* fpBrTofTracks{nullptr};
    TClonesArray* fpBrStsHits{nullptr};
    TClonesArray* fpBrTrdHits{nullptr};
    TClonesArray* fpBrTofHits{nullptr};
    CbmVertex* fpBrPrimaryVertex{nullptr};
 
    //* Output data branches
    std::vector<CbmEventTriggers>* fpBrEventTriggers{nullptr};  //< Branch for event triggers
    // TODO: in principle one can store the found KF particles and vertices as well
 
    //* Temporary data and auxilary variables (per FairTask::Exec() call)
    std::vector<DcaVector> fvTrackDca;         
    std::vector<TrackInfo> fvTrackInfo;        
    std::vector<ParticleInfo> fvParticleInfo;  
    std::unique_ptr<CbmVertex> fpOrigin{
      std::make_unique<CbmVertex>()};  
 
    //* KFParticleFinder utilities
    // Main topology reconstructor
    std::shared_ptr<KFParticleTopoReconstructor> fpTopoReconstructorTs{std::make_shared<KFParticleTopoReconstructor>()};
    std::unique_ptr<KFParticleTopoReconstructor> fpTopoReconstructorEvent{
      std::make_unique<KFParticleTopoReconstructor>()};
 
    //* Control flags
    EProcessingMode fProcessingMode{EProcessingMode::TimeBased};  
    EPidApproach fPidApproach{EPidApproach::Topo};                
    EPvUsageMode fPvUsageMode{EPvUsageMode::Target};              
    bool fbMixedEventMode{false};                                 
    bool fbUseMc{false};                                          
    bool fbUsePvChi2Selection{false};                             
 
    //* QA and monitoring variables
    cbm::core::EnumArray<ECounter, size_t> fCounters{{0}};  
    TString fsQaOutputName{"./V0FinderQa.root"};            
    TString fsConfigName{""};                               
    TString fsCutsConfigName{""};                           
 
 
    ClassDefOverride(V0FinderTask, 0);
  };
}  // namespace cbm::kfp