[Ns-developers] Random Variables API changes

[Tom Henderson]

>-----Original Message-----
>From: Gustavo Carneiro [mailto:gjcarneiro at gmail.com]
>Sent: Tuesday, January 20, 2009 10:09 AM
>To: 'Tom Henderson'
>Cc: 'Raj Bhattacharjea', 'NS3 Developers Mailing List'
>Subject: Re: [Ns-developers] Random Variables API changes
>
>2009/1/20 Tom Henderson <tomh at tomh.org>
>
>>
>> >-----Original Message-----
>> >From: Gustavo Carneiro [mailto:gjcarneiro at gmail.com]
>> >Sent: Tuesday, January 20, 2009 09:19 AM
>> >To: 'Raj Bhattacharjea'
>> >Cc: 'Tom Henderson', 'NS3 Developers Mailing List'
>> >Subject: Re: [Ns-developers] Random Variables API changes
>> >
>> >2009/1/20 Raj Bhattacharjea <raj.b at gatech.edu>
>> >
>> >> On Tue, Jan 20, 2009 at 11:40 AM, Raj Bhattacharjea <raj.b at gatech.edu>
>> >> wrote:
>> >> > quick ideas that need to be looked at.  The biggest of these is a
>> >> > change like the following:
>> >> >
>> >> > - UniformVariable::GetSingleValue (0, N)
>> >> > + UniformVariable().GetValue (0, N)
>> >> >
>> >> > I had to do this in one place to make things compile, but seems a bit
>> >>
>> >> I forgot I had to do this in several places, or things similar to
>> >> this.  The affected files are:
>> >>
>> >> src/devices/csma/backoff.cc
>> >> src/mobility/random-direction-2d-mobility-model.cc
>> >> src/routing/olsr/olsr-agent-impl.cc
>> >>
>> >> I'm sure the maintainers of these would have their preferred
>> >> implementation.
>> >
>> >
>> >I wonder what is the rationale for the removal of GetSingleValue?  It
>> seems
>> >to me that keeping a single static UniformVariable global variable is just
>> a
>> >pointless API change, as it is surely equivalent to previous code, while
>> >keeping one UniformVariable per OLSR instance sounds like a memory waste
>> if
>> >no reason for the change is known.
>> >
>> >I think there is probably a good reason for the API change and, not that I
>> >don't trust you, but I would like to know what that reason is.  Was the
>> >previous GetSingleValue usage pattern incorrect?
>>
>> Here is the background on this proposed change:
>> http://mailman.isi.edu/pipermail/ns-developers/2008-September/004732.html
>>
>> My understanding is that the recommended way would be for users to create
>> their own random variables, but if there is some reason they don't want to
>> do that, they could draw from a common stream; the first stream generated by
>> the RNG.  This stream would only provide Uniform(a,b) random variables,
>> presumably via static functions or else via some global object.
>
>
>From the email:
>
>* remove the GetSingleValue function from RandomVariable classes
>
>The GetSingleValue function allows for potential non-independence as
>it draws values from a single RNG stream for different random
>variables.  Each random variable should have its own RNG stream.
>
>
>From that text it sounds like either a temporary RV instance or a single
>global RV for all OLSR instances is not recommended.  But I am partially
>guessing.  Under which conditions does "Each random variable should have its
>own RNG stream" hold true?  Without reading the source code I can't be 100%
>sure.
>
>Basically I believe the Changes.html files should contain an answer to the
>following question: "how to migrate code using the old GetSingleValue to new
>API?".  The sooner that question is answered, the sooner ns-3's own code can
>be correctly fixed, let alone 3rd party code.
>
>So, in the OLSR example, OLSR agent would have the choice of a per-agent
>> UniformVariable generator, or could access the (global) first stream.  But,
>> I didn't think that we were talking about using anonymous temporary
>> variables for this purpose.
>
>
>I have no idea what a "stream" is and I don't care :-)  I thought we were
>supposed to do everything via XxxVariable classes, not via RNG streams.
>

The simplest would be to require everyone who wants random numbers to create their own RandomVariable instance.  Each such instance would be independent, and there would be no global RandomVariable to draw from.  Perhaps others could comment on why this simplification would be insufficient.   

One other API question I had was concerning the granularity of controlling the seeding of the RandomVariables.  Presently, there seems to be no way to decouple some RandomVariables and hold their generators constant while varying others.  For instance, in a given simulation scenario, there might be a lot of random variables in use.  A user might want to fix (e.g., use a static seed) the randomness of nearly all of those variables while allowing one random variable to vary across run numbers, in order to isolate the contribution of a single random variable.  I thought that this decoupling was a design goal at some point.  The current API seems to amount to requiring all random variables to be fixed across different simulation runs, or all to be reseeded (independently) across runs.

Tom
Tom