CLHEP/Random/RandGeneral.h

00001 // $Id: RandGeneral.h,v 1.9 2002/04/12 15:02:45 evc Exp $
00002 // -*- C++ -*-
00003 //
00004 // -----------------------------------------------------------------------
00005 //                             HEP Random
00006 //                          --- RandGeneral ---
00007 //                          class header file
00008 // -----------------------------------------------------------------------
00009 
00010 // Class defining methods for shooting generally distributed random values,
00011 // given a user-defined probability distribution function.
00012 
00013 // =======================================================================
00014 // S.Magni & G.Pieri  - Created: 29 April 1998 
00015 // G.Cosmo            - Added constructor using default engine from the
00016 //                      static generator: 20 Aug 1998
00017 // S.Magni & G.Pieri  - Added linear interpolation: 24 March 1999
00018 // M. Fischler        - Added private methods that simplify the implementaion
00019 //                      prepareTables(), useFlatDistribution(), mapRandom()
00020 //                    - Added private variable oneOverNbins.
00021 //                    - Made the warning about shoot() not being static a tad
00022 //                      more prominent.                 14 May 1999     
00023 // =======================================================================
00024 
00025 #ifndef RandGeneral_h
00026 #define RandGeneral_h 1
00027 
00028 #include "CLHEP/Random/Random.h"
00029 
00034 class RandGeneral : public HepRandom {
00035 
00036 public:
00037 
00038   RandGeneral ( const double* aProbFunc, 
00039                 int theProbSize, 
00040                 int IntType=0 );
00041   RandGeneral ( HepRandomEngine& anEngine,
00042                 const double* aProbFunc, 
00043                 int theProbSize, 
00044                 int IntType=0 );
00045   RandGeneral ( HepRandomEngine* anEngine, 
00046                 const double* aProbFunc, 
00047                 int theProbSize, 
00048                 int IntType=0 );
00049   // These constructors should be used to instantiate a RandGeneral
00050   // distribution object defining a local engine for it.
00051   // The static generator will be skiped by using the non-static methods
00052   // defined below. In case no engine is specified in the constructor, the
00053   // default engine used by the static generator is applied.
00054   // If the engine is passed by pointer the corresponding engine object
00055   // will be deleted by the RandGeneral destructor.
00056   // If the engine is passed by reference the corresponding engine object
00057   // will not be deleted by the RandGeneral destructor.
00058   // The probability distribution function (Pdf) must be provided by the user
00059   // as an array of positive real number. The array size must also be
00060   // provided. The Pdf doesn't need to be normalized to 1. 
00061   // if IntType = 0 ( default value ) a uniform random number is
00062   // generated using the engine. The uniform number is then transformed
00063   // to the user's distribution using the cumulative probability
00064   // distribution constructed from his histogram. The cumulative
00065   // distribution is inverted using a binary search for the nearest
00066   // bin boundary and a linear interpolation within the
00067   // bin. RandGeneral therefore generates a constant density within
00068   // each bin.
00069   // if IntType = 1 no interpolation is performed and the result is a
00070   // discrete distribution.
00071 
00072   virtual ~RandGeneral();
00073   // Destructor
00074 
00075   // Methods to shoot random values using the static generator
00076   // N.B.: The methods are NOT static since they use nonstatic members
00077   // theIntegralPdf & nBins
00078 
00080         //                 //
00081         // BIG RED WARNING //
00082         //                 //
00084         //
00085         // The above N.B. is telling users that the shoot() methods in this
00086         // class are NOT STATIC.  You cannot do 
00087         //      double x = RandGeneral::shoot();
00088         // It would not make sense to provide a static shoot -- what would 
00089         // the default probability function look like?
00090 
00091   inline double shoot();
00092 
00093   inline void shootArray ( const int size, double* vect);
00094 
00095   //  Methods to shoot random values using a given engine
00096   //  by-passing the static generator.
00097 
00098   double shoot( HepRandomEngine* anEngine );
00099 
00100   void shootArray ( HepRandomEngine* anEngine, const int size,
00101                     double* vect );
00102                             
00103   //  Methods using the localEngine to shoot random values, by-passing
00104   //  the static generator.
00105 
00106   double fire();
00107 
00108   void fireArray ( const int size, double* vect);
00109 
00110   double operator()();
00111 
00112 private:
00113 
00114   // Private copy constructor. Declaring it here disallows use.
00115   RandGeneral(const RandGeneral&);
00116 
00117   HepRandomEngine* localEngine;
00118   bool deleteEngine;
00119   double* theIntegralPdf;
00120   int nBins;
00121   double oneOverNbins;
00122   int InterpolationType;
00123 
00124   // Private methods to factor out replicated implementation sections
00125   void prepareTable(const double* aProbFunc);
00126   void useFlatDistribution();
00127   double mapRandom(double rand) const;
00128 
00129 };
00130 
00131 #include "CLHEP/Random/RandGeneral.icc"
00132 
00133 #endif

Class Library for High Energy Physics (version 1.8)