ComboHypoToolBase Class Reference

Base class for tools which cut on properties of multi-object or multi-leg chains. User should derive from this class and implement the executeAlg function. This will be called once per combination of objects in the event which reach the ComboHypo alg which hosts this tool. More...

#include <ComboHypoToolBase.h>

Inherits extends< AthAlgTool, IComboHypoTool >.

Inherited by DebugComboHypoTool, DeltaRRoIComboHypoTool, DisplacedJetRankComboHypoTool, TrigAFPDijetComboHypoTool, TrigBmumuxComboHypoTool, TrigComboHypoTool, TrigEgammaTopoHypoTool, TrigMultiTrkComboHypoTool, TrigMuonEFIdtpInvMassHypoTool, and TrigMuonEFInvMassHypoTool.

Collaboration diagram for ComboHypoToolBase:

Public Member Functions
	ComboHypoToolBase (const std::string &type, const std::string &name, const IInterface *parent)
virtual StatusCode	decide (Combo::LegDecisionsMap &passingLegs, const EventContext &) const override
	retrieves the decisions associated to this decId, make their combinations and apply the algorithm More...
virtual HLT::Identifier	decisionId () const
	retrieves this ComboHypoTool's chain's decision ID More...
StatusCode	setLegMultiplicity (const Combo::MultiplicityReqMap &multiplicityRequiredMap)
	Sets the number of legs and the multiplicity required on each leg. More...
const std::vector< int > &	legMultiplicity () const
	Gets the number of legs and the multiplicity required on each leg. More...
HLT::Identifier	legDecisionId (size_t i) const
	Retrieves this ComboHypoTool's chain's decision ID for a given leg. More...
const std::vector< HLT::Identifier > &	legDecisionIds () const
	Retrieves this ComboHypoTool's chain's decision IDs for all legs. More...
virtual StatusCode	decideOnSingleObject (TrigCompositeUtils::Decision *, const std::vector< const TrigCompositeUtils::DecisionIDContainer * > &) const
	Alternate method called by BPhysics ComboHypoAlgs instead of the base method decide(...). More...

Protected Member Functions
virtual bool	executeAlg (const std::vector< Combo::LegDecision > &combination) const
	Only a dummy implementation exists in ComboHypoToolBase. More...
StatusCode	selectLegs (const Combo::LegDecisionsMap &IDCombMap, std::vector< std::vector< Combo::LegDecision >> &leg_decisions) const
	Creates the per-leg vectors of Decision objects starting from the initial LegDecision map, storing only those concerning this HypoTool's chain Pack the Decision objects in std::pair<DecisionID, ElementLink<Decision>> so the derived class' executeAlg function knows which leg each object is on. More...
void	updateLegDecisionsMap (const std::vector< std::vector< Combo::LegDecision >> &passing_comb, Combo::LegDecisionsMap &passingLegs) const
	For when the tool accepts some/all combinations. More...
void	eraseFromLegDecisionsMap (Combo::LegDecisionsMap &passingLegs) const
	For when the tool rejects all combinations. More...
StatusCode	printDebugInformation (const Combo::LegDecisionsMap &passingLegs) const
	Print the output of the tool, after having removed failed Decision Objects. More...

Protected Attributes
Gaudi::Property< size_t >	m_combinationsThresholdWarn
Gaudi::Property< size_t >	m_combinationsThresholdBreak
Gaudi::Property< bool >	m_modeOR
Gaudi::Property< bool >	m_enableOverride

Private Attributes
HLT::Identifier	m_decisionId
	The DecisionID of the chain, obtained from the Tool's name. More...
std::vector< HLT::Identifier >	m_legDecisionIds
	The DecisionIDs of the individual legs, derived from both m_decisionId and m_legMultiplicities. More...
std::vector< int >	m_legMultiplicities
	The number of legs, and the required multiplicity on each leg. More...

Detailed Description

Base class for tools which cut on properties of multi-object or multi-leg chains. User should derive from this class and implement the executeAlg function. This will be called once per combination of objects in the event which reach the ComboHypo alg which hosts this tool.

Definition at line 26 of file ComboHypoToolBase.h.

Constructor & Destructor Documentation

ComboHypoToolBase()

