ECCE @ EIC Software
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
RandomEngine.h
Go to the documentation of this file. Or view the newest version in sPHENIX GitHub for file RandomEngine.h
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 
54 
55 public:
56 
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