F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

core: (fixes #2513) - Deprecates Mean attribute in ParetoRandomVariable

Browse Source
This commit is contained in:
Tommaso Pecorella
2016-11-08 01:42:06 +01:00
parent 7a7a87a06d
commit bec49d392d
8 changed files with 95 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
CHANGES.html
View File

@@ -61,6 +61,11 @@ us a note on ns-developers mailing list.</p>
</ul>
<h2>Changes to existing API:</h2>
<ul>
<li><b>ParetoRandomVariable</b> "Mean" attribute has been deprecated,
the "Scale" Attribute have to be used instead.
Changing the Mean attribute has no more an effect on the distribution.
See the documentation for the relationship between Mean, Scale and Shape.
</li>
</ul>
<h2>Changes to build system:</h2>
<ul>

1
RELEASE_NOTES
View File

@@ -28,6 +28,7 @@ Bugs fixed
- Bug 2450 - LogDistancePropagationLossModel is not continuous
- Bug 2492 - uan: Make use of RxGain attribute in UanPhyGen class
- Bug 2511 - HT Greenfield is not working
- Bug 2513 - ParetoRandomVariable needs a "scale", not a "mean" attribute.
- Bug 2521 - Include ipv6-option.h in wscript
- Bug 2527 - PrintRoutingTable extended to add an optional Time::Units parameter
- Bug 2530 - Rename aodv::SetBalckListTimeout to aodv::SetBlackListTimeout

18
src/core/examples/main-random-variable-stream.cc
View File

@@ -138,25 +138,25 @@ int main (int argc, char *argv[])
plot.AppendExtra ("set xrange [0:2]");
Ptr<ParetoRandomVariable> x1 = CreateObject<ParetoRandomVariable> ();
x1->SetAttribute ("Mean", DoubleValue (1.0));
x1->SetAttribute ("Scale", DoubleValue (1.0));
x1->SetAttribute ("Shape", DoubleValue (1.5));
plot.AddDataset ( Histogramm (x1, probes, precision,
"ParetoRandomVariable m=1.0 s=1.5") );
"ParetoRandomVariable scale=1.0 shape=1.5") );
Ptr<ParetoRandomVariable> x2 = CreateObject<ParetoRandomVariable> ();
x2->SetAttribute ("Mean", DoubleValue (1.0));
x2->SetAttribute ("Scale", DoubleValue (1.0));
x2->SetAttribute ("Shape", DoubleValue (2.0));
plot.AddDataset ( Histogramm (x2, probes, precision,
"ParetoRandomVariable m=1.0 s=2.0") );
"ParetoRandomVariable scale=1.0 shape=2.0") );
Ptr<ParetoRandomVariable> x3 = CreateObject<ParetoRandomVariable> ();
x3->SetAttribute ("Mean", DoubleValue (1.0));
x3->SetAttribute ("Scale", DoubleValue (1.0));
x3->SetAttribute ("Shape", DoubleValue (2.5));
plot.AddDataset ( Histogramm (x3, probes, precision,
"ParetoRandomVariable m=1.0 s=2.5") );
"ParetoRandomVariable scale=1.0 shape=2.5") );
gnuplots.AddPlot (plot);
}
@@ -171,21 +171,21 @@ int main (int argc, char *argv[])
x1->SetAttribute ("Shape", DoubleValue (1.0));
plot.AddDataset ( Histogramm (x1, probes, precision,
"WeibullRandomVariable m=1.0 s=1.0") );
"WeibullRandomVariable scale=1.0 shape=1.0") );
Ptr<WeibullRandomVariable> x2 = CreateObject<WeibullRandomVariable> ();
x2->SetAttribute ("Scale", DoubleValue (1.0));
x2->SetAttribute ("Shape", DoubleValue (2.0));
plot.AddDataset ( Histogramm (x2, probes, precision,
"WeibullRandomVariable m=1.0 s=2.0") );
"WeibullRandomVariable scale=1.0 shape=2.0") );
Ptr<WeibullRandomVariable> x3 = CreateObject<WeibullRandomVariable> ();
x3->SetAttribute ("Scale", DoubleValue (1.0));
x3->SetAttribute ("Shape", DoubleValue (3.0));
plot.AddDataset ( Histogramm (x3, probes, precision,
"WeibullRandomVariable m=1.0 s=3.0") );
"WeibullRandomVariable scale=1.0 shape=3.0") );
gnuplots.AddPlot (plot);
}

