User Guide to DaVinciAssociators v4r1

(Ph.Charpentier)

 

Introduction

DaVinciAssociators are a set of specialized associator tools (see documentation) that allow to retrieve the association between high level analysis objects (ProtoParticles/Particles) and Monte-Carlo particles (MCParticles).

 

Generalities

Relations between objects are kept in a Relations’ Table in the TES. Whenever an algorithm looks for such a table, it lookups the TES and in case it is not found, an algorithm is launched that produces the table. It is then possible to access relations 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.

There are two important TES locations that need to be defined for a DaVinciAssociator:

1. The TES path of the relations table
2. The TES path(s) of where the analysis objects are

In addition the associator needs to know which algorithm has to be run in order to build the table (in case it is not already preexisting). An alternative is of course to first run the relation-making algorithm and then run the algorithm that uses the relations.

Associators can be of two types: weighted and unweighted. The difference is that for weighted associators, a “weight” (can be any type, but for DVASct, always a double) is stored for each link between two objects.

 

Gaudi properties

DaVinciAssociators and their algorithms have default values for their properties:

• <DVAsct>.Location = <TablePath>;

TES path for the relations table

• <DVAsct>.AlgorithmType = <AlgType>;

Type of the algorithm to be used

• <DVAsct>.AlgorithmName = <AlgName>;

Name of the algorithm (default = <AlgType>)

• <Algname>.InputData = {<list of TES paths>};

The algorithms have another property (OutputData) that must be set to <TablePath>. This is done automatically by the initialize() method of the associator.

 

DaVinciAssociators

Several instances of the same Associator Type may exist, differentiated only by their properties, in particular their building algorithm. Currently the following DaVinciAssociators exist. They are listed here with their AlgorithmType that in principle the user doesn’t need to change. In case the is an alternate possibility, it is mentioned as “Alt”.

Note that in case more than one instance of the same associator has to be used, different options files should be given in particular for the Location, AlgorithmName and InputData properties.

 

This associator looks for the Track or CaloCluster from which the Protoparticle is originating and associates all MCParticles that are associated to that Track/CaloCluster. In about 1% of the cases, there are more than one MCParticle for Tracks.

 

This associator uses the ChargedPP2MC associator in order to build associations between Particles and MCParticles. Note that there is no check on the ParticleID at this stage.

 

This associator associates a Particle and an MCParticle if all members of their decay trees are associated. Possibly extra photons can be allowed (see later)

 

This associator computes the c² between the charged tracks corresponding to the Particle and the MCParticle. It associates the MCParticle that gives the lowest c². Not cut is applied at this stage, hence all Particles have an associated MCParticle.

 

This associator uses the previous one and applies a configurable cut on the c².

 

Retrieving a DaVinciAssociator

In order to use an associator of a given type, its header file has to be included:

#include “DaVinciAssociator/<AsctType>.h”

 

It is advised to get a private version of the associator in the user algorithm. One may also define an alternate name to the default (identical to the type). A pointer to the associator interface class is returned as an argument (of type <AsctType>::IAsct). This code should be part of the initialize() method of the user algorithm. Note that the first argument should be the associator type as defined in the tables above.

 

 

This retrieves an associator of type <AsctType> with a name <myAlg>.<AsctType> (default)

 

 

This retrieves an associator of type <AsctType> with a name <myAlg>.<AsctName>

 

 

Using a DaVinciAssociator

The following methods are available from the associators interface. For simplicity, we assume here that the From type is Particle, but the same would apply for ProtoParticle.

 

 

The associatedFrom()/associatedTo() methods return the “first” element associated from or to an item. “first” is either the first element associated when creating the table (non-weighted associators) or the element with the smallest weight (weighted associators). This latter behaviour can be changed by a JobOption as follows:

 

<AsctName>.DecreasingWeight = true;

 

Both FromRange and ToRange are classes that behave a bit like standard containers, i.e. one can check their sizes and iterate on them. The Range methods are listed below (identical for ToRange as for FromRange).

 

 

The main difference between Range classes and standard containers is that they cannot directly be dereferenced to the associated item, as there might be two quantities queried for: the item pointer and the weight. Hence the From/ToIterator can be considered as a pointer to an item with the following methods (here the example of a ToIterator), rather than a pointer to a Particle*/MCParticle*:

 

 

As an example, here is the code to retrieve the range associated to a Particle and loop through the associated items:

 

 

Auxiliary associators

Some association-building algorithms are using other associators in order to produce their own tables. It is hence important that they get private instances of this auxiliary associator and of its algorithms. The properties for these two auxiliary items should also be set in a unique and consistent fashion in order to avoid lengthy and painful writing of JobOptions for the user.

Hence these auxiliary associators and algorithms produce private relations table (no need for the user to know their names!) and are forwarded the InputData property from their parent associator. The auxiliary items are given a name that reflect their parenthood.

DaVinciAssociators have the following dependency (<AsctAlgNAme> is the name of the building algorithm for the parent associator).

 

 

 

Note that as there is only one way of building ProtoParticles2MC relations, the associators and their algorithms are generic and not private.

 

 

Particle2MCLinks associator

Although the default Particle2MCLinksAsct assumes the Particles are stored in the TEs and the building algorithm is called to build the full relations table, it is also possible in this specific case to look for the association of Particles that are not stored in the TES, i.e. local instances of Particles. This can be particularly interesting when debugging analysis code. In this case, the association is delegated to the ChargedPP2MC associator without creating a table.

The only jobOption that needs to be changed is the Location of the table that has to be void:

 

 

 

Additional jobOptions

Only two DaVinciAssociators’ algorithms have additional tuneable properties whose default values are listed here:

 

• Particle2MCChi2.Chi2Cut = 100;

This is the cut applied on the Chi2 of the 2 tracks in order for declaring a Particle and an MCParticle associated. The number of degrees of freedom is 5.

 

• CompositeParticle2MCLinks.AllowExtraMCPhotons = false;

When set to true, this allows extra photons to be present in the decay tree.

 

Examples of usage of associators

 

Single instance

Initialize() method of the user algorithm myAlg:

 

 

This retrieves an associator interface of type Particle2MCLinksAsct, of name myAlg.Particle2MCLinks

 

jobOptions file:

 

 

or, if one wants to give a name to the algorithm:

 

 

 

Multiple instances

Initialize() method of the user algorithm myAlg:

 

 

This retrieves two associator interfaces of type Particle2MCLinksAsct, of name myAlg.LinksAsct1 and myAlg.LinksAsct2

 

Corresponding jobOptions file: