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