Geant4  9.6.p02
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
RandomEngine.h
Go to the documentation of this file.
1 // $Id:$
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 
48 namespace CLHEP {
49 
55 
56 public:
57 
59  virtual ~HepRandomEngine();
60  // Constructor and destructor
61 
62  inline bool operator==(const HepRandomEngine& engine);
63  inline bool operator!=(const HepRandomEngine& engine);
64  // Overloaded operators, ==, !=
65 
66  virtual double flat() = 0;
67  // Should return a pseudo random number between 0 and 1
68  // (excluding the end points)
69 
70  virtual void flatArray(const int size, double* vect) = 0;
71  // Fills an array "vect" of specified size with flat random values.
72 
73  virtual void setSeed(long seed, int) = 0;
74  // Should initialise the status of the algorithm according to seed.
75 
76  virtual void setSeeds(const long * seeds, int) = 0;
77  // Should initialise the status of the algorithm according to the zero terminated
78  // array of seeds. It is allowed to ignore one or many seeds in this array.
79 
80  virtual void saveStatus( const char filename[] = "Config.conf") const = 0;
81  // Should save on a file specific to the instantiated engine in use
82  // the current status.
83 
84  virtual void restoreStatus( const char filename[] = "Config.conf" ) = 0;
85  // Should read from a file (specific to the instantiated engine in use)
86  // and restore the last saved engine configuration.
87 
88  virtual void showStatus() const = 0;
89  // Should dump the current engine status on the screen.
90 
91  virtual std::string name() const = 0;
92  // Engine name.
93 
94  virtual std::ostream & put (std::ostream & os) const;
95  virtual std::istream & get (std::istream & is);
96  // Save and restore to/from streams
97 
98  static std::string beginTag ( );
99  virtual std::istream & getState ( std::istream & is );
100  // Helpers for EngineFactory which restores anonymous engine from istream
101 
102  static HepRandomEngine* newEngine(std::istream & is);
103  // Instantiates on the heap a new engine of type specified by content of is
104 
105  static HepRandomEngine* newEngine(const std::vector<unsigned long> & v);
106  // Instantiates on the heap a new engine of type specified by content of v
107 
108  virtual std::vector<unsigned long> put () const;
109  virtual bool get (const std::vector<unsigned long> & v);
110  virtual bool getState (const std::vector<unsigned long> & v);
111  // Save and restore to/from vectors
112 
113  long getSeed() const { return theSeed; }
114  // Gets the current seed.
115 
116  const long* getSeeds() const { return theSeeds; }
117  // Gets the current array of seeds.
118 
119  virtual operator double(); // Returns same as flat()
120  virtual operator float(); // less precise flat, faster if possible
121  virtual operator unsigned int(); // 32-bit int flat, faster if possible
122 
123  // The above three conversion operators permit one to retrieve a pseudo-
124  // random number as either a double-precision float, a single-precision
125  // float, or a 32-bit unsigned integer. The usage, presuming an object
126  // of the respective engine class "e", is as follows:
127 
128  // Recommended:
129  // float x;
130  // x = float( e );
131 
132  // Reasonable:
133  // x = e;
134 
135  // Works, but bad practice:
136  // x = 1.5 + e;
137 
138  // Won't compile:
139  // x = e + 1.5;
140 
141 protected:
142 
143  long theSeed;
144  const long* theSeeds;
145 
146  static inline double exponent_bit_32();
147  static inline double mantissa_bit_12();
148  static inline double mantissa_bit_24();
149  static inline double mantissa_bit_32();
150  static inline double twoToMinus_32();
151  static inline double twoToMinus_48();
152  static inline double twoToMinus_49();
153  static inline double twoToMinus_53();
154  static inline double nearlyTwoToMinus_54();
155 
156  static bool checkFile (std::istream & file,
157  const std::string & filename,
158  const std::string & classname,
159  const std::string & methodname);
160 
161 };
162 
163 std::ostream & operator<< (std::ostream & os, const HepRandomEngine & e);
164 std::istream & operator>> (std::istream & is, HepRandomEngine & e);
165 
166 template <class IS, class T>
167 bool possibleKeywordInput (IS & is, const std::string & key, T & t) {
168  std::string firstWord;
169  is >> firstWord;
170  if (firstWord == key) return true;
171  std::istringstream reread(firstWord);
172  reread >> t;
173  return false;
174 }
175 
176 } // namespace CLHEP
177 
178 #include "CLHEP/Random/RandomEngine.icc"
179 
180 #endif