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