tklds

In this repository, we present the 'tkrg-a-ap5' direction numbers for generating Sobol sequences satisfying properties A and A' as well as a comprehensive set of benchmark test functions from literature that can be used for evaluating low discrepancy sequence quality. The repository accompanies the paper:

On the generation of direction numbers for Sobol Sequences and the application to Quasi Monte Carlo Methods

The set of direction numbers tkrg-a-ap5 satisfying property A for all 50,000 dimensions and A' for five adjacent dimensions can be found in tklds/direction_numbers/tkrgsobol_a_ap5_50000

Quasi Monte Carlo Methods

Monte Carlo methods lie at the heart of many numeric computing tasks ranging from modelling how high velocity ions impinge on an atomic lattice to the pricing of a financial instruments such as stocks and options. While being generic and scaling independently of problem dimension, practical applications of Monte-Carlo suffers from the slow convergence rate imposed by the O(N-1/2) for N samples, thus requiring large numbers of simulations to achieve a desired level of accuracy. Quasi-Monte Carlo integration replaces the pseudo-random sequences with deterministic 'low discrepancy' sequences having greater uniformity and produce error convergence rates of order O(N-1) to O(N-3/2) on suitable problem types. While the asymptotically faster convergence rates of QMC methods may at first be appealing, the use of QMC and low discrepancy sequences carry with them a set of caveats and pathologies that if not addressed are likely to lead to incorrect results when applied in practice.

Installing

Install the project from pypi using pip install tklds

Or by cloning this repository and pip installing them:

https://github.com/TENOKONDA/tklds

• Clone tklds from github git clone https://github.com/TENOKONDA/tklds.git
• Install the requirements using python -m pip install -r requirements.txt from the repository folder
• Install the project by calling python -m pip install tklds from the repository folder.

Quickstart

To generate uniform floating point values in the range [0,1] use the following snippet:

>>> from tklds.interface.generators import generate_lds_rvs
>>> from tklds.constant import SequenceNum
>>> u = generate_lds_rvs(sequence=SequenceNum.TKRG_A_AP5, n=1024, d=5, skip=0)

Here we generate a total of n=1024 points with each point having d=5 dimensions using the sequence generated by the sequence_name=tkrg-a-ap5 direction numbers, without skipping the first point (skip=0).

Examples

Some examples can be found in the notebooks folder:

• Integral benchmark test functions: notebooks/02_integral.ipynb
• Spurious variance: notebooks/05_spurious_variance.ipynb
• Brownian motion: notebooks/06_brownian_motion.ipynb
• Sobol random generator: notebooks/07_sobol_engine_examples.ipynb

Direction Numbers

Folder tklds/direction_numbers contains the direction numbers used to initialize the Sobol sequences

tkrgsobol_a_ap5_50000

This set of direction numbers has 50,000 dimensions, satisfying:

• Property A for all dimensions
• Property A' for 5 adjacent dimensions

For further details on their generation and the properties A and A' see:

On the generation of direction numbers for Sobol Sequences and the application to Quasi Monte Carlo Methods.

new-joe-kuo-6.21201

These contain 21,201 dimensions. Their generation is described in:

19. Joe and F. Y. Kuo, Constructing Sobol sequences with better two-dimensional projections, SIAM J. Sci. Comput. 30, 2635-2654 (2008).

Further details about these direction numbers and an alternative download source is available at:

https://web.maths.unsw.edu.au/~fkuo/sobol/index.html

[Direct download: https://web.maths.unsw.edu.au/~fkuo/sobol/new-joe-kuo-6.21201 ]

File format

Both files follow the same format, the columns of the file:

• d - the index of the dimension. Note that the smallest value is 2, as the first dimension is implicit.
• s - the degree of the primitive polynomial
• a - the primitive polynomial coefficients represented in terms of an integer value
• m_i - the direction numbers of the dimension

For a description of the terms and underlying theory of low discrepancy sequences consult the publication:.

On the generation of direction numbers for Sobol Sequences and the application to Quasi Monte Carlo Methods.

Citation

If you use this codebase, please cite our work using the following reference:

Oliva Denis, Andres and Kell, Gregory and Manyakin, Ilya and Papaioannou, Adrien,
On the Generation of Direction Numbers for Sobol Sequences and their Application to Quasi Monte Carlo Methods
(June 02, 2025). Available at SSRN: https://ssrn.com/abstract=5283131 or http://dx.doi.org/10.2139/ssrn.5283131