ComboHypoToolBase::ComboHypoToolBase	(	const std::string &	type,
		const std::string &	name,
		const IInterface *	parent
	)

Definition at line 10 of file ComboHypoToolBase.cxx.

                                                                                                           :
  base_class(type, name, parent),
  m_decisionId(HLT::Identifier::fromToolName(name)), m_legMultiplicities()
{}

Member Function Documentation

decide()

StatusCode ComboHypoToolBase::decide ( Combo::LegDecisionsMap &  passingLegs, const EventContext &    ) const

overridevirtual

retrieves the decisions associated to this decId, make their combinations and apply the algorithm

Parameters

[in]	LegDecisionsMap	that lists all the passing decisions, to be updated by the tool depending on the outcome of executeAlg
[in]	Event	Context, currently unused

Reimplemented in DisplacedJetRankComboHypoTool.

Definition at line 48 of file ComboHypoToolBase.cxx.

                                                                                                   {
  if (m_legMultiplicities.size() == 0) {
    ATH_MSG_ERROR("ComboHypoTool for " << m_decisionId << " has not been properly configured. setLegMultiplicity should be called by the parent alg in initalize");
    return StatusCode::FAILURE;
  }
 
  // if no combinations passed, then exit 
  if (passingLegs.size() == 0) {
    return StatusCode::SUCCESS;
  }
 
  ATH_MSG_DEBUG("Looking for legs from " << decisionId() << " in the map. Map contains features for " << passingLegs.size() << " legs, which may be data for many chains.");
 
  // select the leg decisions from the map with this ID:
  std::vector<std::vector<Combo::LegDecision>> legDecisions;
  ATH_CHECK(selectLegs(passingLegs, legDecisions));
 
  for (size_t legIndex = 0; legIndex < m_legMultiplicities.size(); ++legIndex) {
    // The static cast is because this gets read as a Gaudi property which only seems to work with vector<int> rather than vector<size_t> 
    if (legDecisions.at(legIndex).size() < static_cast<size_t>(m_legMultiplicities.at(legIndex))) {
      ATH_MSG_DEBUG("Too few features are found for " << m_decisionId << " on leg " << legIndex <<", require:" << m_legMultiplicities.at(legIndex) << " have:" << legDecisions.at(legIndex).size());
      ATH_MSG_DEBUG("This ComboHypoTool cannot run in this event, this chain **REJECTS** this event.");
      eraseFromLegDecisionsMap(passingLegs);
      ATH_CHECK(printDebugInformation(passingLegs));
      return StatusCode::SUCCESS;
    }
  }
 
  // Create and initialise the combinations generator for the requirements of this chain, given the objects available in this event.
  HLT::NestedUniqueCombinationGenerator nucg;
  for (size_t legIndex = 0; legIndex < m_legMultiplicities.size(); ++legIndex) {
    const size_t choose_any = m_legMultiplicities.at(legIndex);
    const size_t out_of = legDecisions.at(legIndex).size();
    nucg.add({out_of, choose_any});
    ATH_MSG_DEBUG("For leg " << legIndex << " we will be choosing any " << choose_any << " Decision Objects out of " << out_of);
  }
 
  std::vector<std::vector<Combo::LegDecision>> passingCombinations;
 
  size_t warnings = 0, iterations = 0;
  do {
 
    const std::vector<size_t> combination = nucg();
    ++nucg;
    std::vector<Combo::LegDecision> combinationToCheck;
 
    size_t location_in_combination = 0;
    for (size_t legIndex = 0; legIndex < m_legMultiplicities.size(); ++legIndex) {
      // We loop over however many objects are required on the leg,
      // but we take their index from the 'combination'. Hence 'object' is not used directly
      for (size_t object = 0; object < static_cast<size_t>(m_legMultiplicities.at(legIndex)); ++object) {
        const size_t objectIndex = combination.at(location_in_combination++);
        combinationToCheck.push_back( legDecisions.at(legIndex).at(objectIndex) );
      }
    }
 
    ++iterations;
 
    try {
      if (executeAlg(combinationToCheck)) {
        ATH_MSG_DEBUG("Combination " << (iterations - 1) << " decided to be passing");
        passingCombinations.push_back(combinationToCheck);
        if (m_modeOR == true and m_enableOverride) {
          break;
        }
      } else { // the combination failed
        if (m_modeOR == false and m_enableOverride) {
          break;
        }
      }
    } catch (std::exception& e) {
      ATH_MSG_ERROR(e.what());
      return StatusCode::FAILURE;
    }
 
    if ((iterations >= m_combinationsThresholdWarn && warnings == 0) or (iterations >= m_combinationsThresholdBreak)) {
      ATH_MSG_WARNING("Have so far processed " << iterations << " combinations for " << m_decisionId << " in this event, " << passingCombinations.size() << " passing.");
      ++warnings;
      if (iterations >= m_combinationsThresholdBreak) {
        ATH_MSG_WARNING("Too many combinations! Breaking the loop at this point.");
        break;
      }
    }
 
  } while (nucg);
 
 
  if (m_modeOR) {
 
    ATH_MSG_DEBUG("Passing " << passingCombinations.size() << " combinations out of " << iterations << ", " 
      << m_decisionId << (passingCombinations.size() ? " **ACCEPTS**" : " **REJECTS**") << " this event based on OR logic.");
 
    if (m_enableOverride) {
      ATH_MSG_DEBUG("Note: stopped after the first successful combination due to the EnableOverride flag.");  
    }
 
  } else {  // modeAND
 
    const bool passAll = (passingCombinations.size() == iterations);
 
    ATH_MSG_DEBUG("Passing " << passingCombinations.size() << " combinations out of " << iterations << ", " 
      << m_decisionId << (passAll ? " **ACCEPTS**" : " **REJECTS**") << " this event based on AND logic.");
 
    if (m_enableOverride) {
      ATH_MSG_DEBUG("Note: stopped after the first failed combination due to the EnableOverride flag.");  
    }
 
    if (not passAll) {
      passingCombinations.clear();
    }
 
  }
 
  if (not passingCombinations.empty()) { // need partial erasure of the decsions (only those not present in any combination)
    updateLegDecisionsMap(passingCombinations, passingLegs);
  } else { // need complete erasure of input decisions
    eraseFromLegDecisionsMap(passingLegs);
  }
 
  ATH_CHECK(printDebugInformation(passingLegs));
  return StatusCode::SUCCESS;
}

