...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::random::sobol_engine
// In header: <boost/random/sobol.hpp> template<typename UIntType, unsigned w, typename SobolTables = default_sobol_table> class sobol_engine { public: // types typedef UIntType result_type; // construct/copy/destruct explicit sobol_engine(std::size_t); // public member functions std::size_t dimension() const; void seed(); void seed(UIntType); result_type operator()(); void discard(boost::uintmax_t); // public static functions static constexpr result_type min(); static constexpr result_type max(); // friend functions friend bool operator==(const sobol_engine &, const sobol_engine &); friend bool operator!=(const sobol_engine &, const sobol_engine &); template<typename CharT, typename Traits> friend std::basic_ostream< CharT, Traits > & operator<<(std::basic_ostream< CharT, Traits > &, const sobol_engine &); template<typename CharT, typename Traits> friend std::basic_istream< CharT, Traits > & operator>>(std::basic_istream< CharT, Traits > &, const sobol_engine &); };
Instantiations of class template sobol_engine model a quasi-random number generator . The sobol_engine uses the algorithm described in
[Bratley+Fox, TOMS 14, 88 (1988)] and [Antonov+Saleev, USSR Comput. Maths. Math. Phys. 19, 252 (1980)]
Note | |
---|---|
sobol_engine skips trivial zeroes at the start of the sequence. For example, the beginning of the 2-dimensional Sobol sequence in 0.5, 0.5, 0.75, 0.25, 0.25, 0.75, 0.375, 0.375, 0.875, 0.875, ... |
In the following documentation X
denotes the concrete class of the template sobol_engine returning objects of type UIntType
, u and v are the values of X
.
Some member functions may throw exceptions of type std::range_error
. This happens when the quasi-random domain is exhausted and the generator cannot produce any more values. The length of the low discrepancy sequence is given by .
sobol_engine
public member functionsstd::size_t dimension() const;
Returns: The dimension of of the quasi-random domain.
Throws: nothing.
void seed();Throws: nothing.
Effects: Resets the quasi-random number generator state to the one given by the default construction. Equivalent to u.seed(0).
void seed(UIntType init);Throws: range_error.
Effects: Effectively sets the quasi-random number generator state to the init
-th vector in the s
-dimensional quasi-random domain, where s
== X::dimension().
X u, v; for(int i = 0; i < N; ++i) for( std::size_t j = 0; j < u.dimension(); ++j ) u(); v.seed(N); assert(u() == v());
result_type operator()();
Returns: Returns a successive element of an s
-dimensional (s = X::dimension()) vector at each invocation. When all elements are exhausted, X::operator() begins anew with the starting element of a subsequent s
-dimensional vector.
Throws: range_error.
void discard(boost::uintmax_t z);
Effects: Advances *this state as if z
consecutive X::operator() invocations were executed.
X u = v; for(int i = 0; i < N; ++i) u(); v.discard(N); assert(u() == v());
Throws: range_error.
sobol_engine
friend functionsfriend bool operator==(const sobol_engine & x, const sobol_engine & y);
Returns true if the two generators will produce identical sequences of outputs.
friend bool operator!=(const sobol_engine & lhs, const sobol_engine & rhs);
Returns true if the two generators will produce different sequences of outputs.
template<typename CharT, typename Traits> friend std::basic_ostream< CharT, Traits > & operator<<(std::basic_ostream< CharT, Traits > & os, const sobol_engine & s);
Writes the textual representation of the generator to a std::ostream
.
template<typename CharT, typename Traits> friend std::basic_istream< CharT, Traits > & operator>>(std::basic_istream< CharT, Traits > & is, const sobol_engine & s);
Reads the textual representation of the generator from a std::istream
.