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
51 /**
52 * @author <Gabriele.Cosmo@cern.ch>
53 * @ingroup random
54 */
55 class HepRandomEngine {
56
57 public:
58
59 HepRandomEngine();
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
getSeed()114 long getSeed() const { return theSeed; }
115 // Gets the current seed.
116
getSeeds()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>
possibleKeywordInput(IS & is,const std::string & key,T & 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
187