ThePEG/Handlers/StepHandler.h

0001 // -*- C++ -*-
0002 //
0003 // StepHandler.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_StepHandler_H
0010 #define ThePEG_StepHandler_H
0011 // This is the declaration of the StepHandler class.
0012
0013 #include "ThePEG/Config/ThePEG.h"
0014 #include "ThePEG/Utilities/Exception.fh"
0015 #include "ThePEG/Handlers/HandlerBase.h"
0016 #include <stdexcept>
0017
0018 namespace ThePEG {
0019
0020 /**
0021  * StepHandler is the base class for implementing any model for a step
0022  * in the event generation chain. It has one main virtual method,
0023  * handle(), which should be overridden by sub classes. The handle
0024  * method is given a reference to a EventHandler, a vector
0025  * of particles and a Hint as arguments. The handler is only allowed
0026  * to treat particles which are in the vector. The Hint may be cast
0027  * dynamically to a sub class and do whatever it wishes with the
0028  * information found there. The EventHandler can be used to
0029  * add other <code>StepHandler</code>s and Hints to modify the
0030  * subsequent generation. If the StepHandler actually performs some
0031  * action, the resulting particles should be added to a new Step which
0032  * should be aquired with the newStep() function.
0033  *
0034  * @see \ref StepHandlerInterfaces "The interfaces"
0035  * defined for StepHandler.
0036  * @see EventHandler
0037  * @see Hint
0038  * @see Step
0039  *
0040  */
0041 class StepHandler: public HandlerBase {
0042
0043 public:
0044
0045   /** @name Standard constructors and destructors. */
0046   //@{
0047   /**
0048    * The destructor.
0049    */
0050   virtual ~StepHandler();
0051   //@}
0052
0053 public:
0054
0055   /** @name Virtual functions to be implemented by concrete sub-classes. */
0056   //@{
0057   /**
0058     * The main function called by the EventHandler class to
0059     * perform a step.
0060     * @param eh the EventHandler in charge of the Event generation.
0061     * @param tagged if not empty these are the only particles which should
0062     * be considered by the StepHandler.
0063     * @param hint a Hint object with possible information from previously
0064     * performed steps.
0065     * @throws Veto if the StepHandler requires the current step to be
0066     * discarded.
0067     * @throws Stop if the generation of the current Event should be stopped
0068     * after this call.
0069     * @throws Exception if something goes wrong.
0070     */
0071   virtual void handle(EventHandler & eh, const tPVector & tagged,
0072               const Hint & hint) = 0;
0073   //@}
0074
0075   /** @name Access to the calling EventHandler and current Step. */
0076   //@{
0077   /**
0078    * Get a pointer to the EventHandler which made the last call to
0079    * handle().
0080    */
0081   tEHPtr eventHandler() const { return theEventHandler; }
0082
0083   /**
0084    * Set a pointer to the EventHandler which made the last call to
0085    * handle().
0086    */
0087   void eventHandler(tEHPtr);
0088
0089   /**
0090    * Return a pointer to a new step. If one has alredy been created in
0091    * the last call to handle(), that step will be returned.
0092    */
0093   tStepPtr newStep() {
0094     if ( !theNewStep ) createNewStep();
0095     return theNewStep;
0096   }
0097
0098   /**
0099    * If a new step has been created, return it, otherwise return the
0100    * current step from the eventHandler().
0101    */
0102   tStepPtr currentStep() {
0103     if ( theNewStep ) return theNewStep;
0104     return theCurrentStep;
0105   }
0106   //@}
0107
0108 public:
0109
0110   /**
0111    * Standard Init function used to initialize the interface.
0112    */
0113   static void Init();
0114
0115 protected:
0116
0117   /**
0118    * Use the collision handler to create a new step.
0119    */
0120   void createNewStep();
0121
0122 private:
0123
0124   /**
0125    * A pointer to the (partial) collision handler which made the current
0126    * call to handle().
0127    */
0128   tEHPtr theEventHandler;
0129
0130   /**
0131    * A pointer to a new step if created in the last call to handle().
0132    */
0133   tStepPtr theNewStep;
0134
0135   /**
0136    * A pointer to the current step. Is equal to theNewStep if one was
0137    * created in the current call to handle().
0138    */
0139   tStepPtr theCurrentStep;
0140
0141 private:
0142
0143   /**
0144    * Describe an abstract class without persistent data.
0145    */
0146   static AbstractNoPIOClassDescription<StepHandler> initStepHandler;
0147
0148   /**
0149    *  Private and non-existent assignment operator.
0150    */
0151   StepHandler & operator=(const StepHandler &) = delete;
0152
0153 };
0154
0155 /** @cond TRAITSPECIALIZATIONS */
0156
0157 /**
0158  * This template specialization informs ThePEG about the base class of
0159  * StepHandler.
0160  */
0161 template <>
0162 struct BaseClassTrait<StepHandler,1>: public ClassTraitsType {
0163   /** Typedef of the base class of StepHandler. */
0164   typedef HandlerBase NthBase;
0165 };
0166
0167 /**
0168  * This template specialization informs ThePEG about the name of the
0169  * StepHandler class.
0170  */
0171 template <>
0172 struct ClassTraits<StepHandler>: public ClassTraitsBase<StepHandler> {
0173   /** Return the class name.  */
0174   static string className() { return "ThePEG::StepHandler"; }
0175 };
0176
0177 /** @endcond */
0178
0179 }
0180
0181 #endif /* ThePEG_StepHandler_H */