A proto-proposal for a standardised ATLAS interface to commom kinematic quantities.

This documentation describes an interface which was implemented and used extensively as part of the development of the new Atlfast suite within Athena.  The reader who at this point is only interested in Atlfast documentation should skip immediately to the section  IKinematic Interface

The motivation for the interface is,however, quite general, and  in the authors opinion quite powerful. It is therefore put forward as a proto-proposal to the wider ATLAS analysis domain.
 
 

Contents

 Discussion

 Proposal

 IKinematic Interface

 Suggestions following from experience with IKinematic

Examples of use of IKinematic

KinematicHelper

Function objects for use with STL algorithms (eg sort)

Simple debugging output
 

Motivation

1. Within an analysis one is generally dealing with several different Types  (Particles, Clusters, Tracks, .....). These are rightly different Types as their constructions, associations ...etc are in general very different.  However in many cases the user will only want to access commom kinematic quantitites such as pT, eta, phi.....etc (for example when making a cut or plotting a histogram).  It therefore makes sense to enforce a standarsdised set of methods for access to such quantities. This would mean, for example, that all users could be sure that if they want to access eta from some object then it is always available through the following:

   double val  = objectname.eta( ) ;
 

2. There are many "standard" kinematic manipultions which are required in an analysis where only the kinematic nature of an a Type is relevant. For example summing energy in a list, taking an invariant mass or finding the distance in eta-phi space between two quantitites. By obliging such Types to honour a common kinematic interface, these manipulations can be provided as common tools which accept all Types polymorphically.  This is potentially very useful as the otherwise the explicit repetition of such code many times by many users in their applications is both inefficient and error prone.
3. This next motivation is somewhat more technical. There are many powerful "generic algorithms" provided with the C++ Standard Template Library. One good example is the generic "sort" algorithm which performs efficient sorting of any collection via iterators. There are many other such generic algorithms which can be used to simplify a user analysis (see STL literature). In order for many of these to function the user needs to supply so called function objects". As example to use sort you must supply a simple function object which returns true or false as a result of comparing two items in the list for precedence.

Writing these function objects is technically very simple, but in practice is not "intuitive" to the novice C++ programmer. However  if all Types honour a kinematic interface, then it is possible to provide many of the commonly needed function objects centrally, avoiding the need for users to write them themselves. This is described more clearly below.
 

Discussion

Solution 1 : One could define an interface which only required all quantities to be "convertable" to a Hep3Vector  or  HepLorentzVector (the HEP standard 4-vector, as included in the CLHEP Class Library for HEP). Technically this means enforcing the conversion operators : operator Hep3Vector( ) and operator HepLorentzVector( ). With these then one could write in an application:

    Particle particle ;
    ....
  HepLorentzVector  pvec = HepLorentzVector( particle )

where Particle is some Type representing an identified particle. Then one would use CLHEP  defined methods of HepLorentzVector, i.e.

    double pT = pvec.perp( ) ;
    double eta = pvec.pseudoRapidity( ) ;

or simply

    double pT = HepLorentzVector( particle ).perp()  ;

These conversion operators would also allow the common tools and function objects to be written by invoking automatic conversion.

The advantages of this are that it is minimal, and that access names are by definition those defined by CLHEP.

