LoKiHybridFilters < LHCb

---+!! Recommended <nop>LoKi::Hybrid Functors
This lists the filters recommended for use in the HLT and the selections. See DaVinciTutorial4 for a hands-on tutorial. A longer, but not necessarily up-to-date, list can be found at LoKiParticleFunctions. It also contains examples on how to use these functors in C++ code.

This page refers to DaVinci v19r12.

%TOC% 

---+ Particle Functors

Some mnemonic rules:
   * The functors with the prefix =BPV=  deal with "the best primary vertex". The best primary vertex is extracted from the desktop-tool using the method <code>IPhysDesktop::relatedVertex</code>;
   * The functors with the suffix =DV= get some even-data (e.g. the list of all vertices) through desktop tool
   * The functors with the suffix =TES= get the event data from the Transient Event Store 
   * The =VD= as a part of the functor name means that the functor deals with "vertex distance"
   * The =VDCHI2= as a part of the functor name means that the functor deals with "vertex <latex>\chi^2</latex>-distance"
   * The =SIGN= as a part of the functor name means that functor return the value of <latex>\chi^2</latex> or distance artificially signed according to some criteria.
   * The =IP= stands for "impact parameter" and =MIP= means "the minimal (with reswpect to some set of vertices) value of impact parameter"
   * Practically all "vertex functors" ( the functors which accept <code>const LHCb::VertexBase*</code> as arguments) have their names starting from =V=, the most evident exception if the functor  =PRIMARY=     
   * All indices, e.g. for =CHILDCUT= or =CHILDFUN= functors, starts from <code>1</code>. <code>0</code> always means the particle itself.
   * For many Particle functors there is an equivalent Particle array functor starting with an <code>A</code>. A notable exception is =ADAMASS= for =ADMASS=.

---++ =ALL=: All
Takes all particles. This is required if one wants to apply no cut.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "ALL" ;
%ENDSYNTAX%

---++ =ABSID=: Absolute value of PID.
Returns the absolute value of the PID. The following lines are equivalent:
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "ABSID==211" ;
FilterDesktop.Filter.Code = "ABSID=='pi+' " ;
FilterDesktop.Filter.Code = "ABSID=='pi-' " ;
%ENDSYNTAX%
Note the last line! The comparison <code>(ABSID=='pi-')</code> takes the absolute value on *both sides*. This avoid having to remember that the <latex>\pi^+</latex> has a positive pid (211) while the <latex>\mu^+</latex> has a negative pid (-13).

The pid can also be used without the absolute value. See =ID=.


---++ =ACHILD=: Compute a function on a particle in an array

The functor ACHILD acts as "meta-functor", it gets the daughter particle number "N" (the second parameter of constructor), apply the functor (the first parameter of contructor) and return the result.

e.g. ACHILD(PT,1) return the transverse momentum of the first particle in the combination,
ACHILD(PT,2) return the transverse momentum of the second particle in the combination.

For example:
%SYNTAX{ syntax="cpp" }%
XXX.CombinationCut = "ACHILD(PT,1)*ACHILD(PT,2)>1500000" ;
%ENDSYNTAX%

See the function AMAXCHILD or AMINCHILD, to get the daughter particle by name.   

---++ =ADMASS=: The absolute mass difference to the reference value
Calculates the absolute difference between the measured mass and the PDG reference value. It takes the pid of the reference particle as argument.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "(ADMASS('KS0')<50*MeV)"
%ENDSYNTAX%

The mass difference can also be used without the absolute value. See =DMASS=.

*TODO* : A version without argument will be provided where the ID of the particle is used to get the reference mass.

---++ =AMAXCHILD or AMINCHILD=: cut an array and return the max/min value of a functor.
Similar to MINTREE and MAXTREE, however can be performed on a particle array.

e.g. the minimal PT for all negative kaons: AMINCHILD(PT,"K-"==ID) 

%SYNTAX{ syntax="cpp" }%
XXX.CombinationCut = "AMINCHILD(PT,"K-"==ID)*ACHILD(PT,"K+"==ID)>1500000" ;
%ENDSYNTAX%

This is computationally expensive, using ACHILD is much quicker if possible.

---++ =BPVDIRA=: Direction angle
Computes the cosine of the angle between the momentum of the particle and the direction fo flight from the best PV to the decay vertex.
%SYNTAX{ syntax="cpp" }%
CombineParticles.MotherCut = "(BPVDIRA>0.9999)" ;
%ENDSYNTAX%

---++ =BPVIPCHI2()=: IP on related PV
Computes the <latex>\chi^2</latex>-IP on the related PV.
%SYNTAX{ syntax="cpp" }%
CombineParticles.MotherCut = "BPVIPCHI2()<25" ;
%ENDSYNTAX%
*TODO* : So far it needs the ().

