diff --git a/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/MuonMatchingTool.h b/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/MuonMatchingTool.h index 8471246d71280964288357de4aecb259278be4fd..a1e9be5697f84a3473b80e7588024376446a0b58 100644 --- a/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/MuonMatchingTool.h +++ b/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/MuonMatchingTool.h @@ -21,6 +21,10 @@ #include <tuple> +/** + * @brief Class that provides functionalities for searching for online muons close to a given offline muon + * and judging they are matched with the specific criteria. + */ class MuonMatchingTool : public AthAlgTool { public: @@ -38,40 +42,133 @@ class MuonMatchingTool : public AthAlgTool { if( "L1_MU15"==l1item) return L1Items::L1_MU15; if( "L1_MU20"==l1item) return L1Items::L1_MU20; if( "L1_MU21"==l1item) return L1Items::L1_MU21; - return L1Items::ERROR; + return L1Items::ERROR; } - - + /** + * @brief Function that searches for a Level 1 muon candidate and judges if it is matched to a given offline muon. + * @param mu Offline muon around which Level 1 candidates are searched. + * @param ctx Reference to the @c EventContext needed for accessing the @c LVL1MuonRoIs container. + * @param trigger Considered level 1 threshold name, e.g. L1_MU10, etc. + * @param pass True if a candidate is found. + * @return Pointer to the matched candidate. This is @c nullptr when there is no candidate found. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + */ const xAOD::MuonRoI* matchL1(const xAOD::Muon *mu, const EventContext& ctx, std::string trigger, bool &pass) const; + + /** + * @brief Function that searches for an L2 standalone muon (L2MuonSA) candidate and judges if it is matched to a given offline muon. + * @param mu Offline muon around which L2MuonSA candidates are searched. + * @param trigger Considered chain name, e.g. HLT_mu26_ivarmedium_L1MU20, etc. + * @param pass True if the matched candidate passed the hypothesis step. + * @return Pointer to the matched candidate. This is @c nullptr when there is no candidate found. + * Important: a valid pointer doesn't mean that it passed the hypothesis, users should check @c pass for the decision. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + */ const xAOD::L2StandAloneMuon* matchSA(const xAOD::Muon *mu, std::string trigger, bool &pass) const; + + /** + * @brief Function that searches for the L2 standalone muon (L2MuonSA) candidate closest to a given offline muon. + * @param mu Offline muon around which L2MuonSA candidates are searched. + * @param trigger Considered chain name, e.g. HLT_mu26_ivarmedium_L1MU20, etc. + * @param dR The dR between the offline muon and the L2MuonSA candidate. + * @return Pointer to the found candidate. This is @c nullptr when there is no candidate found. + * Important: a valid pointer doesn't mean that it passed the hypothesis and matched, + * users should check @c pass for the decision and @c pass for knowing if it is really matched. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + * @todo Consider improving the argument list. + */ const xAOD::L2StandAloneMuon* matchSA(const xAOD::Muon *mu, std::string trigger, float &dR) const; + + /** + * @brief Function that searches for an L2 combined muon (L2muComb) candidate and judges if it is matched to a given offline muon. + * @param mu Offline muon around which L2muComb candidates are searched. + * @param trigger Considered chain name, e.g. HLT_mu26_ivarmedium_L1MU20, etc. + * @param pass True if the matched candidate passed the hypothesis step. + * @return Pointer to the matched candidate. This is @c nullptr when there is no candidate found. + * Important: a valid pointer doesn't mean that it passed the hypothesis, users should check @c pass for the decision. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + */ const xAOD::L2CombinedMuon* matchCB(const xAOD::Muon *mu, std::string trigger, bool &pass) const; + + /** + * @brief Function that searches for an EF standalone muon (EFSA) candidate and judges if it is matched to a given offline muon. + * @param mu Offline muon around which EFSA candidates are searched. + * @param trigger Considered chain name, e.g. HLT_mu26_ivarmedium_L1MU20, etc. + * @param pass True if the matched candidate passed the hypothesis step. + * @return Pointer to the matched candidate. This is @c nullptr when there is no candidate found. + * Important: a valid pointer doesn't mean that it passed the hypothesis, users should check @c pass for the decision. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + */ const xAOD::Muon* matchEFSA(const xAOD::Muon *mu, std::string trigger, bool &pass) const; + + /** + * @brief Function that searches for an EF combined muon (EFCB) candidate and judges if it is matched to a given offline muon. + * @param mu Offline muon around which EFCB candidates are searched. + * @param trigger Considered chain name, e.g. HLT_mu26_ivarmedium_L1MU20, etc. + * @param pass True if the matched candidate passed the hypothesis step. + * @return Pointer to the matched candidate. This is @c nullptr when there is no candidate found. + * Important: a valid pointer doesn't mean that it passed the hypothesis, users should check @c pass for the decision. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + */ const xAOD::Muon* matchEF(const xAOD::Muon *mu, std::string trigger, bool &pass) const; + /** + * @brief Function that searches for an offline muon within @c DR_cut from the given eta-phi (of a online muon) + * @param ctx Reference to the @c EventContext needed for accessing the @c Muons container. + * @param trigEta Eta of the given online muon + * @param trigPhi Phi of the given online muon + * @return Pointer to the matched offline muon. This is @c nullptr when there is no muon found. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + */ const xAOD::Muon* matchOff( const EventContext& ctx, float trigEta, float trigPhi, float DR_cut) const; + /** + * @brief Function to extrapolate a Inner Detector track to the pivot plane i.e. the middle layers of the Muon Spectrometer where the level 1 RoI is defined. + * This functionality is not available yet. + * @param track Inner Detector track that is extrapolated. + * @return Pointer to the extrapolated track parameters. + * @see @c reqdRL1byPt + * @todo Return std::unique_ptr when this is available. + */ const Trk::TrackParameters* extTrackToPivot(const xAOD::TrackParticle *track) const; - const Trk::TrackParameters* extTrackToTGC(const xAOD::TrackParticle *track) const; - const Trk::TrackParameters* extTrackToRPC(const xAOD::TrackParticle *track) const; + /** + * @brief Function compute dR used for matching offline muons and level 1 RoIs at the pivot plane. + * This is needed that the accuracy of the extrapolation by @c extTrackToPivot is dependent on the pt of the offline muon. + * @param mupt Offline muon pt + * @return Required dR between the offline muon and Level 1 muons + */ static double reqdRL1byPt(double mupt); private: // private methods - // See MuonMatchingTool.cxx for specialization and MuonMatchingTool.icc for implementation + /** + * @brief Function that searches for an online muon candidate of type T and judges if it is matched to a given offline muon. + * @param offl Position of the offline muon used for computing dR. + * @param trigger Considered chain name, e.g. HLT_mu26_ivarmedium_L1MU20, etc. + * @param reqdR Requirement of dR used for the matching. Note that reqdR is updated with the dR of the found candidate. + * @param pass True if the matched candidate passed the hypothesis step. + * @param trigPosForMatchFunc Function pointer that implements cuts for the online muon candidates. + * @return Pointer to the matched candidate. This is @c nullptr when there is no candidate found. + * Important: a valid pointer doesn't mean that it passed the hypothesis, users should check @c pass for the decision. + * @see MuonMatchingTool.icc for the implementation and MuonMatchingTool.cxx for the instantiation. + * @todo Consider returning a smart pointer to prevent users from deleting the returned pointer as it is owned by StoreGate. + * @todo Consider improving the argument list. + */ template<class T, class OFFL> const T* match(const OFFL *offl, std::string trigger, float &reqdR, bool &pass, std::tuple<bool,double,double> (*trigPosForMatchFunc)(const T*) = &MuonMatchingTool::trigPosForMatch<T>) const; const Amg::Vector3D offlineMuonAtPivot(const xAOD::Muon *mu) const; double FermiFunction(double x, double x0, double w) const; + const Trk::TrackParameters* extTrackToTGC(const xAOD::TrackParticle *track) const; + const Trk::TrackParameters* extTrackToRPC(const xAOD::TrackParticle *track) const; // static methods // Template methods that perform different matching schemes for T=xAOD::L2StandAloneMuon, xAOD::L2CombinedMuon and xAOD::Muon (EF). template<class T> static inline std::tuple<bool,double,double> trigPosForMatch(const T *trig); static inline std::tuple<bool,double,double> trigPosForMatchEFSA(const xAOD::Muon *trig); - + SG::ReadHandleKey<xAOD::MuonRoIContainer> m_MuonRoIContainerKey {this, "MuonRoIContainerName", "LVL1MuonRoIs", "Level 1 muon container"}; SG::ReadHandleKey<xAOD::MuonContainer> m_MuonContainerKey {this, "MuonContainerName", "Muons", "Offline muon container"}; diff --git a/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/TrigMuonMonitorAlgorithm.h b/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/TrigMuonMonitorAlgorithm.h index 1297ec895ddf4298d56146c521f208ef70592082..8e62bf27461fbb3d37f9456b6f220b2865d7668a 100644 --- a/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/TrigMuonMonitorAlgorithm.h +++ b/Trigger/TrigMonitoring/TrigMuonMonitoringMT/src/TrigMuonMonitorAlgorithm.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2002-2019 CERN for the benefit of the ATLAS collaboration + Copyright (C) 2002-2020 CERN for the benefit of the ATLAS collaboration */ #ifndef TRIGMUONMONITORINGMT_TRIGMUONMONITORALGORITHM_H @@ -10,13 +10,12 @@ #include "StoreGate/ReadHandleKey.h" - -/* -This is a base class from which analyzers can define a derived class to do specific analysis. -e.g. L2MuonSAMonMT is such a class already defined. -Analyzers should define fillVariable and fillVariablePerOfflineMuon and these functions are automatically called in fillHistograms function. -Analyzers can change selectEvents and selectMuons in their specific classes by override them if needed. -TODO: function like fillVariablesPerChain that does per-chain analyses will be useful. +/** + * @brief Base class from which analyzers can define a derived class to do specific analysis. + * e.g. L2MuonSAMonMT is such a class already defined. + * Analyzers should define @c fillVariablesXXX functions and these functions are automatically called in the @c fillHistograms function. + * Analyzers can change @c selectEvents and @c selectMuons in their specific classes by overriding them if needed. + * @todo Support monitoring algorithms using truth muons */ class TrigMuonMonitorAlgorithm : public AthMonitorAlgorithm { @@ -25,14 +24,70 @@ class TrigMuonMonitorAlgorithm : public AthMonitorAlgorithm { virtual StatusCode initialize() override; + + /** + * @brief Function that steers anlayses. + * It currently calles four types of analyses, @c fillVariables, @c fillVariablesPerOfflineMuon, @c fillVariablesPerChain and @c fillVariablesPerOfflineMuonPerChain + * that can be overridden in subclasses to do specific analyses. + * @see @c fillVariables, @c fillVariablesPerOfflineMuon, @c fillVariablesPerChain and @c fillVariablesPerOfflineMuonPerChain + * @param ctx @c EventContext provided by athenaMT + */ virtual StatusCode fillHistograms(const EventContext &ctx) const override; protected: + + /** + * @brief Function that defines the event selection for anlayses + * User should reimlement in a subclass if needed. + * @return True if the event is used for an analysis. + */ virtual bool selectEvents() const; + + /** + * @brief Function that defines the event selection for anlayses + * Users should reimlement in a subclass if needed. + * @param muons Offline muons in the MuonContainer + * @param probes List of offline muons that are used in analyses + */ virtual StatusCode selectMuons(SG::ReadHandle<xAOD::MuonContainer> &muons, std::vector<const xAOD::Muon*> &probes) const; + + /** + * @brief Function that fills variables by just retrieving containers of trigger objects. + * Users should reimlement in a subclass if needed. + * @see @c fillHistograms + * @param ctx @c EventContext provided by athenaMT + */ virtual StatusCode fillVariables(const EventContext &ctx) const; + + /** + * @brief Function that fills variables that are compared to offline muons but the trigger chains are not specified. + * This is called in the for loop of offline muons in @c fillHistograms. + * Users should reimlement in a subclass if needed. + * @see @c fillHistograms + * @param ctx @c EventContext provided by athenaMT + * @param mu Pointer to an offline muon provided in @c fillHistograms + */ virtual StatusCode fillVariablesPerOfflineMuon(const EventContext &ctx, const xAOD::Muon* mu) const; + + /** + * @brief Function that fills variables of trigger objects associated to specified trigger chains. + * This is called in the for loop of trigger chains in @c fillHistograms. + * Users should reimlement in a subclass if needed. + * @see @c fillHistograms + * @param ctx @c EventContext provided by athenaMT + * @param chain Trigger chain provided in @cfillHistograms + */ virtual StatusCode fillVariablesPerChain(const EventContext &ctx, const std::string &chain) const; + + /** + * @brief Function that fills variables of trigger objects associated to specified trigger chains comparing offline muons. + * This is called in the for loop of trigger chains and offline muons in @c fillHistograms. + * Users should reimlement in a subclass if needed. + * @see @c fillHistograms + * @param ctx @c EventContext provided by athenaMT + * @param mu Pointer to an offline muon provided in @c fillHistograms + * @param chain Trigger chain provided in @c fillHistograms + */ virtual StatusCode fillVariablesPerOfflineMuonPerChain(const EventContext &ctx, const xAOD::Muon* mu, const std::string &chain) const; @@ -40,7 +95,9 @@ class TrigMuonMonitorAlgorithm : public AthMonitorAlgorithm { SG::ReadHandleKey<xAOD::MuonContainer> m_MuonContainerKey {this, "MuonContainerName", "Muons", "Offline muon container"}; // Properties + /// List of trigger chains that are monitored in @c fillVariablesPerChain and @c fillVariablesPerOfflineMuonPerChain Gaudi::Property<std::vector<std::string> > m_monitored_chains {this, "MonitoredChains", {}, "Trigger chains that are monitored"}; + /// Requirement for the offline muon type considered in analyses Gaudi::Property<int> m_muontype {this, "MuonType", xAOD::Muon::MuonType::Combined, "MuonType used for monitoring"};