- Random123-1.09 Documentation

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

# Random123/conventional/Engine.hpp

Go to the documentation of this file.

    00001 /*
    00002 Copyright 2010-2011, D. E. Shaw Research.
    00003 All rights reserved.
    00004
    00005 Redistribution and use in source and binary forms, with or without
    00006 modification, are permitted provided that the following conditions are
    00007 met:
    00008
    00009 * Redistributions of source code must retain the above copyright
    00010   notice, this list of conditions, and the following disclaimer.
    00011
    00012 * Redistributions in binary form must reproduce the above copyright
    00013   notice, this list of conditions, and the following disclaimer in the
    00014   documentation and/or other materials provided with the distribution.
    00015
    00016 * Neither the name of D. E. Shaw Research nor the names of its
    00017   contributors may be used to endorse or promote products derived from
    00018   this software without specific prior written permission.
    00019
    00020 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    00021 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    00022 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    00023 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    00024 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    00025 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    00026 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    00027 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    00028 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    00029 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    00030 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    00031 */
    00032 #ifndef __Engine_dot_hpp_
    00033 #define __Engine_dot_hpp_
    00034
    00035 #include "../features/compilerfeatures.h"
    00036 #include "../array.h"
    00037 #include <limits>
    00038 #include <stdexcept>
    00039 #include <sstream>
    00040 #include <algorithm>
    00041 #include <vector>
    00042 #if R123_USE_CXX11_TYPE_TRAITS
    00043 #include <type_traits>
    00044 #endif
    00045
    00046 namespace r123{
    00067 template<typename CBRNG>
    00068 struct Engine {
    00069     typedef CBRNG cbrng_type;
    00070     typedef typename CBRNG::ctr_type ctr_type;
    00071     typedef typename CBRNG::key_type key_type;
    00072     typedef typename CBRNG::ukey_type ukey_type;
    00073     typedef typename ctr_type::value_type result_type;
    00074     typedef size_t elem_type;
    00075
    00076 protected:
    00077     cbrng_type b;
    00078     key_type key;
    00079     ukey_type ukey;
    00080     ctr_type c;
    00081     elem_type elem;
    00082     ctr_type v;
    00083
    00084     void fix_invariant(){
    00085         if( elem != 0 ) {
    00086             v = b(c, key);
    00087         }
    00088     }
    00089 public:
    00090     explicit Engine() : b(), c(), elem() {
    00091         ukey_type x = {{}};
    00092         ukey = x;
    00093         key = ukey;
    00094     }
    00095     explicit Engine(result_type r) : b(), c(), elem() {
    00096         ukey_type x = {{typename ukey_type::value_type(r)}};
    00097         ukey = x;
    00098         key = ukey;
    00099     }
    00100     // 26.5.3 says that the SeedSeq templates shouldn't particpate in
    00101     // overload resolution unless the type qualifies as a SeedSeq.
    00102     // How that is determined is unspecified, except that "as a
    00103     // minimum a type shall not qualify as a SeedSeq if it is
    00104     // implicitly convertible to a result_type."
    00105     //
    00106     // First, we make sure that even the non-const copy constructor
    00107     // works as expected.  In addition, if we've got C++0x
    00108     // type_traits, we use enable_if and is_convertible to implement
    00109     // the convertible-to-result_type restriction.  Otherwise, the
    00110     // template is unconditional and will match in some surpirsing
    00111     // and undesirable situations.
    00112     Engine(Engine& e) : b(e.b), ukey(e.ukey), c(e.c), elem(e.elem){
    00113         key = ukey;
    00114         fix_invariant();
    00115     }
    00116     Engine(const Engine& e) : b(e.b), ukey(e.ukey), c(e.c), elem(e.elem){
    00117         key = ukey;
    00118         fix_invariant();
    00119     }
    00120
    00121     template <typename SeedSeq>
    00122     explicit Engine(SeedSeq &s
    00123 #if R123_USE_CXX11_TYPE_TRAITS
    00124                     , typename std::enable_if<!std::is_convertible<SeedSeq, result_type>::value>::type* =0
    00125 #endif
    00126                     )
    00127         : b(), c(), elem() {
    00128         ukey = ukey_type::seed(s);
    00129         key = ukey;
    00130     }
    00131     void seed(result_type r){
    00132         *this = Engine(r);
    00133     }
    00134     template <typename SeedSeq>
    00135     void seed(SeedSeq &s
    00136 #if R123_USE_CXX11_TYPE_TRAITS
    00137                     , typename std::enable_if<!std::is_convertible<SeedSeq, result_type>::value>::type* =0
    00138 #endif
    00139               ){
    00140         *this = Engine(s);
    00141     }
    00142     void seed(){
    00143         *this = Engine();
    00144     }
    00145     friend bool operator==(const Engine& lhs, const Engine& rhs){
    00146         return lhs.c==rhs.c && lhs.elem == rhs.elem && lhs.ukey == rhs.ukey;
    00147     }
    00148     friend bool operator!=(const Engine& lhs, const Engine& rhs){
    00149         return lhs.c!=rhs.c || lhs.elem != rhs.elem || lhs.ukey!=rhs.ukey;
    00150     }
    00151
    00152     friend std::ostream& operator<<(std::ostream& os, const Engine& be){
    00153         return os << be.c << " " << be.ukey << " " << be.elem;
    00154     }
    00155
    00156     friend std::istream& operator>>(std::istream& is, Engine& be){
    00157         is >> be.c >> be.ukey >> be.elem;
    00158         be.key = be.ukey;
    00159         be.fix_invariant();
    00160         return is;
    00161     }
    00162
    00163     // The <random> shipped with MacOS Xcode 4.5.2 imposes a
    00164     // non-standard requirement that URNGs also have static data
    00165     // members: _Min and _Max.  Later versions of libc++ impose the
    00166     // requirement only when constexpr isn't supported.  Although the
    00167     // Xcode 4.5.2 requirement is clearly non-standard, it is unlikely
    00168     // to be fixed and it is very easy work around.  We certainly
    00169     // don't want to go to great lengths to accommodate every buggy
    00170     // library we come across, but in this particular case, the effort
    00171     // is low and the benefit is high, so it's worth doing.  Thanks to
    00172     // Yan Zhou for pointing this out to us.  See similar code in
    00173     // ../MicroURNG.hpp
    00174     const static result_type _Min = 0;
    00175     const static result_type _Max = ~((result_type)0);
    00176
    00177     static R123_CONSTEXPR result_type min R123_NO_MACRO_SUBST () { return _Min; }
    00178     static R123_CONSTEXPR result_type max R123_NO_MACRO_SUBST () { return _Max; }
    00179
    00180     result_type operator()(){
    00181         if( c.size() == 1 )     // short-circuit the scalar case.  Compilers aren't mind-readers.
    00182             return b(c.incr(), key)[0];
    00183         if( elem == 0 ){
    00184             v = b(c.incr(), key);
    00185             elem = c.size();
    00186         }
    00187         return v[--elem];
    00188     }
    00189
    00190     void discard(R123_ULONG_LONG skip){
    00191         // don't forget:  elem counts down
    00192         size_t nelem = c.size();
    00193         size_t sub = skip % nelem;
    00194         skip /= nelem;
    00195         if (elem < sub) {
    00196             elem += nelem;
    00197             skip++;
    00198         }
    00199         elem -= sub;
    00200         c.incr(skip);
    00201         fix_invariant();
    00202     }
    00203
    00204     //--------------------------
    00205     // Some bonus methods, not required for a Random Number
    00206     // Engine
    00207
    00208     // Constructors and seed() method for ukey_type seem useful
    00209     // We need const and non-const to supersede the SeedSeq template.
    00210     explicit Engine(const ukey_type &uk) : key(uk), ukey(uk), c(), elem(){}
    00211     explicit Engine(ukey_type &uk) : key(uk), ukey(uk), c(), elem(){}
    00212     void seed(const ukey_type& uk){
    00213         *this = Engine(uk);
    00214     }
    00215     void seed(ukey_type& uk){
    00216         *this = Engine(uk);
    00217     }
    00218
    00219     // Forward the e(counter) to the CBRNG we are templated
    00220     // on, using the current value of the key.
    00221     ctr_type operator()(const ctr_type& c) const{
    00222         return b(c, key);
    00223     }
    00224
    00225     // Since you can seed *this with a ukey_type, it seems reasonable
    00226     // to allow the caller to know what seed/ukey *this is using.
    00227     ukey_type getseed() const{
    00228         return ukey;
    00229     }
    00230
    00231     // Maybe the caller want's to know the details of
    00232     // the internal state, e.g., so it can call a different
    00233     // bijection with the same counter.
    00234     std::pair<ctr_type, elem_type> getcounter() const {
    00235         return make_pair(c,  elem);
    00236     }
    00237
    00238     // And the inverse.
    00239     void setcounter(const ctr_type& _c, elem_type _elem){
    00240         static const size_t nelem = c.size();
    00241         if( elem > nelem )
    00242             throw std::range_error("Engine::setcounter called  with elem out of range");
    00243         c = _c;
    00244         elem = _elem;
    00245         fix_invariant();
    00246     }
    00247 };
    00248 } // namespace r123
    00249
    00250 #endif

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines