 (Last update: 28-May-2002)

 THIS FILE CONTAINS SOME INFORMATION ABOUT THE CLASS STRUCTURE
 IN THIS DIRECTORY, AND SOME NOTES ABOUT THE CLASSES.


 --- Class Structure:
 
       ShowerHandler  
          MECorrections      
             MECorrection <--- DrellYanMECorrection 
          ShowerConstrainer
          InsideRangeShowerEvolver
             PartnerFinder
             KinematicsReconstructor
             BackwardShowerEvolver
              ForwardShowerEvolver                 
                 RhoDMatrixPropagator
                 SplittingGenerator
                    SudakovFormFactor <--- QtoQGSudakovFormFactor
                                              (and similar)
                     SplitFun <--- SplitFun1to2 <--- QtoQGSplitFun <--- IS_... , FS_...
                                                    (and similar)
                              <--- SplitFun1to3
                     ShowerAlpha <--- ShowerAlphaQCD <--- IS_... , FS_...
		                      (and similar to define)
                    ShowerKinematics <--- QtildaShowerKinematics1to2 <--- IS_... , FS_... 
                                             (and similar to define)
                    ShowerParticle      
                     ShowerColourLine
                     ShowerIndex


 --- HADRONIZATION SCALE : a parameter, with the dimension of energy,
     has been defined in  GlobalParameters  class, and it can be set
     (for example in src/SimpleLEP.in) by:
        set theGlobalParameters:HadronizationScale 0.5*GeV
     Notice that, despite its name, it is *not* used anywhere in 
     the Hadronization; instead, at the moment, is used only in
     the Showering (precisely in  ShowerHandler  class), and only
     if the multi-scale showering mode is switched on. 
     (However, we decided to put this parameter in  GlobalParameters  
      rather than in one of the Shower classes, because it could be 
      useful in the future, for example for the multi-parton or soft models.)
     The parameter represents the scale such that, if a particle
     has a width above it then its decay affects the showering,
     that is its width determines one of the scales used in the
     multi-scale showering. By setting this scale above the width
     of top, W, and Z, let's say to 2.5 GeV, it is even possible to 
     use (or test) the multi-scale showering only for SUSY particles
     with large widths, excluding instead the widths of those Standard
     Model particles.


 --- SETTING THE GLUONS TO THE EFFECTIVE MASS SHELL
     ----------------------------------------------
     In order to work, Cluster Hadronization needs the final state
     gluons to have an effective mass (750 MeV), such to allow the 
     non-perturbative splitting in u+ubar and d+dbar. 
     Starting from physical massless on-shell gluons, forcing them 
     into an effective mass shell requires kinematical reshuffling 
     in order to preserve the total energy-momentum of the event. 
     This kinematical reshuffling is exactly the same as the one 
     necessary in the Shower for compensating the recoil of the emissions. 
     For this reason, it would be natural to set the gluons on
     the effective mass shell as the final step in the Shower.
     But in doing, we will loose the possibility to use 
     Pythia7 String Fragmentation for the hadronization, after
     Herwig++ showering, because such hadronization model does
     want the gluons on their physical massless shell! So, this
     could suggest to move the setting of gluons on the effective
     mass shell in the Herwig++ Cluster Hadronizaton part, as
     first step. But this wouldn't work either, because in 
     order to do a proper kinematical reshuffling which does not
     shift the masses of on-shell intermediate decayed particles,
     we need the detailed information stored in the collection
     of ShowerParticle, not in the (Pythia7) Event Record.
     ===> The solution is to have a global switch which tells
          whether or not we are going to use Pythia7 String
          Fragmentation, for the hadronization, and then
          setting the gluons on the effective mass shell
          in the (Herwig++) Shower, but only if this flag
          is OFF (which means we will use Herwig++ Cluster
          Hadronization).

     ***LOOKHERE*** AT THE MOMENT WE ARE PROVIDING ONLY THE 
                    INTERFACES, BUT NOT IMPLEMENTATION, THEREFORE
                    IF YOU RUN  runHerwig++ SimpleLHC.run
                    IT WON'T WORK BECAUSE THE GLUONS ARE ON THEIR
                    PHYSICAL MASSLESS SHELL, THEREFORE THE
                    CLUSTER HADRONIZATION CORE DUMP.

     Note :  it is not possible to provide a general mechanism
     ----    to do the opposite:
                Pythia7 Showering  +  Herwig++ Cluster Hadronization
             because there is not enough information to do a proper
             kinematical reshuffling. In practice, this is not a problem,
             because such combination is not expected to work, and 
             therefore should never be used, even if we succeed in 
             performing a proper kinematical reshuffling after setting
             the gluons on the effective mass shell, because the
             Herwig++ Cluster Hadronization is strongly dependent
             on the cluster mass distribution (preconfinement) produced
             by the showering, which is not expected to be well described
             by Pythia7 Showering. Vice versa, Pythia7 String Fragmentation
             is so versatile, that, after proper parameter tuning, it 
             could work basically with any (reasonable) showering.
     
 
 --- GET RID OF ADVANCED FEATURES OF THE SHOWERING
     ---------------------------------------------
     To simplify the showering, by getting rid of some advance features
     of Herwig++ showering, You have the following switches (that you 
     can access, for example, in the file src/SimpleLEP.in):
     1) Switch OFF the  *** multi-scale showering *** :
	  set stdShowerHandler:ShowerConstrainer:theMultiScaleShowerMode 0
        in this case the showering is done in one go,
        from the initial scale down to the cutoff.
        NB) It is also possible to have multi-scale showering on
            but applied only to particles (like many Susy ones)
            with large widths, but not to top, W, Z : in this case
            it is enough to set, above their widths, the parameter: 
              set theGlobalParameters:HadronizationScale 2.5*GeV
     2) Switch ON the  *** decay of heavy coloured particles 
                           before showering *** :   
          set stdShowerHandler:ShowerConstrainer:theDecayBeforeShowerMode 1
        in this case, for those particles specified in
        ShowerConstrainer class, the decay is done before
        the shower starts.
     3) Switch OFF the  *** rhoD propagation *** :
          set theRhoDMatrixPropagator:OnOffSwitchMode 1
        in this case, there will be no spin-correlation. 
     4) Switch OFF all  *** matrix element corrections *** :
          set theMECorrections:OnOffMECorrectionMode 0
        (of course it is also possible, if the above switch is on,
         to switch off either the composition of ME corrections:
           set theMECorrections:OnOffComposeMECorrectionMode 0
         or switch off some particular matrix element, for example:
           set theDrellYanMECorrection:OnOffMECorrectionMode 0
        ) 
     5) Switch OFF all  *** non-QCD (QED, EWK) bremsstrahlung *** 
        (or more in general, switching off some interactions):
          set theSplittingGenerator:OnOffQCDinteractionMode 1
          set theSplittingGenerator:OnOffQEDinteractionMode 0
          set theSplittingGenerator:OnOffEWKinteractionMode 0  
     6) Switch OFF either *** initial state radiation or 
                              final state radiation globally
                              or for each interaction *** :
          set theSplittingGenerator:OnOffISRMode 0
          set theSplittingGenerator:OnOffISR_QCDMode 1
          set theSplittingGenerator:OnOffISR_QEDMode 1
          set theSplittingGenerator:OnOffISR_EWKMode 1
          set theSplittingGenerator:OnOffFSRMode 1
          set theSplittingGenerator:OnOffFSR_QCDMode 1
          set theSplittingGenerator:OnOffFSR_QEDMode 1
          set theSplittingGenerator:OnOffFSR_EWKMode 1
        

 --- WHAT IS NEEDED FOR rho-D PROPAGATION
     ------------------------------------
     The main class  RhoDMatrixPropagator  is basically 
     completed; what need to be done is to write some code
     in  ShowerHandler::cascade()  and  
         ForwardShowerEvolver:timeLikeShower  and
         BackwardShowerEvolver::spaceLikeShower
     (look to the string ***LOOKHERE*** in the corresponding
      .cc files) which proper deals with such rho and D matrices
     in ShowerParticles objects and that uses the above
     main class  RhoDMatrixPropagator.
     Where most of the work must be done, is in writing
     the amplitude for all the hard subprocesses and decays:
     in practice, for each hard subprocess or decay process
     a concrete class, which inherit from 
          Pythia7/MatrixElement/Amplitude.h 
     must be defined, and its virtual methods must be 
     implemented. 
      
    
 --- ADD A NEW MATRIX ELEMENT CORRECTION
     -----------------------------------
     If you want to add a new matrix element correction, for 
     example for D.I.S., you have to do the following:
     (a similar procedure is valid for decay matrix element 
      corrections as well)
     1) create a concrete class  DISMECorrection
        similar to  DrellYanCorrection, in which you have
        to explicitly provide a definition for the virtual
        method:  softMEcorrection .  
     2) create the object and set the pointer of the
        MECorrections object to it, in  src/HerwigDefaults.in
           create /Herwig++/DISMECorrection theDISMECorrection
           insert theMECorrections:VecMECorrection[2] theDISMECorrection
        (where "2" is intended to be replaced with the proper
         index position for the pointer to  theDISMECorrection)
     3) set on(1)/off(0) the switch mode for the new object
        (such switch is already automatically defined in the
         abstract class MECorrection), for example in src/SimpleLEP.in
           set DISMECorrection:OnOffMECorrectionMode 0       
        )
     4) create the object of class  DISPlusJetME  in src/HerwigDefaults.in
        and then set the reference to it (and similarly also for the 
        reference to the object associated to the matrix element of 
        the basic process  e q -> e q) in theDISMECorrection.
     5) create in  Herwig++/MatrixElement/  two new classes:
         i) one derived from
               Pythia7/MatrixElement/MEBase.h  
            which contains the 2->N+Jet matrix element;
        ii) one derived from
               Pythia7/MatrixElement/Amplitude.h
            which contains the amplitude for the 2->N+Jet process
            (used for rho-D propagation).


 --- CHANGE KINEMATICS SHOWERING VARIABLES
     -------------------------------------
     If you want to change kinematics showering variables
     (let's say from Qtilda to another variable) you have to 
     do the following:
     1) in the class ShowerConstrainer, change the definition of 
        the following methods:
           convertMassScaleToQScale(...)
           convertQScaleToMassScale(...)
        or introduce an abstract class... (see comments on 
        ShowerConstrainer.h)
     2) in the class PartnerFinder, change the definition of 
        the methods  calculateInitialEvolutionScales(...)
        or introduce an abstract class... (see comments on 
        PartnerFinder.h)
     3) introduce a new abstract class, similar to 
        QtildaShowerKinematics1to2, which inherits from
        ShowerKinematics, where you put the common part 
        (common for Initial State and Final State showering)
        of the new kinematics variables. Then, you have
        to define two concrete classes, one for Initial State
        and one for Final Stete radiation, which inherits
        from the above new abstract class, similarly to 
            IS_QtildaShowerKinematics1to2 
            FS_QtildaShowerKinematics1to2
        w.r.t. QtildaShowerKinematics1to2
     4) in  SplittingGenerator::chooseForwardBranching  and
            SplittingGenerator::chooseBackwardBranching  
        you have to create explicitly the proper kind of 
        kinematics object you want.
     5) Probably also the class  KinematicsReconstructor
        needs some writing to properly deal with the new
        kinematics variables.


 --- ADD A NEW INTERACTION TYPE OF BREMSSTRAHLUNG
     --------------------------------------------
     If you want to add a new interaction type of bremsstrahlung,
     besides QCD, QED, EWK, like GRA (for gravity), you have to
     do the following:
     1) in  ShowerIndex.h  change increment the number of
        of interaction types, and add a "tag", like GRA, 
        which describes the new kind of interaction: 
     	  enum { NumInteractionTypes = 4, NumTimeOrderType = 2 };
          enum InteractionType { UNDEFINED=-1, QCD, QED, EWK, GRA };  
     2) in  PartnerFinder  class, define a new method
          bool setGRAInitialEvolutionScales(...);
        which, similarly to same methods for the other interaction
        types, find all pairs of partners w.r.t. that interaction,
        and finally fills 
          particle->evolutionScales()[ ShowerIndex::GRA ]; 
     3) in  ShowerConstrainer  class, define a new parameter
        to access/set the low mass scale cutoff for radiation
        of the new interaction introduced;
     4) in  SplittingGenerator  class, define three new switches
        to turn on/off this new interaction, and for turn on/off
        the initial state radiation, and, independently, for 
        final state radiation.


 --- ADD 1->3 SPLITTING FUNCTIONS: FOR EXAMPLE G->GGG
     ------------------------------------------------
     For NLLog parton showers one needs 1->3 splitting functions:
     G->G+G+G. In order to do this:
     1) Fill the already existing, but empty, classes:
          SplitFun1to3, GtoGGGSplitFun, 
          IS_GtoGGGSplitFun, FS_GtoGGGSplitFun
        in a similar way as done, for example, for G->G+G.
     2) Create the class  GtoGGGSudakovFormFactor  which 
        inherits from SudakovFormFactor, in a similar way
        as done for G->G+G.
     3) Create the classes  QtildaShowerKinematics1to3  and
        the derived  IS_QtildaShowerKinematics1to3
        and          FS_QtildaShowerKinematics1to3
        similarly to what as been done for 1->2 case.
     4) In  SplittingGenerator  class do the following:
        a) add a switch for switching on/off the G->G+G+G vertex
        b) in  initializeRun()  create an object
           for each of the following classes:
           IS_GtoGGGSplitFun  ,  IS_GtoGGGSudakovFormFactor
           FS_GtoGGGSplitFun  ,  FS_GtoGGGSudakovFormFactor
        c) in  chooseForwardBranching  (and  chooseBackwardBranching)
           dynamic_ptr_cast  to the class SplitFun1to3, and create an
           object of class  FS_QtildaShowerKinematics1to3  
           similarly to what has been done already for the 1->2 case.
        d) in  generateBranchingKinematics  do eventually something
           for the 1->3 case similarly to what has been done for
           the 1->2 case.
     5) In  ForwardShowerEvolver::timeLikeShower  
        (and similarly in  BackwardShowerEvolver::spaceLikeShower )
        dynamic_ptr_cast  to the class SplitFun1to3, and then
        create the ShowerParticle objects corresponding to the
        shower products,... similarly to what has been done for
        the 1->2 case.
     6) Probably also in  KinematicsReconstructor  one should 
        deal with  QtildaShowerKinematics1to3 , in a similar way
        as it is done for the 1->2 case.