decideOnSingleObject()

StatusCode ComboHypoToolBase::decideOnSingleObject ( TrigCompositeUtils::Decision *  , const std::vector< const TrigCompositeUtils::DecisionIDContainer * > &    ) const

virtual

Alternate method called by BPhysics ComboHypoAlgs instead of the base method decide(...).

This function should be considered a specialist use-case only. It must be over-ridden to do anything useful.

Reimplemented in TrigMultiTrkComboHypoTool, and TrigBmumuxComboHypoTool.

Definition at line 284 of file ComboHypoToolBase.cxx.

                                                                                                                                  {
  ATH_MSG_ERROR("Do not use ComboHypoToolBase on its own, inherit this class and override decideOnSingleObject.");
  ATH_MSG_ERROR("NOTE: Only if you are also supplying your own decide(...) implimentation, or similar.");
  ATH_MSG_ERROR("NOTE: Most uses cases should only need to override executeAlg(...).");
  return StatusCode::FAILURE;
}

decisionId()

virtual HLT::Identifier ComboHypoToolBase::decisionId ( ) const

inlinevirtual

retrieves this ComboHypoTool's chain's decision ID

Definition at line 41 of file ComboHypoToolBase.h.

{ return m_decisionId; }

eraseFromLegDecisionsMap()

void ComboHypoToolBase::eraseFromLegDecisionsMap ( Combo::LegDecisionsMap &  passingLegs ) const

protected

For when the tool rejects all combinations.

Remove all Decision Objects from all the legs of this HypoTool's chain.

Definition at line 253 of file ComboHypoToolBase.cxx.

                                                                                        {
  for (auto& it : passingLegs) {
    DecisionID id = it.first;
    if (id == m_decisionId or (isLegId(id) and getIDFromLeg(id) == m_decisionId)) {
      const size_t nDecisionObjects = it.second.size();
      it.second.clear();
      ATH_MSG_VERBOSE("-- Removed " << nDecisionObjects << " from " << id);
    }
  }
}

executeAlg()

bool ComboHypoToolBase::executeAlg ( const std::vector< Combo::LegDecision > &  combination ) const

protectedvirtual

Only a dummy implementation exists in ComboHypoToolBase.

This should be over-ridden by a derived class. The derived class should return a boolean pass/fail for each possible combination in the event. param[in] combination A single combination of objects to be discriminated against. Vector contains the required number of objects over all legs. Use the pair.first to tell which leg a given pair.second decision object belongs to in the current combination.

Reimplemented in TrigEgammaTopoHypoTool, TrigAFPDijetComboHypoTool, DebugComboHypoTool, DeltaRRoIComboHypoTool, TrigMuonEFIdtpInvMassHypoTool, TrigMuonEFInvMassHypoTool, TrigMultiTrkComboHypoTool, and TrigBmumuxComboHypoTool.

Definition at line 279 of file ComboHypoToolBase.cxx.

                                                                             {
  ATH_MSG_ERROR("Do not use ComboHypoToolBase on its own, inherit this class and override executeAlg.");
  return false;
}

legDecisionId()

HLT::Identifier ComboHypoToolBase::legDecisionId ( size_t  i ) const

inline

Retrieves this ComboHypoTool's chain's decision ID for a given leg.

Only populated for chains with more than one leg. For chains with one leg, use decisionId()

Definition at line 60 of file ComboHypoToolBase.h.

{ return m_legDecisionIds.at(i); }

legDecisionIds()

const std::vector<HLT::Identifier>& ComboHypoToolBase::legDecisionIds ( ) const

inline

Retrieves this ComboHypoTool's chain's decision IDs for all legs.

Only populated for chains with more than one leg. For chains with one leg, use decisionId()

Definition at line 66 of file ComboHypoToolBase.h.

{ return m_legDecisionIds; }

legMultiplicity()

const std::vector<int>& ComboHypoToolBase::legMultiplicity ( ) const

inline

Gets the number of legs and the multiplicity required on each leg.

Definition at line 54 of file ComboHypoToolBase.h.

{ return m_legMultiplicities; }

printDebugInformation()

StatusCode ComboHypoToolBase::printDebugInformation ( const Combo::LegDecisionsMap &  passingLegs ) const

protected

Print the output of the tool, after having removed failed Decision Objects.

Restricted to the ComboHypoTool's chain's legs.

Definition at line 264 of file ComboHypoToolBase.cxx.

                                                                                                 {
  ATH_MSG_DEBUG("ComboHypoToolBase: End of " << m_decisionId << ", passing elements are: ");
  for (const auto& [id, ELV] : passingLegs) {
    // Only print for this chain
    if (id == m_decisionId or (isLegId(id) and m_decisionId == getIDFromLeg(id))) { 
      ATH_MSG_DEBUG("-- " << HLT::Identifier(id) << " with " << ELV.size() << " elements");
      for (const auto& EL : ELV) {
        ATH_MSG_DEBUG("-- -- container:" << EL.dataID() << ", index:" << EL.index());
      }
    }
  }
  return StatusCode::SUCCESS;
}

selectLegs()

StatusCode ComboHypoToolBase::selectLegs ( const Combo::LegDecisionsMap &  IDCombMap, std::vector< std::vector< Combo::LegDecision >> &  leg_decisions  ) const

protected

Creates the per-leg vectors of Decision objects starting from the initial LegDecision map, storing only those concerning this HypoTool's chain Pack the Decision objects in std::pair<DecisionID, ElementLink<Decision>> so the derived class' executeAlg function knows which leg each object is on.

Definition at line 172 of file ComboHypoToolBase.cxx.

