
Boost : 
From: Oliver Kullmann (O.Kullmann_at_[hidden])
Date: 20040622 13:31:18
Hi,
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". 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.
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?!?!
So well, let's have a look at "Random Distribution".
Only that it needs as input a "Uniform Random Number Generator",
and the library does not seem to provide these things?!?!
(We have the "Random Number Library Generators", but this
library seems to provide only models for the most general
concept, the concept of a "Number Generator", but not of
a "Uniform Random Number Generator".)
Let's ignore this for a moment, and continue our investigations
into "Random Distribution".
Here are actually some models, most useful for our purpose seems
to be "Class template uniform_smallint" and "Class template uniform_int".
Now, even if we would know where to get the argument urng from,
still we wouldn't know which to choose:
The documentation on these class templates is rather cryptic,
and additionally asks us to be "wise". Shouldn't this be the job
of the library?!
Final rescue: "random_demo.cpp".
The macros don't enhance readability.
But there is an example
"Define a uniform random number distribution of integer values between
// 1 and 6 inclusive."
where I find the text misleading (since we don't define a distribution,
which is an assignment of probabilities to certain events, but we define a generator),
but looking at the output of the program
experiment: roll a die 10 times:
3 3 2 6 6 5 5 6 6 3
it seems to be what we want. So I could copy and past the relevant
parts of the program (which is not completely trivial), and I would
get close to my goals. If only I would understood the meaning of
what I'm doing! Unfortunately, variate_generator.hpp seems to
be of some importance, but is not documented. Sigh.

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.)
And, of course, for any example of the best way how to solve the above
problem with the library, and explanations how it works, I would be glad!
Oliver
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk