🤏 lds-rs - Low-Discrepancy Sequence Generator in Rust

Overview

This library provides a set of low-discrepancy sequence generators that 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.

All sequence generators are thread-safe, using atomic operations for internal state management, making them safe to use in concurrent environments.

Features

• Van der Corput sequence: Base implementation for 1D sequences
• Halton sequence: 2D and N-dimensional sequences using different bases
• Geometric sequences:
  • Circle: Points on the unit circle
  • Disk: Points in the unit disk
  • Sphere: Points on the unit sphere
  • Sphere3Hopf: Points on the 3-sphere using Hopf fibration
• N-dimensional spheres:
  • Sphere3: Points on 3-sphere (4D)
  • SphereN: Points on n-sphere for arbitrary dimensions
• Integer sequences: Integer versions of Van der Corput and Halton sequences
• Thread-safe: All generators use atomic operations for safe concurrent access
• Prime table: First 1000 prime numbers for use as sequence bases

Installation

Add this to your Cargo.toml:

[dependencies]
lds-gen = "0.1.0"

Usage

Basic Van der Corput Sequence

use lds_gen::VdCorput;

let mut vgen = VdCorput::new(2);
vgen.reseed(0);
println!("First value: {}", vgen.pop()); // 0.5
println!("Second value: {}", vgen.pop()); // 0.25

2D Halton Sequence

use lds_gen::Halton;

let mut hgen = Halton::new([2, 3]);
hgen.reseed(0);
let point = hgen.pop();
println!("Point: {:?}", point); // [0.5, 0.3333333333333333]

Points on a Sphere

use lds_gen::Sphere;

let mut sgen = Sphere::new([2, 3]);
sgen.reseed(0);
let point = sgen.pop();
println!("Sphere point: {:?}", point); // Point on unit sphere

N-Dimensional Spheres

use lds_gen::sphere_n::{Sphere3, SphereN, SphereGen};

// 3-sphere (4D)
let mut sgen3 = Sphere3::new(&[2, 3, 5]);
sgen3.reseed(0);
let point3 = sgen3.pop();
println!("3-sphere point: {:?}", point3); // 4D point on unit 3-sphere

// n-sphere (5D)
let mut sgen_n = SphereN::new(&[2, 3, 5, 7]);
sgen_n.reseed(0);
let point_n = sgen_n.pop();
println!("n-sphere point: {:?}", point_n); // 5D point on unit 4-sphere

The sphere generators use thread-safe lazy initialization and caching for optimal performance in concurrent environments.

Integer Sequences

use lds_gen::ilds::{VdCorput, Halton};

// Integer Van der Corput
let mut ivdc = VdCorput::new(2, 10);
ivdc.reseed(0);
println!("Integer value: {}", ivdc.pop()); // 512

// Integer Halton
let mut ihalton = Halton::new([2, 3], [11, 7]);
ihalton.reseed(0);
let int_point = ihalton.pop();
println!("Integer point: {:?}", int_point); // [1024, 729]

Thread-safe Usage

All sequence generators are thread-safe and can be safely shared across threads:

use std::sync::Arc;
use std::thread;
use lds_gen::Halton;

let halton = Arc::new(Halton::new([2, 3]));
halton.reseed(0);

let mut handles = vec![];

for _ in 0..4 {
    let halton_clone = Arc::clone(&halton);
    let handle = thread::spawn(move || {
        // Each thread safely generates points
        let point = halton_clone.pop();
        println!("Thread point: {:?}", point);
    });
    handles.push(handle);
}

for handle in handles {
    handle.join().unwrap();
}

API Reference

Core Types

• VdCorput: Van der Corput sequence generator (thread-safe)
• Halton: 2D Halton sequence generator (thread-safe)
• Circle: Unit circle sequence generator (thread-safe)
• Disk: Unit disk sequence generator (thread-safe)
• Sphere: Unit sphere sequence generator (thread-safe)
• Sphere3Hopf: 3-sphere sequence generator using Hopf coordinates (thread-safe)
• HaltonN: N-dimensional Halton sequence generator (thread-safe)

N-Dimensional Sphere Types (in sphere_n module)

• sphere_n::SphereGen: Thread-safe trait for sphere generators (implements Send)
• sphere_n::Sphere3: Thread-safe 3-sphere (4D) sequence generator
• sphere_n::SphereN: Thread-safe N-sphere sequence generator for arbitrary dimensions

Integer Types (in ilds module)

• ilds::VdCorput: Integer Van der Corput sequence generator (thread-safe)
• ilds::Halton: Integer 2D Halton sequence generator (thread-safe)

Constants

• TWO_PI: Constant for 2π
• PRIME_TABLE: First 1000 prime numbers

Examples

See the examples directory for more usage examples.

Testing

Run the tests with:

cargo test

🛠️ Installation

📦 Cargo

• Install the rust toolchain in order to have cargo installed by following this guide.
• run cargo install lds-rs

📜 License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🤝 Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md.