Home Computing DAQ E-mail Notes Meetings Subsystems Search

 

User Guide to DaVinciAssociators v6r0 - If you are using a DaVinci version before v11r9, check out the documentation for DaVinciAssociators v4r1. If you are using a DaVinci version before v16r1, check out the documentation for DaVinciAssociators v5r0.

(Ph.Charpentier)

 

Introduction

DaVinciAssociators are a set of specialized helper classes or tools that allow to retrieve the association between high level analysis objects (ProtoParticles/Particles) and Monte-Carlo particles (MCParticles). As from v5r0, their usage was facilitated by the introduction of helper classes. The former association tools are still supported and are backward compatible.

Thereafter we shall call Linker table or Relations table the two types of technologies for keeping the association. The Linker classes and the Associator tools are the two ways to manipulate these tables from the user algorithm. Both tables are filled by the same Associator-algorithms.

 

Generalities

Association between objects are kept  in a Linker Table in the TES. They are generic objects that allow to establish association between objects in KeyedContainers. Hence DaVinciAssociators will only work for objects registered in such a container.

Whenever an algorithm looks for such a table, it lookups the TES and in case the table is not found, an Associator-algorithm is launched that produces the table(s). It is then possible to access associations in both directions.

There is however a preferential direction of the relations that depends on how the table is built: it always originates from the analysis objects towards the MCParticle: the relation is said to go From the analysis object To the MCParticle.

Linker class

This technology for keeping/retrieving associations is present since v5r0 of the DaVinciAssociators. It is based on classes developed by Olivier Callot in the package Event/LinkerEvent. The added value is that, as for the Relations table, if the Linker table is not present in the TES, an algorithm is executed that creates it.

A convention is used as for the name of the path where Linker tables are stored in the TES: there is one such table per From-object container and its name is directly derived from this container’s name by prepending Link/ to its name and appending a string that depends on the association method used to create it (see below).

Helper classes

Depending on whether one needs to access only direct associations (i.e. retrieve the MCParticle(s) associated from a given object) or one needs to also access reverse associations (i.e. retrieve the objects associated to a given MCParticle), two helper classes should be used:

Note that for direct relations, there is no need to define the type of object from which the relation is established. It must only be derived from KeyedObject<int>. The actual obect class must be provided a a template class for bi-directional association though, in order to avoid dynamic casting.

For convenience a typedef has been introduced for Particles association:

typedef Object2FromMC<LHCb::Particle> Particle2MCLinker;

These helper objects should be created in the user algorithm’s initialize() method using a new operator. Attention: it must of course be deleted in the finalize() method!

There is only one header file to include:

#include "DaVinciAssociators/Particle2MCLinker.h"

 

Helper class constructors

Both classes accept the same constructors. Hence here only those for Object2MCLink will be described.

object2MCLinker( [ GaudiAlgorithm | GaudiTool | Algorithm ]* this,

               Particle2MCMethod::<method>,

               [ std::vector<std::string>& containerList |       

                 std::string>& container ]); 

Particle2MCMethod

<method>

Extension

AlgorithmType

WithChi2

/WithChi2

Particle2MCWithChi2

Chi2

/Chi2

Particle2MCChi2

Links

/Links

Particle2MCLinks

Composite

/Composite

CompositeParticle2MCLinks

ChargedPP

/PP2MC

ChargedPP2MC

NeutralPP

NeutralPP2MC

object2MCLinker( [GaudiAlgorithm | GaudiTool | Algorithm]* this,

               std::string& AlgorithmType,

               std::string& extension,

               [ std::vector<std::string>& containerList |       

                 std::string>& container ]);

The name of the algorithm that is executed to build the linker table if not already present is constructed from that of the user algorithm (e.g. myAlg) and its type (e.g. algType) as: myAlg.algType.

Example of code creation:

#include “DaVinciAssociators/Particle2MCLinker.h

. . . .

myAlg::initialize()

{

     StatusCode sc = GaudiAlgorithm::initialize();

     if( sc.isFailure ) return sc;

     m_myParticleLinker = new object2MCLinker(    this,

                                            Particle2MCMethod::Chi2,

                                            "Bd2PiPi/Particles");

}

. . . .

myAlg::finalize()

{

     if( NULL != m_myParticleLinker ) delete m_myParticleLinker;

     return GaudiAlgorithm::finalize();

}

 

Helper class methods for direct association

Below is a list of the methods for direct association that are provided for Object2MCLinker and also for Object2FromMC<ObjectClass> / Particle2MCLinker as it inherits from the former.

These methods are similar to those of the underlying LinkedFrom helper classes. Note the optional suffix MCP that can be used for clarity (symmetric to the P used for reverse associations, see later). They return a NULL pointer if no associated MCParticle was found.

Returns the weight associated to the current association.

Returns the number of MCParticles associated to a given object.

returns true if the linker table was not found for one of the declared containers (or the one given as argument)

returns true if an association is found in any container between obj and mcPart.

Example of usage:

execute()

{

. . . .

     msg << MSG::VERBOSE;

     Particle* part = . . . ;

     int nbAss = m_myParticleLinker->assocaitedMCP( part );

     msg << nbAss << “ MCParticles associated to part”

         << part->key() << endreq;

     MCParticle* mcPart = m_myParticleLinker->firstMCP( part );

     while( NULL != mcPart ) {

        // An MCParticle was found, gets the association weight

        double weight = m_myParticleLinker->weightMCP();

        . . . .

        mcpart = m_myParticleLinker->nextMCP();

     }

. . . .

     mcPart = . . . . ;

     if( checkAssociation( part, mcPart ) {

         msg << "Particle" << part->key() << “ and “

             << "MCParticle" << mcPart->key() << “ are associated”

             << endreq;

         . . . .

     }

}

 

Helper class methods for reverse association

For reverse association to be used, a helper class of type Object2FromMCLink<ObjectClass> should be used. As there is no way to guess in which container a potentially associated ObjectClass object is located, an explicit list of containers has to be either given in the constructor or built by calls to direct association methods before asking for revers association.

Note that typedef are defined for most frequently used types of associated objects in analysis:

typedef Object2FromMC<ProtoParticle> ProtoParticle2MCLink;

typedef Object2FromMC<>              Particle2MCLink;

The following are methods of the reverse association:

 

These methods are similar to those of the underlying LinkedTo helper classes, except for the suffix “P” that indicates it is a reverse association (“P” for ProtoParticle or Particle, the most used objects in DaVinciAssociators). They return a NULL pointer if no associated ObjectClass was found.

Returns the weight associated to the current association.

Returns the number of Objects associated to a given MCParticle.

Helper class methods for usage in the association algorithms

For convenience a number of public methods are available to ease the writing of association algorithms willing to create linker tables for association to MCParticles.

A dummy helper class of type Object2MCLinker should be created in the initialize() method, using the simplest constructor:

Object2MCLinker([GaudiAlgorithm | Algorithm]* this );

One can then create an object of type LinkerWithKey<MCParticle> (aliased to Object2MCLink::Linker) using the following methods:

If no linker table was found for the corresponding tableName, a valid pointer is returned that can be used to create the association table. However, if the table already existed, a NULL pointer is returned. This is very useful, as otherwise another set of associations would be appended to the existing ones, leading to multiple counting of associations. This is the only added value of this helper method.

Note that the first mandatory parameter tableName is that of the table, not of the input object container. Hence if an extension is expected, it should be concatenated to the input container name before calling the method.

The second optional argument must have been created as follows:

Object2MCLinker::To testLink( evtSvc(), NULL, tableName);

It is used first internally for testing the existence of the table. If the table is not found, the linker object is created (see above) and testLink is reset to a valid helper object that can be used later to access the linker table as it is being filled. The main use case is to avoid double association.

Example of usage (extracted from the algorithm Particle2MCLinks):

 

for( std::vector<std::string>::iterator inp= m_inputData.begin();

       m_inputData.end()!= inp; inp++) {

    // create a Linker table for this Particle container

    const std::string linkContainer = *inp +

          Particle2MCMethod::extension[Particle2MCMethod::Links];

    // Just a fake helper class

    Object2MCLink p2MCLink( this );

    Object2MCLink::Linker* linkerTable =

      p2MCLink.linkerTable( linkContainer );

    if( NULL == linkerTable ) continue;

. . . .

// An association is found between part and an mcPart, weight w

//    then register the association in the linker table

          linkerTable->link( part, mcPart, w);

. . . .

}