CLHEP/Random/RandomEngine.h

00001 // $Id: RandomEngine.h,v 1.19 2002/04/12 15:02:45 evc Exp $
00002 // -*- C++ -*-
00003 //
00004 // -----------------------------------------------------------------------
00005 //                             HEP Random
00006 //                        --- HepRandomEngine ---
00007 //                          class header file
00008 // -----------------------------------------------------------------------
00009 // This file is part of Geant4 (simulation toolkit for HEP).
00010 //
00011 // Is the abstract class defining the interface for each random engine. It
00012 // implements the getSeed() and getSeeds() methods which return the initial
00013 // seed value and the initial array of seeds respectively. It defines 7
00014 // pure virtual functions: flat(), flatArray(), setSeed(), setSeeds(),
00015 // saveStatus(), restoreStatus() and showStatus(), which are implemented by
00016 // the concrete random engines each one inheriting from this abstract class.
00017 // Many concrete random engines can be defined and added to the structure,
00018 // simply making them inheriting from HepRandomEngine and defining the six
00019 // functions flat(), flatArray(), setSeed(), setSeeds(), saveStatus(),
00020 // restoreStatus() and showStatus() in such a way that flat() and
00021 // flatArray() return double random values ranging between ]0,1[.
00022 // All the random engines have a default seed value already set but they
00023 // can be instantiated with a different seed value set up by the user.
00024 
00025 // =======================================================================
00026 // Gabriele Cosmo - Created: 5th September 1995
00027 //                - Minor corrections: 31st October 1996
00028 //                - Added methods for engine status: 19th November 1996
00029 //                - Removed default values to setSeed() and
00030 //                  setSeeds() pure virtual methods: 16th Oct 1997
00031 //                - Moved seeds table to HepRandom: 19th Mar 1998
00032 // Ken Smith      - Added conversion operators:  6th Aug 1998
00033 // Mark Fischler  - Added static twoToMinus_xx constants: 11 Sept 1998
00034 // =======================================================================
00035 
00036 #ifndef HepRandomEngine_h
00037 #define HepRandomEngine_h 1
00038 
00039 #include "CLHEP/config/CLHEP.h"
00040 #include "CLHEP/config/iostream.h"
00041 #include "CLHEP/config/fstream.h"
00042 #include "CLHEP/config/iomanip.h"
00043 
00048 class HepRandomEngine {
00049 
00050 public:
00051 
00052   HepRandomEngine();
00053   virtual ~HepRandomEngine();
00054   // Constructor and destructor
00055 
00056   inline bool operator==(const HepRandomEngine& engine);
00057   inline bool operator!=(const HepRandomEngine& engine);
00058   // Overloaded operators, ==, !=
00059 
00060   virtual double flat() = 0;
00061   // Should return a pseudo random number between 0 and 1 
00062   // (excluding the end points)
00063 
00064   virtual void flatArray(const int size, double* vect) = 0;
00065   // Fills an array "vect" of specified size with flat random values.
00066 
00067   virtual void setSeed(long seed, int) = 0;
00068   // Should initialise the status of the algorithm according to seed.
00069 
00070   virtual void setSeeds(const long * seeds, int) = 0;
00071   // Should initialise the status of the algorithm according to the zero terminated
00072   // array of seeds. It is allowed to ignore one or many seeds in this array.
00073 
00074   virtual void saveStatus( const char filename[] = "Config.conf") const = 0;
00075   // Should save on a file specific to the instantiated engine in use
00076   // the current status.
00077 
00078   virtual void restoreStatus( const char filename[] = "Config.conf" ) = 0;
00079   // Should read from a file (specific to the instantiated engine in use)
00080   // and restore the last saved engine configuration.
00081 
00082   virtual void showStatus() const = 0;
00083   // Should dump the current engine status on the screen.
00084 
00085   long getSeed() const { return theSeed; }
00086   // Gets the current seed.
00087 
00088   const long* getSeeds() const { return theSeeds; }
00089   // Gets the current array of seeds.
00090 
00091   void getTableSeeds(long* seeds, int index) const;
00092   // Gets back seed values stored in the table, given the index.
00093 
00094   virtual operator double();        // Returns same as flat()
00095   virtual operator float();         // less precise flat, faster if possible
00096   virtual operator unsigned int();     // 32-bit int flat, faster if possible
00097 
00098   // The above three conversion operators permit one to retrieve a pseudo-
00099   // random number as either a double-precision float, a single-precision
00100   // float, or a 32-bit unsigned integer. The usage, presuming an object
00101   // of the respective engine class "e", is as follows:
00102 
00103   // Recommended:
00104   //    float x;
00105   //    x = float( e );
00106 
00107   // Reasonable:
00108   //    x = e;
00109 
00110   // Works, but bad practice:
00111   //    x = 1.5 + e;
00112 
00113   // Won't compile:
00114   //    x = e + 1.5;
00115 
00116 protected:
00117 
00118   long theSeed;
00119   const long* theSeeds;
00120 
00121   const double exponent_bit_32;
00122 
00123 };
00124 
00125 #include "CLHEP/Random/RandomEngine.icc"
00126 
00127 #endif

Class Library for High Energy Physics (version 1.8)