| Home | Libraries | People | FAQ | More

## Class template sobol_engine

boost::random::sobol_engine

## Synopsis

    // 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 &);
    };

## Description

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 `uniform_01` distribution will look like this:
    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 construct/copy/destruct

1.     explicit sobol_engine(std::size_t s);

   Effects: Constructs the default `s`-dimensional Sobol quasi-random number generator.

   Throws: bad_alloc, invalid_argument, range_error.

### `sobol_engine` public member functions

1.     std::size_t dimension() const;

   Returns: The dimension of of the quasi-random domain.

   Throws: nothing.

2.     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).

3.     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());

4.     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.

5.     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` public static functions

1.     static constexpr result_type min();

   Returns: Tight lower bound on the set of values returned by operator().

   Throws: nothing.

2.     static constexpr result_type max();

   Returns: Tight upper bound on the set of values returned by operator().

   Throws: nothing.

### `sobol_engine` friend functions

1.     friend bool operator==(const sobol_engine & x, const sobol_engine & y);

   Returns true if the two generators will produce identical sequences of outputs.

2.     friend bool operator!=(const sobol_engine & lhs, const sobol_engine & rhs);

   Returns true if the two generators will produce different sequences of outputs.

3.     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`.

4.     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`.