ns3::RandomVariable Class Reference [Random Variable Distributions]

The basic RNG for NS-3.Note: The underlying random number generation method used by NS-3 is the RngStream code by Pierre L'Ecuyer at the University of Montreal. More...

#include <random-variable.h>

Inheritance diagram for ns3::RandomVariable:

List of all members.

Public Member Functions
double	GetValue (void) const
	Returns a random double from the underlying distribution.
uint32_t	GetInteger (void) const
	Returns a random integer integer from the underlying distribution.
void	GetSeed (uint32_t seed[6]) const
	Get the internal state of the RNG.
Static Public Member Functions
static void	UseDevRandom (bool udr=true)
	Set seeding behavior.
static void	UseGlobalSeed (uint32_t s0, uint32_t s1, uint32_t s2, uint32_t s3, uint32_t s4, uint32_t s5)
	Use the global seed to force precisely reproducible results.
static void	SetRunNumber (uint32_t n)
	Set the run number of this simulation.

---

Detailed Description

The basic RNG for NS-3.

Note: The underlying random number generation method used by NS-3 is the RngStream code by Pierre L'Ecuyer at the University of Montreal.

NS-3 has a rich set of random number generators. Class RandomVariable defines the base class functionalty required for all random number generators. By default, the underlying generator is seeded with the time of day, and then deterministically creates a sequence of seeds for each subsequent generator that is created. The rest of the documentation outlines how to change this behavior.

---

Member Function Documentation

uint32_t ns3::RandomVariable::GetInteger

(

void

)

const

Returns a random integer integer from the underlying distribution.

Returns:

Integer cast of GetValue()

void ns3::RandomVariable::GetSeed

(

uint32_t

seed[6]

)

const

Get the internal state of the RNG.

This function is for power users who understand the inner workings of the underlying RngStream method used. It returns the internal state of the RNG via the input parameter.

Parameters:

seed

Output parameter; gets overwritten with the internal state of of the RNG.

double ns3::RandomVariable::GetValue

(

void

)

const

Returns a random double from the underlying distribution.

Returns:

A floating point random value

static void ns3::RandomVariable::SetRunNumber

(

uint32_t

n

)

[static]

Set the run number of this simulation.

These RNGs have the ability to give independent sets of trials for a fixed global seed. For example, suppose one sets up a simulation with RandomVariables with a given global seed. Suppose the user wanted to retry the same simulation with different random values for validity, statistical rigor, etc. The user could either change the global seed and re-run the simulation, or could use this facility to increment all of the RNGs to a next substream state. This predictably advances the internal state of all RandomVariables n steps. This should be called immediately after the global seed is set, and before the creation of any RandomVariables. For example:

 RandomVariable::UseGlobalSeed(1,2,3,4,5,6);
 int N = atol(argv[1]); //read in run number from command line
 RandomVariable::SetRunNumber(N);
 UniformVariable x(0,10);
 ExponentialVariable y(2902);

In this example, N could successivly be equal to 1,2,3, etc. and the user would continue to get independent runs out of the single simulation. For this simple example, the following might work:

 ./simulation 0
 ...Results for run 0:...

 ./simulation 1
 ...Results for run 1:...

static void ns3::RandomVariable::UseDevRandom

(

bool

udr = true

)

[static]

Set seeding behavior.

Specify whether the POSIX device /dev/random is to be used for seeding. When this is used, the underlying generator is seeded with data from /dev/random instead of being seeded based upon the time of day. For this to be effective, it must be called before the creation of the first instance of a RandomVariable or subclass. Example:

 RandomVariable::UseDevRandom();
 UniformVariable x(2,3);  //these are seeded randomly
 ExponentialVariable y(120); //etc

Parameters:

udr

True if /dev/random desired.

static void ns3::RandomVariable::UseGlobalSeed	(	uint32_t	s0,
		uint32_t	s1,
		uint32_t	s2,
		uint32_t	s3,
		uint32_t	s4,
		uint32_t	s5
	)			[static]

Use the global seed to force precisely reproducible results.

It is often desirable to create a simulation that uses random numbers, while at the same time is completely reproducible. Specifying this set of six random seeds initializes the random number generator with the specified seed. Once this is set, all generators will produce fixed output from run to run. This is because each time a new generator is created, the underlying RngStream deterministically creates a new seed based upon the old one, hence a "stream" of RNGs. Example:

 RandomVariable::UseGlobalSeed(...);
 UniformVariable x(2,3);     //these will give the same output everytime
 ExponentialVariable y(120); //as long as the seed stays the same

Parameters:

	s0
	s1
	s2
	s3
	s4
	s5

Returns:

True if seed is valid.

---

The documentation for this class was generated from the following file:

• src/core/random-variable.h