CLHEP/Random/RanshiEngine.h

0001 // $Id: RanshiEngine.h,v 1.5 2010/06/16 17:24:53 garren Exp $
0002 // -*- C++ -*-
0003 //
0004 // -----------------------------------------------------------------------
0005 //                           HEP Random
0006 //                      --- RanshiEngine ---
0007 //                       class header file
0008 // -----------------------------------------------------------------------
0009 //
0010 //
0011 // The algorithm for this random engine was taken from "F.Gutbrod, Comp.
0012 // Phys. Comm. 87 (1995) 291-306".
0013 //
0014 // The algorithm can be imagined as a physical system as follows: Imagine
0015 // 512 "black balls" each with their own unique spin, and positions char-
0016 // acterized by disrete angles, where the spin is a 32-bit unsigned integer.
0017 // A "red ball" collides based upon the angle determined by the last 8 bits
0018 // of its spin, and the spin of the colliding ball is taken as the output
0019 // random number. The spin of the colliding ball is replaced then with the
0020 // left circular shift of the black ball's spin XOR'd with the red ball's
0021 // spin. The black ball's old spin becomes the red ball's.
0022 //
0023 // To avoid the traps presented, two measures are taken: first, the red
0024 // ball will oscillate between hitting the lower half of the buffer on one
0025 // turn and the upper half on another; second, the red ball's spin is
0026 // incremented by a counter of the number of random numbers produced.
0027 //
0028 // The result is scaled to a double precision floating point number to which
0029 // is added another random double further scaled 2^(53-32) places to the
0030 // right in order to ensure that the remaining bits of the result are not
0031 // left empty due to the mere 32 bits representation used internally.
0032
0033 // =======================================================================
0034 // Ken Smith      - Created: 9th June 1998
0035 //                - Removed pow() from flat method: 21st Jul 1998
0036 //                - Added conversion operators:  6th Aug 1998
0037 // Mark Fischler    Methods put, get for instance save/restore 12/8/04
0038 // Mark Fischler    methods for anonymous save/restore 12/27/04
0039 // =======================================================================
0040
0041 #ifndef HepRanshiEngine_h
0042 #define HepRanshiEngine_h
0043
0044 #include "CLHEP/Random/defs.h"
0045 #include "CLHEP/Random/RandomEngine.h"
0046
0047 namespace CLHEP {
0048
0049 /**
0050  * @author
0051  * @ingroup random
0052  */
0053 class RanshiEngine: public HepRandomEngine {
0054
0055 public:
0056
0057     RanshiEngine();
0058     RanshiEngine(std::istream &is);
0059     RanshiEngine(long seed);
0060     RanshiEngine(int rowIndex, int colIndex);
0061     virtual ~RanshiEngine();
0062     // Constructors and destructor
0063
0064     double flat();
0065     // Returns a pseudo random number between 0 and 1
0066
0067     void flatArray(const int size, double* vect);
0068     // Fills the array "vect" of specified size with flat random values
0069
0070     void setSeed(long seed, int);
0071     // Sets the state of the algorithm according to seed.
0072
0073     void setSeeds(const long* seeds, int);
0074     // Sets the state of the algorithm according to the zero-terminated
0075     // array of seeds.
0076
0077     void saveStatus(const char filename[] = "RanshiEngine.conf") const;
0078     // Saves on named file the current engine status
0079
0080     void restoreStatus(const char filename[] = "RanshiEngine.conf");
0081     // Reads from named file the last saved engine status
0082     // and restores it.
0083
0084     void showStatus() const;
0085     // Dumps the engine status on the screen
0086
0087     operator double();       // Returns same as flat()
0088     operator float();        // flat value, without worrying about filling bits
0089     operator unsigned int(); // 32-bit flat value, quickest of all
0090
0091     virtual std::ostream & put (std::ostream & os) const;
0092     virtual std::istream & get (std::istream & is);
0093     static  std::string beginTag ( );
0094     virtual std::istream & getState ( std::istream & is );
0095
0096     std::string name() const;
0097     static std::string engineName() {return "RanshiEngine";}
0098
0099     std::vector<unsigned long> put () const;
0100     bool get (const std::vector<unsigned long> & v);
0101     bool getState (const std::vector<unsigned long> & v);
0102
0103 private:
0104     enum {numBuff = 512};
0105
0106     unsigned int halfBuff, numFlats;
0107     unsigned int buffer[numBuff];
0108     unsigned int redSpin;
0109
0110     static const unsigned int VECTOR_STATE_SIZE = numBuff + 4;
0111
0112 }; // RanshiEngine
0113
0114 }  // namespace CLHEP
0115
0116 #ifdef ENABLE_BACKWARDS_COMPATIBILITY
0117 //  backwards compatibility will be enabled ONLY in CLHEP 1.9
0118 using namespace CLHEP;
0119 #endif
0120
0121 #endif // HepRanshiEngine_h