---++ =BPVLTFITCHI2=: the <latex>\chi^2</latex> of the proper lifetime fit. 
The functor evaluates the <latex>\chi^2</latex> of the proper lifetime fit 
of the particle using <code>ILifetimeFitter</code> tool. This <latex>\chi^2</latex> 
is probably the best measure of the consistency of the hypothesis that the particle 
originates from the given primary vertex. It is also probably the best "pointing" variable. 
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "BPVLTFITCHI2('PropertimeFitter/properTime:PUBLIC')<16" ;

%ENDSYNTAX%
The related primary vertex is extracted from the desktop, the fitter itself  
is extracted using  <code>DVAlgorithm::lifetimeFitter("nick-name")</code>.
Please note that it is completely different functor from =BPVLTCHI2=!


---++ =BPVLTIME=: the proper lifetime of the particle 
The functor evaluates the proper lifetime of the particle using <code>ILifetimeFitter</code> tool.
Unfortunately due to very sad conventions adopted for LHCb, the proper time is measured in 
<code>ns</code> instead of the natural units: <latex>\left[c\tau\right]=\mathrm{mm}</latex>.
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "BPVLTIME('PropertimeFitter/properTime:PUBLIC')>1.5" ;

%ENDSYNTAX%
The related primary vertex is extracted from the desktop, the fitter itself  
is extracted using  <code>DVAlgorithm::lifetimeFitter("nick-name")</code>.

---++ =BPVLTCHI2=: the <latex>\chi^2</latex>-significance of the proper lifetime of the particle 
The functor evaluates the <latex>\chi^2</latex>-significance of the proper lifetime of the particle using 
<code>ILifetimeFitter</code> tool.
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "BPVLTCHI2('PropertimeFitter/properTime:PUBLIC')>9" ;

%ENDSYNTAX%
The related primary vertex is extracted from the desktop, the fitter itself  
is extracted using  <code>DVAlgorithm::lifetimeFitter("nick-name")</code>.
Please note that it is completely different functor from =BPVLTFITCHI2=!

---++ =BPVLTSIGNCHI2=: the signed <latex>\chi^2</latex>-significance of the proper lifetime of the particle 
The functor evaluates the signed <latex>\chi^2</latex>-significance of the proper lifetime of the particle using 
<code>ILifetimeFitter</code> tool.
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "BPVLTSIGNCHI2('PropertimeFitter/properTime:PUBLIC')>-4" ;

%ENDSYNTAX%
The related primary vertex is extracted from the desktop, the fitter itself  
is extracted using  <code>DVAlgorithm::lifetimeFitter("nick-name")</code>.

---++ =BPVVDCHI2=: <latex>\chi^2</latex>-separation from related PV
Computes the <latex>\chi^2</latex>-distance from the related PV.
%SYNTAX{ syntax="cpp" }%
CombineParticles.MotherCut = "BPVVDCHI2>100" ;
%ENDSYNTAX%

---++ =BPVVDZ=: <latex>\delta z</latex>-distance from the end vertex of the particle and the related primary vertex.
The functor computes the <latex>\delta z</latex>-distance from the end vertex of the particle and the related primary vertex.
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "0<BPVVDZ" ;

%ENDSYNTAX%
The concept and the name come from [[mailto:s.brisbane1@physics.oz.ac.uk][Sean Brisbane]]. 
The functor is available starting from Phys/LoKiPhys version >= v7r2. 
 
---++ =BPVVDR=: <latex> \rho</latex>-distance from the end vertex of the particle and the related primary vertex.
The functor computes the <latex>\rho</latex>-distance(cylindrical)  from the end vertex of the particle and the related primary vertex.
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "0.1<BPVVDR" ;

%ENDSYNTAX%
The concept and the name come from [[mailto:s.brisbane1@physics.oz.ac.uk][Sean Brisbane]]. 
The functor is available starting from Phys/LoKiPhys version >= v7r2. 

---++ =BPVVDRHO=: <latex>\rho</latex>-distance from the end vertex of the particle and the related primary vertex.
The functor computes the <latex>\rho</latex>-distance(cylindrical)  from the end vertex of the particle and the related primary vertex.
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "0.1<BPVVDRHO" ;

%ENDSYNTAX%
The concept and the name come from [[mailto:s.brisbane1@physics.oz.ac.uk][Sean Brisbane]]. 
The functor is available starting from Phys/LoKiPhys version >= v7r2. 


---++ =CHILDCUT=: Applies a cut to a given child
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "CHILDCUT ( MIPCHI2DV ( PRIMARY ) > 1 , 2 )" ;
%ENDSYNTAX%
In this example one applies an IP cut on the *first* daughter of the input particle. This requires to know which is the first, second, etc daughter. Can be useful when =(N)INTREE= won't work. Like here for the slow pion in a <latex>D^*</latex> where searching for a pion in the tree would also return the daughters of the <latex>D^0</latex>. Use the safer =INTREE= and =NINTREE= instead.

*TODO* : Is there a way of applying a cut to the daughters only, without navigating the whole tree? From next version =NINGENERATION= and =INGENERATION= will do this.

---++ =DMASS=: The mass difference to the reference value
Calculates the difference between the measured mass and the PDG reference value. It takes the pid of the reference particle as argument. In most reasonable cases one will use the absolute mass difference (see =DMASS=) or the mass itself (see =MM=).

