ThePEG/PDT/Decayer.h

0001 // -*- C++ -*-
0002 //
0003 // Decayer.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_Decayer_H
0010 #define ThePEG_Decayer_H
0011 // This is the declaration of the Decayer class.
0012
0013 #include "ThePEG/Config/ThePEG.h"
0014 #include "Decayer.fh"
0015 #include "ThePEG/Handlers/HandlerBase.h"
0016 #include "ThePEG/MatrixElement/Amplitude.h"
0017
0018 namespace ThePEG {
0019
0020 /**
0021  * Decayer is an abstract base class to specify objects modelling the
0022  * decay of a particle.
0023  *
0024  * @see \ref DecayerInterfaces "The interfaces"
0025  * defined for Decayer.
0026  * @see ParticleData
0027  * @see DecayMode
0028  */
0029 class Decayer: public HandlerBase {
0030
0031 public:
0032
0033   /** @name Virtual functions to be overridden in sub-classes. */
0034   //@{
0035   /**
0036    * Check if this decayer can perfom the decay specified by the
0037    * given decay mode.
0038    * @param dm the DecayMode describing the decay.
0039    * @return true if this decayer can handle the given mode, otherwise false.
0040    */
0041   virtual bool accept(const DecayMode & dm) const = 0;
0042
0043   /**
0044    * Return true if this Decayer need to access the full current step
0045    * when a particle is decayed. If true is returned the standard
0046    * Decay Handler will call the decay(const DecayMode&,const
0047    * Particle&,Step&) function rather than the decay(const
0048    * DecayMode&,const Particle&) function.
0049    */
0050   virtual bool needsFullStep() const;
0051
0052   /**
0053    * Perform a decay for a given DecayMode and a given Particle instance.
0054    * @param dm the DecayMode describing the decay.
0055    * @param p the Particle instance to be decayed.
0056    * @return a ParticleVector containing the decay products.
0057    */
0058   virtual ParticleVector decay(const DecayMode & dm,
0059                    const Particle & p) const = 0;
0060
0061   /**
0062    * Perform a decay for a given DecayMode and a given Particle
0063    * instance. This version allows the decaying particle to borrow
0064    * energy/momentum from its sublings in the current step. This will
0065    * be called by the standard DecayHandler if the needsFullStep()
0066    * function returns true.
0067    *
0068    * @param dm   the DecayMode describing the decay.
0069    * @param p    the Particle instance to be decayed.
0070    * @param step the current step in which to find possible siblings to
0071    *             shuffle energy with.
0072    * @return a ParticleVector containing the decay products.
0073    */
0074   virtual ParticleVector decay(const DecayMode & dm, const Particle & p,
0075                    Step & step) const;
0076
0077   /**
0078    * Calculate branching ratio. If this model has any oppinions on the
0079    * decay rate for a given decay mode \a dm, for a given particle
0080    * type \a pd, this method may be overriden to return this
0081    * oppinion. \a oldbrat is the branching ratio specified in the
0082    * DecayMode or by asking the WidthGenerator of \a pd.
0083    */
0084   virtual double brat(const DecayMode & dm, const ParticleData & pd,
0085               double oldbrat) const;
0086
0087   /**
0088    * Calculate branching ratio. If this model has any oppinions on the
0089    * decay rate for a given decay mode \a dm, for a given particle \a
0090    * p, this method may be overriden to return this oppinion. \a
0091    * oldbrat is the branching ratio specified in the DecayMode or by
0092    * asking the WidthGenerator of \a p.
0093    */
0094   virtual double brat(const DecayMode & dm, const Particle & p,
0095               double oldbrat) const;
0096
0097   /**
0098    * Produce the children. Can be used by sub-class decay() functions
0099    * to produce instances of the children. This default implementation
0100    * just calls the produceProducts() of the specified decay products
0101    * in DecayMode object, \a dm.
0102    */
0103   virtual ParticleVector getChildren(const DecayMode & dm,
0104                      const Particle & parent) const;
0105
0106   /**
0107    * Boost the decay products. Can be used by sub-classes to perform
0108    * the final boost back from the parents cms. This default version
0109    * does just that.
0110    */
0111   virtual void finalBoost(const Particle & parent,
0112               const ParticleVector & children) const;
0113
0114   /**
0115    * Set the scales. Can be used by sub classes to set the production
0116    * scale of the children. This default version sets the scale to the
0117    * parents mass.
0118    */
0119   virtual void setScales(const Particle & parent,
0120              const ParticleVector & children) const;
0121   //@}
0122
0123   /**
0124    * Return an amplitude associated with this decay matrix
0125    * element. May return null.
0126    */
0127   Ptr<Amplitude>::pointer amplitude() const { return theAmplitude; }
0128
0129   /**
0130    * Static function to administer the decay of a \a particle. The
0131    * children are properly added to the particle and to the given \a
0132    * step. Maximum \a maxtry attempts to decay the particle is
0133    * performed.
0134    * @return the produced children.
0135    */
0136   static ParticleVector
0137   DecayParticle(tPPtr parent, Step & step, long maxtry = 1000);
0138
0139   /**
0140    * Exception class used if something goes wrong in DecayParticle().
0141    */
0142   struct DecayFailure: public Exception {};
0143
0144 public:
0145
0146
0147   /** @name Functions used by the persistent I/O system. */
0148   //@{
0149   /**
0150    * Function used to write out object persistently.
0151    * @param os the persistent output stream written to.
0152    */
0153   void persistentOutput(PersistentOStream & os) const;
0154
0155   /**
0156    * Function used to read in object persistently.
0157    * @param is the persistent input stream read from.
0158    * @param version the version number of the object when written.
0159    */
0160   void persistentInput(PersistentIStream & is, int version);
0161   //@}
0162
0163   /**
0164    * Standard Init function used to initialize the interfaces.
0165    */
0166   static void Init();
0167
0168 private:
0169
0170   /**
0171    * The static object used to initialize the description of this class.
0172    * Indicates that this is an abstract class without persistent data.
0173    */
0174   static AbstractNoPIOClassDescription<Decayer> initDecayer;
0175
0176   /**
0177    *  Private and non-existent assignment operator.
0178    */
0179   Decayer & operator=(const Decayer &) = delete;
0180
0181   /**
0182    * A possible null pointer to an amplitude associated with this
0183    * matrix element.
0184    */
0185   Ptr<Amplitude>::pointer theAmplitude;
0186
0187 };
0188
0189 /** @cond TRAITSPECIALIZATIONS */
0190
0191 /** This template specialization informs ThePEG about the base classes
0192  *  of Decayer. */
0193 template <>
0194 struct BaseClassTrait<Decayer,1>: public ClassTraitsType {
0195   /** Typedef of the first base class of Decayer. */
0196   typedef HandlerBase NthBase;
0197 };
0198
0199 /** This template specialization informs ThePEG about the name of the
0200  *  Decayer class. */
0201 template <>
0202 struct ClassTraits<Decayer>: public ClassTraitsBase<Decayer> {
0203   /** Return a platform-independent class name */
0204   static string className() { return "ThePEG::Decayer"; }
0205 };
0206
0207 /** @endcond */
0208
0209 }
0210
0211 #endif /* ThePEG_Decayer_H */