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.

double	Average (Ptr< RandomVariableStream > rng) const
	Compute the average of a random variable.

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.

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.

virtual double	ChiSquaredTest (Ptr< RandomVariableStream > rng) const
	Compute the chi square value from a random variable.

void	SetTestSuiteSeed ()
	Set the seed used for this test suite.

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.

double	Variance (Ptr< RandomVariableStream > rng, double average) const
	Compute the variance of a random variable.

Public Member Functions inherited from ns3::TestCase
	TestCase (const TestCase &)=delete

virtual	~TestCase ()
	Destructor.

std::string	GetName () const

TestCase &	operator= (const TestCase &)=delete

Static Public Attributes
static const uint32_t	N_BINS {50}
	Number of bins for sampling the distributions.

static const uint32_t	N_MEASUREMENTS {1000000}
	Number of samples to draw when populating the distributions.

static const uint32_t	N_RUNS {5}
	Number of retry attempts to pass a chi-square test.

Static Public Attributes inherited from ns3::TestCase
static constexpr auto	QUICK = Duration::QUICK
	Deprecated test duration simple enums.

static constexpr auto	EXTENSIVE = Duration::EXTENSIVE

static constexpr auto	TAKES_FOREVER = Duration::TAKES_FOREVER

Private Attributes
bool	m_seedSet = false
	`true` if we've already set the seed the correctly.

Additional Inherited Members
Public Types inherited from ns3::TestCase
enum class	Duration { 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.

void	AddTestCase (TestCase *testCase, Duration duration=Duration::QUICK)
	Add an individual child TestCase to this test suite.

TestCase *	GetParent () const
	Get the parent of this TestCase.

bool	IsStatusFailure () const
	Check if any tests failed.

bool	IsStatusSuccess () const
	Check if all tests passed.

void	SetDataDir (std::string directory)
	Set the data directory where reference trace files can be found.

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.

bool	MustAssertOnFailure () const
	Check if this run should assert on failure.

bool	MustContinueOnFailure () const
	Check if this run should continue on failure.

std::string	CreateDataDirFilename (std::string filename)
	Construct the full path to a file in the data directory.

std::string	CreateTempDirFilename (std::string filename)
	Construct the full path to a file in a temporary directory.

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] name The 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

Compute the average of a random variable.

Parameters

[in] rng The random variable to sample.

Returns: The average of N_MEASUREMENTS samples.

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

References N_MEASUREMENTS, and NS_LOG_FUNCTION.

Here is the caller graph for this function:

◆ 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]	h	The histogram, which defines the binning for sampling.
[in]	expected	The expected distribution.
[in]	rng	The random variable to sample.

Returns: The chi square value.

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

References N_MEASUREMENTS, NS_ASSERT_MSG, and NS_LOG_FUNCTION.

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]	generator	The factory to create instances of the random number generator.
[in]	nRuns	The number of runs to average over.

Returns: The average chi square over the number of runs.

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

References ChiSquaredTest(), ns3::test::RandomVariable::TestCaseBase::RngGeneratorBase::Create(), and NS_LOG_FUNCTION.

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] rng The random number generator to test.

Returns: The chi squared value.

Definition at line 269 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 ( )

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 328 of file random-variable-stream-test-suite.cc.

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

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]	h	The GSL histogram to configure.
[in]	start	The minimum value of the lowest bin.
[in]	end	The maximum value of the last bin.
[in]	underflow	If `true` the lowest bin should contain the underflow,
[in]	overflow	If `true` 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 NS_LOG_FUNCTION.