Class for digital nets in Dakota. More...

Inheritance diagram for DigitalNet:

Public Member Functions
	DigitalNet (const UInt64Matrix &generatingMatrices, int mMax, int tMax, int tScramble, bool digitalShiftFlag, bool scramblingFlag, int seedValue, DigitalNetOrdering ordering, bool mostSignificantBit, short outputLevel)
	Default constructor. More...

	DigitalNet (const UInt64Matrix &generatingMatrices, int mMax, int tMax)
	A constructor that uses gray code ordering and a digital shift with linear matrix scramble. More...

	DigitalNet (int seedValue)
	A constructor with only the random seed as argument.

	DigitalNet ()
	A constructor with no arguments.

	DigitalNet (ProblemDescDB &problem_db)
	A constructor that takes a problem description database.

	DigitalNet (std::tuple< UInt64Matrix, int, int > data, ProblemDescDB &problem_db)
	A constructor that takes a tuple and a problem description database The tuple contains the generating matrices, corresponding log2 of the maximum number of points, number of bits in each integer of the generating matrices, and the number of rows in the linear scramble matrix. More...

	~DigitalNet ()
	Destructor.

void	randomize ()
	Randomize this digital net NOTE: required for 'unique' sampling in `NonDLowDiscrepancySampling`

void	digital_shift ()
	Digitally shift this digital net.

void	no_digital_shift ()
	Do not digitally shift this digital net.

void	scramble ()
	Apply linear matrix scramble to this digital net.

void	no_scrambling ()
	Do not apply linear matrix scramble to this digital net.

Public Member Functions inherited from LowDiscrepancySequence
	LowDiscrepancySequence (int mMax, int dMax, int seedValue, short outputLevel)
	Default constructor. More...

void	get_points (RealMatrix &points)
	Get points from this low-discrepancy generator This function will store the points in-place in the matrix `points` Each column of `points` contains a `dimension`-dimensional point where `dimension` is equal to the number of rows of `points` and the number of points is equal to the number of columns of `points`

void	get_points (const size_t n, RealMatrix &points)
	Get the first `n` points from this low-discrepancy generator This function will store the points in-place in the matrix `points` Each column of `points` contains a `dimension`-dimensional point where `dimension` is equal to the number of rows of `points`

void	get_points (const size_t nMin, const size_t nMax, RealMatrix &points)
	Generates low-discrepancy points between given indices Returns the points with index `nMin`, `nMin` + 1, ..., `nMax` - 1 This function will store the points in-place in the matrix `points` Each column of `points` contains a `dimension`-dimensional point. More...

Private Member Functions
std::tuple< UInt64Matrix, int, int >	get_data (ProblemDescDB &problem_db)
	Extract the generating matrices, corresponding log2 of the maximum number of points and number of bits in each integer of the generating matrices from the given problem. More...

const std::tuple< UInt64Matrix, int, int >	get_generating_matrices_from_file (ProblemDescDB &problem_db)
	Case I: the generating matrices are provided in an external file. More...

const std::tuple< UInt64Matrix, int, int >	get_inline_generating_matrices (ProblemDescDB &problem_db)
	Case II: the generating matrices are provided in the input file. More...

const std::tuple< UInt64Matrix, int, int >	get_default_generating_matrices (ProblemDescDB &problem_db)
	Case III: a set of default generating matrices has been selected. More...

void	digital_shift (int seed)
	Apply digital shift to this digital net Uses the given seed to initialize the RNG When the seed is < 0, the random shift will be removed. More...

void	scramble (int seed)
	Scramble this digital net. More...

UInt64Matrix	get_linear_scrambling_matrices (int seed)
	Returns a set of linear scrambling matrices for this digital net. More...

void	bitreverse_generating_matrices ()
	Reverse the bits in the scrambled generating matrices.

void	unsafe_get_points (const size_t nMin, const size_t nMax, RealMatrix &points)
	Generates digital net points without error checking. More...

void	next (int n, UInt64Vector &current_point)
	Get the next point of the sequence represented as an unsigned integer vector. More...

UInt64	reorder_natural (UInt64 k)
	Position of the `k`th digital net point in DIGITAL_NET_NATURAL_ORDERING.

UInt64	reorder_gray_code (UInt64 k)
	Position of the `k`th digital net point in DIGITAL_NET_GRAY_CODE_ORDERING.

Private Attributes
UInt64Matrix	generatingMatrices
	Generating matrices of this digital net.

UInt64Matrix	scrambledGeneratingMatrices
	Scrambled generating matrices of this digital net.

int	tMax
	Number of bits of each integer in generatingMatrices Also: number of rows in each generating matrix.

int	tScramble
	Number of rows in the linear scramble matrix.

bool	digitalShiftFlag
	Digitally shift this digital net if true.

bool	scramblingFlag
	Perform linear matrix scramble if true.

UInt64Vector	digitalShift
	Digital shift associated with this digital net.

DigitalNetOrdering	ordering
	Order of the points of this digital net.

bool	mostSignificantBitFirst
	Most significant bit comes first in generatingMatrices when true.

UInt64(DigitalNet::*	reorder )(UInt64)
	Function pointer to the chosen order of the points.

Additional Inherited Members
Protected Member Functions inherited from LowDiscrepancySequence
void	check_sizes (const size_t nMin, const size_t nMax, RealMatrix &points)
	Perform checks on the matrix `points` Each column of `points` contains a `dimension`-dimensional point where `dimension` is equal to the number of rows of `points` The number of points `numPoints` is `nMax` - `nMin` Checks if the requested number of points `numPoints` exceeds the maximum number of points allowed in this low-discrepancy sequence Checks if the number of rows of the matrix `points` exceeds the maximum dimension allowed in this low-discrepancy sequence Checks if the matrix `points` has `numPoints` columns. More...

Protected Attributes inherited from LowDiscrepancySequence
int	dMax
	Maximum dimension of this low-discrepancy sequence.

int	mMax
	`log2` of the maximum number of points of this low-discrepancy sequence More...

int	seedValue
	The seed of this low-discrepancy sequence.

short	outputLevel
	The output verbosity level, can be one of {SILENT, QUIET, NORMAL, VERBOSE, DEBUG}_OUTPUT.

Detailed Description

Class for digital nets in Dakota.

Constructor & Destructor Documentation

◆ DigitalNet() [1/3]

DigitalNet	(	const UInt64Matrix &	generatingMatrices,
		int	mMax,
		int	tMax,
		int	tScramble,
		bool	digitalShiftFlag,
		bool	scramblingFlag,
		int	seedValue,
		DigitalNetOrdering	ordering,
		bool	mostSignificantBit,
		short	outputLevel
	)

Default constructor.

Shape of the generating matrices

Print summary info when debugging

If most significant bit first, bitreverse the generating matrices

Options for setting the digital shift of this digital net

Print digital shift vector when debugging

Print warning about missing digital shift (will include the 0 point)

Options for setting the scrambling of this digital net

Check if 'tScramble' >= 'tMax'

Check if 'tMax' is > 0

Scramble the generating matrices

Print scrambled generating matrices

Options for setting the ordering of this digital net

Check that the generating matrix has 'mMax' columns NOTE: we could also derive 'mMax' from the number of columns of the provided generating matrix, but that would cause issues with the option to read inline generating matrices (because we need the number of columns from the user, as the generating matrices are read in as an integer list) NOTE: We could also work on reading the inline generating matrices as proper matrices, but I couldn't figure that out right away

Print generating matrices with most significant bit first

Parameters

mMax	Generating matrices
tMax	log2 of maximum number of points
tScramble	Number of bits of integers in the generating matrices
digitalShiftFlag	Number of rows in the linear scramble matrix
scramblingFlag	Use digital shift if true
seedValue	Use linear matrix scramble if true
ordering	Random seed value
mostSignificantBit	Order of the digital net points
outputLevel	Generating matrices are stored with most significant bit first if true Verbosity

References Dakota::abort_handler(), Dakota::bitreverse(), DigitalNet::digital_shift(), DigitalNet::digitalShift, DigitalNet::digitalShiftFlag, LowDiscrepancySequence::dMax, DigitalNet::generatingMatrices, LowDiscrepancySequence::mMax, DigitalNet::mostSignificantBitFirst, DigitalNet::ordering, LowDiscrepancySequence::outputLevel, DigitalNet::reorder, DigitalNet::reorder_gray_code(), DigitalNet::reorder_natural(), DigitalNet::scramble(), DigitalNet::scrambledGeneratingMatrices, DigitalNet::scramblingFlag, LowDiscrepancySequence::seedValue, DigitalNet::tMax, and DigitalNet::tScramble.

◆ DigitalNet() [2/3]

DigitalNet	(	const UInt64Matrix &	generatingMatrices,
		int	mMax,
		int	tMax
	)

A constructor that uses gray code ordering and a digital shift with linear matrix scramble.

A constructor that uses radical inverse ordering, digital shift and linear matrix scrambling.

◆ DigitalNet() [3/3]

DigitalNet	(	std::tuple< UInt64Matrix, int, int >	data,
		ProblemDescDB &	problem_db
	)

A constructor that takes a tuple and a problem description database The tuple contains the generating matrices, corresponding log2 of the maximum number of points, number of bits in each integer of the generating matrices, and the number of rows in the linear scramble matrix.

A constructor that takes a tuple and a problem description database.

Member Function Documentation

◆ get_data()

std::tuple< UInt64Matrix, int, int > get_data ( ProblemDescDB & problem_db )

private

Extract the generating matrices, corresponding log2 of the maximum number of points and number of bits in each integer of the generating matrices from the given problem.

Extract the generating matrices, corresponding log2 of the maximum number of points and number of bits in each integer of the generating matrices from the given problem description database There are 3 different ways to specify generating matrices:

+-----------------------------------------------—+ | Case I: "generating_matrices file [...]" | +-----------------------------------------------—+ The generating matrices will be read from the file with the given name

+-----------------------------------------------—+ | Case II: "generating_matrices inline [...]" | +-----------------------------------------------—+ Assumes the generating matrices is given as an inline matrix of integers

+-----------------------------------------------—+ | Case III: "generating_matrices predefined [...]" | +-----------------------------------------------—+ The given name should match the name of a predefined set of generating matrices Choose one of:

joe_kuo
sobol

Name of the file with the generating matrices

Get the inline generating matrices

NOTE: outputLevel has not been set yet, so gettting it directly from the 'problem_db' instead

Case I: the generating matrices are provided in an external file

Case II: the generating matrices are provided in the input file

Case III: default generating matrices have been selected

Verify that mMax has not been provided

Verify that tMax has not been provided

Verify that {most|least}_significant_bit_first has not been set

References Dakota::abort_handler(), ProblemDescDB::get_bool(), DigitalNet::get_default_generating_matrices(), DigitalNet::get_generating_matrices_from_file(), DigitalNet::get_inline_generating_matrices(), ProblemDescDB::get_int(), ProblemDescDB::get_iv(), ProblemDescDB::get_short(), ProblemDescDB::get_string(), and LowDiscrepancySequence::outputLevel.

◆ get_generating_matrices_from_file()

const std::tuple< UInt64Matrix, int, int > get_generating_matrices_from_file ( ProblemDescDB & problem_db )

private

Case I: the generating matrices are provided in an external file.

Wrap in try-block

Catch-all handler

References Dakota::abort_handler(), DigitalNet::generatingMatrices, ProblemDescDB::get_int(), and ProblemDescDB::get_string().

Referenced by DigitalNet::get_data().

◆ get_inline_generating_matrices()

const std::tuple< UInt64Matrix, int, int > get_inline_generating_matrices ( ProblemDescDB & problem_db )

private

Case II: the generating matrices are provided in the input file.

Get the inline generating matrices NOTE: generating matrices are read as an integer vector and reshaped into matrices here, using the number of columns given in the 'm_max' keyword

NOTE: Catch missing 'm_max' here to avoid division by 0 in numRows

Can't get away without making a copy here, conversion from int to UInt64, maybe there's a smarter way to do this? NOTE: what if UInt64 integer is provided? We can't store this as an 'INTEGERLIST' anymore...

References Dakota::abort_handler(), DigitalNet::generatingMatrices, ProblemDescDB::get_int(), and ProblemDescDB::get_iv().

Referenced by DigitalNet::get_data().

◆ get_default_generating_matrices()

const std::tuple< UInt64Matrix, int, int > get_default_generating_matrices ( ProblemDescDB & problem_db )

private

Case III: a set of default generating matrices has been selected.

NOTE: outputLevel has not been set yet, so gettting it directly from the 'problem_db' instead

Select predefined generating matrices

References ProblemDescDB::get_bool(), ProblemDescDB::get_short(), Dakota::joe_kuo_d1024_t32_m32, LowDiscrepancySequence::outputLevel, and Dakota::sobol_d250_t64_m32.

Referenced by DigitalNet::get_data().

