ThePEG/Handlers/AnalysisHandler.h

0001 // -*- C++ -*-
0002 //
0003 // AnalysisHandler.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_AnalysisHandler_H
0010 #define ThePEG_AnalysisHandler_H
0011 // This is the declaration of the AnalysisHandler class.
0012
0013 #include "HandlerBase.h"
0014 #include "AnalysisHandler.fh"
0015 #include "ThePEG/Vectors/LorentzRotation.h"
0016 #include "ThePEG/Analysis/FactoryBase.h"
0017 #include "ThePEG/EventRecord/Event.h"
0018 #include <stdexcept>
0019
0020 namespace ThePEG {
0021
0022 /**
0023  * The AnalysisHandler is the base class of all analysis objects which
0024  * may be handled by the FullEventGenerator. The main function is the
0025  * virtual <code>analyze()</code> method which which is called for
0026  * each analysis handler after each event. The method may be called
0027  * several times for each event - this may be checked by the analysis
0028  * handler by looking at the <code>ieve</code>, <code>loop</code> and
0029  * <code>state</code> arguments to the <code>analyze</code> method.
0030  *
0031  * Initialization of histograms etc. should be made in the
0032  * <code>doinitrun()</code> function, while writing out of histograms
0033  * and analysis results should be performed in the
0034  * <code>dofinish()</code> function.
0035  *
0036  * @see \ref AnalysisHandlerInterfaces "The interfaces"
0037  * defined for AnalysisHandler.
0038  * @see FullEventGenerator
0039  * @see Event
0040  */
0041 class AnalysisHandler: public HandlerBase {
0042
0043 public:
0044
0045   /**
0046    * Convenient typedef for pointer to AIDA::IHistogram1D.
0047    */
0048   typedef FactoryBase::tH1DPtr tH1DPtr;
0049
0050   /**
0051    * Convenient typedef for pointer to AIDA::IHistogram1D.
0052    */
0053   typedef FactoryBase::tcH1DPtr tcH1DPtr;
0054
0055   /**
0056    * Convenient typedef for pointer to AIDA::IHistogram1D.
0057    */
0058   typedef FactoryBase::tH2DPtr tH2DPtr;
0059
0060   /**
0061    * Convenient typedef for pointer to AIDA::IHistogram1D.
0062    */
0063   typedef FactoryBase::tcH2DPtr tcH2DPtr;
0064
0065 public:
0066
0067   /** @name Virtual functions required by the AnalysisHandler class. */
0068   //@{
0069   /**
0070    * Analyze a given Event. Note that a fully generated event may be
0071    * presented several times, if it has been manipulated in
0072    * between. The default version of this function will extract all
0073    * final state particles, temporarily boost them according to the
0074    * transform(tEventPtr) function and call analyze(tPVector) of this
0075    * analysis object and those of all associated analysis objects. The
0076    * default version will not, however, do anything on events which
0077    * have not been fully generated, or have been manipulated in any
0078    * way.
0079    * @param event pointer to the Event to be analyzed.
0080    * @param ieve  the event number.
0081    * @param loop  the number of times this event has been presented.
0082    *              If negative the event is now fully generated.
0083    * @param state a number different from zero if the
0084    *              event has been manipulated in some way since it was last
0085    *              presented.
0086    */
0087   virtual void analyze(tEventPtr event, long ieve, int loop, int state);
0088
0089   /**
0090    * Transform the event to the desired Lorentz frame and return the
0091    * corresponding LorentzRotation.
0092    * @param event a pointer to the Event to be transformed.
0093    * @return the LorentzRotation used in the transformation.
0094    * @deprecated Use transform(tcEventPtr) instead. This method is no
0095    *    longer used automatically.
0096    */
0097   virtual LorentzRotation transform(tEventPtr event) const;
0098
0099   /**
0100    * Return a LorentzTransform which would put the event in the
0101    * desired Lorentz frame.
0102    * @param event a pointer to the Event to be considered.
0103    * @return the LorentzRotation used in the transformation.
0104    */
0105   virtual LorentzRotation transform(tcEventPtr event) const;
0106
0107   /**
0108    * Analyze the given vector of particles. The default version calls
0109    * analyze(tPPtr) for each of the particles.
0110    * @param particles the vector of pointers to particles to be analyzed
0111    * @deprecated Use analyze(const tPVector &, double) instead.
0112    */
0113   virtual void analyze(const tPVector & particles);
0114
0115   /**
0116    * Analyze the given vector of particles. The default version calls
0117    * analyze(tPPtr) for each of the particles.
0118    * @param particles the vector of pointers to particles to be analyzed
0119    * @param weight the weight of the current event.
0120    */
0121   virtual void analyze(const tPVector & particles, double weight);
0122
0123   /**
0124    * Analyze the given particle.
0125    * @param particle pointer to the particle to be analyzed.
0126    * @deprecated us analyze(tPPtr, double) instead.
0127    */
0128   virtual void analyze(tPPtr particle);
0129
0130   /**
0131    * Analyze the given particle.
0132    * @param particle pointer to the particle to be analyzed.
0133    * @param weight the weight of the current event.
0134    */
0135   virtual void analyze(tPPtr particle, double weight);
0136
0137   //@}
0138
0139   /** @name Functions to access histograms. */
0140   //@{
0141   /**
0142    * Check if the associated EventGenerator has been assigned a
0143    * histogram factory. If \a warn is true also emit a warning saying
0144    * that no histograms will be generated.
0145    */
0146   bool checkHistogramFactory(bool warn = false) const;
0147
0148   /**
0149    * Access the HistogramFactory from the EventGenerator.
0150    */
0151   FactoryBase & histogramFactory();
0152
0153   /**
0154    * Access the HistogramFactory from the EventGenerator.
0155    */
0156   const FactoryBase & histogramFactory() const;
0157
0158   /**
0159    * Access the underlying AIDA::IHistogramFactory in the
0160    * HistogramFactory from the EventGenerator.
0161    */
0162   AIDA::IHistogramFactory & iHistogramFactory() const {
0163     return histogramFactory().histogramFactory();
0164   }
0165
0166   /**
0167    * Normalize the histogran \a h using the collected statistics from
0168    * the EventGenerator. If the histogram has been filled with the
0169    * Event::weight() as weight a plotted function will correspond to a
0170    * proper cross section distribution in units of \a unit. This only
0171    * works for evenly binned histograms. If not evenly binned, nothing
0172    * will be done.
0173    */
0174   void normalize(tH1DPtr h, CrossSection unit = picobarn) const;
0175
0176   /**
0177    * Normalize the histogran \a h to unit integral.
0178    */
0179   void unitNormalize(tH1DPtr h) const;
0180   //@}
0181
0182 public:
0183
0184   /** @name Functions used by the persistent I/O system. */
0185   //@{
0186   /**
0187    * Function used to write out object persistently.
0188    * @param os the persistent output stream written to.
0189    */
0190   void persistentOutput(PersistentOStream & os) const;
0191
0192   /**
0193    * Function used to read in object persistently.
0194    * @param is the persistent input stream read from.
0195    * @param version the version number of the object when written.
0196    */
0197   void persistentInput(PersistentIStream & is, int version);
0198
0199   //@}
0200
0201   /**
0202    * Standard Init function used to initialize the interface.
0203    */
0204   static void Init();
0205
0206 protected:
0207
0208   /** @name Clone Methods. */
0209   //@{
0210   /**
0211    * Make a simple clone of this object.
0212    * @return a pointer to the new object.
0213    */
0214   virtual IBPtr clone() const;
0215
0216   /** Make a clone of this object, possibly modifying the cloned object
0217    * to make it sane.
0218    * @return a pointer to the new object.
0219    */
0220   virtual IBPtr fullclone() const;
0221
0222   //@}
0223
0224 private:
0225
0226   /**
0227    * A list of slave analysis objects which are called for the same
0228    * extracted particles and in the same Lorentz frame as this one.
0229    */
0230   AnalysisVector theSlaves;
0231   //@}
0232
0233 public:
0234
0235   /** Exception class used if no histogram factory was found. */
0236   class NoHistFactory: public InitException {};
0237
0238 private:
0239
0240   /**
0241    * The static object used to initialize the description of this class.
0242    * Indicates that this is a concrete class with persistent data.
0243    */
0244   static ClassDescription<AnalysisHandler> initAnalysisHandler;
0245
0246 };
0247
0248 /** @cond TRAITSPECIALIZATIONS */
0249
0250 /** This template specialization informs ThePEG about the
0251  *  base classes of AnalysisHandler. */
0252 template <>
0253 struct BaseClassTrait<AnalysisHandler,1>: public ClassTraitsType {
0254   /** Typedef of the first base class of AnalysisHandler. */
0255   typedef HandlerBase NthBase;
0256 };
0257
0258 /** This template specialization informs ThePEG about the name of
0259  *  the AnalysisHandler class and the shared object where it is defined. */
0260 template <>
0261 struct ClassTraits<AnalysisHandler>: public ClassTraitsBase<AnalysisHandler> {
0262   /** Return a platform-independent class name */
0263   static string className() { return "ThePEG::AnalysisHandler"; }
0264 };
0265
0266 /** @endcond */
0267
0268 }
0269
0270 #endif /* ThePEG_AnalysisHandler_H */