[Ns-developers] Random Variables API changes

Michele Weigle mweigle at csnet.cs.odu.edu
Tue Jan 20 11:45:50 PST 2009

On Jan 20, 2009, at 1:59 PM, Tom Henderson wrote:
>> -----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.

This is definitely something that would be useful.

Here's what I would propose:
* create a runNumber variable in RandomVariable
* create a setRun function in RandomVariable
* upon initialization of the random variable, copy the value in  
SeedManager::runNumber to runNumber

Then, for each random variable, the user can override the runNumber in  
SeedManager. We'd have to change the calls when initializing new RNGs  
(for instance, in GetValue) to use the RandomVariable version of  
runNumber instead of SeedManager::runNumber.  We'd also want to ensure  
that once the RandomVariable was initialized (or used for the first  
time) that the run number couldn't change.

Is this something we want to go ahead and add now while we're messing  
with the API, or something to add later?


More information about the Ns-developers mailing list