The Random Number Generator (RNG) that has a specified empirical distribution. More...
#include "random-variable-stream.h"
Public Member Functions | |
EmpiricalRandomVariable () | |
Creates an empirical RNG that has a specified, empirical distribution, and configured for interpolating mode. More... | |
void | CDF (double v, double c) |
Specifies a point in the empirical distribution. More... | |
virtual uint32_t | GetInteger () |
Get the next random value drawn from the distribution. More... | |
double | GetValue () override |
Get the next random value drawn from the distribution. More... | |
virtual double | Interpolate () |
Returns the next value in the empirical distribution using linear interpolation. More... | |
bool | SetInterpolate (bool interpolate) |
Switch the mode between sampling the CDF and interpolating. More... | |
Public Member Functions inherited from ns3::RandomVariableStream | |
RandomVariableStream () | |
Default constructor. More... | |
RandomVariableStream (const RandomVariableStream &)=delete | |
~RandomVariableStream () override | |
Destructor. More... | |
int64_t | GetStream () const |
Returns the stream number for the RngStream. More... | |
bool | IsAntithetic () const |
Check if antithetic values will be generated. More... | |
RandomVariableStream & | operator= (const RandomVariableStream &)=delete |
void | SetAntithetic (bool isAntithetic) |
Specify whether antithetic values should be generated. More... | |
void | SetStream (int64_t stream) |
Specifies the stream number for the RngStream. More... | |
Public Member Functions inherited from ns3::Object | |
Object () | |
Constructor. More... | |
~Object () override | |
Destructor. More... | |
void | AggregateObject (Ptr< Object > other) |
Aggregate two Objects together. More... | |
void | Dispose () |
Dispose of this Object. More... | |
AggregateIterator | GetAggregateIterator () const |
Get an iterator to the Objects aggregated to this one. More... | |
TypeId | GetInstanceTypeId () const override |
Get the most derived TypeId for this Object. More... | |
template<typename T > | |
Ptr< T > | GetObject () const |
Get a pointer to the requested aggregated Object. More... | |
template<> | |
Ptr< Object > | GetObject () const |
Specialization of () for objects of type ns3::Object. More... | |
template<typename T > | |
Ptr< T > | GetObject (TypeId tid) const |
Get a pointer to the requested aggregated Object by TypeId. More... | |
template<> | |
Ptr< Object > | GetObject (TypeId tid) const |
Specialization of (TypeId tid) for objects of type ns3::Object. More... | |
void | Initialize () |
Invoke DoInitialize on all Objects aggregated to this one. More... | |
bool | IsInitialized () const |
Check if the object has been initialized. More... | |
Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter > | |
SimpleRefCount () | |
Default constructor. More... | |
SimpleRefCount (const SimpleRefCount &o[[maybe_unused]]) | |
Copy constructor. More... | |
uint32_t | GetReferenceCount () const |
Get the reference count of the object. More... | |
SimpleRefCount & | operator= (const SimpleRefCount &o[[maybe_unused]]) |
Assignment operator. More... | |
void | Ref () const |
Increment the reference count. More... | |
void | Unref () const |
Decrement the reference count. More... | |
Public Member Functions inherited from ns3::ObjectBase | |
virtual | ~ObjectBase () |
Virtual destructor. More... | |
void | GetAttribute (std::string name, AttributeValue &value) const |
Get the value of an attribute, raising fatal errors if unsuccessful. More... | |
bool | GetAttributeFailSafe (std::string name, AttributeValue &value) const |
Get the value of an attribute without raising errors. More... | |
void | SetAttribute (std::string name, const AttributeValue &value) |
Set a single attribute, raising fatal errors if unsuccessful. More... | |
bool | SetAttributeFailSafe (std::string name, const AttributeValue &value) |
Set a single attribute without raising errors. More... | |
bool | TraceConnect (std::string name, std::string context, const CallbackBase &cb) |
Connect a TraceSource to a Callback with a context. More... | |
bool | TraceConnectWithoutContext (std::string name, const CallbackBase &cb) |
Connect a TraceSource to a Callback without a context. More... | |
bool | TraceDisconnect (std::string name, std::string context, const CallbackBase &cb) |
Disconnect from a TraceSource a Callback previously connected with a context. More... | |
bool | TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb) |
Disconnect from a TraceSource a Callback previously connected without a context. More... | |
Static Public Member Functions | |
static TypeId | GetTypeId () |
Register this type. More... | |
Static Public Member Functions inherited from ns3::RandomVariableStream | |
static TypeId | GetTypeId () |
Register this type. More... | |
Static Public Member Functions inherited from ns3::Object | |
static TypeId | GetTypeId () |
Register this type. More... | |
Static Public Member Functions inherited from ns3::ObjectBase | |
static TypeId | GetTypeId () |
Get the type ID. More... | |
Private Member Functions | |
double | DoInterpolate (double r) |
Linear interpolation between two points on the CDF to estimate the value at r . More... | |
double | DoSampleCDF (double r) |
Sample the CDF as a histogram (without interpolation). More... | |
bool | PreSample (double &value) |
Do the initial rng draw and check against the extrema. More... | |
void | Validate () |
Check that the CDF is valid. More... | |
Private Attributes | |
std::map< double, double > | m_empCdf |
The map of CDF points (x, F(x)). More... | |
bool | m_interpolate |
If true GetValue will interpolate, otherwise treat CDF as normal histogram. More... | |
bool | m_validated |
true once the CDF has been validated. More... | |
Additional Inherited Members | |
Protected Member Functions inherited from ns3::RandomVariableStream | |
RngStream * | Peek () const |
Get the pointer to the underlying RngStream. More... | |
Protected Member Functions inherited from ns3::Object | |
Object (const Object &o) | |
Copy an Object. More... | |
virtual void | DoDispose () |
Destructor implementation. More... | |
virtual void | DoInitialize () |
Initialize() implementation. More... | |
virtual void | NotifyNewAggregate () |
Notify all Objects aggregated to this one of a new Object being aggregated. More... | |
Protected Member Functions inherited from ns3::ObjectBase | |
void | ConstructSelf (const AttributeConstructionList &attributes) |
Complete construction of ObjectBase; invoked by derived classes. More... | |
virtual void | NotifyConstructionCompleted () |
Notifier called once the ObjectBase is fully constructed. More... | |
Related Functions inherited from ns3::ObjectBase | |
static TypeId | GetObjectIid () |
Ensure the TypeId for ObjectBase gets fully configured to anchor the inheritance tree properly. More... | |
The Random Number Generator (RNG) that has a specified empirical distribution.
Defines a random variable that has a specified, empirical distribution. The cumulative probability distribution function (CDF) is specified by a series of calls to the CDF() member function, specifying a value and the probability that the distribution is less than the specified value. When random values are requested, a uniform random variable is used to select a probability, and the return value is chosen as the largest input value with CDF less than the random value. This method is known as inverse transform sampling.
This generator has two modes: sampling and interpolating. In sampling mode this random variable generator treats the CDF as an exact histogram and returns one of the histogram inputs exactly. This is appropriate when the configured CDF represents the exact probability distribution, for a categorical variable, for example.
In interpolating mode this random variable generator linearly interpolates between the CDF values defining the histogram bins. This is appropriate when the configured CDF is an approximation to a continuous underlying probability distribution.
For historical reasons the default is sampling. To switch modes use the Interpolate
Attribute, or call SetInterpolate(). You can change modes at any time.
If you find yourself switching frequently it could be simpler to set the mode to sampling, then use the GetValue() function for sampled values, and Interpolate() function for interpolated values.
The CDF need not start with a probability of zero, nor end with a probability of 1.0. If the selected uniform random value is less than the probability of the first CDF point, that point is selected. If is greater than the probability of the last CDF point the last point is selected. In either case the interpolating mode will not interpolate (since there is no value beyond the first/last to work with), but simply return the extremal CDF value, as in sampling.
Here is an example of how to use this class:
The expected values and probabilities returned by GetValue() are
Value | Probability |
---|---|
0.0 | 0 |
5.0 | 25% |
10.0 | 75% |
The only two values ever returned are 5 and 10, in the ratio 1:3.
If instead you want linear interpolation between the points of the CDF use the Interpolate() function:
double interp = x->Interpolate ();
This will return continuous values on the range [0,1), 25% of the time less than 5, and 75% of the time between 5 and 10.
See empirical-random-variable-example.cc for an example.
If an instance of this RNG is configured to return antithetic values, the actual value returned, , is generated by using instead. of on [0, 1].
Definition at line 1971 of file random-variable-stream.h.
ns3::EmpiricalRandomVariable::EmpiricalRandomVariable | ( | ) |
Creates an empirical RNG that has a specified, empirical distribution, and configured for interpolating mode.
Definition at line 1554 of file random-variable-stream.cc.
References NS_LOG_FUNCTION.
void ns3::EmpiricalRandomVariable::CDF | ( | double | v, |
double | c | ||
) |
Specifies a point in the empirical distribution.
[in] | v | The function value for this point |
[in] | c | Probability that the function is less than or equal to v In other words this is cumulative distribution function at v . |
Definition at line 1680 of file random-variable-stream.cc.
References m_empCdf, NS_LOG_FUNCTION, and NS_LOG_WARN.
|
private |
Linear interpolation between two points on the CDF to estimate the value at r
.
[in] | r | The argument value to interpolate to. |
Definition at line 1653 of file random-variable-stream.cc.
References m_empCdf, NS_LOG_FUNCTION, and prev.
Referenced by GetValue(), and Interpolate().
|
private |
Sample the CDF as a histogram (without interpolation).
[in] | r | The CDF value at which to sample the CDF. |
r
. Definition at line 1626 of file random-variable-stream.cc.
References m_empCdf, and NS_LOG_FUNCTION.
Referenced by GetValue().
|
virtual |
Get the next random value drawn from the distribution.
Reimplemented from ns3::RandomVariableStream.
Definition at line 155 of file random-variable-stream.cc.
|
static |
Register this type.
Definition at line 1538 of file random-variable-stream.cc.
References m_interpolate, ns3::MakeBooleanAccessor(), ns3::MakeBooleanChecker(), and ns3::TypeId::SetParent().
|
overridevirtual |
Get the next random value drawn from the distribution.
Implements ns3::RandomVariableStream.
Definition at line 1603 of file random-variable-stream.cc.
References DoInterpolate(), DoSampleCDF(), m_interpolate, NS_LOG_FUNCTION, and PreSample().
|
virtual |
Returns the next value in the empirical distribution using linear interpolation.
Definition at line 1637 of file random-variable-stream.cc.
References DoInterpolate(), NS_LOG_FUNCTION, and PreSample().
|
private |
Do the initial rng draw and check against the extrema.
If the extrema apply, value
will have the extremal value and the return will be true
.
If the extrema do not apply value
will have the URNG value and the return will be false
.
[out] | value | The extremal value, or the URNG. |
true
if value
is the extremal result, or false
if value
is the URNG value. Definition at line 1570 of file random-variable-stream.cc.
References ns3::RandomVariableStream::IsAntithetic(), m_empCdf, m_validated, NS_LOG_FUNCTION, ns3::RandomVariableStream::Peek(), ns3::RngStream::RandU01(), and Validate().
Referenced by GetValue(), and Interpolate().
bool ns3::EmpiricalRandomVariable::SetInterpolate | ( | bool | interpolate | ) |
Switch the mode between sampling the CDF and interpolating.
The default mode is sampling.
[in] | interpolate | If true set to interpolation, otherwise sampling. |
Definition at line 1561 of file random-variable-stream.cc.
References m_interpolate, NS_LOG_FUNCTION, and prev.
|
private |
Check that the CDF is valid.
A valid CDF has
It is a fatal error to fail validation.
Definition at line 1697 of file random-variable-stream.cc.
References m_empCdf, m_validated, NS_FATAL_ERROR, and NS_LOG_FUNCTION.
Referenced by PreSample().
|
private |
The map of CDF points (x, F(x)).
The CDF points are stored in the std::map in reverse order, as follows: Key: CDF F(x) [0, 1] | Value: domain value (x) [-inf, inf].
Definition at line 2069 of file random-variable-stream.h.
Referenced by CDF(), DoInterpolate(), DoSampleCDF(), PreSample(), and Validate().
|
private |
If true
GetValue will interpolate, otherwise treat CDF as normal histogram.
Definition at line 2074 of file random-variable-stream.h.
Referenced by GetTypeId(), GetValue(), and SetInterpolate().
|
private |
true
once the CDF has been validated.
Definition at line 2063 of file random-variable-stream.h.
Referenced by PreSample(), and Validate().