lds-gen 0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
lds_gen/__init__.py ADDED
@@ -0,0 +1,16 @@
1
+ import sys
2
+
3
+ if sys.version_info[:2] >= (3, 8):
4
+ # TODO: Import directly (no need for conditional) when `python_requires = >= 3.9`
5
+ from importlib.metadata import PackageNotFoundError, version # pragma: no cover
6
+ else:
7
+ from importlib_metadata import PackageNotFoundError, version # pragma: no cover
8
+
9
+ try:
10
+ # Change here if project is renamed and does not equal the package name
11
+ dist_name = "lds-gen"
12
+ __version__ = version(dist_name)
13
+ except PackageNotFoundError: # pragma: no cover
14
+ __version__ = "unknown"
15
+ finally:
16
+ del version, PackageNotFoundError
lds_gen/ilds.py ADDED
@@ -0,0 +1,186 @@
1
+ """
2
+ ilds.py
3
+
4
+ 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.
5
+
6
+ The code defines three main components: a function called vdc_i, and two classes named VdCorput and Halton.
7
+
8
+ 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.
9
+
10
+ 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.
11
+
12
+ 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.
13
+
14
+ 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).
15
+
16
+ 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.
17
+
18
+ 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.
19
+
20
+ 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.
21
+ """
22
+
23
+ from typing import List, Sequence
24
+
25
+
26
+ def vdc_i(k: int, base: int = 2, scale: int = 10) -> int:
27
+ """
28
+ The function `vdc_i` converts a given number `k` from base `base` to a decimal number using a
29
+ specified scale.
30
+
31
+ :param k: The parameter `k` represents the number for which we want to calculate the van der Corput
32
+ sequence value
33
+
34
+ :type k: int
35
+
36
+ :param base: The `base` parameter represents the base of the number system being used. In this case,
37
+ it is set to 2, which means the number system is binary (base 2), defaults to 2
38
+
39
+ :type base: int (optional)
40
+
41
+ :param scale: The `scale` parameter determines the precision or number of digits after the decimal
42
+ point in the resulting VDC (Van der Corput) sequence. It specifies the number of times the base is
43
+ raised to calculate the factor, defaults to 10
44
+
45
+ :type scale: int (optional)
46
+
47
+ :return: The function `vdc_i` returns an integer value.
48
+
49
+ Examples:
50
+ >>> vdc_i(1, 2, 10)
51
+ 512
52
+ """
53
+ vdc: int = 0
54
+ factor: int = base**scale
55
+ while k != 0:
56
+ factor //= base
57
+ remainder: int = k % base
58
+ k //= base
59
+ vdc += remainder * factor
60
+ return vdc
61
+
62
+
63
+ # The `VdCorput` class initializes an object with a base and scale value, and sets the count to 0.
64
+ class VdCorput:
65
+ def __init__(self, base: int = 2, scale: int = 10) -> None:
66
+ """
67
+ The function initializes an object with a base and scale value, and sets the count to 0.
68
+
69
+ :param base: The `base` parameter is an optional integer argument that specifies the base of the
70
+ number system. By default, it is set to 2, which means the number system is binary (base 2).
71
+ However, you can change the value of `base` to any other prime number to use a different, defaults to 2
72
+
73
+ :type base: int (optional)
74
+
75
+ :param scale: The `scale` parameter determines the number of digits that can be represented in the
76
+ number system. For example, if `scale` is set to 10, the number system can represent digits from 0
77
+ to 9, defaults to 10
78
+
79
+ :type scale: int (optional)
80
+ """
81
+ self._base: int = base
82
+ self._scale: int = scale
83
+ self._count: int = 0
84
+
85
+ def pop(self) -> int:
86
+ """
87
+ The `pop()` function is a member function of the `VdCorput` class that increments the count and
88
+ calculates the next value in the Van der Corput sequence.
89
+
90
+ :return: The `pop()` function is returning an `int` value.
91
+
92
+ Examples:
93
+ >>> vdc = VdCorput(2, 10)
94
+ >>> vdc.pop()
95
+ 512
96
+ """
97
+ self._count += 1
98
+ return vdc_i(self._count, self._base, self._scale)
99
+
100
+ def reseed(self, seed: int) -> None:
101
+ """
102
+ The `reseed` function resets the state of a sequence generator to a specific seed value.
103
+
104
+ :param seed: The `seed` parameter is an integer value that is used to reset the state of the
105
+ sequence generator. It determines the starting point of the sequence generation
106
+
107
+ :type seed: int
108
+
109
+ Examples:
110
+ >>> vdc = VdCorput(2, 10)
111
+ >>> vdc.reseed(0)
112
+ >>> vdc.pop()
113
+ 512
114
+ """
115
+ self._count = seed
116
+
117
+
118
+ class Halton:
119
+ """Halton sequence generator
120
+
121
+ The `Halton` class is a sequence generator that generates points in a
122
+ 2-dimensional space using the Halton sequence. The Halton sequence is a
123
+ low-discrepancy sequence that is often used in quasi-Monte Carlo methods.
124
+ It is generated by iterating over two different bases and calculating the
125
+ fractional parts of the numbers in those bases. The `Halton` class keeps
126
+ track of the current count and bases, and provides a `pop()` method that
127
+ returns the next point in the sequence as a `List[int]`.
128
+
129
+ Examples:
130
+ >>> hgen = Halton([2, 3], [11, 7])
131
+ >>> hgen.reseed(0)
132
+ >>> for _ in range(10):
133
+ ... print(hgen.pop())
134
+ ...
135
+ [1024, 729]
136
+ [512, 1458]
137
+ [1536, 243]
138
+ [256, 972]
139
+ [1280, 1701]
140
+ [768, 486]
141
+ [1792, 1215]
142
+ [128, 1944]
143
+ [1152, 81]
144
+ [640, 810]
145
+ """
146
+
147
+ def __init__(self, base: Sequence[int], scale: Sequence[int]) -> None:
148
+ """
149
+ The `__init__()` function is a constructor for the `Halton` class that initializes two `VdCorput`
150
+ objects with the given bases.
151
+
152
+ :param base: The `base` parameter is a list of two integers. These integers are used as the bases
153
+ for generating the Halton sequence. The first integer in the list is used as the base for generating
154
+ the first component of the sequence, and the second integer is used as the base for generating the
155
+ second component
156
+
157
+ :type base: Sequence[int]
158
+ """
159
+ self._vdc0 = VdCorput(base[0], scale[0])
160
+ self._vdc1 = VdCorput(base[1], scale[1])
161
+
162
+ def pop(self) -> List[int]:
163
+ """
164
+ The `pop` function returns a list of two integers by popping elements from `vdc0` and `vdc1`.
165
+
166
+ :return: The `pop` method is returning a list of two integers.
167
+ """
168
+ return [self._vdc0.pop(), self._vdc1.pop()]
169
+
170
+ def reseed(self, seed: int) -> None:
171
+ """
172
+ The `reseed` function resets the state of a sequence generator to a specific seed value.
173
+
174
+ :param seed: The `seed` parameter is an integer value that is used to reset the state of the
175
+ sequence generator. It determines the starting point of the sequence generation
176
+
177
+ :type seed: int
178
+ """
179
+ self._vdc0.reseed(seed)
180
+ self._vdc1.reseed(seed)
181
+
182
+
183
+ if __name__ == "__main__":
184
+ import doctest
185
+
186
+ doctest.testmod()