🤏 lds-gen

Low Discrepancy Sequence Generation

This library implements a set of low-discrepancy sequence generators, which are used to create sequences of numbers that exhibit a greater degree of uniformity than random numbers. The utility of these sequences is evident in a number of fields, including computer graphics, numerical integration, and Monte Carlo simulations.

The library defines a number of classes, each of which represents a distinct type of low-discrepancy sequence generator. The primary sequence types that are implemented are as follows:

1. van der Corput sequence
2. Halton sequence
3. Circle sequence
4. Disk sequence
5. Sphere sequence
6. 3-Sphere Hopf sequence
7. N-dimensional Halton sequence

Each generator is designed to accept specific inputs, which are typically presented in the form of base numbers or sequences of base numbers. The selection of bases serves to determine the manner in which the sequences are generated. The generators produce outputs in the form of floating-point numbers or lists of floating-point numbers, contingent upon the dimensionality of the sequence.

The fundamental algorithm utilized in the majority of these generators is the van der Corput sequence. The van der Corput sequence is generated by expressing integers in a specified base, reversing the digits, and inserting them after a decimal point. To illustrate, in base 2, the sequence would commence as follows: The sequence then progresses as follows: 1/2, 1/4, 3/4, 1/8, 5/8, and so on.

The Halton sequence extends this concept to multiple dimensions by employing a distinct base for each dimension. The Circle and Sphere sequences employ trigonometric functions to map the low-discrepancy sequences onto circular or spherical surfaces.

Furthermore, the library incorporates a set of utility functions and classes that facilitate the operation of these generators. To illustrate, a list of prime numbers may be employed as bases for the sequences.

Each generator class has methods for producing the next value in the sequence (pop()) and for resetting the sequence to a specific starting point (reseed()). This enables the generators to be employed in a variety of contexts in a flexible manner.

Thread Safety

The following generator classes are now thread-safe:

• VdCorput classes in both lds.py and ilds.py modules
• Sphere3 class in sphere_n.py module
• SphereN class in sphere_n.py module

The internal state in all these generators is protected by threading locks, ensuring atomic operations when multiple threads access the same generator instance. This makes the library safe to use in multi-threaded applications without additional synchronization. The pop() and reseed() methods in all thread-safe classes use proper locking to prevent race conditions.

The objective of this library is to provide a toolkit for the generation of sequences of numbers that are distributed in a well-balanced manner. These can be used in place of random numbers in many applications to achieve a more uniform coverage of a given space or surface. This can result in more efficient and accurate outcomes in tasks such as sampling, integration, and optimization.

Quick Start

Installation

pip install lds-gen

Basic Usage

from lds_gen import VdCorput, Halton, Circle, Sphere

# van der Corput sequence (1D)
vdc = VdCorput(base=2)
for _ in range(5):
    print(vdc.pop())
# Output: 0.5, 0.25, 0.75, 0.125, 0.625

# Using iterator protocol
for value in VdCorput(base=2):
    print(value)
    # Use break to stop iteration

# Generate multiple values at once
batch = VdCorput(base=2).pop_batch(10)

# Halton sequence (2D)
halton = Halton(base=[2, 3])
for _ in range(3):
    print(halton.pop())
# Output: [0.5, 0.333...], [0.25, 0.666...], [0.75, 0.111...]

# Points on unit circle
circle = Circle(base=2)
for _ in range(4):
    print(circle.pop())
# Output: points evenly distributed on circle

# Points on unit sphere
sphere = Sphere(base=[2, 3])
for _ in range(3):
    print(sphere.pop())
# Output: 3D points evenly distributed on sphere surface

# Reset sequence to specific seed
generator = VdCorput(base=2)
generator.reseed(5)
# Sequence now starts from position 5

Key Features

• Thread-safe: All generators are safe to use in multi-threaded applications
• Iterator protocol: Use for loops directly with generator objects
• Batch generation: Generate multiple points efficiently with pop_batch(n)
• Resettable: Use reseed(n) to reset sequence to any position

Common Use Cases

# Monte Carlo integration
from lds_gen import HaltonN

points = HaltonN(base=[2, 3, 5]).pop_batch(1000)
# Use these points for 3D integration with better convergence

# Sampling on surfaces
from lds_gen import Circle, Disk, Sphere

circle_points = Circle(base=2).pop_batch(100)  # On circumference
disk_points = Disk(base=[2, 3]).pop_batch(100)  # Inside circle
sphere_points = Sphere(base=[2, 3]).pop_batch(100)  # On sphere surface

Used In

• sphere-n
• physdes-py
• ginger

👀 See also

• lds-gen-cpp
• lds-rs
• sphere-n

👉 Note

This project has been set up using PyScaffold 4.5. For details and usage information on PyScaffold see https://pyscaffold.org/.