{
  /*
    legDecisions: nested vector like:
    [(leg0, el0), (leg0, el1), (leg0, el2), (leg0, el3)], <-- All leg0 objects are in legDecisions[0][X]
    [(leg1, mu0), (leg1, mu1)] <-- All leg1 objects are in legDecisions[1][X]
    We keep the legID in the std::pair inside the inner vector as these pairs will be flattened into a single vector
    when individual combinations of objects are passed to executeAlg, pair.first then contains the leg, with pair.second containing the Decision Object.
  */
 
  // Extract from IDCombMap the features for this chain. Wrap the features up in a pair along with their leg ID
  for (size_t legIndex = 0; legIndex < m_legMultiplicities.size(); ++ legIndex) {
 
    // If the chain has more than one leg, then we have per-leg IDs. Otherwise we just use the chain's ID
    const HLT::Identifier& legIdentifier = (m_legMultiplicities.size() > 1 ? m_legDecisionIds.at(legIndex) : m_decisionId);
 
    // Combo::LegDecision is a pair of <DecisionID, ElementLink<Decision>>
    std::vector<Combo::LegDecision> decisionObjectsOnLeg;
 
    // Find physics objects on this leg. May be zero.
    const Combo::LegDecisionsMap::const_iterator it = IDCombMap.find(legIdentifier.numeric());
 
    if (it != IDCombMap.end()) {
      for (const ElementLink<DecisionContainer>& el : it->second) {
        decisionObjectsOnLeg.emplace_back(legIdentifier, el);
      }
    }
 
    legDecisions.push_back(std::move(decisionObjectsOnLeg));
  }
 
  if (msgLvl(MSG::DEBUG)) {
    ATH_MSG_DEBUG("Getting " << legDecisions.size() << " legs to combine, for ID: " << decisionId());
    size_t count = 0;
    for (const auto& leg : legDecisions) {
      ATH_MSG_DEBUG("Leg " << count++ << " --");
      for (const auto& dEL : leg) {
        ATH_MSG_DEBUG("-- " << HLT::Identifier(dEL.first) << " container:" << dEL.second.dataID() << ", index:" << dEL.second.index());
      }
    }
  }
  return StatusCode::SUCCESS;
}

setLegMultiplicity()

StatusCode ComboHypoToolBase::setLegMultiplicity

(

const Combo::MultiplicityReqMap &

multiplicityRequiredMap

)

Sets the number of legs and the multiplicity required on each leg.

This should be called when the Tool is retrieved by its parent ComboHypo alg. This also sets the leg Decision IDs at the same time param[in] multiplicityRequiredMap: Mapping of chains to required multiplicity per leg.

Definition at line 16 of file ComboHypoToolBase.cxx.

                                                                                                       {
  const std::string nameOfToolsChain = m_decisionId.name();
  const Combo::MultiplicityReqMap::const_iterator it = multiplicityRequiredMap.find(nameOfToolsChain);
 
  if (it == multiplicityRequiredMap.end()) {
    ATH_MSG_ERROR("ComboHypoTool for " << m_decisionId << " could not find its required multiplcity data in the map supplied by its parent alg.");
    return StatusCode::FAILURE;
  }
 
  m_legMultiplicities = it->second;
  if (m_legMultiplicities.size() == 0) {
    ATH_MSG_ERROR("ComboHypoTool for " << m_decisionId << " was listed in the supplied multiplicityRequiredMap, but data was not supplied for any legs.");
    return StatusCode::FAILURE;
  }
 
  m_legDecisionIds.clear();
  for (size_t i = 0; i < m_legMultiplicities.size(); ++i) {
    if(m_legMultiplicities.at(i) <= 0) {
      ATH_MSG_ERROR("ComboHypoTool for " << m_decisionId << " has been configured with an impossible multiplicity requirement of " << m_legMultiplicities.at(i) << " on leg " << i);
      return StatusCode::FAILURE;
    }
    ATH_MSG_DEBUG("ComboHypoTool for " << m_decisionId << " will require multiplicity " << m_legMultiplicities.at(i) << " on leg " << i);
    if (m_legMultiplicities.size() > 1) { // We only have per-leg IDs when there is more than one leg
      m_legDecisionIds.push_back(createLegName(m_decisionId, i));
    } else {  // For one leg, just repete the chain's ID
      m_legDecisionIds.push_back(m_decisionId);
    }
  }
 
  return StatusCode::SUCCESS;
}

updateLegDecisionsMap()

void ComboHypoToolBase::updateLegDecisionsMap ( const std::vector< std::vector< Combo::LegDecision >> &  passing_comb, Combo::LegDecisionsMap &  passingLegs  ) const

protected

For when the tool accepts some/all combinations.

Remove Decision Objects from legs of this HypoTool's chain which participated in NONE of combinations which were flagged as accepting the event.

Definition at line 216 of file ComboHypoToolBase.cxx.

                                                                                                                                                {
  if (msgLvl(MSG::DEBUG)) {
    size_t count = 0;
    for (const std::vector<Combo::LegDecision>& comb : passingComb) {
      ATH_MSG_DEBUG("-- Passing combination " << count++ << " of " << passingComb.size());
      for (const auto& [id, EL] : comb) {
        ATH_MSG_DEBUG("-- -- " << HLT::Identifier(id) << " container:" << EL.dataID() << ", index:" << EL.index());
      }
    }
  }
 
  // remove combinations that didn't pass from the final map passingLegs
  for (auto& it : passingLegs) {
    DecisionID legId = it.first;
    if (not(legId == m_decisionId or (isLegId(legId) and getIDFromLeg(legId) == m_decisionId))) {
      continue; // Some other chain, ignore it to get faster execution.
    } 
    std::vector<ElementLink<DecisionContainer>> updatedDecisionObjectsOnLeg;
    bool update = false;
    // Loop over all passing combinations, and all Decision Objects in each passing combination. Find Decision Objects on this leg.
    for (const std::vector<Combo::LegDecision>& comb : passingComb) {
      for (const auto& [id, EL] : comb) {
        // Check that this Decision Object is on the correct leg, and that we haven't collated it already from another combination.
        if (id == legId and std::find(updatedDecisionObjectsOnLeg.begin(), updatedDecisionObjectsOnLeg.end(), EL) == updatedDecisionObjectsOnLeg.end()) {
          ATH_MSG_VERBOSE("Keeping on leg " << HLT::Identifier(id) << " the Decision Object container:" << EL.dataID() << ", index:" << EL.index());
          updatedDecisionObjectsOnLeg.push_back(EL);
          update = true;
        }
      }
    }
    // only update those concerning this tool ID
    if (update){ 
      it.second = updatedDecisionObjectsOnLeg;
    }
  }
}

Member Data Documentation

m_combinationsThresholdBreak

Gaudi::Property<size_t> ComboHypoToolBase::m_combinationsThresholdBreak

protected

Initial value:

{this, "CombinationsThresholdBreak", 10000,
    "Events processing this many combinations will generate a second WARNING message, and the loop over combinations will be terminated at this point."}

Definition at line 109 of file ComboHypoToolBase.h.

m_combinationsThresholdWarn

Gaudi::Property<size_t> ComboHypoToolBase::m_combinationsThresholdWarn

protected

Initial value:

{this, "CombinationsThresholdWarn", 1000,
    "Events processing this many combinations will generate a WARNING message."}

Definition at line 106 of file ComboHypoToolBase.h.

m_decisionId

HLT::Identifier ComboHypoToolBase::m_decisionId

private

The DecisionID of the chain, obtained from the Tool's name.

Definition at line 122 of file ComboHypoToolBase.h.

m_enableOverride

Gaudi::Property<bool> ComboHypoToolBase::m_enableOverride

protected

Initial value:

{this, "EnableOverride", false,
    "Stops processing combinations as soon as a valid combination is found in OR mode, or as soon as an invalid combination is found in AND mode. This is to save CPU."}

Definition at line 115 of file ComboHypoToolBase.h.

m_legDecisionIds

std::vector<HLT::Identifier> ComboHypoToolBase::m_legDecisionIds

private

The DecisionIDs of the individual legs, derived from both m_decisionId and m_legMultiplicities.

Definition at line 123 of file ComboHypoToolBase.h.

m_legMultiplicities

std::vector<int> ComboHypoToolBase::m_legMultiplicities

private

The number of legs, and the required multiplicity on each leg.

Definition at line 124 of file ComboHypoToolBase.h.

m_modeOR

Gaudi::Property<bool> ComboHypoToolBase::m_modeOR

protected

Initial value:

{this, "ModeOR", true,
    "Accepts based on the logical OR over all calls to executeAlg. If this flag is set to false then the logical AND is required instead."}

Definition at line 112 of file ComboHypoToolBase.h.

---

The documentation for this class was generated from the following files:

• ComboHypoToolBase.h
• ComboHypoToolBase.cxx