lds_gen package¶
Submodules¶
lds_gen.ilds module¶
ilds.py
This code implements two low-discrepancy sequence generators: the Van der Corput sequence and the Halton sequence (specific for integer output). These sequences are used to generate evenly distributed points in a space, which can be useful for various applications like sampling, optimization, or numerical integration.
The code defines three main components: a function called vdc_i, and two classes named VdCorput and Halton.
The vdc_i function is the core of the Van der Corput sequence generation. It takes an integer k, a base (default 2), and a scale (default 10) as inputs. It converts the number k from the given base to a decimal number, using the specified scale for integer output. This function is used to generate individual elements of the Van der Corput sequence.
The VdCorput class is a wrapper around the vdc_i function. It keeps track of the current count and allows you to generate successive elements of the Van der Corput sequence by calling its pop method. You can also reset the sequence to a specific starting point using the reseed method.
The Halton class generates points in a 2-dimensional space using two Van der Corput sequences with different bases. It creates two VdCorput objects internally and uses them to generate pairs of numbers. The pop method of the Halton class returns a list of two integers, representing a point in 2D space.
The main logic flow in this code is the generation of these low-discrepancy sequences. For the Van der Corput sequence, it works by repeatedly dividing the input number by the base and using the remainders to construct the output number. This process creates a sequence of numbers that are well-distributed between 0 and N (when properly scaled).
The Halton sequence extends this idea to multiple dimensions by using different bases for each dimension. In this implementation, it generates 2D points by combining two Van der Corput sequences.
The code doesn’t take any direct input from the user. Instead, it provides classes and functions that can be used in other programs to generate these sequences. The output of these generators are individual numbers (for Van der Corput) or pairs of numbers (for Halton) that form the respective sequences.
This code is particularly useful for applications that need well-distributed random-like numbers, but with more uniformity than typical pseudo-random number generators provide. It’s a building block that can be used in more complex algorithms and simulations.
- class lds_gen.ilds.Halton(base: Sequence[int], scale: Sequence[int])[source]¶
Bases:
object
Halton sequence generator
The Halton class is a sequence generator that generates points in a 2-dimensional space using the Halton sequence. The Halton sequence is a low-discrepancy sequence that is often used in quasi-Monte Carlo methods. It is generated by iterating over two different bases and calculating the fractional parts of the numbers in those bases. The Halton class keeps track of the current count and bases, and provides a pop() method that returns the next point in the sequence as a List[int].
Examples
>>> hgen = Halton([2, 3], [11, 7]) >>> hgen.reseed(0) >>> for _ in range(10): ... print(hgen.pop()) ... [1024, 729] [512, 1458] [1536, 243] [256, 972] [1280, 1701] [768, 486] [1792, 1215] [128, 1944] [1152, 81] [640, 810]
- pop() List[int] [source]¶
The pop function returns a list of two integers by popping elements from vdc0 and vdc1.
- Returns:
The pop method is returning a list of two integers.
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
- class lds_gen.ilds.VdCorput(base: int = 2, scale: int = 10)[source]¶
Bases:
object
- pop() int [source]¶
The pop() function is a member function of the VdCorput class that increments the count and calculates the next value in the Van der Corput sequence.
- Returns:
The pop() function is returning an int value.
Examples
>>> vdc = VdCorput(2, 10) >>> vdc.pop() 512
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
Examples
>>> vdc = VdCorput(2, 10) >>> vdc.reseed(0) >>> vdc.pop() 512
- lds_gen.ilds.vdc_i(k: int, base: int = 2, scale: int = 10) int [source]¶
The function vdc_i converts a given number k from base base to a decimal number using a specified scale.
- Parameters:
k (int) – The parameter k represents the number for which we want to calculate the van der Corput sequence value
base (int (optional)) – The base parameter represents the base of the number system being used. In this case, it is set to 2, which means the number system is binary (base 2), defaults to 2
scale (int (optional)) – The scale parameter determines the precision or number of digits after the decimal point in the resulting VDC (Van der Corput) sequence. It specifies the number of times the base is raised to calculate the factor, defaults to 10
- Returns:
The function vdc_i returns an integer value.
Examples
>>> vdc_i(1, 2, 10) 512
lds_gen.lds module¶
Low-Discrepancy Sequence (LDS) Generator
This code implements a set of low-discrepancy sequence generators, which are used to create sequences of numbers that are more evenly distributed than random numbers. These sequences are particularly useful in various fields such as computer graphics, numerical integration, and Monte Carlo simulations.
The code defines several classes, each representing a different type of low-discrepancy sequence generator. The main types of sequences implemented are:
Van der Corput sequence
Halton sequence
Circle sequence
Sphere sequence
3-Sphere Hopf sequence
N-dimensional Halton sequence
Each generator takes specific inputs, usually in the form of base numbers or sequences of base numbers. These bases determine how the sequences are generated. The generators produce outputs in the form of floating-point numbers or lists of floating-point numbers, depending on the dimensionality of the sequence.
The core algorithm used in most of these generators is the Van der Corput sequence. This sequence is created by expressing integers in a given base, reversing the digits, and placing them after a decimal point. For example, in base 2, the sequence would start: 1/2, 1/4, 3/4, 1/8, 5/8, and so on.
The Halton sequence extends this concept to multiple dimensions by using a different base for each dimension. The Circle and Sphere sequences use trigonometric functions to map these low-discrepancy sequences onto circular or spherical surfaces.
The code also includes utility functions and classes to support these generators. For instance, there’s a list of prime numbers that can be used as bases for the sequences.
Each generator class has methods to produce the next value in the sequence (pop()) and to reset the sequence to a specific starting point (reseed()). This allows for flexible use of the generators in various applications.
The purpose of this code is to provide a toolkit for generating well-distributed sequences of numbers, which can be used in place of random numbers in many applications to achieve more uniform coverage of a given space or surface. This can lead to more efficient and accurate results in tasks like sampling, integration, and optimization.
- class lds_gen.lds.Circle(base: int)[source]¶
Bases:
object
Unit Circle sequence generator
Examples
>>> cgen = Circle(2) >>> cgen.reseed(0) >>> for _ in range(2): ... print(cgen.pop()) ... [-1.0, 1.2246467991473532e-16] [6.123233995736766e-17, 1.0]
- pop() List[float] [source]¶
The pop() function is used to generate the next value in the sequence. For example, in the VdCorput class, pop() increments the count and calculates the Van der Corput sequence value for that count and base. In the Halton class, pop() returns the next point in the Halton sequence as a List[float; 2]. Similarly, in the Circle class, pop() returns the next point on the unit circle as a List[float; 2]. In the Sphere class, pop() returns the next point on the unit sphere as a List[float; 3]. And in the Sphere3Hopf class, pop() returns the next point on the 3-sphere using the Hopf fibration as a List[float; 4].
Examples
>>> cgen = Circle(2) >>> cgen.pop() [-1.0, 1.2246467991473532e-16]
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
- class lds_gen.lds.Halton(base: Sequence[int])[source]¶
Bases:
object
Halton sequence generator
The Halton class is a sequence generator that generates points in a 2-dimensional space using the Halton sequence. The Halton sequence is a low-discrepancy sequence that is often used in quasi-Monte Carlo methods. It is generated by iterating over two different bases and calculating the fractional parts of the numbers in those bases. The Halton class keeps track of the current count and bases, and provides a pop() method that returns the next point in the sequence as a List[float].
Examples
>>> hgen = Halton([2, 3]) >>> hgen.reseed(0) >>> for _ in range(10): ... print(hgen.pop()) ... [0.5, 0.3333333333333333] [0.25, 0.6666666666666666] [0.75, 0.1111111111111111] [0.125, 0.4444444444444444] [0.625, 0.7777777777777777] [0.375, 0.2222222222222222] [0.875, 0.5555555555555556] [0.0625, 0.8888888888888888] [0.5625, 0.037037037037037035] [0.3125, 0.37037037037037035]
- pop() List[float] [source]¶
The pop() function is used to generate the next value in the sequence. For example, in the VdCorput class, pop() increments the count and calculates the Van der Corput sequence value for that count and base. In the Halton class, pop() returns the next point in the Halton sequence as a List[float; 2]. Similarly, in the Circle class, pop() returns the next point on the unit circle as a List[float; 2]. In the Sphere class, pop() returns the next point on the unit sphere as a List[float; 3]. And in the Sphere3Hopf class, pop() returns the next point on the 3-sphere using the Hopf fibration as a List[float; 4].
Examples
>>> hgen = Halton([2, 3]) >>> hgen.pop() [0.5, 0.3333333333333333]
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
- class lds_gen.lds.HaltonN(base: Sequence[int])[source]¶
Bases:
object
HaltonN sequence generator
Examples
>>> hgen = HaltonN([2, 3, 5]) >>> hgen.reseed(0) >>> for _ in range(2): ... print(hgen.pop()) ... [0.5, 0.3333333333333333, 0.2] [0.25, 0.6666666666666666, 0.4]
- pop() List[float] [source]¶
The pop() function is used to generate the next value in the sequence. For example, in the VdCorput class, pop() increments the count and calculates the Van der Corput sequence value for that count and base. In the Halton class, pop() returns the next point in the Halton sequence as a List[float; 2]. Similarly, in the Circle class, pop() returns the next point on the unit circle as a List[float; 2]. In the Sphere class, pop() returns the next point on the unit sphere as a List[float; 3]. And in the Sphere3Hopf class, pop() returns the next point on the 3-sphere using the Hopf fibration as a List[float; 4].
Examples
>>> hgen = HaltonN([2, 3, 5]) >>> hgen.pop() [0.5, 0.3333333333333333, 0.2]
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
- class lds_gen.lds.Sphere(base: Sequence[int])[source]¶
Bases:
object
Unit Sphere sequence generator
Examples
>>> sgen = Sphere([2, 3]) >>> sgen.reseed(0) >>> res = sgen.pop() >>> res [-0.4999999999999998, 0.8660254037844387, 0.0]
- pop() List[float] [source]¶
The pop() function is used to generate the next value in the sequence. For example, in the VdCorput class, pop() increments the count and calculates the Van der Corput sequence value for that count and base. In the Halton class, pop() returns the next point in the Halton sequence as a List[float; 2]. Similarly, in the Circle class, pop() returns the next point on the unit circle as a List[float; 2]. In the Sphere class, pop() returns the next point on the unit sphere as a List[float; 3]. And in the Sphere3Hopf class, pop() returns the next point on the 3-sphere using the Hopf fibration as a List[float; 4].
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
- class lds_gen.lds.Sphere3Hopf(base: Sequence[int])[source]¶
Bases:
object
Sphere-3 sequence generator using Hopf coordinates
- @article{yershova2010generating,
title={Generating uniform incremental grids on SO (3) using the Hopf fibration}, author={Yershova, Anna and Jain, Swati and LaValle, Steven M and Mitchell, Julie C}, journal={The International journal of robotics research}, volume={29}, number={7}, pages={801–812}, year={2010}, publisher={SAGE Publications}
}
Examples
>>> sp3hgen = Sphere3Hopf([2, 3, 5]) >>> sp3hgen.reseed(0) >>> res = sp3hgen.pop() >>> res [-0.22360679774997885, 0.3872983346207417, 0.4472135954999573, -0.7745966692414837]
- pop() List[float] [source]¶
The pop() function is used to generate the next value in the sequence. For example, in the VdCorput class, pop() increments the count and calculates the Van der Corput sequence value for that count and base. In the Halton class, pop() returns the next point in the Halton sequence as a List[float; 2]. Similarly, in the Circle class, pop() returns the next point on the unit circle as a List[float; 2]. In the Sphere class, pop() returns the next point on the unit sphere as a List[float; 3]. And in the Sphere3Hopf class, pop() returns the next point on the 3-sphere using the Hopf fibration as a List[float; 4].
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
- class lds_gen.lds.VdCorput(base: int = 2)[source]¶
Bases:
object
Van der Corput sequence generator
VdCorput is a class that generates the Van der Corput sequence. The Van def Corput sequence is a low-discrepancy sequence that is commonly used in quasi-Monte Carlo methods. The sequence is generated by iterating over a base and calculating the fractional part of the number in that base. The VdCorput class keeps track of the current count and base, and provides a pop() method that returns the next value in the sequence.
Examples
>>> vgen = VdCorput(2) >>> vgen.reseed(0) >>> for _ in range(10): ... print(vgen.pop()) ... 0.5 0.25 0.75 0.125 0.625 0.375 0.875 0.0625 0.5625 0.3125
- pop() float [source]¶
The pop() function is used to generate the next value in the sequence. For example, in the VdCorput class, pop() increments the count and calculates the Van der Corput sequence value for that count and base. In the Halton class, pop() returns the next point in the Halton sequence as a List[float; 2]. Similarly, in the Circle class, pop() returns the next point on the unit circle as a List[float; 2]. In the Sphere class, pop() returns the next point on the unit sphere as a List[float; 3]. And in the Sphere3Hopf class, pop() returns the next point on the 3-sphere using the Hopf fibration as a List[float; 4].
Examples
>>> vgen = VdCorput(2) >>> vgen.pop() 0.5
- reseed(seed: int) None [source]¶
The reseed function resets the state of a sequence generator to a specific seed value.
- Parameters:
seed (int) – The seed parameter is an integer value that is used to reset the state of the sequence generator. It determines the starting point of the sequence generation
- lds_gen.lds.vdc(k: int, base: int = 2) float [source]¶
Van der Corput sequence
The function vdc converts a given number k from base base to a floating point number.
- Parameters:
k (int) – The parameter k represents the number for which we want to calculate the van der Corput sequence value
base (int (optional)) – The base parameter represents the base of the number system being used. In this case, it is set to 2, which means the number system is binary (base 2), defaults to 2
- Returns:
The function vdc returns a floating point value.
Examples
>>> vdc(11, 2) 0.8125
lds_gen.skeleton module¶
This is a skeleton file that can serve as a starting point for a Python
console script. To run this script uncomment the following lines in the
[options.entry_points]
section in setup.cfg
:
console_scripts =
fibonacci = lds_gen.skeleton:run
Then run pip install .
(or pip install -e .
for editable mode)
which will install the command fibonacci
inside your current environment.
Besides console scripts, the header (i.e. until _logger
…) of this file can
also be used as template for Python modules.
Note
This file can be renamed depending on your needs or safely removed if not needed.
References
- lds_gen.skeleton.main(args)[source]¶
Wrapper allowing
fib()
to be called with string arguments in a CLI fashionInstead of returning the value from
fib()
, it prints the result to thestdout
in a nicely formatted message.- Parameters:
args (List[str]) – command line parameters as list of strings (for example
["--verbose", "42"]
).
- lds_gen.skeleton.parse_args(args)[source]¶
Parse command line parameters
- Parameters:
args (List[str]) – command line parameters as list of strings (for example
["--help"]
).- Returns:
command line parameters namespace
- Return type: