# 🤏 lds-rs - Low-Discrepancy Sequence Generator in Rust
[](https://crates.io/crates/lds-rs)
[](https://docs.rs/lds-rs)
[](https://github.com/luk036/lds-rs/actions)
[](https://codecov.io/gh/luk036/lds-rs)
## 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`:
```toml
[dependencies]
lds-rs = "0.1.0"
```
## Usage
### Basic van der Corput Sequence
```rust
use lds_rs::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
```rust
use lds_rs::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
```rust
use lds_rs::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
```rust
use lds_rs::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
```rust
use lds_rs::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:
```rust
use std::sync::Arc;
use std::thread;
use lds_rs::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](examples/) directory for more usage examples.
## Testing
Run the tests with:
```bash
cargo test
```
## 🛠️ Installation
### 📦 Cargo
- Install the rust toolchain in order to have cargo installed by following
[this](https://www.rust-lang.org/tools/install) guide.
- run `cargo install lds-rs`
## 📜 License
Licensed under either of
- Apache License, Version 2.0
([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license
([LICENSE-MIT](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](CONTRIBUTING.md).