18
src/core/examples/main-random-variable.cc
View File

@@ -138,25 +138,25 @@ int main (int argc, char *argv[])
plot.AppendExtra ("set xrange [0:2]");
Ptr<ParetoRandomVariable> x1 = CreateObject<ParetoRandomVariable> ();
x1->SetAttribute ("Mean", DoubleValue (1.0));
x1->SetAttribute ("Scale", DoubleValue (1.0));
x1->SetAttribute ("Shape", DoubleValue (1.5));
plot.AddDataset ( Histogramm (x1, probes, precision,
"ParetoRandomVariable m=1.0 s=1.5") );
"ParetoRandomVariable scale=1.0 shape=1.5") );
Ptr<ParetoRandomVariable> x2 = CreateObject<ParetoRandomVariable> ();
x2->SetAttribute ("Mean", DoubleValue (1.0));
x2->SetAttribute ("Scale", DoubleValue (1.0));
x2->SetAttribute ("Shape", DoubleValue (2.0));
plot.AddDataset ( Histogramm (x2, probes, precision,
"ParetoRandomVariable m=1.0 s=2.0") );
"ParetoRandomVariable scale=1.0 shape=2.0") );
Ptr<ParetoRandomVariable> x3 = CreateObject<ParetoRandomVariable> ();
x3->SetAttribute ("Mean", DoubleValue (1.0));
x3->SetAttribute ("Scale", DoubleValue (1.0));
x3->SetAttribute ("Shape", DoubleValue (2.5));
plot.AddDataset ( Histogramm (x3, probes, precision,
"ParetoRandomVariable m=1.0 s=2.5") );
"ParetoRandomVariable scale=1.0 shape=2.5") );
gnuplots.AddPlot (plot);
}
@@ -171,21 +171,21 @@ int main (int argc, char *argv[])
x1->SetAttribute ("Shape", DoubleValue (1.0));
plot.AddDataset ( Histogramm (x1, probes, precision,
"WeibullRandomVariable m=1.0 s=1.0") );
"WeibullRandomVariable scale=1.0 shape=1.0") );
Ptr<WeibullRandomVariable> x2 = CreateObject<WeibullRandomVariable> ();
x2->SetAttribute ("Scale", DoubleValue (1.0));
x2->SetAttribute ("Shape", DoubleValue (2.0));
plot.AddDataset ( Histogramm (x2, probes, precision,
"WeibullRandomVariable m=1.0 s=2.0") );
"WeibullRandomVariable scale=1.0 shape=2.0") );
Ptr<WeibullRandomVariable> x3 = CreateObject<WeibullRandomVariable> ();
x3->SetAttribute ("Scale", DoubleValue (1.0));
x3->SetAttribute ("Shape", DoubleValue (3.0));
plot.AddDataset ( Histogramm (x3, probes, precision,
"WeibullRandomVariable m=1.0 s=3.0") );
"WeibullRandomVariable scale=1.0 shape=3.0") );
gnuplots.AddPlot (plot);
}

43
src/core/model/random-variable-stream.cc
View File

@@ -33,6 +33,7 @@
#include "log.h"
#include "rng-stream.h"
#include "rng-seed-manager.h"
#include "unused.h"
#include <cmath>
#include <iostream>
@@ -455,9 +456,15 @@ ParetoRandomVariable::GetTypeId (void)
.SetGroupName ("Core")
.AddConstructor<ParetoRandomVariable> ()
.AddAttribute("Mean", "The mean parameter for the Pareto distribution returned by this RNG stream.",
DoubleValue(1.0),
MakeDoubleAccessor(&ParetoRandomVariable::m_mean),
MakeDoubleChecker<double>())
DoubleValue(0.0),
MakeDoubleAccessor(&ParetoRandomVariable::m_mean),
MakeDoubleChecker<double>(),
TypeId::DEPRECATED,
"Not anymore used. Use 'Scale' instead - changing this attribute has no effect.")
.AddAttribute("Scale", "The scale parameter for the Pareto distribution returned by this RNG stream.",
DoubleValue(1.0),
MakeDoubleAccessor(&ParetoRandomVariable::m_scale),
MakeDoubleChecker<double>())
.AddAttribute("Shape", "The shape parameter for the Pareto distribution returned by this RNG stream.",
DoubleValue(2.0),
MakeDoubleAccessor(&ParetoRandomVariable::m_shape),
@@ -471,23 +478,34 @@ ParetoRandomVariable::GetTypeId (void)
}
ParetoRandomVariable::ParetoRandomVariable ()
{
// m_mean, m_shape, and m_bound are initialized after constructor
// m_shape, m_shape, and m_bound are initialized after constructor
// by attributes
NS_LOG_FUNCTION (this);
NS_UNUSED (m_mean);
}
double
ParetoRandomVariable::GetMean (void) const
{
NS_LOG_FUNCTION (this);
return m_mean;
double mean = std::numeric_limits<double>::infinity();
if (m_shape > 1)
{
mean = m_shape * m_scale / (m_shape -1);
}
return mean;
}
double
ParetoRandomVariable::GetShape (void) const
{
NS_LOG_FUNCTION (this);
return m_shape;
}
double
ParetoRandomVariable::GetBound (void) const
{
@@ -496,11 +514,10 @@ ParetoRandomVariable::GetBound (void) const
}
double
ParetoRandomVariable::GetValue (double mean, double shape, double bound)
ParetoRandomVariable::GetValue (double scale, double shape, double bound)
{
// Calculate the scale parameter.
NS_LOG_FUNCTION (this << mean << shape << bound);
double scale = mean * (shape - 1.0) / shape;
NS_LOG_FUNCTION (this << scale << shape << bound);
while (1)
{
@@ -522,23 +539,23 @@ ParetoRandomVariable::GetValue (double mean, double shape, double bound)
}
}
uint32_t
ParetoRandomVariable::GetInteger (uint32_t mean, uint32_t shape, uint32_t bound)
ParetoRandomVariable::GetInteger (uint32_t scale, uint32_t shape, uint32_t bound)
{
NS_LOG_FUNCTION (this << mean << shape << bound);
return static_cast<uint32_t> ( GetValue (mean, shape, bound) );
NS_LOG_FUNCTION (this << scale << shape << bound);
return static_cast<uint32_t> ( GetValue (scale, shape, bound) );
}
double
ParetoRandomVariable::GetValue (void)
{
NS_LOG_FUNCTION (this);
return GetValue (m_mean, m_shape, m_bound);
return GetValue (m_scale, m_shape, m_bound);
}
uint32_t
ParetoRandomVariable::GetInteger (void)
{
NS_LOG_FUNCTION (this);
return (uint32_t)GetValue (m_mean, m_shape, m_bound);
return (uint32_t)GetValue (m_scale, m_shape, m_bound);
}
NS_OBJECT_ENSURE_REGISTERED(WeibullRandomVariable);

78
src/core/model/random-variable-stream.h
View File

