CLHEP/Random/RandGeneral.h

// $Id: RandGeneral.h,v 1.5 2000/09/07 13:18:36 mf Exp $
// -*- C++ -*-
//
// -----------------------------------------------------------------------
//                             HEP Random
//                          --- RandGeneral ---
//                          class header file
// -----------------------------------------------------------------------

// Class defining methods for shooting generally distributed random values,
// given a user-defined probability distribution function.

// =======================================================================
// S.Magni & G.Pieri  - Created: 29 April 1998 
// G.Cosmo            - Added constructor using default engine from the
//                     	static generator: 20 Aug 1998
// S.Magni & G.Pieri  - Added linear interpolation: 24 March 1999
// M. Fischler	      - Added private methods that simplify the implementaion
// 			prepareTables(), useFlatDistribution(), mapRandom()
//		      - Added private variable oneOverNbins.
//	     	      - Made the warning about shoot() not being static a tad
//			more prominent.   		14 May 1999	
// =======================================================================

#ifndef RandGeneral_h
#define RandGeneral_h 1

#include "CLHEP/Random/Random.h"

class RandGeneral : public HepRandom {

public:

  RandGeneral ( const HepDouble* aProbFunc, 
		HepInt theProbSize, 
		HepInt IntType=0 );
  RandGeneral ( HepRandomEngine& anEngine,
                const HepDouble* aProbFunc, 
		HepInt theProbSize, 
		HepInt IntType=0 );
  RandGeneral ( HepRandomEngine* anEngine, 
                const HepDouble* aProbFunc, 
		HepInt theProbSize, 
		HepInt IntType=0 );
  // These constructors should be used to instantiate a RandGeneral
  // distribution object defining a local engine for it.
  // The static generator will be skiped by using the non-static methods
  // defined below. In case no engine is specified in the constructor, the
  // default engine used by the static generator is applied.
  // If the engine is passed by pointer the corresponding engine object
  // will be deleted by the RandGeneral destructor.
  // If the engine is passed by reference the corresponding engine object
  // will not be deleted by the RandGeneral destructor.
  // The probability distribution function (Pdf) must be provided by the user
  // as an array of positive real number. The array size must also be
  // provided. The Pdf doesn't need to be normalized to 1. 
  // if IntType = 0 ( default value ) a uniform random number is
  // generated using the engine. The uniform number is then transformed
  // to the user's distribution using the cumulative probability
  // distribution constructed from his histogram. The cumulative
  // distribution is inverted using a binary search for the nearest
  // bin boundary and a linear interpolation within the
  // bin. RandGeneral therefore generates a constant density within
  // each bin.
  // if IntType = 1 no interpolation is performed and the result is a
  // discrete distribution.

  virtual ~RandGeneral();
  // Destructor

  // Methods to shoot random values using the static generator
  // N.B.: The methods are NOT static since they use nonstatic members
  // theIntegralPdf & nBins

	/////////////////////
	//		   //
	// BIG RED WARNING //
	//		   //
	/////////////////////
	//
	// The above N.B. is telling users that the shoot() methods in this
	// class are NOT STATIC.  You cannot do 
	//	double x = RandGeneral::shoot();
	// It would not make sense to provide a static shoot -- what would 
	// the default probability function look like?

  inline HepDouble shoot();

  inline void shootArray ( const HepInt size, HepDouble* vect);

  //  Methods to shoot random values using a given engine
  //  by-passing the static generator.

  HepDouble shoot( HepRandomEngine* anEngine );

  void shootArray ( HepRandomEngine* anEngine, const HepInt size,
                    HepDouble* vect );
			    
  //  Methods using the localEngine to shoot random values, by-passing
  //  the static generator.

  HepDouble fire();

  void fireArray ( const HepInt size, HepDouble* vect);

  HepDouble operator()();

private:

  // Private copy constructor. Declaring it here disallows use.
  RandGeneral(const RandGeneral&);

  HepRandomEngine* localEngine;
  HepBoolean deleteEngine;
  HepDouble* theIntegralPdf;
  HepInt nBins;
  HepDouble oneOverNbins;
  HepInt InterpolationType;

  // Private methods to factor out replicated implementation sections
  void prepareTable(const HepDouble* aProbFunc);
  void useFlatDistribution();
  HepDouble mapRandom(HepDouble rand) const;

};

#include "CLHEP/Random/RandGeneral.icc"

#endif