class sorter_setup: public TObject

_HADES_CLASS_DESCRIPTION



 HParticleTrackSorter

 This Class loops over the HParticleCand category and
 analyze the objects. If the ECAL detector is used a loop over
 HEmcCluster is performed too to mark the clusters used by selected
 candidates. The Purpose of the procedure is to categorize
 the objects in the case of multiple usage of the single detector
 hits (RICH, InnerMDC, OuterMDC, META) as Double_t hit and to provide
 a hint which of the candidates is the best with respect to certain
 criteria (described by the bit flags below). If a HParticleCand
 object has been marked before by an other task with HParticleCand::kIsUsed it
 will be ignored by the sort process and stay unchanged. For the description
 of the differnt set/get functions of the HParticleCand objects see the
 documentation.
 To use HParticleTrackSorter without changing the flags of the HParticleCand objects
 (non persitent way inside a macro or reconstructor) one can call the
 backupFlags() function before and modification of the flags and
 restore the flags by calling restoreFlags() after the privat work has been
 done.

 For debugging purpose one cand set screen printouts to check the sorting
 (setDebug() + setPrintLevel(Int_t level)(level = 1-3)).

 The analysis of the HParticleCand objects is done in several steps:

 1. Create the HParticleTrackSorter object and call the HParticleTrackSorter::Init()
    To initialze the sorter object with category pointers etc ...
 2. The internal structures are filled per event from the HParticleCand
    category by calling the
    Int_t HParticleTrackSorter::fill(Bool_t (*function)(HParticleCand* ))
    function which expects a function pointer to a function taking an
    HParticleCand pointer as argument and returning a Bool_t if the conditions on
    the HParticleCand object are fullfilled (like for example in
    Bool_t HParticleTrackSorter::selectHadrons(HParticleCand* pcand). For objects
    failing the test the kIsRejected bit is set. The user can provide
    his own selection functions to replace the build in selectLeptons(.....)
    and selectHadrons(....) select functions.
    The function pointer can be a pointer to a global function or member function
    of an Object for example:

    Bool_t select(HParticleCand* cand){             // global function
             if ( put all selection criteria here ) return kTRUE;
             else                                   return kFALSE;
    } or

    static Bool_t dummy::select(HParticleCand* cand){ // member function of object dummy
                                                      // needs to be declared static !
             if ( put all selection criteria here ) return kTRUE;
             else                                   return kFALSE;
    }
    would be called in the code like

    dummy d;
    HParticleCand* p= new HParticleCand() // just to get an object
    HParticleTrackSorter sorter;               // create the sorter object
    // now we have 3 possibilities to call the
    // test function
    1. sorter.fill(select)        // global function
    2. sorter.fill(dummy::select) // member function of object dummy (static call without object creation)
    3. sorter.fill(d.select)      // member function of real object dummy
 3. For all accepted objects the quality criteria and Double_t hit flags are
    evaluated in within the selected sample and flagged to the HParticleCand objects.
    The objects which fullfill the given minimum criteria the kIsAcceptedXXX bit is
    flagged. For the RICH, InnerMDC, OuterMDC and META the kIsDoubleHitXXX bit are set
    if the same detector hit index has been used more than once in the sample.
    For the double hit rejection of Meta hits only the selected Meta hits
    (ParticleCand::getSelectedMeta()) are taken into account. In the case of RPCClst+SHOWERHIT
    The shower hit might be used by more than one candidate.
 4. With the call of
    Int_t HParticleTrackSorter::selectBest(Particle::ESwitch byQuality, Int_t byParticle)
    the final selection on the objects is performed. The by the fill() procedure
    selected objects are sorted by the selected quality criteria. Starting from the
    best object one goes down the list and marks all objects with the kIsUsed and
    kIsBestXXX bit if they do not reuse an already used detector hit index
    (Double_t hit rejection).
    For leptons the kIsLepton bit is flagged in addition. Individual detector hits
    can be ignored in the selection procedure with the setIgnoreXXX(kTRUE) functions
    (by default all hits are taken into account).
    Particle::ESwitch byQuality can be used as quality criteria switch for

          Particle::kIsBestHitRichSorter          (by number of pads)
          Particle::kIsBestHitInnerMdcSorter      (by chi2, non fitted segments last)
	    Particle::kIsBestHitOuterMdcSorter      (by chi2, non fitted segments last)
          Particle::kIsBestHitMetaSorter          (by RK metamatch quality (or metaMatch quality if no RK , lower proirity))
          Particle::kIsBestRKSorter               (by RK chi2, none fitted outer segments with lower priority)
          Particle::kIsBestRKRKMETASorter         (by RK chi2 * RK META match quality)
          Particle::kIsBestRKRKMETARadiusSorter   (by RK chi2 * RK META match radius)
          Particle::kIsBestUserSorter             (by user provided sort function, no default function!)

    user provide sort function:
    static void   setUserSort(Bool_t    (*function)(candidateSort*, candidateSort*)
    The user has to provide a function for sorting of the candidates:

    Bool_t mysort(candidateSort* a, candidateSort* b) {
      // this example does the same as kIsBestRKRKMETA
      // sort in ascending order by RK_Chi2 * RK_META_match_Quality
      // the function can use all data members of struct candidateSort defined in hparticletracksorter.h
      return (a->RK_Chi2 * a->RK_META_match_Quality)  < (b->RK_Chi2 * b->RK_META_match_Quality);
    }


 5. The scheme allows for multiple selection following each other as
    the already used objects are excluded from the next steps (for example first
    select leptons and in the second iteration hadrons). The detector hit indicies
    of the previous selection of kIsUsed marked objects are added to list of used
    indicies by default not allowing to use a detector hit twice. To skip that
    memory one can set setIgnorePreviousIndex(kTRUE).
 6. After the analysis call HParticleTrackSorter::finalize(). After the selection
    the user has to take into account only HParticleCand objects which  have
    been flagged with kIsUsed. The objects slected by the Lepton selection will
    be marked in addition with kIsLepton to identify them easily.
 7. For lepton selections the internal selectLepton() function cand be manipulated.
    With setRICHMatching(Particle::EMatch ,Float_t window) the matching between
    inner MDC and RICH hit can be selected (default: HParticleTrackSorter::kUseRKRICHWindow,4 degree ).
 8. For Better suppression of background the build in select functions can apply
    a spacial match to the meta cell in y coordinate. setUseYMatching(kTRUE) (default)
    makes use of a match in y in within 3 mm. ( see HParticleTool::isGoodMetaCell(HParticleCand* c,Float_t bound))
 9. For Better suppression of background the build in select functions can require a valid beta measurement (beta>0)
    setUseBeta(kTRUE) (default), for leptons in addition a low cut in beta can be set setBetaLetonCut(0.9) (default)
10. For Better suppression of background the build in select functions can suppress fake measurement
    setUseFakeRejection(kTRUE) (default)


    A selection of unique lepton and hadron tracks could look like
    the following example :

 void myMacro(Int_t nEvents,TString inputDir, TString inFile)
 {
    Hades* myHades = new Hades;
    gHades->setQuietMode(2);

    HRootSource* source = new HRootSource();
    source->setDirectory(((Text_t *)inputDir.Data()));
    source->addFile((Text_t *)inFile.Data());

    myHades->setDataSource(source);

    if(!myHades->init()){
	cout<<"Hades Init() failed!"<<endl;
	exit(1);
    }


    //------------------------------------------------------------------------
    // get category ointers and iterators
    HCategory* pidCat  = (HCategory*)gHades->getCurrentEvent()->getCategory(catParticleCand);
    HIterator* iter    = NULL;
    if(pidCat)
    {
         iter = (HIterator *)pidCat->MakeIterator("native");
    } else {
        cout<<"Category Pointer is NULL!"<<endl;
	exit(1);
    }
    //------------------------------------------------------------------------


    //--------------------------CONFIGURATION---------------------------------------------------
    //At begin of the program (outside the event loop)
    HParticleTrackSorter sorter;
    //sorter.setDebug();                                            // for debug
    //sorter.setPrintLevel(3);                                      // max prints
    //sorter.setRICHMatching(Particle::kUseRKRICHWindowSorter,4.); // select matching RICH-MDC for selectLeptons() function
    //sorter.setUseYMatching(kTRUE);                                // use meta cell build in select functions
    //sorter.setMetaBoundary(4.0);                                   // match in 4 mm to meta cell
    //sorter.setUseBeta(kTRUE);                                     // require beta >0 in build in select functions
    //sorter.setTOFMAXCut( 60.);                                    // maximum tof [ns] allowd for match ( if beta is used)
    //sorter.setBetaLeptonCut(0.9);                                 // lower beta cut for lepton select
    //sorter.setUseFakeRejection(kTRUE);                            // reject fakes in  build in select functions (default kTRUE)
    //sorter.setUseMETAQA(kTRUE);                                   // metaqa in  build in select functions (default kTRUE)
    //sorter.setMETAQACut(3.0);                                     // metaqa cut for ahdrons+leptons
    //sorter.setIgnoreInnerMDC();                                   // do not reject Double_t inner MDC hits
    //sorter.setIgnoreOuterMDC();                                   // do not reject Double_t outer MDC hits
    //sorter.setIgnoreMETA();                                       // do not reject Double_t META hits
    //sorter.setIgnorePreviousIndex();                              // do not reject indices from previous selctions
    sorter.init();                                                  // get catgegory pointers etc...



    //------------------------------------------------------------------------
    // Event loop
    for(Int_t i = 1;i < nEvents; i ++)
    {
        //----------break if last event is reached-------------
        if(!gHades->eventLoop(1)) break;

        //------------------------------------------------------------------------
        // run your selection and set all flags

        //------------------------------------------------------------------------
        // clean vectors and index arrays
        sorter.cleanUp();
        //------------------------------------------------------------------------

        // if you do not want to modify the flags
        // for the following tasks etc (needs call of
        // restoreFlags() at the end of the eventloop)
        //sorter.backupFlags();

        sorter.resetFlags(kTRUE,kTRUE,kTRUE,kTRUE);     // reset all flags for flags (0-28) ,reject,used,lepton
        Int_t nCandLep     = sorter.fill(HParticleTrackSorter::selectLeptons);   // fill only good leptons
        Int_t nCandLepBest = sorter.selectBest(Particle::kIsBestRKSorter,HParticleTrackSorter::kIsLeptonSorter);
        Int_t nCandHad     = sorter.fill(HParticleTrackSorter::selectHadrons);   // fill only good hadrons (already marked good leptons will be skipped)
        Int_t nCandHadBest = sorter.selectBest(Particle::kIsBestRKSorter,HParticleTrackSorter::kIsHadronSorter);
        //------------------------------------------------------------------------

        //------------------------------------------------------------------------
        // analylize marked tracks (kIsUsed) ....
    	  iter->Reset();
        HParticleCand* pcand;
        while((pcand = (HParticleCand*)iter->Next()) != NULL)
	  {
           // accept only objects marked as good
	     if(!pcand->isFlagBit(HParticleCand::kIsUsed) ) continue;

           // do other selection......
        }
        //------------------------------------------------------------------------

        // if you do not want to modify the flags
        // for the following tasks etc (needs call of
        // backupFlags() at the beginning of the eventloop)
        // sorter.restoreFlags();


    }
    //------------------------------------------------------------------------
    //At the end of program
    sorter.finalize();
 }