Re: lognormal_distribution documentation error

From: Brad Hanson (bradh_at_[hidden])
Date: 2001-10-23 01:12:27

 > > The documentation of the lognormal_distribution constructor
 > > indicates that the second and third arguments are the mean
 > > and standard deviation parameters (the desired mean and
 > > standard deviation of the log of the generated variables).
 > > Actually, the second and third arguments of the constructor
 > > are the mean and standard deviation of the lognormal
 > > distribution (the desired mean and standard deviation of the
 > > generated variables). The documentation for the function
 > > call operator refers to a mean and sigma that should differ
 > > from the mean and sigma referred to in the constructor.
 >
 > There's the obvious cut-and-paste error where the docs talk
 > about "normal_distribution" instead of
 > "lognormal_distribution".  The docs for
 > "lognormal_distribution" should not refer to
 > normal_distribution in any way.
 >
 > Your message seems to indicate that there's a further
 > mismatch between the semantics of the sigma, mean referred
 > to in the constructor and their actual meaning in p(x) while
 > defining operator().
 >
 > I don't understand that.  Could you please be more specific?
 > In particular, the docs don't claim that sigma, mean are
 > the mean and standard deviation of the distribution (it
 > would be nice if they would be, though). In short, am I
 > using sigma, mean wrongly when talking about p(x)?

It looks to me the way the lognormal_distribution
constructor is written that the mean and sigma arguments are
in fact the mean and standard deviation of the lognormal
distribution, as opposed to the mean and standard deviation
of the underlying normal distribution. The mean and sigma in
p(x) should be the mean and standard deviation of the
underlying normal distribution. I also think that
sqrt(2*pi*sigma) should be sqrt(2*pi) in p(x).

Here's how I would modify the documentation of the
lognormal_distribution members:

<h3>Members</h3>

<pre>lognormal_distribution(base_type& rng, const result_type& mean,
                          const result_type& sigma)</pre>

<strong>Effects:</strong> Constructs a
<code>lognormal_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>mean</code> and <code>sigma</code> are the mean and
standard deviation of the lognormal distribution.
<p>

<pre>result_type operator()()</pre>

<strong>Returns:</strong> A random floating-point value <em>x</em>
with p(x) = 1/(x * normal_sigma * sqrt(2*pi)) * exp(
-(log(x)-normal_mean)<sup>2</sup> / (2*normal_sigma<sup>2</sup>) )
for x > 0,
where normal_mean = log(mean<sup>2</sup>/sqrt(sigma<sup>2</sup>
+ mean<sup>2</sup>))
and normal_sigma = sqrt(log(1 + sigma<sup>2</sup>/mean<sup>2</sup>)).

Brad Hanson