| Home | Libraries | People | FAQ | More

## Class template faure_engine

boost::random::faure_engine

## Synopsis

    // In header: <boost/random/faure.hpp>

    template<typename RealType, typename SeqSizeT,
             typename PrimeTable = default_faure_prime_table>
    class faure_engine {
    public:
      // types
      typedef RealType result_type;

      // construct/copy/destruct
      explicit faure_engine(std::size_t);

      // friend functions
      friend bool operator==(const faure_engine &, const faure_engine &);
      friend bool operator!=(const faure_engine &, const faure_engine &);
      template<typename CharT, typename Traits>
        friend std::basic_ostream< CharT, Traits > &
        operator<<(std::basic_ostream< CharT, Traits > &, const faure_engine &);
      template<typename CharT, typename Traits>
        friend std::basic_istream< CharT, Traits > &
        operator>>(std::basic_istream< CharT, Traits > &, const faure_engine &);

      // public static functions
      static constexpr result_type min();
      static constexpr result_type max();

      // public member functions
      void seed(SeqSizeT = 0);
      std::size_t dimension() const;
      result_type operator()();
      void discard(boost::uintmax_t);
    };

## Description

Instantiations of class template faure_engine model a quasi-random number generator . The faure_engine uses the algorithm described in

> Henri Faure, Discrepance de suites associees a un systeme de numeration (en dimension s), Acta Arithmetica, Volume 41, 1982, pages 337-351.

> Bennett Fox, Algorithm 647: Implementation and Relative Efficiency of Quasirandom Sequence Generators, ACM Transactions on Mathematical Software, Volume 12, Number 4, December 1986, pages 362-376.

In the following documentation `X` denotes the concrete class of the template faure_engine returning objects of type `RealType`, u and v are the values of `X`.

Some member functions may throw exceptions of type `std::bad_alloc`.

### `faure_engine` public construct/copy/destruct

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

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

   Throws: bad_alloc, invalid_argument.

### `faure_engine` friend functions

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

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

2.     friend bool operator!=(const faure_engine & lhs, const faure_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 faure_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 faure_engine & s);

   Reads the textual representation of the generator from a `std::istream`.

### `faure_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.

### `faure_engine` public member functions

1.     void seed(SeqSizeT init = 0);

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

   Throws: bad_alloc.

2.     std::size_t dimension() const;

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

   Throws: nothing.

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

4.     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. Throws: bad_alloc.