Gaudi Framework Tutorial, April 2006
77
Algorithm Tools: what they are, how to write them, how
to use them
Algorithm Tools: what they are, how to write them, how
to use them
7-2 Gaudi Framework Tutorial, April 2006
ObjectivesObjectives
After completing this lesson you should After completing this lesson you should be able to:be able to:
• Understand the difference between tools and algorithms
• Retrieve and use tools in an algorithm
• Understand tools interfaces
• Define and implement a tool
After completing this lesson you should After completing this lesson you should be able to:be able to:
• Understand the difference between tools and algorithms
• Retrieve and use tools in an algorithm
• Understand tools interfaces
• Define and implement a tool
7-3 Gaudi Framework Tutorial, April 2006
Why Algorithm Tools?Why Algorithm Tools?
Sometimes in an Algorithm it is necessary Sometimes in an Algorithm it is necessary to execute the same operation more than to execute the same operation more than once per event, only for some events, on once per event, only for some events, on specific non identifiable data objects, specific non identifiable data objects, producing new objects that will be put in producing new objects that will be put in the Event Store later. Or the same the Event Store later. Or the same operation might need to be performed by operation might need to be performed by several different algorithms.several different algorithms.
Needed to introduce a new conceptNeeded to introduce a new concept
Sometimes in an Algorithm it is necessary Sometimes in an Algorithm it is necessary to execute the same operation more than to execute the same operation more than once per event, only for some events, on once per event, only for some events, on specific non identifiable data objects, specific non identifiable data objects, producing new objects that will be put in producing new objects that will be put in the Event Store later. Or the same the Event Store later. Or the same operation might need to be performed by operation might need to be performed by several different algorithms.several different algorithms.
Needed to introduce a new conceptNeeded to introduce a new concept
7-4 Gaudi Framework Tutorial, April 2006
Algorithm ToolsAlgorithm Tools
The concept of The concept of Algorithms ToolsAlgorithms Tools, being a , being a sort of simple algorithms callable many sort of simple algorithms callable many times and with arguments, was introduced times and with arguments, was introduced in Gaudiin Gaudi
• Examples– Vertexing
– Track transport
– Association to truth
– Filtering of particles based on a pID CL
The concept of The concept of Algorithms ToolsAlgorithms Tools, being a , being a sort of simple algorithms callable many sort of simple algorithms callable many times and with arguments, was introduced times and with arguments, was introduced in Gaudiin Gaudi
• Examples– Vertexing
– Track transport
– Association to truth
– Filtering of particles based on a pID CL
7-5 Gaudi Framework Tutorial, April 2006
ToolSvcToolSvc
The ToolSvc is the service that manages The ToolSvc is the service that manages Algorithm Tools (private or shared)Algorithm Tools (private or shared)• Algorithms ask the ToolSvc for a given Tool by
type/name, they can then keep a pointer to the tool and use it when necessary
• Manages the life-cycle of Tools creating them on a first request basis
• Keeps track of existing Tools, holding all instances and dispatching them as requested
Tools can be configured using the Tools can be configured using the JobOptions, like Algorithms or Services JobOptions, like Algorithms or Services
The ToolSvc is the service that manages The ToolSvc is the service that manages Algorithm Tools (private or shared)Algorithm Tools (private or shared)• Algorithms ask the ToolSvc for a given Tool by
type/name, they can then keep a pointer to the tool and use it when necessary
• Manages the life-cycle of Tools creating them on a first request basis
• Keeps track of existing Tools, holding all instances and dispatching them as requested
Tools can be configured using the Tools can be configured using the JobOptions, like Algorithms or Services JobOptions, like Algorithms or Services
7-6 Gaudi Framework Tutorial, April 2006
Accessing Tools from GaudiAlgorithm
Accessing Tools from GaudiAlgorithm
In MyAlgorithm.h:In MyAlgorithm.h:private:private:
IMCAcceptanceTool* m_accTool; ///< Tool interface IMCAcceptanceTool* m_accTool; ///< Tool interface
In MyAlgorithm::initialize()In MyAlgorithm::initialize()
// Get the tool from the toolSvc// Get the tool from the toolSvc
m_accTool = tool<IMCAcceptanceTool>( m_accTool = tool<IMCAcceptanceTool>( "MCAcceptanceTool/MyTool" ); "MCAcceptanceTool/MyTool" );
In MyAlgorithm::execute()In MyAlgorithm::execute()// Do something with it// Do something with itif( m_accTool->accepted( *itP )) { ++numAccepted; }if( m_accTool->accepted( *itP )) { ++numAccepted; }
In MyAlgorithm.h:In MyAlgorithm.h:private:private:
IMCAcceptanceTool* m_accTool; ///< Tool interface IMCAcceptanceTool* m_accTool; ///< Tool interface
In MyAlgorithm::initialize()In MyAlgorithm::initialize()
// Get the tool from the toolSvc// Get the tool from the toolSvc
m_accTool = tool<IMCAcceptanceTool>( m_accTool = tool<IMCAcceptanceTool>( "MCAcceptanceTool/MyTool" ); "MCAcceptanceTool/MyTool" );
In MyAlgorithm::execute()In MyAlgorithm::execute()// Do something with it// Do something with itif( m_accTool->accepted( *itP )) { ++numAccepted; }if( m_accTool->accepted( *itP )) { ++numAccepted; }
7-7 Gaudi Framework Tutorial, April 2006
ParentName.ToolNameParentName.ToolName
Configuring a toolConfiguring a tool
A concrete tool can be configured using A concrete tool can be configured using the jobOptions the jobOptions
Follow usual convention:Follow usual convention:IdentifyingNameOfTool.NameOfProperty
A concrete tool can be configured using A concrete tool can be configured using the jobOptions the jobOptions
Follow usual convention:Follow usual convention:IdentifyingNameOfTool.NameOfProperty
Through the base class all tools have the Through the base class all tools have the OutputLevel propertyOutputLevel property
• The default value is that of the parent
Through the base class all tools have the Through the base class all tools have the OutputLevel propertyOutputLevel property
• The default value is that of the parent
ToolSvc.MyTool.MinPz = 0.1*GeV;ToolSvc.MyTool.MinPz = 0.1*GeV;ToolSvc.MyTool.MinPz = 0.1*GeV;ToolSvc.MyTool.MinPz = 0.1*GeV;
7-8 Gaudi Framework Tutorial, April 2006
Algorithm Tools TypesAlgorithm Tools Types
Different tools can implement the same Different tools can implement the same functionalityfunctionality
Since the algorithms interacts with them Since the algorithms interacts with them only through the interface they are only through the interface they are interchangeableinterchangeable
The choice can be done via the job The choice can be done via the job options at run timeoptions at run time
This offers a way to evolve and improve This offers a way to evolve and improve ToolsTools
Different tools can implement the same Different tools can implement the same functionalityfunctionality
Since the algorithms interacts with them Since the algorithms interacts with them only through the interface they are only through the interface they are interchangeableinterchangeable
The choice can be done via the job The choice can be done via the job options at run timeoptions at run time
This offers a way to evolve and improve This offers a way to evolve and improve ToolsTools
7-9 Gaudi Framework Tutorial, April 2006
Tools Specific InterfacesTools Specific Interfaces
A tool must have an additional interface to A tool must have an additional interface to define its functionalitydefine its functionality
– which must inherit from the IAlgTool interface, so that the tool can be managed by ToolSvc
– Remember: The implementation of the IAlgTool interface is Remember: The implementation of the IAlgTool interface is done by the AlgTool base class, you don’t need to worry about itdone by the AlgTool base class, you don’t need to worry about it
– Tools performing a similar operation in different ways will share the same interface (ex. Vertexer)
A tool must have an additional interface to A tool must have an additional interface to define its functionalitydefine its functionality
– which must inherit from the IAlgTool interface, so that the tool can be managed by ToolSvc
– Remember: The implementation of the IAlgTool interface is Remember: The implementation of the IAlgTool interface is done by the AlgTool base class, you don’t need to worry about itdone by the AlgTool base class, you don’t need to worry about it
– Tools performing a similar operation in different ways will share the same interface (ex. Vertexer)
7-10 Gaudi Framework Tutorial, April 2006
Tools InterfacesTools Interfaces
YourTool
IAlgTool
IYourTool
IAlgToolIAlgTool
• name(), type(), parent()
IYourToolIYourTool
• Interface for your tool
7-11 Gaudi Framework Tutorial, April 2006
GaudiTool base classGaudiTool base class
All tools should inherit from GaudiToolAll tools should inherit from GaudiTool
• Similar functionality to GaudiAlgorithm
• Hides details of– MsgStream
– Event Data Service access
– etc.
All tools should inherit from GaudiToolAll tools should inherit from GaudiTool
• Similar functionality to GaudiAlgorithm
• Hides details of– MsgStream
– Event Data Service access
– etc.
7-12 Gaudi Framework Tutorial, April 2006
How to write concrete toolsHow to write concrete tools
When encapsulating some reoccurring When encapsulating some reoccurring functionality in a tool you need to:functionality in a tool you need to:
• Identify the tool functionality and define its special interface: ITool.h
– Unless the interface already exists
• Inherit from the GaudiTool base class in MyTool.h
• Implement the tool specific functionality in MyTool.cpp
When encapsulating some reoccurring When encapsulating some reoccurring functionality in a tool you need to:functionality in a tool you need to:
• Identify the tool functionality and define its special interface: ITool.h
– Unless the interface already exists
• Inherit from the GaudiTool base class in MyTool.h
• Implement the tool specific functionality in MyTool.cpp
7-13 Gaudi Framework Tutorial, April 2006
Tools interfaces in practiceSee Kernel/IMCAcceptanceTool.h in Tutorial/TutKernel package
Tools interfaces in practiceSee Kernel/IMCAcceptanceTool.h in Tutorial/TutKernel package
class IMCAcceptanceTool : virtual public IAlgTool {class IMCAcceptanceTool : virtual public IAlgTool {
public:public:
} }
class IMCAcceptanceTool : virtual public IAlgTool {class IMCAcceptanceTool : virtual public IAlgTool {
public:public:
} }
#include “GaudiKernel/IAlgTool.h”#include “GaudiKernel/IAlgTool.h”#include “GaudiKernel/IAlgTool.h”#include “GaudiKernel/IAlgTool.h”
static const InterfaceID static const InterfaceID
IID_IMCAcceptanceTool(“IMCAcceptanceTool”, 1, 0)IID_IMCAcceptanceTool(“IMCAcceptanceTool”, 1, 0)
static const InterfaceID static const InterfaceID
IID_IMCAcceptanceTool(“IMCAcceptanceTool”, 1, 0)IID_IMCAcceptanceTool(“IMCAcceptanceTool”, 1, 0)
Necessary for InheritanceNecessary for Inheritance
Unique interface IDUnique interface ID
/// Retrieve interface ID /// Retrieve interface ID
static const InterfaceID& interfaceID() { static const InterfaceID& interfaceID() {
return IID_IMCAcceptanceTool; return IID_IMCAcceptanceTool;
}}
/// Retrieve interface ID /// Retrieve interface ID
static const InterfaceID& interfaceID() { static const InterfaceID& interfaceID() {
return IID_IMCAcceptanceTool; return IID_IMCAcceptanceTool;
}}
/// + specific signature/// + specific signature
virtual bool accepted(const LHCb::MCParticle* mother) = 0;virtual bool accepted(const LHCb::MCParticle* mother) = 0;
/// + specific signature/// + specific signature
virtual bool accepted(const LHCb::MCParticle* mother) = 0;virtual bool accepted(const LHCb::MCParticle* mother) = 0;
Pure virtual method(s)Pure virtual method(s)
7-14 Gaudi Framework Tutorial, April 2006
A concrete tool will inherit from the A concrete tool will inherit from the GaudiToolGaudiTool base class: base class:
– has properties
– debug(), info(), warning() etc.
– get()
– tool(), svc()
– possible initialize(), finalize()
A concrete tool will inherit from the A concrete tool will inherit from the GaudiToolGaudiTool base class: base class:
– has properties
– debug(), info(), warning() etc.
– get()
– tool(), svc()
– possible initialize(), finalize()
Called after creation by ToolSvcCalled after creation by ToolSvc
GaudiTool inheritanceGaudiTool inheritance
Configurable via job optionsConfigurable via job options
access to event dataaccess to event data
Configured at creationConfigured at creation
access to other tools, servicesaccess to other tools, services
7-15 Gaudi Framework Tutorial, April 2006
GaudiTools life-cycleGaudiTools life-cycle
GaudiTools are created by a factoryGaudiTools are created by a factoryGaudiTools are created by a factoryGaudiTools are created by a factory
DECLARE_TOOL_FACTORY( MCAcceptanceTool );DECLARE_TOOL_FACTORY( MCAcceptanceTool );
This must be instantiated in the This must be instantiated in the implementation fileimplementation file
•As for Algorithms but TOOL_FACTORY
•Done for you by emacs
This must be instantiated in the This must be instantiated in the implementation fileimplementation file
•As for Algorithms but TOOL_FACTORY
•Done for you by emacs
7-16 Gaudi Framework Tutorial, April 2006
How to write concrete tools: implementation file
How to write concrete tools: implementation file
Declare in constructor specific propertiesDeclare in constructor specific properties
Get services necessary for implementation Get services necessary for implementation in constructor or initialize methodin constructor or initialize method
– Very similarly to Algorithms
Implement necessary functionalityImplement necessary functionality– Additional methods specific to the tool
Declare in constructor specific propertiesDeclare in constructor specific properties
Get services necessary for implementation Get services necessary for implementation in constructor or initialize methodin constructor or initialize method
– Very similarly to Algorithms
Implement necessary functionalityImplement necessary functionality– Additional methods specific to the tool
7-17 Gaudi Framework Tutorial, April 2006
A note about packagingA note about packaging
Tools, like Algorithms, are Tools, like Algorithms, are componentscomponents– They should reside in a component library
Header files of Tool interfaces are public– They should reside in a public include directory
Component packages should not export an include directory
– include_path none
– Put the interface in a separate Kernel package
• e.g. TutKernel/vxry/Kernel
– Component library will depend on Kernel package
• If interface changes, Components must be recompiled
• THINK TWICE before changing an interface!
Tools, like Algorithms, are Tools, like Algorithms, are componentscomponents– They should reside in a component library
Header files of Tool interfaces are public– They should reside in a public include directory
Component packages should not export an include directory
– include_path none
– Put the interface in a separate Kernel package
• e.g. TutKernel/vxry/Kernel
– Component library will depend on Kernel package
• If interface changes, Components must be recompiled
• THINK TWICE before changing an interface!
7-18 Gaudi Framework Tutorial, April 2006
Hands on: MCAcceptanceToolHands on: MCAcceptanceTool
Write a simple Monte Carlo tool that:Write a simple Monte Carlo tool that:• checks if a MCParticle satisfies a list of
criteria and returns true/false– Define the cuts as properties of the Tool
• implements simple cuts:– Minimum Pz cut
– Is produced close to IP (zOrigin < value)
– Does not decay before end of the magnet (zDecay> value)
– Use what you learned about MCParticle & MCVertex
Write a simple Monte Carlo tool that:Write a simple Monte Carlo tool that:• checks if a MCParticle satisfies a list of
criteria and returns true/false– Define the cuts as properties of the Tool
• implements simple cuts:– Minimum Pz cut
– Is produced close to IP (zOrigin < value)
– Does not decay before end of the magnet (zDecay> value)
– Use what you learned about MCParticle & MCVertex
When you start from scratch emacs will provide you with a skeletonWhen you start from scratch emacs will provide you with a skeleton
7-19 Gaudi Framework Tutorial, April 2006
Hands on: MCAcceptanceToolHands on: MCAcceptanceTool
Modify VisibleEnergyAlgorithm to use the Modify VisibleEnergyAlgorithm to use the new tool plot the primary vertex multiplicity new tool plot the primary vertex multiplicity of MCParticles in the acceptance of MCParticles in the acceptance
– Retrieve and use the tool as shown in slide 7-6
If you have time afterward (homework?) If you have time afterward (homework?) extend the toolextend the tool
– Check if the MCParticle has reached the last Tracking stations (has hits in at least n layers of the Inner Tracker or Outer Tracker after a certain z position)
Modify VisibleEnergyAlgorithm to use the Modify VisibleEnergyAlgorithm to use the new tool plot the primary vertex multiplicity new tool plot the primary vertex multiplicity of MCParticles in the acceptance of MCParticles in the acceptance
– Retrieve and use the tool as shown in slide 7-6
If you have time afterward (homework?) If you have time afterward (homework?) extend the toolextend the tool
– Check if the MCParticle has reached the last Tracking stations (has hits in at least n layers of the Inner Tracker or Outer Tracker after a certain z position)
7-20 Gaudi Framework Tutorial, April 2006
Hands on: MCAcceptanceTool.hHands on: MCAcceptanceTool.h
Inherit from IMCAcceptanceToolInherit from IMCAcceptanceTool
Declare the interface method(s)Declare the interface method(s)
Inherit from IMCAcceptanceToolInherit from IMCAcceptanceTool
Declare the interface method(s)Declare the interface method(s)
class MCAcceptanceTool : public GaudiTool,class MCAcceptanceTool : public GaudiTool,
virtual public IMCAcceptanceTool {virtual public IMCAcceptanceTool {
virtual bool accepted( const LHCb::MCParticle* mother );virtual bool accepted( const LHCb::MCParticle* mother );
class MCAcceptanceTool : public GaudiTool,class MCAcceptanceTool : public GaudiTool,
virtual public IMCAcceptanceTool {virtual public IMCAcceptanceTool {
virtual bool accepted( const LHCb::MCParticle* mother );virtual bool accepted( const LHCb::MCParticle* mother );
7-21 Gaudi Framework Tutorial, April 2006
Hands on: MCAcceptanceTool.cpp constructor
Hands on: MCAcceptanceTool.cpp constructor
Declare specific Interface(s)Declare specific Interface(s)
Implement the interface methodImplement the interface method
Declare specific Interface(s)Declare specific Interface(s)
Implement the interface methodImplement the interface methoddeclareInterface< declareInterface< IMCAcceptanceTool IMCAcceptanceTool >(this);>(this);declareInterface< declareInterface< IMCAcceptanceTool IMCAcceptanceTool >(this);>(this);
bool MCAcceptanceTool::accepted( const LHCb::MCParticle* mcpart ) bool MCAcceptanceTool::accepted( const LHCb::MCParticle* mcpart ) { {
/// Momentum cut (Pz)/// Momentum cut (Pz)
if ( mcpart->momentum().z() < m_minPz ) {if ( mcpart->momentum().z() < m_minPz ) {
return false;return false;
} else {} else {
return true;return true;
}}
}}
bool MCAcceptanceTool::accepted( const LHCb::MCParticle* mcpart ) bool MCAcceptanceTool::accepted( const LHCb::MCParticle* mcpart ) { {
/// Momentum cut (Pz)/// Momentum cut (Pz)
if ( mcpart->momentum().z() < m_minPz ) {if ( mcpart->momentum().z() < m_minPz ) {
return false;return false;
} else {} else {
return true;return true;
}}
}}
7-22 Gaudi Framework Tutorial, April 2006
SolutionSolution
In src.data directory of In src.data directory of Tutorial/Components packageTutorial/Components package
To try this solution:To try this solution:
In src.data directory of In src.data directory of Tutorial/Components packageTutorial/Components package
To try this solution:To try this solution:
cd ~/cmtuser/Tutorial/Component/v7r0/src
Move your modified files if you want to keep themcp ../src.usetool/*.* .
cd ../cmt
gmake
$MAINROOT/$CMTCONFIG/Main.exe $MAINROOT/options/jobOptions.opts
cd ~/cmtuser/Tutorial/Component/v7r0/src
Move your modified files if you want to keep themcp ../src.usetool/*.* .
cd ../cmt
gmake
$MAINROOT/$CMTCONFIG/Main.exe $MAINROOT/options/jobOptions.opts