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
 TestCase (const TestCase &)=delete
 
virtual ~TestCase ()
 Destructor. More...
 
std::string GetName (void) const
 
TestCaseoperator= (const TestCase &)=delete
 

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 61 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 75 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 196 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

Average the chi squared value over some number of runs, each run with a new instance of the random number generator.

Parameters
[in]generatorThe factory to create instances of the random number generator.
[in]nRunsThe number of runs to average over.
Returns
The average chi square over the number of runs.

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

References ChiSquaredTest(), ns3::test::RandomVariable::TestCaseBase::RngGeneratorBase::Create(), NS_LOG_FUNCTION, test-ns3::result, and sample-rng-plot::rng.

Referenced by 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().

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

◆ 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 257 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.

This test suite is designed to be run with both deterministic and random seed and run number values. Deterministic values can be used for basic regression testing; random values can be used to more exhaustively test the generated streams, with the side effect of occasional test failures.

By default, this test suite will use the default values of RngSeed = 1 and RngRun = 1. Users can configure any other seed and run number in the usual way, but the special value of RngRun = 0 results in selecting a RngSeed value that corresponds 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 allows the test to be exposed to a wider range of seeds.

In either case, the values produced will be checked with a chi-squared test.

For example, this command will cause this test suite to use the deterministic value of seed=3 and default run number=1 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" ./ns3 run "test-runner --suite=random-variable-stream-generators"

Conversely, this command will cause this test suite to use a seed based on time-of-day, and run number=0: NS_GLOBAL_VALUE="RngRun=0" ./test.py -s random-variable-stream-generators

Definition at line 318 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(), ns3::test::RandomVariable::EmpiricalAntitheticTestCase::DoRun(), and ns3::test::RandomVariable::NormalCachingTestCase::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 91 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 343 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 65 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 67 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: