util/X86LINUX64/cuda-6.5/include/thrust/random/xor_combine_engine.h

   1 /*
   2  *  Copyright 2008-2013 NVIDIA Corporation
   3  *
   4  *  Licensed under the Apache License, Version 2.0 (the "License");
   5  *  you may not use this file except in compliance with the License.
   6  *  You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *  Unless required by applicable law or agreed to in writing, software
  11  *  distributed under the License is distributed on an "AS IS" BASIS,
  12  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *  See the License for the specific language governing permissions and
  14  *  limitations under the License.
  15  */
  16
  17 /*! \file xor_combine_engine.h
  18  *  \brief A pseudorandom number generator which produces pseudorandom
  19  *         numbers from two integer base engines by merging their
  20  *         pseudorandom numbers with bitwise exclusive-or.
  21  */
  22
  23 #pragma once
  24
  25 #include <thrust/detail/config.h>
  26 #include <thrust/detail/type_traits.h>
  27 #include <thrust/random/detail/xor_combine_engine_max.h>
  28 #include <thrust/random/detail/random_core_access.h>
  29 #include <iostream>
  30 #include <cstddef> // for size_t
  31
  32 namespace thrust
  33 {
  34
  35 namespace random
  36 {
  37
  38 /*! \addtogroup random_number_engine_adaptors
  39  *  \{
  40  */
  41
  42 /*! \class xor_combine_engine
  43  *  \brief An \p xor_combine_engine adapts two existing base random number engines and
  44  *         produces random values by combining the values produced by each.
  45  *
  46  *  \tparam Engine1 The type of the first base random number engine to adapt.
  47  *  \tparam s1 The size of the first shift to use in the generation algorithm.
  48  *  \tparam Engine2 The type of the second base random number engine to adapt.
  49  *  \tparam s2 The second of the second shift to use in the generation algorithm. Defaults to \c 0.
  50  *
  51  *  The following code snippet shows an example of using an \p xor_combine_engine instance:
  52  *
  53  *  \code
  54  *  #include <thrust/random/linear_congruential_engine.h>
  55  *  #include <thrust/random/xor_combine_engine.h>
  56  *  #include <iostream>
  57  *
  58  *  int main(void)
  59  *  {
  60  *    // create an xor_combine_engine from minstd_rand and minstd_rand0
  61  *    // use a shift of 0 for each
  62  *    thrust::xor_combine_engine<thrust::minstd_rand,0,thrust::minstd_rand0,0> rng;
  63  *
  64  *    // print a random number to standard output
  65  *    std::cout << rng() << std::endl;
  66  *
  67  *    return 0;
  68  *  }
  69  *  \endcode
  70  */
  71 template<typename Engine1, size_t s1,
  72          typename Engine2, size_t s2=0u>
  73   class xor_combine_engine
  74 {
  75   public:
  76     // types
  77
  78     /*! \typedef base1_type
  79      *  \brief The type of the first adapted base random number engine.
  80      */
  81     typedef Engine1 base1_type;
  82
  83     /*! \typedef base2_type
  84      *  \brief The type of the second adapted base random number engine.
  85      */
  86     typedef Engine2 base2_type;
  87
  88     /*! \typedef result_type
  89      *  \brief The type of the unsigned integer produced by this \p xor_combine_engine.
  90      */
  91     typedef typename thrust::detail::eval_if<
  92       (sizeof(typename base2_type::result_type) > sizeof(typename base1_type::result_type)),
  93       thrust::detail::identity_<typename base2_type::result_type>,
  94       thrust::detail::identity_<typename base1_type::result_type>
  95     >::type result_type;
  96
  97     /*! The size of the first shift used in the generation algorithm.
  98      */
  99     static const size_t shift1 = s1;
 100
 101     /*! The size of the second shift used in the generation algorithm.
 102      */
 103     static const size_t shift2 = s2;
 104
 105     /*! The smallest value this \p xor_combine_engine may potentially produce.
 106      */
 107     static const result_type min = 0;
 108
 109     /*! The largest value this \p xor_combine_engine may potentially produce.
 110      */
 111     static const result_type max =
 112       detail::xor_combine_engine_max<
 113         Engine1, s1, Engine2, s2, result_type
 114       >::value;
 115
 116     // constructors and seeding functions
 117
 118     /*! This constructor constructs a new \p xor_combine_engine and constructs
 119      *  its adapted engines using their null constructors.
 120      */
 121     __host__ __device__
 122     xor_combine_engine(void);
 123
 124     /*! This constructor constructs a new \p xor_combine_engine using
 125      *  given \p base1_type and \p base2_type engines to initialize its adapted base engines.
 126      *
 127      *  \param urng1 A \p base1_type to use to initialize this \p xor_combine_engine's
 128      *         first adapted base engine.
 129      *  \param urng2 A \p base2_type to use to initialize this \p xor_combine_engine's
 130      *         first adapted base engine.
 131      */
 132     __host__ __device__
 133     xor_combine_engine(const base1_type &urng1, const base2_type &urng2);
 134
 135     /*! This constructor initializes a new \p xor_combine_engine with a given seed.
 136      *
 137      *  \param s The seed used to intialize this \p xor_combine_engine's adapted base engines.
 138      */
 139     __host__ __device__
 140     xor_combine_engine(result_type s);
 141
 142     /*! This method initializes the state of this \p xor_combine_engine's adapted base engines
 143      *  by using their \p default_seed values.
 144      */
 145     __host__ __device__
 146     void seed(void);
 147
 148     /*! This method initializes the state of this \p xor_combine_engine's adapted base engines
 149      *  by using the given seed.
 150      *
 151      *  \param s The seed with which to intialize this \p xor_combine_engine's adapted base engines.
 152      */
 153     __host__ __device__
 154     void seed(result_type s);
 155
 156     // generating functions
 157
 158     /*! This member function produces a new random value and updates this \p xor_combine_engine's state.
 159      *  \return A new random number.
 160      */
 161     __host__ __device__
 162     result_type operator()(void);
 163
 164     /*! This member function advances this \p xor_combine_engine's state a given number of times
 165      *  and discards the results.
 166      *
 167      *  \param z The number of random values to discard.
 168      *  \note This function is provided because an implementation may be able to accelerate it.
 169      */
 170     __host__ __device__
 171     void discard(unsigned long long z);
 172
 173     // property functions
 174
 175     /*! This member function returns a const reference to this \p xor_combine_engine's
 176      *  first adapted base engine.
 177      *
 178      *  \return A const reference to the first base engine this \p xor_combine_engine adapts.
 179      */
 180     __host__ __device__
 181     const base1_type &base1(void) const;
 182
 183     /*! This member function returns a const reference to this \p xor_combine_engine's
 184      *  second adapted base engine.
 185      *
 186      *  \return A const reference to the second base engine this \p xor_combine_engine adapts.
 187      */
 188     __host__ __device__
 189     const base2_type &base2(void) const;
 190
 191     /*! \cond
 192      */
 193   private:
 194     base1_type m_b1;
 195     base2_type m_b2;
 196
 197     friend struct thrust::random::detail::random_core_access;
 198
 199     __host__ __device__
 200     bool equal(const xor_combine_engine &rhs) const;
 201
 202     template<typename CharT, typename Traits>
 203     std::basic_istream<CharT,Traits>& stream_in(std::basic_istream<CharT,Traits> &is);
 204
 205     template<typename CharT, typename Traits>
 206     std::basic_ostream<CharT,Traits>& stream_out(std::basic_ostream<CharT,Traits> &os) const;
 207
 208     /*! \endcond
 209      */
 210 }; // end xor_combine_engine
 211
 212
 213 /*! This function checks two \p xor_combine_engines for equality.
 214  *  \param lhs The first \p xor_combine_engine to test.
 215  *  \param rhs The second \p xor_combine_engine to test.
 216  *  \return \c true if \p lhs is equal to \p rhs; \c false, otherwise.
 217  */
 218 template<typename Engine1_, size_t s1_, typename Engine2_, size_t s2_>
 219 __host__ __device__
 220 bool operator==(const xor_combine_engine<Engine1_,s1_,Engine2_,s2_> &lhs,
 221                 const xor_combine_engine<Engine1_,s1_,Engine2_,s2_> &rhs);
 222
 223
 224 /*! This function checks two \p xor_combine_engines for inequality.
 225  *  \param lhs The first \p xor_combine_engine to test.
 226  *  \param rhs The second \p xor_combine_engine to test.
 227  *  \return \c true if \p lhs is not equal to \p rhs; \c false, otherwise.
 228  */
 229 template<typename Engine1_, size_t s1_, typename Engine2_, size_t s2_>
 230 __host__ __device__
 231 bool operator!=(const xor_combine_engine<Engine1_,s1_,Engine2_,s2_> &lhs,
 232                 const xor_combine_engine<Engine1_,s1_,Engine2_,s2_> &rhs);
 233
 234
 235 /*! This function streams a xor_combine_engine to a \p std::basic_ostream.
 236  *  \param os The \p basic_ostream to stream out to.
 237  *  \param e The \p xor_combine_engine to stream out.
 238  *  \return \p os
 239  */
 240 template<typename Engine1_, size_t s1_, typename Engine2_, size_t s2_,
 241          typename CharT, typename Traits>
 242 std::basic_ostream<CharT,Traits>&
 243 operator<<(std::basic_ostream<CharT,Traits> &os,
 244            const xor_combine_engine<Engine1_,s1_,Engine2_,s2_> &e);
 245
 246
 247 /*! This function streams a xor_combine_engine in from a std::basic_istream.
 248  *  \param is The \p basic_istream to stream from.
 249  *  \param e The \p xor_combine_engine to stream in.
 250  *  \return \p is
 251  */
 252 template<typename Engine1_, size_t s1_, typename Engine2_, size_t s2_,
 253          typename CharT, typename Traits>
 254 std::basic_istream<CharT,Traits>&
 255 operator>>(std::basic_istream<CharT,Traits> &is,
 256            xor_combine_engine<Engine1_,s1_,Engine2_,s2_> &e);
 257
 258
 259 /*! \} // end random_number_engine_adaptors
 260  */
 261
 262
 263 } // end random
 264
 265 // import names into thrust::
 266 using random::xor_combine_engine;
 267
 268 } // end thrust
 269
 270 #include <thrust/random/detail/xor_combine_engine.inl>
 271