[boost] Random: Minor documentation fix

From: Michael Stevens (Michael.Stevens_at_[hidden])
Date: 2004-02-19 16:20:44

Looking at the documentation I stumbed across a couple of issues.
In normal_distribution is states
Requires: sigma > 0

This looks like a typo as the constructor uses 
    assert(sigma >= result_type(0));
and sigma ==0 is no problem numerically.

Oddly lognormal_distribution has no "Requires" section. The constructor 
requires
  assert(mean > result_type(0));
and it inherits the sigma requirement from normal_distribution.

I think I have also found a few left overs from the old interface.

The introduction states
"All of the distribution functions described below store a non-const reference 
to the underlying source of random numbers. Therefore, the distribution 
functions are not Assignable...

This is no longer true. Only uniform_01 now constructed with a reference to an 
underlying UniformRandomNumberGenerator.

Actually uniform_01 seems to be a very odd beast now. It is different from all 
the other Distributions. It would seem to make sense to document it 
separately as a special case.

One major stumbling block for me in the documentation is the definition of the 
operator() as:
  template<class UniformRandomNumberGenerator>
  result_type operator()(UniformRandomNumberGenerator& urng);

This leads the unsuspecting user to think they can use any type the models a 
UniformRandomNumberGenerator for example a boost::mt19937

Although in theory this is correct this can lead to big surprises in practice. 
For example normal_distribution uses a probability density function p(x) = 
1/sqrt(2*pi*sigma) * exp(- (x-mean)2 / (2*sigma2) )
This combine with the numerical range of the result_type will lead to 
normal_distribution almost always producing NaN!

variate_generate implicitly goes to great care to avoid this, so the problem 
only arrises if the distribution is used directly.

Obviously a big Caution in the type documentation would be good. However I am 
wondering if a better way to deal with it would be to add a new concept. 
Something like RestrictedUniformRandomNumberGenerator where the range of the 
output is restricted in order for the distribution to give meaningful 
results.

Anyway apart from these Minor doc issues the new Random looks very good. 
Thanks Jens,

Michael

-- 
___________________________________
Michael Stevens Systems Engineering
Navigation Systems, Estimation  and
                 Bayesian Filtering
    http://www.sf.net/Bayes++
___________________________________