include/GaudiUtils/QuasiRandom.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2019 CERN for the benefit of the LHCb and ATLAS collaborations *
0003 *                                                                                   *
0004 * This software is distributed under the terms of the Apache version 2 licence,     *
0005 * copied verbatim in the file "LICENSE".                                            *
0006 *                                                                                   *
0007 * In applying this licence, CERN does not waive the privileges and immunities       *
0008 * granted to it by virtue of its status as an Intergovernmental Organization        *
0009 * or submit itself to any jurisdiction.                                             *
0010 \***********************************************************************************/
0011 #ifndef GAUDIUTILS_QUASIRANDOM_H
0012 #define GAUDIUTILS_QUASIRANDOM_H 1
0013
0014 // Include files
0015 #include <string>
0016
0017 // boost
0018 #include <boost/integer/integer_mask.hpp>
0019
0020 /// Create a hash with a large avalanche effect from 32 or 64 bit integers or a string.
0021 ///
0022 /// note: the constants below are _not_ arbitrary, but are picked
0023 ///       carefully such that the bit shuffling has a large 'avalanche' effect...
0024 ///       Code by Brett Mulvey (old link: http://bretm.home.comcast.net/~bretm/hash/)
0025 ///
0026 /// note: as a result, you might call this a quasi-random (not to be confused
0027 ///       with psuedo-random!) number generator, in that it generates an output
0028 ///       which satisfies a requirement on the uniformity of its output distribution.
0029 ///       (and not on the predictability of the next number in the sequence,
0030 ///       based on knowledge of the preceding numbers)
0031 ///
0032 /// note: another way to look at this is is as an (approximation of an) evaporating
0033 ///       black hole: whatever you dump in to it, you get something uniformly
0034 ///       distributed back ;-)
0035 ///
0036 namespace Gaudi {
0037   namespace Utils {
0038     namespace QuasiRandom {
0039
0040       /// Create a hash with a large avalanche effect from a 32 bit integer
0041       uint32_t mix( uint32_t state );
0042
0043       /// mix some 'extra' entropy into 'state' and return result
0044       uint32_t mix32( uint32_t state, uint32_t extra );
0045
0046       /// mix some 'extra' entropy into 'state' and return result
0047       uint32_t mix64( uint32_t state, uint64_t extra );
0048
0049       /// mix some 'extra' entropy into 'state' and return result
0050       uint32_t mixString( uint32_t state, const std::string& extra );
0051     } // namespace QuasiRandom
0052   }   // namespace Utils
0053 } // namespace Gaudi
0054 #endif // GAUDIUTILS_QUASIRANDOM_H