A Discrete-Event Network Simulator
API
ns3::test::RandomVariable::TestCaseBase Class Reference

Base class for RandomVariableStream test suites. More...

+ Inheritance diagram for ns3::test::RandomVariable::TestCaseBase:
+ Collaboration diagram for ns3::test::RandomVariable::TestCaseBase:

Classes

class  RngGenerator
 Factory class to create new instances of a particular random variable stream. More...
 
class  RngGeneratorBase
 A factory base class to create new instances of a random variable. More...
 

Public Member Functions

 TestCaseBase (std::string name)
 Constructor. More...
 
double Average (Ptr< RandomVariableStream > rng) const
 Compute the average of a random variable. More...
 
double ChiSquared (gsl_histogram *h, const std::vector< double > &expected, Ptr< RandomVariableStream > rng) const
 Compute the chi squared value of a sampled distribution compared to the expected distribution. More...
 
double ChiSquaredsAverage (const RngGeneratorBase *generator, std::size_t nRuns) const
 Average the chi squared value over some number of runs, each run with a new instance of the random number generator. More...
 
virtual double ChiSquaredTest (Ptr< RandomVariableStream > rng) const
 Compute the chi square value from a random variable. More...
 
void SetTestSuiteSeed (void)
 Set the seed used for this test suite. More...
 
std::vector< double > UniformHistogramBins (gsl_histogram *h, double start, double end, bool underflow=true, bool overflow=true) const
 Configure a GSL histogram with uniform bins, with optional under/over-flow bins. More...
 
- Public Member Functions inherited from ns3::TestCase
virtual ~TestCase ()
 Destructor. More...
 
std::string GetName (void) const
 

Static Public Attributes

static const uint32_t N_BINS {50}
 Number of bins for sampling the distributions. More...
 
static const uint32_t N_MEASUREMENTS {1000000}
 Number of samples to draw when populating the distributions. More...
 
static const uint32_t N_RUNS {5}
 Number of retry attempts to pass a chi-square test. More...
 

Private Attributes

bool m_seedSet = false
 true if we've already set the seed the correctly. More...
 

Additional Inherited Members

- Public Types inherited from ns3::TestCase
enum  TestDuration { QUICK = 1, EXTENSIVE = 2, TAKES_FOREVER = 3 }
 How long the test takes to execute. More...
 
- Protected Member Functions inherited from ns3::TestCase
 TestCase (std::string name)
 Constructor. More...
 
void AddTestCase (TestCase *testCase, TestDuration duration=QUICK)
 Add an individual child TestCase to this test suite. More...
 
TestCaseGetParent () const
 Get the parent of this TestCsse. More...
 
bool IsStatusFailure (void) const
 Check if any tests failed. More...
 
bool IsStatusSuccess (void) const
 Check if all tests passed. More...
 
void SetDataDir (std::string directory)
 Set the data directory where reference trace files can be found. More...
 
void ReportTestFailure (std::string cond, std::string actual, std::string limit, std::string message, std::string file, int32_t line)
 Log the failure of this TestCase. More...
 
bool MustAssertOnFailure (void) const
 Check if this run should assert on failure. More...
 
bool MustContinueOnFailure (void) const
 Check if this run should continue on failure. More...
 
std::string CreateDataDirFilename (std::string filename)
 Construct the full path to a file in the data directory. More...
 
std::string CreateTempDirFilename (std::string filename)
 Construct the full path to a file in a temporary directory. More...
 

Detailed Description

Base class for RandomVariableStream test suites.

Definition at line 54 of file random-variable-stream-test-suite.cc.

Constructor & Destructor Documentation

◆ TestCaseBase()

ns3::test::RandomVariable::TestCaseBase::TestCaseBase ( std::string  name)
inline

Constructor.

Parameters
[in]nameThe test case name.

Definition at line 68 of file random-variable-stream-test-suite.cc.

Member Function Documentation

◆ Average()

double ns3::test::RandomVariable::TestCaseBase::Average ( Ptr< RandomVariableStream rng) const
inline

◆ ChiSquared()

double ns3::test::RandomVariable::TestCaseBase::ChiSquared ( gsl_histogram *  h,
const std::vector< double > &  expected,
Ptr< RandomVariableStream rng 
) const
inline

Compute the chi squared value of a sampled distribution compared to the expected distribution.

This function captures the actual computation of the chi square, given an expected distribution.

The random variable is sampled N_MEASUREMENTS times, filling a histogram. The chi square value is formed by comparing to the expected distribution.

Parameters
[in,out]hThe histogram, which defines the binning for sampling.
[in]expectedThe expected distribution.
[in]rngThe random variable to sample.
Returns
The chi square value.

Definition at line 189 of file random-variable-stream-test-suite.cc.

References N_MEASUREMENTS, NS_ASSERT_MSG, NS_LOG_FUNCTION, and sample-rng-plot::rng.

Referenced by ns3::test::RandomVariable::UniformTestCase::ChiSquaredTest(), ns3::test::RandomVariable::UniformAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::NormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::NormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ErlangTestCase::ChiSquaredTest(), and ns3::test::RandomVariable::ErlangAntitheticTestCase::ChiSquaredTest().

+ Here is the caller graph for this function:

◆ ChiSquaredsAverage()

double ns3::test::RandomVariable::TestCaseBase::ChiSquaredsAverage ( const RngGeneratorBase generator,
std::size_t  nRuns 
) const
inline

◆ ChiSquaredTest()

virtual double ns3::test::RandomVariable::TestCaseBase::ChiSquaredTest ( Ptr< RandomVariableStream rng) const
inlinevirtual

Compute the chi square value from a random variable.

This function sets up the binning and expected distribution needed to actually compute the chi squared value, which should be done by a call to ChiSquared.

This is the point of customization expected to be implemented in derived classes with the appropriate histogram binning and expected distribution. For example

SomeRngTestCase::ChiSquaredTest (Ptr<RandomVariableStream> rng) const { gsl_histogram * h = gsl_histogram_alloc (N_BINS); auto range = UniformHistogramBins (h, -4., 4.); std::vector<double> expected (N_BINS); // Populated expected for (std::size_t i = 0; i < N_BINS; ++i) { expected[i] = ...; expected[i] *= N_MEASUREMENTS; } double chiSquared = ChiSquared (h, expected, rng); gsl_histogram_free (h); return chiSquared; }

Parameters
[in]rngThe random number generator to test.
Returns
The chi squared value.

Reimplemented in ns3::test::RandomVariable::ErlangAntitheticTestCase, ns3::test::RandomVariable::ErlangTestCase, ns3::test::RandomVariable::GammaAntitheticTestCase, ns3::test::RandomVariable::GammaTestCase, ns3::test::RandomVariable::LogNormalAntitheticTestCase, ns3::test::RandomVariable::LogNormalTestCase, ns3::test::RandomVariable::WeibullAntitheticTestCase, ns3::test::RandomVariable::WeibullTestCase, ns3::test::RandomVariable::ParetoAntitheticTestCase, ns3::test::RandomVariable::ParetoTestCase, ns3::test::RandomVariable::ExponentialAntitheticTestCase, ns3::test::RandomVariable::ExponentialTestCase, ns3::test::RandomVariable::NormalAntitheticTestCase, ns3::test::RandomVariable::NormalTestCase, ns3::test::RandomVariable::UniformAntitheticTestCase, and ns3::test::RandomVariable::UniformTestCase.

Definition at line 250 of file random-variable-stream-test-suite.cc.

Referenced by ChiSquaredsAverage().

+ Here is the caller graph for this function:

◆ SetTestSuiteSeed()

void ns3::test::RandomVariable::TestCaseBase::SetTestSuiteSeed ( void  )
inline

Set the seed used for this test suite.

Over time, this test suite is designed to be run with varying seed values so that the distributions can be evaluated with chi-squared tests. To enable this, normal invocation of this test suite will result in a seed value corresponding to the seconds since epoch (time (0) from ctime). Note: this is not a recommended practice for seeding normal simulations, as described in the ns-3 manual, but suits our purposes here.

However, we also want to provide the ability to run this test suite with a repeatable value, such as when the seed or run number is configured to a specific value. Therefore, we adopt the following policy. When the test program is being run with the default global values for seed and run number, this function will instead pick a random, time-based seed for use within this test suite. If the global values for seed or run number have been configured differently from the default values, the global seed value will be used instead of the time-based one.

For example, this command will cause this test suite to use the deterministic value of seed=3 every time: NS_GLOBAL_VALUE="RngSeed=3" ./test.py -s random-variable-stream-generators or equivalently (to see log output): NS_LOG="RandomVariableStreamGenerators" NS_GLOBAL_VALUE="RngSeed=3" ./waf –run "test-runner --suite=random-variable-stream-generators" Similarly, if the value of RngRun is not set to 1, the globals will be used.

Definition at line 309 of file random-variable-stream-test-suite.cc.

References ns3::RngSeedManager::GetRun(), ns3::RngSeedManager::GetSeed(), m_seedSet, NS_LOG_DEBUG, and ns3::RngSeedManager::SetSeed().

Referenced by ns3::test::RandomVariable::UniformTestCase::DoRun(), ns3::test::RandomVariable::UniformAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ConstantTestCase::DoRun(), ns3::test::RandomVariable::SequentialTestCase::DoRun(), ns3::test::RandomVariable::NormalTestCase::DoRun(), ns3::test::RandomVariable::NormalAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ExponentialTestCase::DoRun(), ns3::test::RandomVariable::ExponentialAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ParetoTestCase::DoRun(), ns3::test::RandomVariable::ParetoAntitheticTestCase::DoRun(), ns3::test::RandomVariable::WeibullTestCase::DoRun(), ns3::test::RandomVariable::WeibullAntitheticTestCase::DoRun(), ns3::test::RandomVariable::LogNormalTestCase::DoRun(), ns3::test::RandomVariable::LogNormalAntitheticTestCase::DoRun(), ns3::test::RandomVariable::GammaTestCase::DoRun(), ns3::test::RandomVariable::GammaAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ErlangTestCase::DoRun(), ns3::test::RandomVariable::ErlangAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ZipfTestCase::DoRun(), ns3::test::RandomVariable::ZipfAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ZetaTestCase::DoRun(), ns3::test::RandomVariable::ZetaAntitheticTestCase::DoRun(), ns3::test::RandomVariable::DeterministicTestCase::DoRun(), ns3::test::RandomVariable::EmpiricalTestCase::DoRun(), and ns3::test::RandomVariable::EmpiricalAntitheticTestCase::DoRun().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ UniformHistogramBins()

std::vector<double> ns3::test::RandomVariable::TestCaseBase::UniformHistogramBins ( gsl_histogram *  h,
double  start,
double  end,
bool  underflow = true,
bool  overflow = true 
) const
inline

Configure a GSL histogram with uniform bins, with optional under/over-flow bins.

Parameters
[in,out]hThe GSL histogram to configure.
[in]startThe minimum value of the lowest bin.
[in]endThe maximum value of the last bin.
[in]underflowIf true the lowest bin should contain the underflow,
[in]overflowIf ture the highest bin should contain the overflow.
Returns
A vector of the bin edges, including the top of the highest bin. This vector has one more entry than the number of bins in the histogram.

Definition at line 84 of file random-variable-stream-test-suite.cc.

References max, NS_LOG_FUNCTION, and visualizer.core::start().

Referenced by ns3::test::RandomVariable::NormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::NormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ErlangTestCase::ChiSquaredTest(), and ns3::test::RandomVariable::ErlangAntitheticTestCase::ChiSquaredTest().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Member Data Documentation

◆ m_seedSet

bool ns3::test::RandomVariable::TestCaseBase::m_seedSet = false
private

true if we've already set the seed the correctly.

Definition at line 334 of file random-variable-stream-test-suite.cc.

Referenced by SetTestSuiteSeed().

◆ N_BINS

const uint32_t ns3::test::RandomVariable::TestCaseBase::N_BINS {50}
static

Number of bins for sampling the distributions.

Definition at line 58 of file random-variable-stream-test-suite.cc.

Referenced by ns3::test::RandomVariable::UniformTestCase::ChiSquaredTest(), ns3::test::RandomVariable::UniformAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::NormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::NormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ErlangTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ErlangAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::UniformTestCase::DoRun(), ns3::test::RandomVariable::UniformAntitheticTestCase::DoRun(), ns3::test::RandomVariable::NormalTestCase::DoRun(), ns3::test::RandomVariable::NormalAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ExponentialTestCase::DoRun(), ns3::test::RandomVariable::ExponentialAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ParetoTestCase::DoRun(), ns3::test::RandomVariable::ParetoAntitheticTestCase::DoRun(), ns3::test::RandomVariable::WeibullTestCase::DoRun(), ns3::test::RandomVariable::WeibullAntitheticTestCase::DoRun(), ns3::test::RandomVariable::LogNormalTestCase::DoRun(), ns3::test::RandomVariable::LogNormalAntitheticTestCase::DoRun(), ns3::test::RandomVariable::GammaTestCase::DoRun(), ns3::test::RandomVariable::GammaAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ErlangTestCase::DoRun(), and ns3::test::RandomVariable::ErlangAntitheticTestCase::DoRun().

◆ N_MEASUREMENTS

const uint32_t ns3::test::RandomVariable::TestCaseBase::N_MEASUREMENTS {1000000}
static

Number of samples to draw when populating the distributions.

Definition at line 60 of file random-variable-stream-test-suite.cc.

Referenced by Average(), ChiSquared(), ns3::test::RandomVariable::UniformTestCase::ChiSquaredTest(), ns3::test::RandomVariable::UniformAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::NormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::NormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ExponentialAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ParetoAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullTestCase::ChiSquaredTest(), ns3::test::RandomVariable::WeibullAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalTestCase::ChiSquaredTest(), ns3::test::RandomVariable::LogNormalAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaTestCase::ChiSquaredTest(), ns3::test::RandomVariable::GammaAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ErlangTestCase::ChiSquaredTest(), ns3::test::RandomVariable::ErlangAntitheticTestCase::ChiSquaredTest(), ns3::test::RandomVariable::UniformTestCase::DoRun(), ns3::test::RandomVariable::UniformAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ConstantTestCase::DoRun(), ns3::test::RandomVariable::NormalTestCase::DoRun(), ns3::test::RandomVariable::NormalAntitheticTestCase::DoRun(), ns3::test::RandomVariable::ExponentialTestCase::DoRun(), ns3::test::RandomVariable::ExponentialAntitheticTestCase::DoRun(), ns3::test::RandomVariable::EmpiricalTestCase::DoRun(), and ns3::test::RandomVariable::EmpiricalAntitheticTestCase::DoRun().

◆ N_RUNS


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