ThePEG/Handlers/HandlerGroup.h

0001 // -*- C++ -*-
0002 //
0003 // HandlerGroup.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_HandlerGroup_H
0010 #define ThePEG_HandlerGroup_H
0011 // This is the declaration of the HandlerGroup class.
0012
0013 #include "ThePEG/Config/ThePEG.h"
0014 // #include "HandlerGroup.fh"
0015 // #include "HandlerGroup.xh"
0016
0017 namespace ThePEG {
0018
0019 /**
0020  * HandlerGroupBase is the base class for the templated HandlerGroup
0021  * utility class to manage a group of <code>StepHandler</code>s.
0022  *
0023  * The derived StepHandler has a main StepHandler (CascadeHandler,
0024  * MultipleInteractionHandler, HadronizationHandler or DecayHandler)
0025  * while this bease class has a list of pre-hadlers and a list of
0026  * post-handlers.
0027  *
0028  * The <code>HandlerGroup</code> class is used in the
0029  * EventHandler and SubProcessHandler to manage the
0030  * post-sub-process handler, the cascade, multiple interaction,
0031  * hadronization and decay handler groups. When an event is generated,
0032  * after the main sub-process is performed, all handler groups are
0033  * processed in turn. In each group the pre-hadnlers are run first,
0034  * followed by the main handler (which may be run several times is
0035  * more than one Hint has been specified) and finally the
0036  * post-handlers are run.
0037  *
0038  * When a group is initialised before each run, an auxilliary
0039  * HandlerGroupBase object may be specified to override the default
0040  * handlers in this group.
0041  *
0042  * @see HandlerGroup
0043  */
0044 class HandlerGroupBase {
0045
0046 public:
0047
0048   /** Associate a StepHandler with a Hint object. */
0049   typedef pair<StepHdlPtr, HintPtr> StepWithHint;
0050
0051   /** A vector of StepHandler objects. */
0052   typedef vector<StepHdlPtr> StepVector;
0053
0054   /** A vector of StepHandler objects associated with Hint objects. */
0055   typedef vector<StepWithHint> StepHintVector;
0056
0057   /** A vector of Hint objects. */
0058   typedef deque<HintPtr> HintVector;
0059
0060 public:
0061
0062   /**
0063    * Default constructor.
0064    */
0065   HandlerGroupBase();
0066
0067   /**
0068    * Destructor.
0069    */
0070   virtual ~HandlerGroupBase();
0071
0072   /**
0073    * Returns true if current selections in this group is empty.
0074    */
0075   bool empty() const { return isEmpty; }
0076
0077   /**
0078    * Initialize, taking the default StepHandlers as the current ones,
0079    * possibly overridden by the default ones in the auxilliary group
0080    * supplied in the argument.
0081    */
0082   void init(const HandlerGroupBase & ext) {
0083     clear();
0084     refillDefaults(ext);
0085   }
0086
0087   /**
0088    * Return the next step;
0089    */
0090   StepWithHint next();
0091
0092   /**
0093    * Add a step handler, \a sh to the current list of
0094    * pre-handlers. Optionally a \a hint may be specified. If the main
0095    * handler has already been executed, the object is reinitialized
0096    * using \a ext to override defaults.
0097    */
0098   void addPreHandler(tStepHdlPtr sh, tHintPtr hint,
0099              const HandlerGroupBase & ext);
0100
0101   /**
0102    * Add a step handler, \a sh, to the current list of
0103    * post-handlers. Optionally a \a hint may be specified. If the main
0104    * handler has already been executed, the object is reinitialized
0105    * using \a ext to override defaults.
0106    */
0107   void addPostHandler(tStepHdlPtr sh, tHintPtr hint,
0108               const HandlerGroupBase &);
0109
0110   /**
0111    * Add a \a hint to the currently selected main handler. If the main
0112    * handler has already been executed, the object is reinitialized
0113    * using \a ext to override defaults.
0114    */
0115   void addHint(tHintPtr hint, const HandlerGroupBase & ext);
0116
0117   /**
0118    * Return a reference to the list of default pre-handlers.
0119    */
0120   StepVector & preHandlers() { return theDefaultPreHandlers; }
0121
0122   /**
0123    * Return a reference to the list of default pre-handlers.
0124    */
0125   const StepVector & preHandlers() const { return theDefaultPreHandlers; }
0126
0127   /**
0128    * Return a pointer to the default main handler.
0129    */
0130   virtual tStepHdlPtr defaultHandler() const = 0;
0131
0132   /**
0133    * Return a reference to the list of default post-handlers.
0134    */
0135   StepVector & postHandlers() { return theDefaultPostHandlers; }
0136
0137   /**
0138    * Return a reference to the list of default post-handlers.
0139    */
0140   const StepVector & postHandlers() const { return theDefaultPostHandlers; }
0141
0142   /**
0143    * Return a pointer to the current main handler.
0144    */
0145   virtual tStepHdlPtr handler() const = 0;
0146
0147   /**
0148    * Unset the current main handler.
0149    */
0150   virtual void setHandler() = 0;
0151
0152   /**
0153    * Set the current main handler, but also refill the current pre-
0154    * and post- handlers with the defaults from \a ext.
0155    */
0156   virtual bool setHandler(tStepHdlPtr, const HandlerGroupBase & ext) = 0;
0157
0158   /**
0159    * Set the current main handler. If the null pointer use the default
0160    * main handler.
0161    */
0162   virtual void refillDefaultHandler(tStepHdlPtr) = 0;
0163
0164   /**
0165    * Fill main, pre- and post- handlers with the default ones. The
0166    * default handlers in the argument takes precedence to this.
0167    */
0168   void refillDefaults(const HandlerGroupBase &);
0169
0170   /**
0171    * Clear all current handlers, but don't touch the default ones.
0172    */
0173   virtual void clear();
0174
0175   /**
0176    * Return the base class name of the main handler type.
0177    */
0178   virtual string handlerClass() const = 0;
0179
0180   /**
0181    * Utility function used for the interface.
0182    */
0183   void interfaceSetPrehandler(StepHdlPtr p, int i);
0184
0185   /**
0186    * Utility function used for the interface.
0187    */
0188   void interfaceInsertPrehandler(StepHdlPtr p, int i);
0189
0190   /**
0191    * Utility function used for the interface.
0192    */
0193   void interfaceErasePrehandler(int i);
0194
0195   /**
0196    * Utility function used for the interface.
0197    */
0198   vector<StepHdlPtr> interfaceGetPrehandlers() const;
0199
0200   /**
0201    * Utility function used for the interface.
0202    */
0203   void interfaceSetPosthandler(StepHdlPtr p, int i);
0204
0205   /**
0206    * Utility function used for the interface.
0207    */
0208   void interfaceInsertPosthandler(StepHdlPtr p, int i);
0209
0210   /**
0211    * Utility function used for the interface.
0212    */
0213   void interfaceErasePosthandler(int i);
0214
0215   /**
0216    * Utility function used for the interface.
0217    */
0218   vector<StepHdlPtr> interfaceGetPosthandlers() const;
0219
0220   /**
0221    * Write to persistent streams.
0222    */
0223   virtual void write(PersistentOStream &) const;
0224
0225   /**
0226    * Read from persistent streams.
0227    */
0228   virtual void read(PersistentIStream &);
0229
0230 protected:
0231
0232   /**
0233    * The copy constructor is only used via subclasses.
0234    */
0235   HandlerGroupBase(const HandlerGroupBase &);
0236
0237   /**
0238    * True if the current handlers are empty.
0239    */
0240   bool isEmpty;
0241
0242 private:
0243
0244   /**
0245    * Add handlers from the def vector to the current, supplying them
0246    * with default hints.
0247    */
0248   void checkInsert(StepHintVector & current, const StepVector & def);
0249
0250 protected:
0251
0252   /**
0253    * The default pre-handlers with hints.
0254    */
0255   StepVector theDefaultPreHandlers;
0256
0257   /**
0258    * The default post-handlers with hints.
0259    */
0260   StepVector theDefaultPostHandlers;
0261
0262   /**
0263    * The current pre-handlers with hints.
0264    */
0265   StepHintVector thePreHandlers;
0266
0267   /**
0268    * The current hints for the main handler.
0269    */
0270   HintVector theHints;
0271
0272   /**
0273    * The current post-handlers with hints.
0274    */
0275   StepHintVector thePostHandlers;
0276
0277 private:
0278
0279   /**
0280    * Assignment is private.
0281    */
0282   HandlerGroupBase & operator=(const HandlerGroupBase &) = delete;
0283
0284 };
0285
0286 /**
0287  * HandlerGroup is a templated utility class to manage a
0288  * group of <code>StepHandler</code>s. All HandlerGroup
0289  * classes are derived from the <code>HandlerGroupBase</code> class. As
0290  * an example the specialization
0291  * <code>HandlerGroup<CascadeHandler></code> keeps a
0292  * CascadeHandler object and associated pre- and
0293  * post- StepHandlers, defining shich steps should be
0294  * performed before the perturbative cascade, which object should be
0295  * used for the cascade and which steps should be performed after.
0296  *
0297  * The <code>HandlerGroup</code> keesp both a default main handler and
0298  * the corresponding default pre- and post- handlers as well as the
0299  * main handler and pre/post hadlers chosen for the current event. The
0300  * current handlers are accompanied by Hints. Handlers which are
0301  * copied from the default ones are accompanied by the default Hint,
0302  * while handlers supplied from the outside may be accompanied by any
0303  * kind of hint. The main handler can be supplied with several hints,
0304  * the pre- and post- handlers may only have one hint each.
0305  *
0306  * The <code>HandlerGroup</code> class is used in the
0307  * EventHandler and SubProcessHandler to manage the
0308  * post-sub-process handler, the cascade, multiple interaction,
0309  * hadronization and decay handler groups.
0310  *
0311  * @see EventHandler
0312  * @see SubProcessHandler
0313  * @see StepHandler
0314  * @see CascadeHandler
0315  * @see MultipleInteractionHandler
0316  * @see HadronizationHandler
0317  * @see DecayHandler
0318  *
0319  */
0320 template <typename HDLR>
0321 class HandlerGroup: public HandlerGroupBase {
0322
0323 public:
0324
0325   /** A pointer to the template argument class. */
0326   typedef typename Ptr<HDLR>::pointer HdlPtr;
0327
0328   /** A transient pointer to the template argument class. */
0329   typedef typename Ptr<HDLR>::transient_pointer tHdlPtr;
0330
0331 public:
0332
0333   /**
0334    * Destructor.
0335    */
0336   virtual ~HandlerGroup();
0337
0338   /**
0339    * Set the current main handler. Also refill the current pre- and
0340    * post- handlers with the defaults from \a ext.
0341    */
0342   virtual bool setHandler(tStepHdlPtr, const HandlerGroupBase & ext);
0343
0344   /**
0345    * Unset the current main handler.
0346    */
0347   virtual void setHandler() { theHandler = HdlPtr(); }
0348
0349   /**
0350    * Return a pointer to the current main handler.
0351    */
0352   virtual tStepHdlPtr handler() const {
0353     return dynamic_ptr_cast<tStepHdlPtr>(theHandler);
0354   }
0355
0356   /**
0357    * Return a pointer to the default main handler.
0358    */
0359   virtual tStepHdlPtr defaultHandler() const {
0360     return dynamic_ptr_cast<tStepHdlPtr>(theDefaultHandler);
0361   }
0362
0363   /**
0364    * Set the current main handler. If the null pointer use the default
0365    * main handler.
0366    */
0367   virtual void refillDefaultHandler(tStepHdlPtr);
0368
0369   /**
0370    * Clear all current handlers, but don't touch the default ones.
0371    */
0372   virtual void clear();
0373
0374   /**
0375    * Return the base class name of the main handler type.
0376    */
0377   virtual string handlerClass() const;
0378
0379   /**
0380    * Utility function used for the interface.
0381    */
0382   void interfaceSetHandler(HdlPtr);
0383
0384   /**
0385    * Utility function used for the interface.
0386    */
0387   HdlPtr interfaceGetHandler() const;
0388
0389   /**
0390    * Write to persistent streams.
0391    */
0392   virtual void write(PersistentOStream & os) const {
0393     os << theDefaultHandler << theHandler;
0394     HandlerGroupBase::write(os);
0395   }
0396
0397   /**
0398    * Read from persistent streams.
0399    */
0400   virtual void read(PersistentIStream & is) {
0401     is >> theDefaultHandler >> theHandler;
0402     HandlerGroupBase::read(is);
0403   }
0404
0405 private:
0406
0407
0408   /**
0409    * The default main handler.
0410    */
0411   HdlPtr theDefaultHandler;
0412
0413   /**
0414    * The current main handler.
0415    */
0416   HdlPtr theHandler;
0417
0418 private:
0419
0420   /**
0421    * Assignment is private.
0422    */
0423   HandlerGroup<HDLR> & operator=(const HandlerGroup<HDLR> &) = delete;
0424
0425 };
0426
0427 /** Namespace to encapsulate enums related to <code>HandlerGroup</code>s. */
0428 namespace Group {
0429
0430 /**
0431  * Enumeration for the type of <code>HandlerGroup</code>s.
0432  */
0433 enum Handler {
0434   subproc, /**< The sub-process group. */
0435   cascade, /**< The CascadeHandler group. */
0436   multi,   /**< The MultipleInteractionHandler group. */
0437   hadron,  /**< The HadronizationHandler group. */
0438   decay    /**< The DecayHandler group. */
0439 };
0440
0441 /** Enumeration for the type of step handler */
0442 enum Level {
0443   before, /**< A pre-handler. */
0444   main,   /**< The mainhandler. */
0445   after   /**< A post-handler. */
0446 };
0447 }
0448
0449 /** Output a HandlerGroup to a PersistentOStream. */
0450 template <typename HDLR>
0451 inline PersistentOStream & operator<<(PersistentOStream & os,
0452                       const HandlerGroup<HDLR> & hg) {
0453   hg.write(os);
0454   return os;
0455 }
0456
0457 /** Input a HandlerGroup from a PersistentIStream. */
0458 template <typename HDLR>
0459 inline PersistentIStream & operator>>(PersistentIStream & is,
0460                       HandlerGroup<HDLR> & hg) {
0461   hg.read(is);
0462   return is;
0463 }
0464
0465 }
0466
0467 /** Macro for declaring a prepost group */
0468 #define ThePEG_DECLARE_PREPOST_GROUP(HandlerClass,prepost)                    \
0469 /** Utility function for the interface. */                                    \
0470 void interfaceSet##prepost##HandlerClass(StepHdlPtr, int);                    \
0471 /** Utility function for the interface. */                                    \
0472 void interfaceInsert##prepost##HandlerClass(StepHdlPtr, int);                 \
0473 /** Utility function for the interface. */                                    \
0474 void interfaceErase##prepost##HandlerClass(int);                              \
0475 /** Utility function for the interface. */                                    \
0476 vector<StepHdlPtr> interfaceGet##prepost##HandlerClass() const
0477
0478 /** Macro for declaring a group interface */
0479 #define ThePEG_DECLARE_GROUPINTERFACE(HandlerClass,ptr)                       \
0480 ThePEG_DECLARE_PREPOST_GROUP(HandlerClass,Pre);                               \
0481 /** Utility function for the interface. */                                    \
0482 void interfaceSet##HandlerClass(ptr);                                         \
0483 /** Utility function for the interface. */                                    \
0484 ptr interfaceGet##HandlerClass() const;                                       \
0485 ThePEG_DECLARE_PREPOST_GROUP(HandlerClass,Post)
0486
0487 /** Macro for implementing a prepost group. */
0488 #define ThePEG_IMPLEMENT_PREPOST_GROUP(ThisClass,HandlerClass,member,pp)      \
0489 void ThisClass::interfaceSet##pp##HandlerClass(StepHdlPtr p , int i) {     \
0490   member.interfaceSet##pp##handler(p,i);                                     \
0491 }                                                                              \
0492 void ThisClass::interfaceInsert##pp##HandlerClass(StepHdlPtr p, int i) {   \
0493   member.interfaceInsert##pp##handler(p,i);                                  \
0494 }                                                                              \
0495 void ThisClass::interfaceErase##pp##HandlerClass(int i) {                  \
0496   member.interfaceErase##pp##handler(i);                                     \
0497 }                                                                              \
0498 vector<StepHdlPtr> ThisClass::interfaceGet##pp##HandlerClass() const {     \
0499   return member.interfaceGet##pp##handlers();                                  \
0500 }
0501
0502 /** Macro for implementing a group interface. */
0503 #define ThePEG_IMPLEMENT_GROUPINTERFACE(ThisClass,HandlerClass,member,ptr)     \
0504 ThePEG_IMPLEMENT_PREPOST_GROUP(ThisClass,HandlerClass,member,Pre)              \
0505 void ThisClass::interfaceSet##HandlerClass(ptr p) {                            \
0506   member.interfaceSetHandler(p);                                               \
0507 }                                                                              \
0508 ptr ThisClass::interfaceGet##HandlerClass() const {                            \
0509   return member.interfaceGetHandler();                                         \
0510 }                                                                              \
0511 ThePEG_IMPLEMENT_PREPOST_GROUP(ThisClass,HandlerClass,member,Post)             \
0512
0513 /** Macro for declaring prepost objects. */
0514 #define ThePEG_DECLARE_PREPOST_OBJECTS(ThisClass,HandlerClass,pp,ba)           \
0515 static RefVector<ThisClass,StepHandler> interface##pp##HandlerClass            \
0516 (#pp #HandlerClass "s",                                                        \
0517  "A list of handlers to be called " #ba " the " #HandlerClass ". "             \
0518  "If handler objects are specified in a EventHandler and "                     \
0519  "the SubProcessHandler chosen in a given collision also specifies some, "     \
0520  "the latter will caled first.",                                               \
0521  0, 0, false, false, true, false,                                              \
0522  &ThisClass::interfaceSet##pp##HandlerClass,                                   \
0523  &ThisClass::interfaceInsert##pp##HandlerClass,                                \
0524  &ThisClass::interfaceErase##pp##HandlerClass,                                 \
0525  &ThisClass::interfaceGet##pp##HandlerClass)
0526
0527 /** Macro for declaring group interface objects. */
0528 #define ThePEG_DECLARE_GROUPINTERFACE_OBJECTS(ThisClass,HandlerClass)          \
0529 ThePEG_DECLARE_PREPOST_OBJECTS(ThisClass,HandlerClass,Pre, before);            \
0530 static Reference<ThisClass,HandlerClass> interface ## HandlerClass             \
0531 (#HandlerClass,                                                                \
0532  "The " #HandlerClass " object used in this " #ThisClass ". "                  \
0533  "If a " #HandlerClass " object is specified in a EventHandler and "           \
0534  "the SubProcessHandler chosen in a given collision also specifies one,"       \
0535  "the latter will be used.",                                                   \
0536  0, false, false, true, true,                                                  \
0537  &ThisClass::interfaceSet ## HandlerClass,                                     \
0538  &ThisClass::interfaceGet ## HandlerClass);                                    \
0539 ThePEG_DECLARE_PREPOST_OBJECTS(ThisClass,HandlerClass,Post, after)
0540
0541 #ifndef ThePEG_TEMPLATES_IN_CC_FILE
0542 #include "HandlerGroup.tcc"
0543 #endif
0544
0545 #endif /* ThePEG_HandlerGroup_H */