---++ =ID=: Particle ID
Like =ABSID= but without the absolute value. 


---++ =INGENERATION=: "in generation"
The predicate which checks the existence of the particle satisfying the requirements in the decay tree at the given depth
 %SYNTAX{ syntax="cpp" }%

FilterDesktop.Filter.Code = "INGENERATION ( ( 'mu+'==ABSID)  & ( PT > 2 * GeV ) , 2 ) " ;

%ENDSYNTAX%
Requires the presence of at least one granddaughter <latex>\mu^{\pm}</latex>, which the transverse momentum 
<latex>p_T>2\mathrm{GeV}/c</latex>. 
The generations are defined as: 0 - the particle itself,  1 - the direct children, 
2 - grandchildren , etc. 
The concept and the name come from [[mailto:Patrick.Koppenburg@cern.ch][Patrick Koppenburg]]. 
The functor is available starting from Phys/LoKiPhys version >= v7r2.

 
---++ =INTREE=: In tree
Requires there is a particle in the decay tree satisfying the requirements.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "(INTREE( (ID=='J/psi(1S)') & (BPVVDCHI2>25) ) )" ;
%ENDSYNTAX%
Requires there is a <latex>J/\psi</latex> in the tree more than <latex>5\sigma</latex> away from the best vertex.

---++ =MAXTREE=: Maximum value in the decay tree
Returns the maximum value of some functor in the decay tree. Useful to apply cuts on all particles, or to extract some value from the tree.
%SYNTAX{ syntax="cpp" }%
CombineParticles.MotherCut = "(M-MAXTREE('D0'==ABSID,M)<165.5)" ;
%ENDSYNTAX%
This example looks for all <latex>D^0</latex> in the decay, returns the largest mass (which is the mass of the <latex>D^0</latex> as there's only one) and computes the mass difference with the mother.

---++ =MINTREE=: Minimal value in the decay tree
Takes a functor as agrument and returns its minimal value searching through the decay tree.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "(MINTREE(ABSID=='K+',PT)>1400*MeV)" ;
%ENDSYNTAX%
This would look for all particles kaons in the decay tree and find their <latex>P_T</latex> and return the minimum. The cut then requires that all kaon descendents have a <latex>P_T>1.4 \:\rm GeV</latex>.


---++ =MINVDDV=: minimum distance between the particle's end-vertex and any other vertex
The functor evaluates the minimal 3D-distance between the particle's end-vertex and the vertices form "list".
The list of vertices is extracted from the desktop:
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "MINVDDV(PRIMARY)>1" ;

%ENDSYNTAX%
Requires that the particle's end-vertex has at least one millimeter separation with respect to any primary vertex.


---++ =MINVDSOURCE=: minimum distance between the particle's end-vertex and any other vertex
The functor evaluates the minimal 3D-distance between the particle's end-vertex and the vertices form "list".
The list of vertices is extracted from the "source":
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "MINVDSOURCE( VSOURCEDV ( PRIMARY ) )>1" ;

%ENDSYNTAX%
Requires that the particle's end-vertex has at least one millimeter separation with respect to any primary vertex.

---++ =MINVDTES=: minimum distance between the particle's end-vertex and any other vertex
The functor evaluates the minimal 3D-distance between the particle's end-vertex and the vertices form "list".
The list of vertices is extracted from the TES:
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "MINVDTES('SomeLocationInTES',PRIMARY)>1" ;

%ENDSYNTAX%
Requires that the particle's end-vertex has at least one millimeter separation with respect to any primary vertex.

---++ =MIPCHI2DV=: Minimum IP-<latex>\chi^2</latex> 
Returns the minimum <latex>\chi^2</latex> distance of a particles's trajectory to any set of vertices. Most useful in conjunction with the =PRIMARY= argument that looks at PVs.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "(MIPCHI2DV(PRIMARY)>9)" ;
%ENDSYNTAX%
This requires that the particle is <latex>3\sigma</latex> away from any PV.

---++ =MIPDV=: Minimum IP
Returns the minimum distance of a particles's trajectory to any set of vertices. Most useful in conjunction with the =PRIMARY= argument that looks at PVs.%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "(MIPDV(PRIMARY)>0.15)" ;
%ENDSYNTAX%
This requires that the particle is 0.15 mm away from any PV.

---++ =M=: Mass
Returns <latex>\sqrt{E^2-p^2}</latex>.  Uses the function =LHCb::Particle::momentum().M()=.  For many cases it should be practically the  same as =MM=.

---++ =MM=: Measured Mass
Returns the measured mass of the particle. The function =LHCb::Particle::measuredMass()= is used for evaluation.
%SYNTAX{ syntax="cpp" }%
HltSharedDiMuon.CombinationCuts = "(AM<11*GeV)"
%ENDSYNTAX%
This selects dimuons up to a mass of 11 GeV.


---++ =NINGENERATION=: "Number of particles in generation"
The function  which counts the particles satisfying the requirements in the decay tree at the given depth:
 %SYNTAX{ syntax="cpp" }%

FilterDesktop.Filter.Code = " 2 == NINGENERATION ( ( 'mu+'==ABSID)  & ( PT > 2 * GeV ) , 2 ) " ;

%ENDSYNTAX%
Requires the presence of exactly two granddaughter <latex>\mu^{\pm}</latex> with the transverse momentum 
<latex>p_T>2\mathrm{GeV}/c</latex>. 
The generations are defined as: 0 - the particle itself,  1 - the direct children, 
2 - grandchildren , etc. 
The concept and the name come from [[mailto:Patrick.Koppenburg@cern.ch][Patrick Koppenburg]]. 
The functor is available starting from Phys/LoKiPhys version >= v7r2.


---++ =NINTREE=: Number of particles in tree
Returns the number of particles in a tree satisfying some selection criteria.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "( 2 == NINTREE( (ABSID=='e-') & (PT>1*GeV)))" ;
%ENDSYNTAX%
Requires that there are two electrons in the tree with <latex>P_T>2 \rm\: GeV</latex>.

---++ =P=: Momentum
Gets the momentum of the particle.
%SYNTAX{ syntax="cpp" }%

FilterDesktop.Filter.Code = "P>2*GeV";

%ENDSYNTAX%
Gets particles with <latex>P>2 \rm\: GeV</latex>.

---++ =PIDe=, =PIDmu=, =PIDK=, =PIDp=,  =PIDpi= : PID <latex>\Delta\log\mathcal{L}_{x-\pi}</latex>
Gets the combined delta-log-likelihood for the given hypothesis (wrt the pion), <latex>\Delta\log\mathcal{L}=\log\frac{\mathcal{L}_{x}}{\mathcal{L}_{\pi}}</latex>: 
%SYNTAX{ syntax="cpp" }%

FilterDesktop.Filter.Code = "PIDe-PIDpi>6" ;

%ENDSYNTAX%

---++ =PT=: Transverse momentum
Gets the transverse momentum of the particle. Note that this is evaluated at the first measurement of the particle, which might not be where you want it for pions in <latex>K_S</latex> decays.
%SYNTAX{ syntax="cpp" }%

FilterDesktop.Filter.Code = "PT>1*GeV";

%ENDSYNTAX%
Gets particles with <latex>P_T>1 \rm\: GeV</latex>.

---++ =TRCHI2=: <latex>\chi^2</latex> the track fit
Gets the <latex>\chi^2</latex> of the track fit.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "TRCHI2<1*GeV" ;
%ENDSYNTAX%


---++ =TRCHI2DOF=: <latex>\chi^2</latex> per degree of freedom of the track fit
Gets the <latex>\chi^2</latex> per degree of freedom of the track fit.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "TRCHI2DOF<20" ;
%ENDSYNTAX%

---++ =TRPCHI2=: <latex>\chi^2</latex>-probability the track fit
Gets the <latex>\chi^2</latex>-probability of the track fit.
%SYNTAX{ syntax="cpp" }%
FilterDesktop.Filter.Code = "TRPCHI2>0.01" ;
%ENDSYNTAX%


---++ =VDMIN=: Distance of two vertices
*TODO* : Not yet supported.

---++ =VFASPF=: Vertex Function as Particle Function.
Allows to apply vertex functors to the particle's =endVertex()=. 
%SYNTAX{ syntax="cpp" }%
CombineParticles.MotherCut = "VFASPF(VCHI2/VDOF)<10" ;
%ENDSYNTAX%
Applies a <latex>\chi^2</latex> cut to the vertex of the particle.

---+ Particle Array Functors
Applied to a set of particles, typically the daughters

---++ =ADAMASS=: The absolute mass difference to the PDG reference value
Calculates the absolute difference between the measured mass and the PDG reference value. It takes the pid of the reference particle as argument.
%SYNTAX{ syntax="cpp" }%

CombineParticles.CombinationCut = "ADAMASS('KS0')<50*MeV"

%ENDSYNTAX%

---++ =AM=: Mass of the combination
Returns <latex>\sqrt{E^2-p^2}</latex>. 

---++ =APT=: Sum transverse momentum of the array
Gets the transverse momentum of the array (that's the <latex>P_T</latex> of the sum 4-vector, not the sum of the <latex>P_T</latex>). Note that this is evaluated at the first measurement of the particles, which might not be where you want it for pions in <latex>K_S</latex> decays.
%SYNTAX{ syntax="cpp" }%

CombineParticles.CombinationCut = "APT>1*GeV";

%ENDSYNTAX%
Gets particles with <latex>P_T>1 \rm\: GeV</latex>.

---++ =AP=: Sum momentum of the array
Gets the momentum of the array.
%SYNTAX{ syntax="cpp" }%

CombineParticles.CombinationCut = "AP>1*GeV";

%ENDSYNTAX%
Gets particles with <latex>P>1 \rm\: GeV</latex>.


---+ Vertex functors
Vertex functors are accessed using =VFASPF=.

---++ =VCHI2= : Vertex <latex>\chi^2</latex> 
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "VFASPF(VCHI2/VDOF)<10" ;

%ENDSYNTAX%

---++ =VDOF= : Vertex fit number of degrees of freedom
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "VFASPF(VCHI2/VDOF)<10" ;

%ENDSYNTAX%

---++ =VMINVDDV=: minimum distance between the vertex and any other vertex
The functor evaluates the minimal 3D-distance between the vertex and the vertices from "list".
The list of vertices is extracted from the desktop:
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "VFASFP(VMINVDDV(PRIMARY))>1" ;

%ENDSYNTAX%
Requires that the particle's end-vertex has at least one millimeter separation with respect to any primary vertex.


---++ =VMINVDSOURCE=: minimum distance between the vertex and any other vertex
The functor evaluates the minimal 3D-distance between the vertex and the vertices form "list".
The list of vertices is extracted from the "source":
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "VFASPF( VMINVDSOURCE( VSOURCEDV ( PRIMARY ) ) ) >1" ;

%ENDSYNTAX%
Requires that the particle's end-vertex has at least one millimeter separation with respect to any primary vertex.

---++ =VMINVDTES=: minimum distance between the vertex and any other vertex
The functor evaluates the minimal 3D-distance between the vertex and the vertices form "list".
The list of vertices is extracted from the TES:
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "VFASPF( VMINVDTES ( 'SomeLocationInTES' , PRIMARY ) ) >1" ;

%ENDSYNTAX%
Requires that the particle's end-vertex has at least one millimeter separation with respect to any primary vertex.


---++ =VPCHI2=: <latex>\chi^2</latex>-probability
The functor evaluates the <latex>\chi^2</latex>-probability of the vertex, taking into account the number of degrees of freedom.
The GSL routine <code>gsl_cdf_chisq_Q</code> functon is used for evaluation.
%SYNTAX{ syntax="cpp" }%

CombineParticles.MotherCut = "VFASPF(VPCHI2)>1*perCent" ;

%ENDSYNTAX%
The functor is available starting from Phys/LoKiPhys version >= v7r2 


---+ Units
Presently units are not supported easily. This will change in the next release. To avoid confusion between =M= (mass) and =m= (meter) for instance a limited set will be defined. Vanya suggests:

   * MeV, GeV
   * mm, millimeter, cm , centimeter, meter 
   * perCent 
   * ns, fs, nanosecond, femtosecond, ps, picoseconds  
These units are available starting from Phys/LoKiPhys version >= v7r2 

---+ Syntax
Cut are combined using the bit-wide =&= and =|= operators, not boolean operators. This also requires that cuts are well protected using parentheses. Example:
%SYNTAX{ syntax="cpp" }%

FilterDesktop.Filter.Code = "( ((ABSID=='pi+') & (PT>400*MeV)) | 
                               ((ABSID=='KS0') & (PT>1*GeV)))"

%ENDSYNTAX%
Cuts can be split over several lines.

---++Types

Some allowed symbols are instances, therefore they do not require  any parentheses, e.g. P, PT etc... 
Some symbols are *types*, e.g. =MIPDV=, and they require to be instantiated.
The parentheses means invocation of constructor.
E.g. <code>MIPDV(PRIMARY)</code> is just invocation of the constructor of *type* =MIPDV= with parameter =PRIMARY= (the predicate to select the vertices).
the simplest way to check if  
the symbol is a type or instance is through inspection using the  
interactive python:
%SYNTAX{ syntax="cpp" }%
[lxplus097] ~/cmtuser/DaVinci_v19r12/Phys/DaVinci/v19r12/cmt % python
Python 2.5 (r25:51908, Oct 18 2007, 16:04:48)
[GCC 3.4.6 20060404 (Red Hat 3.4.6-8)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>from LoKiPhys.decorators import *
>>>from LoKiArrayFunctors.decorators import *
>>>P
P
>>>MIPDV
<class 'LoKiPhys.functions.LoKi::Particles::MinImpParDV'>

%ENDSYNTAX%

---+ Use of =CombineParticles=.
=CombineParticles= is a =LoKI::Algo=, and a =DVAlgorithm= that combines the input particles according to the decay descriptor. There are three cuts applied :

---++!! =DaughtersCuts= : 
On the incoming daughter particles. It is a map of <code>"particle" : "cuts"</code>

%SYNTAX{ syntax="cpp" }%

HltSelB2DstarMu.DaughtersCuts = { 
// PT cut for muons
"mu-" :  "PT>400*MeV", 
// IP_chi2 cut for D0 in D*+ 
"D*(2010)+'" : "MAXTREE('D0'==ABSID,BPVVDCHI2) >6.25 "
} ; 

%ENDSYNTAX%

---++!! <code>CombinationCut</code>  
Once a combination has been made according to the decay descriptor but before the vertex fit. This cut is applied to the set of daughters. Therefore only Particle array functors can be used. They all start with an <code>A</code>.

---++!!<code>MotherCut</code> 
Applied the vertex fit on the mother. All the cuts that require the position of the vertex must be applied in <code>MotherCut</code>, while the others can be applied earlier (saving CPU). Note that for long lived particles like Ks it pays off to apply a loose mass cut in <code>CombinationCut</code> and a harder in <code>MotherCut=. The reason is that the vertex fit does a propagation of the momenta through the detector. You thus get the momentum at the Ks vertex, while in <code>CombinationCut</code> it's just the sum of the momenta of the daughters at their first measurement.

A simple example:
%SYNTAX{ syntax="cpp" }%

HltShared.Members += { "CombineParticles/HltSharedPhi2KK" } ;

HltSharedPhi2KK.PhysDesktop.InputLocations = { "Phys/HltNoPIDsKaons" };

HltSharedPhi2KK.DecayDescriptor = "phi(1020) -> K+ K-";

// (IP > 2 sigma^2)
HltSharedPhi2KK.DaughtersCuts = { "K+" : "MIPCHI2DV(PRIMARY)>4" } ;   

// mass window +/- 300 MeV
HltSharedPhi2KK.CombinationCut = "ADAMASS('phi(1020)')<50"; 
 
// chi2/ degrees of freedom < 25 
HltSharedPhi2KK.MotherCut = "VFASPF(VCHI2/VDOF)<25" ;

%ENDSYNTAX%

The decay descriptor can be overwritten by =DecayDescriptors= which allows to reconstruct several decays in one go.
%SYNTAX{ syntax="cpp" }%

HltShared.Members += { "CombineParticles/HltSharedDstarWithD02KPi" } ;
HltSharedDstarWithD02KPi.PhysDesktop.InputLocations = { "Phys/HltSharedD02KPi", "Phys/HltSharedSlowPions" };

// also wrong-sign ones
HltSharedDstarWithD02KPi.DecayDescriptors = {"[D*(2010)+ -> pi+ D0]cc", "[D*(2010)+ -> pi+ D~0]cc" }; 

// mass window +/- 50 MeV, PT> 1.25 GeV
HltSharedDstarWithD02KPi.CombinationCut = "(ADAMASS('D*(2010)+')<50) & (APT>1250)";  

// Chi2/nDoF < 25 .  m(D*-D0) = 145.5 MeV, +2
HltSharedDstarWithD02KPi.MotherCut = "(VFASPF(VCHI2/VDOF)<25) & (M-MAXTREE('D0'==ABSID,M)<165.5)" ;       

%ENDSYNTAX%

---++ Mother Cut, Daughter Cut, Combination Cut

Each cut, which is applicable to mother is also applicable to  
daughter (and vice versa).
Moreover the cut, used for daughter particle, being equipped with the  
proper <code>CHILD,CHILDFUN,CHILDCUT,MINTREE,MAXTREE,INTREE,NINTREE</code> meta- 
function, gives *IDENTICAL* result being applied for
the mother  particle.

From pure C++ point of view, both =DaughterCuts= and =MotherCuts=  
are objects which get as argument <code>const LHCb::Particle*</code>.  But  
=CombinationCut= accepts as an  argument  
<code>LoKi::Range_<LHCb::Particle::ConstVector>"</code>.

Therefore is requires the DIFFERENT objects.
=CombinationCut= is applied for the combination of "good" daughter  
particles, and only for the combinations, which satisfy  
<code>CombinationCut</code>, the effective mother particle is created through  
teh vertex fit procedure, and <code>MotherCut</code> is applied for this effective mother particle.

---+ Use of =FilterDesktop=.

=FilterDesktop= is a =DVAlgorithm= that applies a cut and clones the selected particles. It has one filter (=Filter=) but the default is not the =LoKi::Hybrid::FilterCriterion= which needs to be set by hand using the =FilterCriterion= property.
%SYNTAX{ syntax="cpp" }%

HltExclusive.Members += { "FilterDesktop/HltSelSingleMuon" } ;

HltSelSingleMuon.PhysDesktop.InputLocations  = {"Phys/HltMuons"} ;

HltSelSingleMuon.FilterCriterion = "LoKi::Hybrid::FilterCriterion" ;
/**
 * Pt > 3 GeV & IP/err > 5 & IP > 0.15 mm 
 */
HltSelSingleMuon.Filter.Code = "(PT>3*GeV) & (MIPCHI2DV(PRIMARY)>25) & (MIPDV(PRIMARY)>0.15)" ; 

%ENDSYNTAX%

---+ Help
Please do not send mails directly to the authors, but send the questions and requests through the following mailing lists:

=lhcb-davinci@cern.ch=, =lhcb-loki@cern.ch=, =lhcb-bender@cern.ch=

In this case more colleagues can profit from solutions to the problems and it will allow a bit more wide distribution of useful information, tricks, recipes, experience and  the  solutions. Also it will simplify  the monitoring of the progress with the implementation of the missing functionality.
As alternative to the mailing lists the following actions are also accepted: 
   1. One can submit the question to  [[LHCb.FAQ.LoKiFAQ#Add_your_own_Question][LoKi FAQ]].
   1. One can submit new task or request new feature through [[http://savannah.cern.ch/projects/loki][Savannah LoKi portal]]
   1. One can submit new task or request new feature through [[http://savannah.cern.ch/projects/bender][Savannah Bender portal]]

---++ Examples
Many working examples can be found in the =Hlt/HltSelections= package from version =v6r0= released with =DaVinci v19r11=. 

---+ Feature requests
Feature requests should be sent to the same mailing lists as above. For every new feature a suggested name should be provided. This drastically simplifies the life of developers and results in a __MUCH HIGHER PRIORITY__  for the implementation.

---++ Change of names
Although it is very simple to define aliases for these functors (and many of them are actually available) their use is not encouraged. This is because we would like to define a minimum vocabulary everyone would have to be able to understand. Since this is rather new, suggestions for changes of names are accepted but should be agreed by the community. Please send requests to the mailing lists above. It is suggested to freeze this in the next version.

Suggestions for the names of the filters in =CombineParticles= are also welcome.


---+ Few related tools/algorithms.
 A few simple tools can be used for debugging and/or validation/testing  the various =LoKi::Hybrid= construction. 

---++ =LoKi::Hybrid::PrintTool=

The most primitive tool, it implements the abstract interface
[[http://cern.ch/LHCb-release-area/DOC/lhcb/releases/latest/doxygen/class_i_print_decay.html][<code>IPrintDecay</code>]], 
and it allows to print some information about the decay tree.
It is convinient to use the high-level algorithm =PrintDecayTree= to drive the tool:

%SYNTAX{ syntax="cpp" }%

// append the algorithm to the list of top level algorithms:
ApplicationMgr.TopAlg += { "PrintDecayTree/Printer"} ;

// declare the actual type/name of the IPrintDecay tool:
Printer.PrintDecayTool = "LoKi::Hybrid::PrintTool/PRINT" ;

// declare the variables to be printed by the tool, each "variable" is just LoKi-functor:
Printer.PRINT.Variables = {  "ID"  , "P/GeV"  ,  "PT/GeV"  , "M/GeV"   ,  "KEY"   } ;

%ENDSYNTAX%

With this configuration one obtains the following printout:
 
<verbatim>
Printer.PRINT             INFO Print the decay tree:  ( B0 ->  mu+  mu-  K+  K-  )
 ---------------------------------------------------------------------------------------------------------
 |#         Decay        |       ID      |    (P/1000)   |   (PT/1000)   |       M       |      KEY      |
 ---------------------------------------------------------------------------------------------------------
 |0 |--> B0              |      511      |     262.81    |     6.1192    |     5099.1    |       5       |
 |1    |--> mu+          |      -13      |     56.877    |     1.6668    |     105.66    |       0       |
 |1    |--> mu-          |       13      |     128.8     |     3.7141    |     105.66    |       1       |
 |1    |--> K+           |      321      |     56.877    |     1.6668    |     493.68    |       2       |
 |1    |--> K-           |      -321     |     20.261    |    0.63129    |     493.68    |       5       |
 ---------------------------------------------------------------------------------------------------------
</verbatim>
For the default configuration, all columns are printed using =14.5g= "scientific" format and the column title is 
constructed from the functor itself. However both the format and the table header could be modified, 
e.g. if one adds into the previous configuration the explicit specification of =Format= and =Header=:
%SYNTAX{ syntax="cpp" }%

// Format: print only 5th (KEY) and 1st (ID) variable from the list of "Variables": 
Printer.PRINT.Format = "| %5% %|6t|| %1% %|14t||";

// specify explicitly the table header: column names
Printer.PRINT.Header = "| Key | PdgID |";

%ENDSYNTAX%
In this case the output table looks like:
<verbatim>
Printer.PRINT                         INFO Print the decay tree:  ( B0 ->  mu+  mu-  K+  K-  )
 ---------------------------------------
 |#         Decay        | Key | PdgID |
 ---------------------------------------
 |0 |--> B0              | 5   | 511   |
 |1    |--> mu+          | 0   | -13   |
 |1    |--> mu-          | 1   | 13    |
 |1    |--> K+           | 2   | 321   |
 |1    |--> K-           | 5   | -321  |
 ---------------------------------------
</verbatim>

For more detailes see  the Doxygen documentation [[http://cern.ch/LHCb-release-area/DOC/lhcb/releases/latest/doxygen/class_lo_ki_1_1_hybrid_1_1_print_tool.html][here]].

---++ =LoKi::Hybrid::PlotTool=


The simple tool, which implements the abstract interface [[http://cern.ch/LHCb-release-area/DOC/lhcb/releases/latest/doxygen/class_i_plot_tool.html][<code>IPlotTool</code>]]
and allows to fill some histograms for the selected particles.

For more detailes see  the Doxygen documentation [[http://cern.ch/LHCb-release-area/DOC/lhcb/releases/latest/doxygen/class_lo_ki_1_1_hybrid_1_1_plot_tool.html][here]].

---++ =LoKi::Hybrid::TupleTool=
The simple tool, which implements the abstract interface 
[[http://cern.ch/LHCb-release-area/DOC/lhcb/releases/latest/doxygen/class_i_particle_tuple_tool.html][here]]
and allows to fill N-tuple with useful information for the selected particles.



The tool is a specialization of general "tuple tools", the concept developed by Jeremie Borel. 
The usage is failrly trivial:

The tool is a specialization of general "tuple tools", the concept developed by Jeremie Borel. 
The usage is failrly trivial:
%SYNTAX{ syntax="cpp" }%

ApplicationMgr.TopAlg += { "DecayTreeTuple/MyDecayTreeTuple" };

// specify location of input data in TES 
MyDecayTreeTuple.PhysDesktop.InputLocations = {"Phys/HltSelBd2MuMuKstar"}; 

// use varios tools, developed by Jeremie
MyDecayTreeTuple.ToolList = {  
      "TupleToolTrigger"
      , "TupleToolMCTruth"
      , "TupleToolMCBackgroundInfo"
      , "TupleToolGeometry"
      , "TupleToolKinematic"
      , "TupleToolPropertime"
      , "TupleToolPrimaries"
     , "TupleToolEventInfo"
     // use also LoKi-based Tuple Tool!!
     , "LoKi::Hybrid::TupleTool/LoKiTool" /// < THIS LINE 
};

// configure LoKi tuple tool:
HltDecayTreeTuple.LoKiTool.Variables = 
{ 
  "mass" : "M/GeV" ,
  "p"       : "P/GeV" ,
  "pt"      : "PT/GeV" 
};

%ENDSYNTAX%


For this example, the tool adds three columns into N-Tuple, defines the names of the column to be 
="head"+"mass"=, ="head"+"p"= and ="head"+"pt"=.
The content of the colums will be filled with tresult of evaluation of the following LoKi functors:
==M/GeV==, ==P/GeV== and ==PT/GeV==.  


For more detailes see  the Doxygen documentation [[http://cern.ch/LHCb-release-area/DOC/lhcb/releases/latest/doxygen/class_lo_ki_1_1_hybrid_1_1_tuple_tool.html][here]].

---++ The direct manipulatuon with factories 

Sometime for debugging purposes the direct manipulation with factories could be useful. 
Also it could have some sense for validation of functors and  comparison with some other calculations. 

Since the factory is ==AlgTool== in Gaudi sense, first one needs to acquire the factory

%SYNTAX{ syntax="cpp" }%

#include "LoKi/IHybridFactory.h"

...
const std::string factoryName = "LoKi::Hybrid::Tool/HybridFactory:PUBLIC" ;

LoKi::IHybridFactory* factory = tool<LoKi::IHybridFactory> ( factoryName ) ;

%ENDSYNTAX%


And now one can use the factory for creation of  of functors (functions  and predicates) :

%SYNTAX{ syntax="cpp" }%

using namespace LoKi::Types ;
using namespace LoKi::Cuts   ;

// initialize the function with *some* values 

Fun fun = -1.E+10 * ONE ;

// get the code 
const std::string& code = .... ; 

// instantiate the functor:
StatusCode sc = factory->get ( code , fun ) ;

if ( sc.isFailure() ) { .... } // handle the error 


%ENDSYNTAX%
In a similar way one can create predicate (the functor with returns ==bool==):
 
%SYNTAX{ syntax="cpp" }%

using namespace LoKi::Types ;
using namespace LoKi::Cuts   ;

// initialize the predicate with *some* values 

Cut cut = NONE ;

// get the code 
const std::string& code = .... ; 

// instantiate the functor:
StatusCode sc = factory->get ( code , cut ) ;

if ( sc.isFailure() ) { .... } // handle the error 


%ENDSYNTAX%

Finally one can operate with ==fun== and ==cut== objects as with regular LoKi functors.

The complete example is available [[%ATTACHURL%/TestFunctor.cpp][here]].




---+ More documentation
For more information please refer to

   * LoKiParticleFunctions: a longer not up-to-date list.
   * [[http://lhcb-release-area.web.cern.ch/LHCb-release-area/DOC/lhcb/releases/latest/doxygen/class_lo_ki_1_1_functor.html][Doxygen]]
   * The talks at [[http://indico.cern.ch/conferenceDisplay.py?confId=25000#2008-03-19][March 2008 software week]]
   * The DaVinciTutorial4



--- Main.PatrickKoppenburg - 28 Mar 2008
--- Main.PatrickKoppenburg - 25 Apr 2008
--- [[Main.KarolHennesy][Karol Hennessy]] - 15 May 2008
--- [[Main.VanyaBelyaev][Vanya Belyaev]] - 12 Jun 2008
This topic: LHCb > WebHome > LHCbComputing > DaVinci > LoKiHybridFilters
Topic revision: r19 - 2008-08-13 - unknown