util/X86LINUX64/cuda-6.5/include/thrust/random/discard_block_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
  18 /*! \file discard_block_engine.h
  19  *  \brief A random number engine which adapts a base engine and produces
  20  *         numbers by discarding all but a contiguous blocks of its values.
  21  */
  22
  23 #pragma once
  24
  25 #include <thrust/detail/config.h>
  26
  27 #include <thrust/detail/config.h>
  28 #include <iostream>
  29 #include <thrust/detail/cstdint.h>
  30 #include <thrust/random/detail/random_core_access.h>
  31
  32 namespace thrust
  33 {
  34
  35 namespace random
  36 {
  37
  38 /*! \addtogroup random_number_engine_adaptors Random Number Engine Adaptor Class Templates
  39  *  \ingroup random
  40  *  \{
  41  */
  42
  43 /*! \class discard_block_engine
  44  *  \brief A \p discard_block_engine adapts an existing base random number engine and produces
  45  *         random values by discarding some of the values returned by its base engine.
  46  *         Each cycle of the compound engine begins by returning \c r values successively produced
  47  *         by the base engine and ends by discarding <tt>p-r</tt> such values. The engine's state
  48  *         is the state of its base engine followed by the number of calls to <tt>operator()</tt>
  49  *         that have occurred since the beginning of the current cycle.
  50  *
  51  *  \tparam Engine The type of the base random number engine to adapt.
  52  *  \tparam p The discard cycle length.
  53  *  \tparam r The number of values to return of the base engine. Because <tt>p-r</tt> will be
  54  *            discarded, <tt>r <= p</tt>.
  55  *
  56  *  The following code snippet shows an example of using a \p discard_block_engine instance:
  57  *
  58  *  \code
  59  *  #include <thrust/random/linear_congruential_engine.h>
  60  *  #include <thrust/random/discard_block_engine.h>
  61  *  #include <iostream>
  62  *
  63  *  int main(void)
  64  *  {
  65  *    // create a discard_block_engine from minstd_rand, with a cycle length of 13
  66  *    // keep every first 10 values, and discard the next 3
  67  *    thrust::discard_block_engine<thrust::minstd_rand, 13, 10> rng;
  68  *
  69  *    // print a random number to standard output
  70  *    std::cout << rng() << std::endl;
  71  *
  72  *    return 0;
  73  *  }
  74  *  \endcode
  75  */
  76 template<typename Engine, size_t p, size_t r>
  77   class discard_block_engine
  78 {
  79   public:
  80     // types
  81
  82     /*! \typedef base_type
  83      *  \brief The type of the adapted base random number engine.
  84      */
  85     typedef Engine base_type;
  86
  87     /*! \typedef result_type
  88      *  \brief The type of the unsigned integer produced by this \p linear_congruential_engine.
  89      */
  90     typedef typename base_type::result_type result_type;
  91
  92     // engine characteristics
  93
  94     /*! The length of the production cycle.
  95      */
  96     static const size_t block_size = p;
  97
  98     /*! The number of used numbers per production cycle.
  99      */
 100     static const size_t used_block = r;
 101
 102     /*! The smallest value this \p discard_block_engine may potentially produce.
 103      */
 104     static const result_type min = base_type::min;
 105
 106     /*! The largest value this \p discard_block_engine may potentially produce.
 107      */
 108     static const result_type max = base_type::max;
 109
 110     // constructors and seeding functions
 111
 112     /*! This constructor constructs a new \p discard_block_engine and constructs
 113      *  its \p base_type engine using its null constructor.
 114      */
 115     __host__ __device__
 116     discard_block_engine();
 117
 118     /*! This constructor constructs a new \p discard_block_engine using
 119      *  a given \p base_type engine to initialize its adapted base engine.
 120      *
 121      *  \param urng A \p base_type to use to initialize this \p discard_block_engine's
 122      *         adapted base engine.
 123      */
 124     __host__ __device__
 125     explicit discard_block_engine(const base_type &urng);
 126
 127     /*! This constructor initializes a new \p discard_block_engine with a given seed.
 128      *
 129      *  \param s The seed used to intialize this \p discard_block_engine's adapted base engine.
 130      */
 131     __host__ __device__
 132     explicit discard_block_engine(result_type s);
 133
 134     /*! This method initializes the state of this \p discard_block_engine's adapted base engine
 135      *  by using its \p default_seed value.
 136      */
 137     __host__ __device__
 138     void seed(void);
 139
 140     /*! This method initializes the state of this \p discard_block_engine's adapted base engine
 141      *  by using the given seed.
 142      *
 143      *  \param s The seed with which to intialize this \p discard_block_engine's adapted base engine.
 144      */
 145     __host__ __device__
 146     void seed(result_type s);
 147
 148     // generating functions
 149
 150     /*! This member function produces a new random value and updates this \p discard_block_engine's state.
 151      *  \return A new random number.
 152      */
 153     __host__ __device__
 154     result_type operator()(void);
 155
 156     /*! This member function advances this \p discard_block_engine's state a given number of times
 157      *  and discards the results.
 158      *
 159      *  \param z The number of random values to discard.
 160      *  \note This function is provided because an implementation may be able to accelerate it.
 161      */
 162     __host__ __device__
 163     void discard(unsigned long long z);
 164
 165     // property functions
 166
 167     /*! This member function returns a const reference to this \p discard_block_engine's
 168      *  adapted base engine.
 169      *
 170      *  \return A const reference to the base engine this \p discard_block_engine adapts.
 171      */
 172     __host__ __device__
 173     const base_type &base(void) const;
 174
 175     /*! \cond
 176      */
 177   private:
 178     base_type m_e;
 179     unsigned int m_n;
 180
 181     friend struct thrust::random::detail::random_core_access;
 182
 183     __host__ __device__
 184     bool equal(const discard_block_engine &rhs) const;
 185
 186     template<typename CharT, typename Traits>
 187     std::basic_ostream<CharT,Traits>& stream_out(std::basic_ostream<CharT,Traits> &os) const;
 188
 189     template<typename CharT, typename Traits>
 190     std::basic_istream<CharT,Traits>& stream_in(std::basic_istream<CharT,Traits> &is);
 191     /*! \endcond
 192      */
 193 }; // end discard_block_engine
 194
 195
 196 /*! This function checks two \p discard_block_engines for equality.
 197  *  \param lhs The first \p discard_block_engine to test.
 198  *  \param rhs The second \p discard_block_engine to test.
 199  *  \return \c true if \p lhs is equal to \p rhs; \c false, otherwise.
 200  */
 201 template<typename Engine, size_t p, size_t r>
 202 __host__ __device__
 203 bool operator==(const discard_block_engine<Engine,p,r> &lhs,
 204                 const discard_block_engine<Engine,p,r> &rhs);
 205
 206
 207 /*! This function checks two \p discard_block_engines for inequality.
 208  *  \param lhs The first \p discard_block_engine to test.
 209  *  \param rhs The second \p discard_block_engine to test.
 210  *  \return \c true if \p lhs is not equal to \p rhs; \c false, otherwise.
 211  */
 212 template<typename Engine, size_t p, size_t r>
 213 __host__ __device__
 214 bool operator!=(const discard_block_engine<Engine,p,r> &lhs,
 215                 const discard_block_engine<Engine,p,r> &rhs);
 216
 217
 218 /*! This function streams a discard_block_engine to a \p std::basic_ostream.
 219  *  \param os The \p basic_ostream to stream out to.
 220  *  \param e The \p discard_block_engine to stream out.
 221  *  \return \p os
 222  */
 223 template<typename Engine, size_t p, size_t r,
 224          typename CharT, typename Traits>
 225 std::basic_ostream<CharT,Traits>&
 226 operator<<(std::basic_ostream<CharT,Traits> &os,
 227            const discard_block_engine<Engine,p,r> &e);
 228
 229
 230 /*! This function streams a discard_block_engine in from a std::basic_istream.
 231  *  \param is The \p basic_istream to stream from.
 232  *  \param e The \p discard_block_engine to stream in.
 233  *  \return \p is
 234  */
 235 template<typename Engine, size_t p, size_t r,
 236          typename CharT, typename Traits>
 237 std::basic_istream<CharT,Traits>&
 238 operator>>(std::basic_istream<CharT,Traits> &is,
 239            discard_block_engine<Engine,p,r> &e);
 240
 241 /*! \} // end random_number_engine_adaptors
 242  */
 243
 244 } // end random
 245
 246 // import names into thrust::
 247 using random::discard_block_engine;
 248
 249 } // end thrust
 250
 251 #include <thrust/random/detail/discard_block_engine.inl>
 252