
Boost : 
From: Oliver Kullmann (O.Kullmann_at_[hidden])
Date: 20040622 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 "userfriendly".
>
> 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
> > pseudorandomnumber generator for random
> > numbers from min, min + 1, ..., max (uniform
> > distribution). The generator should take a seed,
> > and then producing a sequence of pseudorandom
> > 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 plainvanilla 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 pseudorandom 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 pseudorandom
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
> > email. (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
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk