Re: [boost] Random number library

From: Oliver Kullmann (O.Kullmann_at_[hidden])
Date: 2004-06-22 18:45:06

> > one of my students tried some time in vain
> > to use the random number generator from
> > the boost library, but he couldn't understand
> > the documentation. I must say, the documentation
> > is not exactly "user-friendly".
> 
> Did he try playing around with the "very quick start"
> example?  It should at least have gotten him started. 
> See below for a more thorough explanation.
>

The problem with the "very quick start" is, that without
already understanding the architecture of the library it
seems impossible to understand it. It should be quite a bit
longer, with output and some explanations.
 
> > Here's the problem:
> > 
> > Given integers min and max, we want to have a
> > pseudo-random-number generator for random
> > numbers from min, min + 1, ..., max (uniform
> > distribution). The generator should take a seed,
> > and then producing a sequence of pseudo-random
> > numbers (and we should be able to find out about
> > the period of the generator).
> > 
> > I couldn't think of anything more basic for a
> > library on random numbers, and so I would expect
> > an example of how to get such a thing in the
> > documentation. (I mean, a real example, complete
> > with code, explanations, and how to use it.)
> > But there's no such a thing, which I find rather
> > strange.
> 
> Assuming min and max are plain-vanilla integers, the
> following instructions:
> 
>   typedef boost::uniform_int<> UniformDist;
>   UniformDist dist(min,max);
> 
> produce an object named dist that holds your uniform
> distribution.  The following instructions:
> 
>   typedef boost::mt19937 BaseRNG;
>   BaseRNG rng;
> 
> produce a "base pseudo-random number generator", which
> produces numbers along the *entire* range of integers
> (-2^31 to +2^31 or something like that). 
> boost::mt19937 is one of many such generators provided
> by the library.
> 
> The following instruction puts it all together and
> gives you the random integer generator you want:
> 
>   boost::variate_generator<BaseRNG&,UniformDist>
>      your_generator(rng, dist);
> 
> Note the ampersand; your program will fail silently if
> you omit it.
>

I don't understand the need for the reference type --- otherwise
the object rng would be copied, which should also be alright?!

> The base random number generator (rng) holds the seed
> function; simply call
> 
>   rng.seed(42L);
> 
> or whatever seed you want to provide.
>

I see; this wouldn't work without the reference.
 
> Finally, assuming you want to store your sequence in a
> vector<int>:
> 
>   vector<int> sample;
>   for (int c = 0; c < desired_size; c++)
>   {
>     sample.push_back(your_generator());
>   }
> 
> > We have the concept of a "Uniform Random Number
> > Generator",
> > which looks exactly what we want, but, alas, it
> > seems to
> > be more of a fictitious concept, since no models
> > seem to
> > be provided?!?!
> 
> Actually, they do exist.  In the main page is a
> section called "Library Organization"; though the
> concepts don't exactly map to the subsections, you
> should be able to find what you're looking for now
> that I've (hopefully) made things clearer.
>

Perhaps one should emphasise, that models of pseudo-random
generators are models of uniform random generators,
and that also for example uniform_int yields a model of a uniform
random generator.
Inclusion of something like the above explanations into
the documentation would already help a lot!
 
> [snip other complaints]
> 
> > My student didn't get to this point, although he is
> > rather good.  But there are too many unknowns in
> > the "equation" to solve (starting with the concept
> > of a concept, ...), so the job becomes overwhelming.
> > Now it doesn't look too complicated for me to write
> > a nice explanation for the above problem in a
> > tutorial style, explaining on the way all the
> > concepts and concepts of concepts in the library,
> > and that's what I wanted to kindly request with my
> > e-mail. (And also the rest of the documentation
> > could need a sentence here and there, as mentioned
> > in the above case study.)
> 
> We'll see what Jens Maurer has to say on that.  In the
> meantime, tell your student not to give up!
>

Thanks for your help! 

Oliver