boost/random/exponential_distribution.hpp

   1 /* boost random/exponential_distribution.hpp header file
   2  *
   3  * Copyright Jens Maurer 2000-2001
   4  * Copyright Steven Watanabe 2011
   5  * Distributed under the Boost Software License, Version 1.0. (See
   6  * accompanying file LICENSE_1_0.txt or copy at
   7  * http://www.boost.org/LICENSE_1_0.txt)
   8  *
   9  * See http://www.boost.org for most recent version including documentation.
  10  *
  11  * $Id: exponential_distribution.hpp 71018 2011-04-05 21:27:52Z steven_watanabe $
  12  *
  13  * Revision history
  14  *  2001-02-18  moved to individual header files
  15  */
  16
  17 #ifndef BOOST_RANDOM_EXPONENTIAL_DISTRIBUTION_HPP
  18 #define BOOST_RANDOM_EXPONENTIAL_DISTRIBUTION_HPP
  19
  20 #include <boost/config/no_tr1/cmath.hpp>
  21 #include <iosfwd>
  22 #include <boost/assert.hpp>
  23 #include <boost/limits.hpp>
  24 #include <boost/random/detail/config.hpp>
  25 #include <boost/random/detail/operators.hpp>
  26 #include <boost/random/uniform_01.hpp>
  27
  28 namespace boost {
  29 namespace random {
  30
  31 /**
  32  * The exponential distribution is a model of \random_distribution with
  33  * a single parameter lambda.
  34  *
  35  * It has \f$\displaystyle p(x) = \lambda e^{-\lambda x}\f$
  36  */
  37 template<class RealType = double>
  38 class exponential_distribution
  39 {
  40 public:
  41     typedef RealType input_type;
  42     typedef RealType result_type;
  43
  44     class param_type
  45     {
  46     public:
  47
  48         typedef exponential_distribution distribution_type;
  49
  50         /**
  51          * Constructs parameters with a given lambda.
  52          *
  53          * Requires: lambda > 0
  54          */
  55         param_type(RealType lambda_arg = RealType(1.0))
  56           : _lambda(lambda_arg) { BOOST_ASSERT(_lambda > RealType(0)); }
  57
  58         /** Returns the lambda parameter of the distribution. */
  59         RealType lambda() const { return _lambda; }
  60
  61         /** Writes the parameters to a @c std::ostream. */
  62         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
  63         {
  64             os << parm._lambda;
  65             return os;
  66         }
  67
  68         /** Reads the parameters from a @c std::istream. */
  69         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
  70         {
  71             is >> parm._lambda;
  72             return is;
  73         }
  74
  75         /** Returns true if the two sets of parameters are equal. */
  76         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
  77         { return lhs._lambda == rhs._lambda; }
  78
  79         /** Returns true if the two sets of parameters are different. */
  80         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
  81
  82     private:
  83         RealType _lambda;
  84     };
  85
  86     /**
  87      * Constructs an exponential_distribution with a given lambda.
  88      *
  89      * Requires: lambda > 0
  90      */
  91     explicit exponential_distribution(RealType lambda_arg = RealType(1.0))
  92       : _lambda(lambda_arg) { BOOST_ASSERT(_lambda > RealType(0)); }
  93
  94     /**
  95      * Constructs an exponential_distribution from its parameters
  96      */
  97     explicit exponential_distribution(const param_type& parm)
  98       : _lambda(parm.lambda()) {}
  99
 100     // compiler-generated copy ctor and assignment operator are fine
 101
 102     /** Returns the lambda parameter of the distribution. */
 103     RealType lambda() const { return _lambda; }
 104
 105     /** Returns the smallest value that the distribution can produce. */
 106     RealType min BOOST_PREVENT_MACRO_SUBSTITUTION () const
 107     { return RealType(0); }
 108     /** Returns the largest value that the distribution can produce. */
 109     RealType max BOOST_PREVENT_MACRO_SUBSTITUTION () const
 110     { return (std::numeric_limits<RealType>::infinity)(); }
 111
 112     /** Returns the parameters of the distribution. */
 113     param_type param() const { return param_type(_lambda); }
 114     /** Sets the parameters of the distribution. */
 115     void param(const param_type& parm) { _lambda = parm.lambda(); }
 116
 117     /**
 118      * Effects: Subsequent uses of the distribution do not depend
 119      * on values produced by any engine prior to invoking reset.
 120      */
 121     void reset() { }
 122
 123     /**
 124      * Returns a random variate distributed according to the
 125      * exponential distribution.
 126      */
 127     template<class Engine>
 128     result_type operator()(Engine& eng) const
 129     {
 130         using std::log;
 131         return -result_type(1) /
 132             _lambda * log(result_type(1)-uniform_01<RealType>()(eng));
 133     }
 134
 135     /**
 136      * Returns a random variate distributed according to the exponential
 137      * distribution with parameters specified by param.
 138      */
 139     template<class Engine>
 140     result_type operator()(Engine& eng, const param_type& parm) const
 141     {
 142         return exponential_distribution(parm)(eng);
 143     }
 144
 145     /** Writes the distribution to a std::ostream. */
 146     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, exponential_distribution, ed)
 147     {
 148         os << ed._lambda;
 149         return os;
 150     }
 151
 152     /** Reads the distribution from a std::istream. */
 153     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, exponential_distribution, ed)
 154     {
 155         is >> ed._lambda;
 156         return is;
 157     }
 158
 159     /**
 160      * Returns true iff the two distributions will produce identical
 161      * sequences of values given equal generators.
 162      */
 163     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(exponential_distribution, lhs, rhs)
 164     { return lhs._lambda == rhs._lambda; }
 165
 166     /**
 167      * Returns true iff the two distributions will produce different
 168      * sequences of values given equal generators.
 169      */
 170     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(exponential_distribution)
 171
 172 private:
 173     result_type _lambda;
 174 };
 175
 176 } // namespace random
 177
 178 using random::exponential_distribution;
 179
 180 } // namespace boost
 181
 182 #endif // BOOST_RANDOM_EXPONENTIAL_DISTRIBUTION_HPP