@@ -576,7 +576,7 @@ public:
/**
* \brief Get the next random value, as an unsigned integer from
* the exponential distribution with the specified mean and upper bound.
* \param [in] mean Mean value of the unbounded exponential distributuion.
* \param [in] mean Mean value of the unbounded exponential distribution.
* \param [in] bound Upper bound on values returned.
* \return A random unsigned integer value.
*/
@@ -607,9 +607,9 @@ private:
* The probability density function of a Pareto variable is defined
* over the range [\f$x_m\f$,\f$+\infty\f$) as: \f$ k \frac{x_m^k}{x^{k+1}}\f$
* where \f$x_m > 0\f$ is called the scale parameter and \f$ k > 0\f$
* is called the pareto index or shape.
* is called the Pareto index or shape.
*
* The parameter \f$ x_m \f$ can be infered from the mean and the parameter \f$ k \f$
* The parameter \f$ x_m \f$ can be inferred from the mean and the parameter \f$ k \f$
* with the equation \f$ x_m = mean \frac{k-1}{k}, k > 1\f$.
*
* Since Pareto distributions can theoretically return unbounded values,
@@ -619,11 +619,11 @@ private:
*
* Here is an example of how to use this class:
* \code
* double mean = 5.0;
* double scale = 5.0;
* double shape = 2.0;
*
* Ptr<ParetoRandomVariable> x = CreateObject<ParetoRandomVariable> ();
* x->SetAttribute ("Mean", DoubleValue (mean));
* x->SetAttribute ("Scale", DoubleValue (scale));
* x->SetAttribute ("Shape", DoubleValue (shape));
*
* // The expected value for the mean of the values returned by a
@@ -632,11 +632,7 @@ private:
* // shape * scale
* // E[value] = --------------- ,
* // shape - 1
* //
* // where
* //
* // scale = mean * (shape - 1.0) / shape .
* //
*
* double value = x->GetValue ();
* \endcode
*/
@@ -659,8 +655,15 @@ public:
* \brief Returns the mean parameter for the Pareto distribution returned by this RNG stream.
* \return The mean parameter for the Pareto distribution returned by this RNG stream.
*/
NS_DEPRECATED
double GetMean (void) const;
/**
* \brief Returns the scale parameter for the Pareto distribution returned by this RNG stream.
* \return The scale parameter for the Pareto distribution returned by this RNG stream.
*/
double GetScale (void) const;
/**
* \brief Returns the shape parameter for the Pareto distribution returned by this RNG stream.
* \return The shape parameter for the Pareto distribution returned by this RNG stream.
@@ -674,8 +677,8 @@ public:
double GetBound (void) const;
/**
* \brief Returns a random double from a Pareto distribution with the specified mean, shape, and upper bound.
* \param [in] mean Mean parameter for the Pareto distribution.
* \brief Returns a random double from a Pareto distribution with the specified scale, shape, and upper bound.
* \param [in] scale Mean parameter for the Pareto distribution.
* \param [in] shape Shape parameter for the Pareto distribution.
* \param [in] bound Upper bound on values returned.
* \return A floating point random value.
@@ -688,27 +691,22 @@ public:
* x = \frac{scale}{u^{\frac{1}{shape}}}
* \f]
*
* is a value that would be returned normally, where
*
* \f[
* scale = mean * (shape - 1.0) / shape .
* \f]
* is a value that would be returned normally.
*
* Then \f$(1 - u\f$) is the distance that \f$u\f$ would be from
* \f$1\f$. The value returned in the antithetic case, \f$x'\f$, is
* The value returned in the antithetic case, \f$x'\f$, is
* calculated as
*
* \f[
* x' = \frac{scale}{{(1 - u)}^{\frac{1}{shape}}} ,
* \f]
*
* which now involves the distance \f$u\f$ is from 1 in the denonator.
* which now involves the distance \f$u\f$ is from 1 in the denominator.
*/
double GetValue (double mean, double shape, double bound);
double GetValue (double scale, double shape, double bound);
/**
* \brief Returns a random unsigned integer from a Pareto distribution with the specified mean, shape, and upper bound.
* \param [in] mean Mean parameter for the Pareto distribution.
* \param [in] scale Scale parameter for the Pareto distribution.
* \param [in] shape Shape parameter for the Pareto distribution.
* \param [in] bound Upper bound on values returned.
* \return A random unsigned integer value.
@@ -721,23 +719,18 @@ public:
* x = \frac{scale}{u^{\frac{1}{shape}}}
* \f]
*
* is a value that would be returned normally, where
*
* \f[
* scale = mean * (shape - 1.0) / shape .
* \f]
*
* Then \f$(1 - u\f$) is the distance that \f$u\f$ would be from
* \f$1\f$. The value returned in the antithetic case, \f$x'\f$, is
* is a value that would be returned normally.
*
* The value returned in the antithetic case, \f$x'\f$, is
* calculated as
*
* \f[
* x' = \frac{scale}{{(1 - u)}^{\frac{1}{shape}}} ,
* \f]
*
* which now involves the distance \f$u\f$ is from 1 in the denonator.
* which now involves the distance \f$u\f$ is from 1 in the denominator.
*/
uint32_t GetInteger (uint32_t mean, uint32_t shape, uint32_t bound);
uint32_t GetInteger (uint32_t scale, uint32_t shape, uint32_t bound);
/**
* \brief Returns a random double from a Pareto distribution with the current mean, shape, and upper bound.
@@ -757,15 +750,14 @@ public:
* scale = mean * (shape - 1.0) / shape .
* \f]
*
* Then \f$(1 - u\f$) is the distance that \f$u\f$ would be from
* \f$1\f$. The value returned in the antithetic case, \f$x'\f$, is
* The value returned in the antithetic case, \f$x'\f$, is
* calculated as
*
* \f[
* x' = \frac{scale}{{(1 - u)}^{\frac{1}{shape}}} ,
* \f]
*
* which now involves the distance \f$u\f$ is from 1 in the denonator.
* which now involves the distance \f$u\f$ is from 1 in the denominator.
*
* Note that we have to re-implement this method here because the method is
* overloaded above for the three-argument variant and the c++ name resolution
@@ -786,21 +778,16 @@ public:
* x = \frac{scale}{u^{\frac{1}{shape}}}
* \f]
*
* is a value that would be returned normally, where
*
* \f[
* scale = mean * (shape - 1.0) / shape .
* \f]
*
* Then \f$(1 - u\f$) is the distance that \f$u\f$ would be from
* \f$1\f$. The value returned in the antithetic case, \f$x'\f$, is
* is a value that would be returned normally.
*
* The value returned in the antithetic case, \f$x'\f$, is
* calculated as
*
* \f[
* x' = \frac{scale}{{(1 - u)}^{\frac{1}{shape}}} ,
* \f]
*
* which now involves the distance \f$u\f$ is from 1 in the denonator.
* which now involves the distance \f$u\f$ is from 1 in the denominator.
*/
virtual uint32_t GetInteger (void);
@@ -808,6 +795,9 @@ private:
/** The mean parameter for the Pareto distribution returned by this RNG stream. */
double m_mean;
/** The scale parameter for the Pareto distribution returned by this RNG stream. */
double m_scale;
/** The shape parameter for the Pareto distribution returned by this RNG stream. */
double m_shape;