The disadvantages are that it is that an explicit type conversion has to be done in the code (a bit cumbersome) and also that the frequent use of such type conversions may confuse novice programmers (in particular if a Particle os passed as an argument to a function which is expecting a HepLorenzVector then an automatic type conversion takes place which is not explicitly clear when reading the code.

Note: a conversion looks like this:
 
    class Particle {
         ....
        operator HepLorentzVector() const
            {
                double x,y,z,t ;
                // calculate the 4-momentum components fo this object
                .x =  ......
                ....
                HepLoentzVector  temp( x,y,x,t ) ;
                return temp ;
            }
            .......
    }
 
 

Solution 2:    A very minimal extention is to define an interface which also enforces the method :

   HepLorentzVector  momentum()

Then in the user code access is simply via

    Particle particle ;
    ....
    double pT = particle.momentum().perp() ;
    double eta = particle.momentum().presudoRapidity() ;

This is certainly more explicit and more "standard looking".  Some of the proponents think this is OK since it is well defined and centrally documented in CLHP, some think it is rather cumbersome for each and every access to quantities like pT and eta. This is a matter for the reader to decide !.
 

Solution 3:  If we now go much further  we might take the veiw that we are confusing interface with internal implementation by worrying about CLHEP vector method names at all. We should instead ask what questions do we want to ask our analysis entities in out ATLAS pp collision context., and then define an interface which promises these attributes.

The fact that we may chose to implement kinematic quantities via a contained HepLorentzVector is immaterial. In fact we should not expect that the method names chosen by CLHEP should necessarily be appropriate (they are after all meant to be very general classes applicable in many other contexts than physics analysis in a pp environment) nor should we feel obliged to only have a method to return a HepLorenzVector just because we might "have one" (n fact for a Track class we may well use an entirely different internal representation).

For the development of the new Atlfast code we have adopted this latter philosophy . However this subject is clearly worthy of much wider debate.
 

Proposal

The detailed form of the interface is secondary to the decision to adopt AN interface. For common kinematic manipulation tools, and function objects, the method names are irrelevant, it only matters that  there is an interface which they can use to access the types polymorphically.

A workable prototype example which has been implemented and used extensively (to great advantage) by the new Atlfast code is given below.  Following this further suggestions are made which follow from the experience of the prototype.
 

IKinematic Interface

Include file: "AtlfastCode/IKinematic.h
 

 The methods promised by the IKinematic interface are detailed in the table below.
 
 
 

Analysis entities should inherit this interface where appropriate, eg:

class Particle: virtual public IKinematic ;

We suggest the virtual qualifier now for technical reasons, in case there is ever any multiple inheritance - although no reason to do this is known at present.

We emphasise that the main point is achieved by just having an interface. We do not insist on the extent or name of the methods (although at some point these should be fixed ). Thus the question of whether to be minimal (i.e just have pT, eta, phi) or try to be more extensive is not crucial at this point. We defer to wider discussion and agreement.
 
 

Examples of use of IKinematic

KinematicHelper : a helper class to encapsulate common functions needed on IKinematic types.

Function objects for use with STL algorithms (eg sort)  : pre-defined function objects to help the user make use of the STL generic algorithms.

Simple debugging output
 
 

Suggested evolution of interface following experience of IKinematic

class ReconstructedParticle

class Jet

class Cell

class Cluster

class Track

Cetainly this working decision was not "bad" in that it achieved all of the stated goals.

However from a more purist point of view there are philosophical problems with this:
 

1. The first two classes (ReconstructedParticle and Jet) are certainly treatable as IKinematic as defined. By this we mean that all methods produce an intuitive and meaningful result.
2. Consider the Track class. No matter how it is implemented, it can never give meaning to more than three-momentum type kinematic quantitites. A three momentum can be well defined as the magnitude and direction at some fixed point such as the distnace of closest approach. But what do energy and mass mean ? They may be given meaning by assuming a mass or associating with a cluster, but then this is more than a track. For example if a mass is assumed then one has elevated a Track to a ReconstructedParticle.

=>  IKinematic is not really the correct interface, even though in practice it works well

3. Similarly for Cell and Cluster. The fundamental attributes of these are an energy and a position of the deposit at some three-position(not the origin). Thus e() and rCentroid( ) may be more appropriate. Of course in a simple approach use of the Hep3Vector "sort of" does the job, however it is at least a different sort to a Track as the direction has an entirely different meaning.

=> Cell, CLuster are not really even three-momenta , therefore certainly not IKinematic.

1. Define

    IThreeMomentum

for use by entities which are legitimately treatable as a three-momentum (Track). One woulod almost certainly also want to define something like

    ITrackTrajectory : virtual publicIThreeMomentum

to define methods to access the information other than pure three-momentum (eg d0, z0)

2. Define

    IFourMomentum : virtual public  IThreeMomentum

to extend this for entities legitimately treatable as a four-momentum (ReconstructedParticle, Jet)

3. For Cell and Cluster ? presumably something different like

    IEnergyDeposit

but here we do not claim to have thought deeply about this. Note that by so doing it would allow general functions to be written which would recognise the difference between a Track and a Cluster kinematics, and hence allow for a B-field shift automatically ?
 
 

The following are some thoughts on what ATLAS might want to do for the actual methods promised by such an interface.

1)There could be four methods which are pure virtual:
     virtual double p_x() const =0;
     virtual double p_y() const =0;
     virtual double p_z() const =0;
     virtual double mass() const =0;   // or equivalently energy

then other methods like eta, phi, eT, etc. could be predefined (to give the intuitive return value as calculated from the above 4 methods, but still be virtual so that they can be over-ridden for more complicated cases.
I.e.:
    inline virtual double pT() {  return sqrt( p_x()*p_x() + p_y()*p_y() );    }

so that for many applications (like for particle), the programmer only needs to implement four methods to get the full 4-vector machinery -  thus not only does IKinematic standardize the interface, it also saves he programmer time.

There is a worry about mixing interface with implementation here, but this could be avoided by using private implementation inheritance in some suitable way.

 
2) ATLAS might avoid having any  CLHEP dependencies -- i.e. not returning a  HepLorentzVector ???

3) Other methods which could be  implemented (but these are all debatable):

cos_theta,
mass_squared,
true rapidity

 other operators: = + - += -+ * *= == !=