ThePEG/Handlers/ClusterCollapser.h

0001 // -*- C++ -*-
0002 //
0003 // ClusterCollapser.h is a part of ThePEG - Toolkit for HEP Event Generation
0004 // Copyright (C) 1999-2019 Leif Lonnblad
0005 //
0006 // ThePEG is licenced under version 3 of the GPL, see COPYING for details.
0007 // Please respect the MCnet academic guidelines, see GUIDELINES for details.
0008 //
0009 #ifndef ThePEG_ClusterCollapser_H
0010 #define ThePEG_ClusterCollapser_H
0011 // This is the declaration of the ClusterCollapser class.
0012
0013 #include "ThePEG/Handlers/StepHandler.h"
0014 #include "ThePEG/Handlers/FlavourGenerator.h"
0015 #include "ThePEG/EventRecord/ColourSinglet.h"
0016 #include "ClusterCollapser.fh"
0017 // #include "ClusterCollapser.xh"
0018
0019
0020 namespace ThePEG {
0021
0022 /**
0023  * ClusterCollapser is a general StepHandler which can be called
0024  * anywhere in the event generation (typically as a pre-handler to the
0025  * hadronization or a post-hadnler to the cascade) to find colour-less
0026  * clusters of partons which are deemed to have to small invariant
0027  * mass to be hadronized in the normal way. Instead these clusters are
0028  * allowed to collapse into hadrons. Possible energy imbalance du to
0029  * the clustering is compensated by shifting the momenta of nearby
0030  * particles.
0031  *
0032  * @see \ref ClusterCollapserInterfaces "The interfaces"
0033  * defined for ClusterCollapser.
0034  */
0035 class ClusterCollapser: public StepHandler {
0036
0037 public:
0038
0039   /** Declare a pointer to a FlavourGenerator object. */
0040   typedef Ptr<FlavourGenerator>::pointer FlavGenPtr;
0041
0042   /** Declare a multimap of singlets indexed by their mass. */
0043   typedef multimap<Energy,ColourSinglet> SingletMap;
0044
0045 public:
0046
0047   /** @name Standard constructors and destructors. */
0048   //@{
0049   /**
0050    * The default constructor.
0051    */
0052   ClusterCollapser()
0053     : theEnergyCut(1.0*GeV), theNTry2(2), errorlevel(Exception::eventerror),
0054       pStrange(1.0/3.0) {}
0055
0056   /**
0057    * The destructor.
0058    */
0059   virtual ~ClusterCollapser();
0060   //@}
0061
0062 public:
0063
0064   /** @name Virtual functions required by the StepHandler class. */
0065   //@{
0066   /**
0067     * The main function called by the EventHandler class to
0068     * perform a step. This function simply calls the collapse() function.
0069     * @param eh the EventHandler in charge of the Event generation.
0070     * @param tagged if not empty these are the only particles which should
0071     * be considered by the StepHandler.
0072     * @param hint a Hint object with possible information from previously
0073     * performed steps.
0074     * @throws Veto if the StepHandler requires the current step to be discarded.
0075     * @throws Stop if the generation of the current Event should be stopped
0076     * after this call.
0077     * @throws Exception if something goes wrong.
0078     */
0079   virtual void handle(EventHandler & eh, const tPVector & tagged,
0080               const Hint & hint);
0081   //@}
0082
0083   /**
0084    * Perform all necessary collapses. Return the uncollapsed clusters.
0085    */
0086   virtual vector<ColourSinglet> collapse(tPVector tagged,
0087                      tStepPtr newstep);
0088
0089   /**
0090    * Go through the tagged partons and extract all colour singlet
0091    * combination of partons. Order them in invariant mass (minus the
0092    * constituent masses of the partons).
0093    */
0094   virtual SingletMap getSinglets(const tPVector & tagged) const;
0095
0096   /**
0097    * If a singlet contains at least one diquark and a junction, split
0098    * the diquark and split off a new colour singlet.
0099    */
0100   virtual ColourSinglet splitDiQuarkJunction(ColourSinglet & cs,
0101                          tStepPtr newStep) const;
0102
0103   /**
0104    * If a singlet contains a simple string with diquarks in both ends,
0105    * split them into quarks and split off a new colour singlet.
0106    */
0107   virtual ColourSinglet splitDiDiQuark(ColourSinglet & cs,
0108                        tStepPtr newStep) const;
0109
0110   /**
0111    * Returns true iff the given singlet contains a junction and at
0112    * least one diquark.
0113    */
0114   static bool diQuarkJunction(const ColourSinglet & cs);
0115
0116   /**
0117    * Returns true iff the given singlet contains one string piece with
0118    * diquarks in both ends.
0119    */
0120   static bool diDiQuark(const ColourSinglet & cs);
0121
0122   /**
0123    * If the invariant mass of a cluster, minus the constituent masses
0124    * of its partons is below this cut, it will be collapsed into one
0125    * or two particles.
0126    */
0127   Energy cut() const { return theEnergyCut; }
0128
0129   /**
0130    * The number of attempts to collapse a cluster into two particles,
0131    * before it is collapsed into one particle.
0132    */
0133   int nTry2() const { return theNTry2; }
0134
0135   /**
0136    * Return the invariant mass of a cluster minus the constituent
0137    * masses of its partons.
0138    */
0139   static Energy mass(const ColourSinglet & cl);
0140
0141   /**
0142    * Insert a ColourSinglet object in a SingletMap.
0143    */
0144   static void insert(SingletMap & mmap, const ColourSinglet & cl);
0145
0146   /**
0147    * Pick a random flavour. Default version picks u,d or s with ratio
0148    * 3:3:1.
0149    */
0150   virtual tcPDPtr pickFlavour() const;
0151
0152 protected:
0153
0154   /**
0155    * Perform the actual collapse of a cluster into one hadron.  Add
0156    * the produced hadron to the given step as decay products of the
0157    * partons in the cluster. The \a tagged particles are used for
0158    * momentum compensation.
0159    */
0160   virtual void collapse(tStepPtr newStep, const ColourSinglet & cs,
0161             const tPVector & tagged) const;
0162   /**
0163    * Perform the actual collapse of a cluster into two hadrons. Add
0164    * the produced hadrons to the given step as decay products of the
0165    * partons in the cluster. The \a tagged particles are used for
0166    * momentum compensation.  @return false if the collapse failed in
0167    * some way.
0168    */
0169   virtual bool collapse2(tStepPtr newStep, const ColourSinglet & cs) const;
0170
0171   /**
0172    * Get particles for compensation. Look through the \a tagged vector
0173    * for particles (which are not in the colour singlet \a cs) which can
0174    * be used to compensate momentum when \a cs collapses into a hadron
0175    * with mass \a mh. These partons are then copied into the new step so
0176    * that their momentum can be changed and then returned.
0177    */
0178   virtual tPVector getCompensators(Energy mh, const ColourSinglet & cs,
0179                    const tPVector & tagged,
0180                    tStepPtr newStep) const;
0181
0182   /**
0183    * Return a hadron into which the given cluster may collapse.
0184    */
0185   virtual tcPDPtr getHadron(const ColourSinglet & cs) const;
0186
0187   /**
0188    * Return a pair of hadrons into which the given cluster may collapse.
0189    */
0190   virtual tcPDPair getHadrons(const ColourSinglet & cs) const;
0191
0192   /**
0193    * Uptate the vector of particles and remove partons which have
0194    * already collapsed and insert their children instead.
0195    */
0196   void updateTagged(tPVector & tagged) const;
0197
0198 public:
0199
0200   /** @name Functions used by the persistent I/O system. */
0201   //@{
0202   /**
0203    * Function used to write out object persistently.
0204    * @param os the persistent output stream written to.
0205    */
0206   void persistentOutput(PersistentOStream & os) const;
0207
0208   /**
0209    * Function used to read in object persistently.
0210    * @param is the persistent input stream read from.
0211    * @param version the version number of the object when written.
0212    */
0213   void persistentInput(PersistentIStream & is, int version);
0214   //@}
0215
0216   /**
0217    * Standard Init function used to initialize the interfaces.
0218    */
0219   static void Init();
0220
0221 protected:
0222
0223   /** @name Clone Methods. */
0224   //@{
0225   /**
0226    * Make a simple clone of this object.
0227    * @return a pointer to the new object.
0228    */
0229   virtual IBPtr clone() const;
0230
0231   /** Make a clone of this object, possibly modifying the cloned object
0232    * to make it sane.
0233    * @return a pointer to the new object.
0234    */
0235   virtual IBPtr fullclone() const;
0236   //@}
0237
0238   /** @cond EXCEPTIONCLASSES */
0239   /** Exception class used by ClusterCollapser. */
0240   class ClusterException: public Exception {
0241   public:
0242     /** Standard constructor. */
0243     ClusterException(const ClusterCollapser & cc) {
0244       theMessage << "In ClusterCollapser '" << cc.name() << "': ";
0245     }
0246   };
0247   /** @endcond */
0248
0249 private:
0250
0251   /**
0252    * Energy cut. If the invariant mass of a cluster, minus the
0253    * constituent masses of its partons is below this cut, it will be
0254    * collapsed into one or two particles.
0255    */
0256   Energy theEnergyCut;
0257
0258   /**
0259    * The number of attempts to collapse a cluster into two particles,
0260    * before it is collapsed into one particle.
0261    */
0262   int theNTry2;
0263
0264   /**
0265    * The flavour generator object to use to combine quarks and diqurks
0266    * into hadrons.
0267    */
0268   FlavGenPtr flavGen;
0269
0270 protected:
0271
0272   /**
0273    * How should we respond to errors? 0 means do nothing, ie. the
0274    * cluster will not be collapsed, or the momentum will not be
0275    * consterved. Otherwise the severity will be what is defined in the
0276    * class Exception.
0277    */
0278   Exception::Severity errorlevel;
0279
0280   /**
0281    * The relative probability to produce a s-sbar pair in a split as
0282    * compared to a u-ubar or d-dbar pair.
0283    */
0284   double pStrange;
0285
0286 private:
0287
0288   /**
0289    * Describe a concrete class with persistent data.
0290    */
0291   static ClassDescription<ClusterCollapser> initClusterCollapser;
0292
0293   /**
0294    *  Private and non-existent assignment operator.
0295    */
0296   ClusterCollapser & operator=(const ClusterCollapser &) = delete;
0297
0298 };
0299
0300 }
0301
0302
0303 namespace ThePEG {
0304
0305 /** @cond TRAITSPECIALIZATIONS */
0306
0307 /**
0308  * The following template specialization informs ThePEG about the
0309  * base class of ClusterCollapser.
0310  */
0311 template <>
0312 struct BaseClassTrait<ClusterCollapser,1>: public ClassTraitsType {
0313   /** Typedef of the first base class of ClusterCollapser. */
0314   typedef StepHandler NthBase;
0315 };
0316
0317 /**
0318  * The following template specialization informs ThePEG about the name
0319  * of the ClusterCollapser class and the shared object where it is
0320  * defined.
0321  */
0322 template <>
0323 struct ClassTraits<ClusterCollapser>:
0324     public ClassTraitsBase<ClusterCollapser> {
0325   /**
0326    * Return the class name.
0327    */
0328   static string className() { return "ThePEG::ClusterCollapser"; }
0329
0330 };
0331
0332 /** @endcond */
0333
0334 }
0335
0336 #endif /* ThePEG_ClusterCollapser_H */