20
src/core/test/random-variable-stream-test-suite.cc
View File

@@ -1036,11 +1036,8 @@ RandomVariableStreamParetoTestCase::ChiSquaredTest (Ptr<ParetoRandomVariable> p)
double expected[N_BINS];
// Note that this assumes that p has mean equal to 1 and shape equal
// to 2, which are their default values for this distribution.
double mean = 1.0;
double shape = 2.0;
double scale = mean * (shape - 1.0) / shape;
double scale = 1.0;
for (uint32_t i = 0; i < N_BINS; ++i)
{
@@ -1094,15 +1091,14 @@ RandomVariableStreamParetoTestCase::DoRun (void)
NS_TEST_ASSERT_MSG_LT (sum, maxStatistic, "Chi-squared statistic out of range");
double mean = 5.0;
double shape = 2.0;
double scale = mean * (shape - 1.0) / shape;
double scale = 1.0;
double value;
// Create the RNG with the specified range.
Ptr<ParetoRandomVariable> x = CreateObject<ParetoRandomVariable> ();
x->SetAttribute ("Mean", DoubleValue (mean));
x->SetAttribute ("Shape", DoubleValue (shape));
x->SetAttribute ("Scale", DoubleValue (scale));
// Calculate the mean of these values.
sum = 0.0;
@@ -1170,11 +1166,8 @@ RandomVariableStreamParetoAntitheticTestCase::ChiSquaredTest (Ptr<ParetoRandomVa
double expected[N_BINS];
// Note that this assumes that p has mean equal to 1 and shape equal
// to 2, which are their default values for this distribution.
double mean = 1.0;
double shape = 2.0;
double scale = mean * (shape - 1.0) / shape;
double scale = 1.0;
for (uint32_t i = 0; i < N_BINS; ++i)
{
@@ -1232,15 +1225,14 @@ RandomVariableStreamParetoAntitheticTestCase::DoRun (void)
NS_TEST_ASSERT_MSG_LT (sum, maxStatistic, "Chi-squared statistic out of range");
double mean = 5.0;
double shape = 2.0;
double scale = mean * (shape - 1.0) / shape;
double scale = 1.0;
double value;
// Create the RNG with the specified range.
Ptr<ParetoRandomVariable> x = CreateObject<ParetoRandomVariable> ();
x->SetAttribute ("Mean", DoubleValue (mean));
x->SetAttribute ("Shape", DoubleValue (shape));
x->SetAttribute ("Scale", DoubleValue (scale));
// Make this generate antithetic values.
x->SetAttribute ("Antithetic", BooleanValue (true));

1
src/core/test/rng-test-suite.cc
View File

@@ -408,6 +408,7 @@ RngParetoTestCase::DoRun (void)
{
Ptr<ParetoRandomVariable> e = CreateObject<ParetoRandomVariable> ();
e->SetAttribute ("Shape", DoubleValue (1.5));
e->SetAttribute ("Scale", DoubleValue (0.33333333));
double result = ChiSquaredTest (e);
sum += result;
}