CLHEP/Random/RandGeneral.h

0001 // $Id: RandGeneral.h,v 1.5 2010/06/16 17:24:53 garren Exp $
0002 // -*- C++ -*-
0003 //
0004 // -----------------------------------------------------------------------
0005 //                             HEP Random
0006 //                          --- RandGeneral ---
0007 //                          class header file
0008 // -----------------------------------------------------------------------
0009
0010 // Class defining methods for shooting generally distributed random values,
0011 // given a user-defined probability distribution function.
0012
0013 // =======================================================================
0014 // S.Magni & G.Pieri  - Created: 29 April 1998
0015 // G.Cosmo            - Added constructor using default engine from the
0016 //                      static generator: 20 Aug 1998
0017 // S.Magni & G.Pieri  - Added linear interpolation: 24 March 1999
0018 // M. Fischler        - Added private methods that simplify the implementaion
0019 //          prepareTables(), useFlatDistribution(), mapRandom()
0020 //            - Added private variable oneOverNbins.
0021 //                - Made the warning about shoot() not being static a tad
0022 //          more prominent.         14 May 1999
0023 // M Fischler         - put and get to/from streams 12/15/04
0024 // =======================================================================
0025
0026 #ifndef RandGeneral_h
0027 #define RandGeneral_h 1
0028
0029 #include "CLHEP/Random/defs.h"
0030 #include "CLHEP/Random/Random.h"
0031 #include "CLHEP/Utility/memory.h"
0032 #include <vector>
0033
0034 namespace CLHEP {
0035
0036 /**
0037  * @author
0038  * @ingroup random
0039  */
0040 class RandGeneral : public HepRandom {
0041
0042 public:
0043
0044   RandGeneral ( const double* aProbFunc,
0045         int theProbSize,
0046         int IntType=0 );
0047   RandGeneral ( HepRandomEngine& anEngine,
0048                 const double* aProbFunc,
0049         int theProbSize,
0050         int IntType=0 );
0051   RandGeneral ( HepRandomEngine* anEngine,
0052                 const double* aProbFunc,
0053         int theProbSize,
0054         int IntType=0 );
0055   // These constructors should be used to instantiate a RandGeneral
0056   // distribution object defining a local engine for it.
0057   // The static generator will be skipped by using the non-static methods
0058   // defined below. In case no engine is specified in the constructor, the
0059   // default engine used by the static generator is applied.
0060   // If the engine is passed by pointer the corresponding engine object
0061   // will be deleted by the RandGeneral destructor.
0062   // If the engine is passed by reference the corresponding engine object
0063   // will not be deleted by the RandGeneral destructor.
0064   // The probability distribution function (Pdf) must be provided by the user
0065   // as an array of positive real number. The array size must also be
0066   // provided. The Pdf doesn't need to be normalized to 1.
0067   // if IntType = 0 ( default value ) a uniform random number is
0068   // generated using the engine. The uniform number is then transformed
0069   // to the user's distribution using the cumulative probability
0070   // distribution constructed from his histogram. The cumulative
0071   // distribution is inverted using a binary search for the nearest
0072   // bin boundary and a linear interpolation within the
0073   // bin. RandGeneral therefore generates a constant density within
0074   // each bin.
0075   // if IntType = 1 no interpolation is performed and the result is a
0076   // discrete distribution.
0077
0078   virtual ~RandGeneral();
0079   // Destructor
0080
0081   // Methods to shoot random values using the static generator
0082   // N.B.: The methods are NOT static since they use nonstatic members
0083   // theIntegralPdf & nBins
0084
0085     /////////////////////
0086     //         //
0087     // BIG RED WARNING //
0088     //         //
0089     /////////////////////
0090     //
0091     // The above N.B. is telling users that the shoot() methods in this
0092     // class are NOT STATIC.  You cannot do
0093     //  double x = RandGeneral::shoot();
0094     // It would not make sense to provide a static shoot -- what would
0095     // the default probability function look like?
0096
0097   inline double shoot();
0098
0099   inline void shootArray ( const int size, double* vect);
0100
0101   //  Methods to shoot random values using a given engine
0102   //  by-passing the static generator.
0103
0104   double shoot( HepRandomEngine* anEngine );
0105
0106   void shootArray ( HepRandomEngine* anEngine, const int size,
0107                     double* vect );
0108
0109   //  Methods using the localEngine to shoot random values, by-passing
0110   //  the static generator.
0111
0112   double fire();
0113
0114   void fireArray ( const int size, double* vect);
0115
0116   double operator()();
0117
0118   // Save and restore to/from streams
0119
0120   std::ostream & put ( std::ostream & os ) const;
0121   std::istream & get ( std::istream & is );
0122
0123   std::string name() const;
0124   HepRandomEngine & engine();
0125
0126   static std::string distributionName() {return "RandGeneral";}
0127   // Provides the name of this distribution class
0128
0129
0130 private:
0131
0132   std::shared_ptr<HepRandomEngine> localEngine;
0133   std::vector<double> theIntegralPdf;
0134   int nBins;
0135   double oneOverNbins;
0136   int InterpolationType;
0137
0138   // Private methods to factor out replicated implementation sections
0139   void prepareTable(const double* aProbFunc);
0140   void useFlatDistribution();
0141   double mapRandom(double rand) const;
0142
0143 };
0144
0145 }  // namespace CLHEP
0146
0147 #ifdef ENABLE_BACKWARDS_COMPATIBILITY
0148 //  backwards compatibility will be enabled ONLY in CLHEP 1.9
0149 using namespace CLHEP;
0150 #endif
0151
0152 #include "CLHEP/Random/RandGeneral.icc"
0153
0154 #endif