◆ digital_shift()

void digital_shift ( int seed )

private

Apply digital shift to this digital net Uses the given seed to initialize the RNG When the seed is < 0, the random shift will be removed.

Apply digital shift to this digital net Uses the given seed to initialize the RNG When the seed is < 0, the digital shift will be removed.

Sets all entries to 0

References DigitalNet::digitalShift, and LowDiscrepancySequence::dMax.

◆ scramble()

void scramble ( int seed )

private

Scramble this digital net.

Remove scrambling

Get linear scrambling matrices

Left-multiply the scramble matrices with the generating matrices to scramble this digital net

Get row 'd' from the scramble matrices

Get row 'd' from the generating matrices

Perform binary multiplication

Fill 'd'th row of 'scrambledGeneratingMatrices' with the scrambled generating matrices

Reverse bits if needed

References DigitalNet::bitreverse_generating_matrices(), LowDiscrepancySequence::dMax, DigitalNet::generatingMatrices, DigitalNet::get_linear_scrambling_matrices(), Dakota::matmul_base2(), LowDiscrepancySequence::mMax, DigitalNet::scrambledGeneratingMatrices, and DigitalNet::tMax.

◆ get_linear_scrambling_matrices()

UInt64Matrix get_linear_scrambling_matrices ( int seed )

private

Returns a set of linear scrambling matrices for this digital net.

Generates scrambling matrices (shape 'dMax' x 'tMax') A linear scrambling matrix is a lower-tridiagonal matrix with shape 'tScramble' x 'tMax', i.e., 1 0 0 0 0 x 1 0 0 0 x x 1 0 0 x x x 1 0 x x x x 1 which is encoded as a vector of length 'tMax' with integer entries with 'tScramble' bits each (analogous to the generating matrices)

Get random number x x x x x x x x | 64

Truncate to 'tScramble - k' least significant bits 0 0 0 0 x x x x | tScramble - k

Set diagonal bit 0 0 0 0 x x x 1

Shift to the left x x x 1 0 0 0 0 | | | k tScramble - 1

Return the scrambling matrices

References LowDiscrepancySequence::dMax, DigitalNet::tMax, and DigitalNet::tScramble.

Referenced by DigitalNet::scramble().

◆ unsafe_get_points()

void unsafe_get_points	(	const size_t	nMin,
		const size_t	nMax,
		RealMatrix &	points
	)

privatevirtual

Generates digital net points without error checking.

Generates digital net points without error checking Returns the points with index nMin, nMin + 1, ..., nMax - 1 This function will store the points in-place in the matrix points Each column of points contains a dimension-dimensional point where dimension is equal to the number of rows of points

Check if a power of 2 number of points is request when using natural ordering

Iterativey generate all points up to nMin-1

Set to 0 by default

Generate points between nMin and nMax

1 / 2^(-tMax)

Loop over all points

Generate the next point as UInt64Vector

Loop over all dimensions

Implements LowDiscrepancySequence.

References Dakota::abort_handler(), DigitalNet::digitalShift, Dakota::ispow2(), DigitalNet::next(), DigitalNet::ordering, and DigitalNet::reorder.

◆ next()

void next	(	int	k,
		UInt64Vector &	current_point
	)

private

Get the next point of the sequence represented as an unsigned integer vector.

Get the next point of the sequence represented as an unsigned integer vector NOTE: Uses the Antonov & Saleev (1979) iterative construction: knowing the current point with index k, the next point with index k + 1 is obtained by XOR'ing the current point with the n-th column of the j-th generating matrix, i.e.,.

              x_{k+1}[j] = x_{k}[j] ^ C[j][n]

where n is the rightmost zero-bit of k (= the position of the bit that will change from k to k+1 in Gray code)

References Dakota::count_consecutive_trailing_zero_bits(), and DigitalNet::scrambledGeneratingMatrices.

Referenced by DigitalNet::unsafe_get_points().

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

DigitalNet.hpp
DigitalNet.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DigitalNet() [1/3]

◆ DigitalNet() [2/3]

◆ DigitalNet() [3/3]

Member Function Documentation

◆ get_data()

◆ get_generating_matrices_from_file()

◆ get_inline_generating_matrices()

◆ get_default_generating_matrices()

◆ digital_shift()

◆ scramble()

◆ get_linear_scrambling_matrices()

◆ unsafe_get_points()

◆ next()