CLHEP VERSION Reference Documentation
   
CLHEP Home Page     CLHEP Documentation     CLHEP Bug Reports

Matrix/CLHEP/Random/RandomEngine.h
Go to the documentation of this file.
1 // $Id: RandomEngine.h,v 1.6 2010/10/25 18:18:47 garren Exp $
2 // -*- C++ -*-
3 //
4 // -----------------------------------------------------------------------
5 // HEP Random
6 // --- HepRandomEngine ---
7 // class header file
8 // -----------------------------------------------------------------------
9 // This file is part of Geant4 (simulation toolkit for HEP).
10 //
11 // Is the abstract class defining the interface for each random engine. It
12 // implements the getSeed() and getSeeds() methods which return the initial
13 // seed value and the initial array of seeds respectively. It defines 7
14 // pure virtual functions: flat(), flatArray(), setSeed(), setSeeds(),
15 // saveStatus(), restoreStatus() and showStatus(), which are implemented by
16 // the concrete random engines each one inheriting from this abstract class.
17 // Many concrete random engines can be defined and added to the structure,
18 // simply making them inheriting from HepRandomEngine and defining the six
19 // functions flat(), flatArray(), setSeed(), setSeeds(), saveStatus(),
20 // restoreStatus() and showStatus() in such a way that flat() and
21 // flatArray() return double random values ranging between ]0,1[.
22 // All the random engines have a default seed value already set but they
23 // can be instantiated with a different seed value set up by the user.
24 
25 // =======================================================================
26 // Gabriele Cosmo - Created: 5th September 1995
27 // - Minor corrections: 31st October 1996
28 // - Added methods for engine status: 19th November 1996
29 // - Removed default values to setSeed() and
30 // setSeeds() pure virtual methods: 16th Oct 1997
31 // - Moved seeds table to HepRandom: 19th Mar 1998
32 // Ken Smith - Added conversion operators: 6th Aug 1998
33 // Mark Fischler - Added static twoToMinus_xx constants: 11 Sept 1998
34 // Mark Fischler - Removed getTableSeeds, which was migrated to HepRandom
35 // in 1998. 10 Feb 2005.
36 // =======================================================================
37 
38 #ifndef HepRandomEngine_h
39 #define HepRandomEngine_h 1
40 
41 #include <iostream>
42 #include <fstream>
43 #include <iomanip>
44 #include <string>
45 #include <sstream>
46 #include <vector>
47 #include "CLHEP/Random/defs.h"
48 
49 namespace CLHEP {
50 
56 
57 public:
58 
60  virtual ~HepRandomEngine();
61  // Constructor and destructor
62 
63  inline bool operator==(const HepRandomEngine& engine);
64  inline bool operator!=(const HepRandomEngine& engine);
65  // Overloaded operators, ==, !=
66 
67  virtual double flat() = 0;
68  // Should return a pseudo random number between 0 and 1
69  // (excluding the end points)
70 
71  virtual void flatArray(const int size, double* vect) = 0;
72  // Fills an array "vect" of specified size with flat random values.
73 
74  virtual void setSeed(long seed, int) = 0;
75  // Should initialise the status of the algorithm according to seed.
76 
77  virtual void setSeeds(const long * seeds, int) = 0;
78  // Should initialise the status of the algorithm according to the zero terminated
79  // array of seeds. It is allowed to ignore one or many seeds in this array.
80 
81  virtual void saveStatus( const char filename[] = "Config.conf") const = 0;
82  // Should save on a file specific to the instantiated engine in use
83  // the current status.
84 
85  virtual void restoreStatus( const char filename[] = "Config.conf" ) = 0;
86  // Should read from a file (specific to the instantiated engine in use)
87  // and restore the last saved engine configuration.
88 
89  virtual void showStatus() const = 0;
90  // Should dump the current engine status on the screen.
91 
92  virtual std::string name() const = 0;
93  // Engine name.
94 
95  virtual std::ostream & put (std::ostream & os) const;
96  virtual std::istream & get (std::istream & is);
97  // Save and restore to/from streams
98 
99  static std::string beginTag ( );
100  virtual std::istream & getState ( std::istream & is );
101  // Helpers for EngineFactory which restores anonymous engine from istream
102 
103  static HepRandomEngine* newEngine(std::istream & is);
104  // Instantiates on the heap a new engine of type specified by content of is
105 
106  static HepRandomEngine* newEngine(const std::vector<unsigned long> & v);
107  // Instantiates on the heap a new engine of type specified by content of v
108 
109  virtual std::vector<unsigned long> put () const;
110  virtual bool get (const std::vector<unsigned long> & v);
111  virtual bool getState (const std::vector<unsigned long> & v);
112  // Save and restore to/from vectors
113 
114  long getSeed() const { return theSeed; }
115  // Gets the current seed.
116 
117  const long* getSeeds() const { return theSeeds; }
118  // Gets the current array of seeds.
119 
120  virtual operator double(); // Returns same as flat()
121  virtual operator float(); // less precise flat, faster if possible
122  virtual operator unsigned int(); // 32-bit int flat, faster if possible
123 
124  // The above three conversion operators permit one to retrieve a pseudo-
125  // random number as either a double-precision float, a single-precision
126  // float, or a 32-bit unsigned integer. The usage, presuming an object
127  // of the respective engine class "e", is as follows:
128 
129  // Recommended:
130  // float x;
131  // x = float( e );
132 
133  // Reasonable:
134  // x = e;
135 
136  // Works, but bad practice:
137  // x = 1.5 + e;
138 
139  // Won't compile:
140  // x = e + 1.5;
141 
142 protected:
143 
144  long theSeed;
145  const long* theSeeds;
146 
147  static inline double exponent_bit_32();
148  static inline double mantissa_bit_12();
149  static inline double mantissa_bit_24();
150  static inline double mantissa_bit_32();
151  static inline double twoToMinus_32();
152  static inline double twoToMinus_48();
153  static inline double twoToMinus_49();
154  static inline double twoToMinus_53();
155  static inline double nearlyTwoToMinus_54();
156 
157  static bool checkFile (std::istream & file,
158  const std::string & filename,
159  const std::string & classname,
160  const std::string & methodname);
161 
162 };
163 
164 std::ostream & operator<< (std::ostream & os, const HepRandomEngine & e);
165 std::istream & operator>> (std::istream & is, HepRandomEngine & e);
166 
167 template <class IS, class T>
168 bool possibleKeywordInput (IS & is, const std::string & key, T & t) {
169  std::string firstWord;
170  is >> firstWord;
171  if (firstWord == key) return true;
172  std::istringstream reread(firstWord);
173  reread >> t;
174  return false;
175 }
176 
177 } // namespace CLHEP
178 
179 #ifdef ENABLE_BACKWARDS_COMPATIBILITY
180 // backwards compatibility will be enabled ONLY in CLHEP 1.9
181 using namespace CLHEP;
182 #endif
183 
184 #include "CLHEP/Random/RandomEngine.icc"
185 
186 #endif
static double mantissa_bit_32()
virtual void setSeeds(const long *seeds, int)=0
static double twoToMinus_32()
virtual void restoreStatus(const char filename[]="Config.conf")=0
bool operator!=(const HepRandomEngine &engine)
static double twoToMinus_53()
static double nearlyTwoToMinus_54()
virtual double flat()=0
virtual void saveStatus(const char filename[]="Config.conf") const =0
virtual std::istream & getState(std::istream &is)
Definition: RandomEngine.cc:71
static double twoToMinus_49()
virtual std::string name() const =0
virtual void setSeed(long seed, int)=0
static double twoToMinus_48()
static double mantissa_bit_12()
bool operator==(const HepRandomEngine &engine)
static bool checkFile(std::istream &file, const std::string &filename, const std::string &classname, const std::string &methodname)
Definition: RandomEngine.cc:46
virtual void flatArray(const int size, double *vect)=0
virtual std::istream & get(std::istream &is)
Definition: RandomEngine.cc:62
static double mantissa_bit_24()
static HepRandomEngine * newEngine(std::istream &is)
Definition: RandomEngine.cc:90
static std::string beginTag()
Definition: RandomEngine.cc:67
static double exponent_bit_32()
virtual void showStatus() const =0
virtual std::vector< unsigned long > put() const
Definition: RandomEngine.cc:76
#define double(obj)
Definition: excDblThrow.cc:32
bool possibleKeywordInput(IS &is, const std::string &key, T &t)
std::ostream & operator<<(std::ostream &os, const HepAxisAngle &aa)
Definition: AxisAngle.cc:86
std::istream & operator>>(std::istream &is, HepAxisAngle &aa)
Definition: AxisAngle.cc:96