[SciPy-dev] random.set_state also in need of EXPERT attention

[Robert Kern]

On Tue, Jul 28, 2009 at 15:16, David Goldsmith<d_l_goldsmith at yahoo.com> wrote:
>
> --- On Tue, 7/28/09, Robert Kern <robert.kern at gmail.com> wrote:
>
>> Goldsmith<d_l_goldsmith at yahoo.com>
>> wrote:
>> >
>> NR is old and stodgy. They don't cover the state-of-the-art
>> for many arts. Ignore them.
>
> Understood.  (Still, I'm looking at the 2007 edition - very disappointing.  Well, at least I know now not to invest my money in a copy for myself.)
>
>> What "expert attention" is required?
>
> Quoting Ralf from the Discussion section: "[random.set_state] needs some expert explanation of what the tuple elements mean, and an example of how to use this function to modify the generator state in a meaningful way. [later] [Matsumoto/Nishimura, 1997] is reasonably clear, there's a link to it on the Wikipedia page. I think it will only give you elements 2 and 3 though, 4 and 5 were added later in the implementation and I guess are for some of the distributions in the random module. [Perhaps irrelevant if one doesn't need to decipher the code to write an intelligible docstring] The other difficulty is the Pyrex/Cython source, a bit harder to read than plain Python."

What is wrong with the current docstring's explanation of the tuple
elements? If anything, there should be less information. People should
be treating it as an opaque object unless if they are in an unusual
circumstance like trying to match an MT implementation in another
language. In such a circumstance, they really need to go source diving
and understand the code. No amount of documentation is suitable for
that.

But basically, element 4 is a boolean flag (encoded as an int) for
whether element 5 is a cached value for the Gaussian distribution or
not. The Gaussian generator generates two values at a time, so we
return one and cache one and turn on the flag. The next call returns
the cached value and turns off the flag.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
  -- Umberto Eco