Skip to main content

openqmc/
sobol.rs

1//! Port of `oqmc/sobol.h` — the Owen-scrambled Sobol sampler.
2//!
3//! Since upstream `b6a204e`, the generator matrices are SZ sequences (Ahmed
4//! et al. 2025) rather than the classic Sobol direction numbers: dimensions 0
5//! and 1 are unchanged, while every pair of the four dimensions is a
6//! (0, 2)-sequence in base 4. See [`crate::owen`].
7//!
8//! No cache: all samples are computed on the fly. The per-draw cost is higher
9//! than the other samplers, but Owen scrambling gives excellent random error
10//! cancellation and a very high rate of integration for smooth functions.
11
12use crate::owen::shuffled_scrambled_sobol;
13use crate::pcg;
14use crate::sampler::{Sampler, SamplerImpl};
15use crate::state::State64Bit;
16
17/// Implementation behind [`SobolSampler`]. Use it through [`Sampler`].
18#[derive(Clone, Copy, Debug)]
19pub struct SobolImpl {
20    state: State64Bit,
21}
22
23impl SamplerImpl for SobolImpl {
24    #[inline]
25    fn from_pixel(x: i32, y: i32, frame: i32, index: i32) -> Self {
26        Self {
27            state: State64Bit::new(x, y, frame, index).pixel_decorrelate(),
28        }
29    }
30
31    #[inline]
32    fn new_domain(&self, key: i32) -> Self {
33        Self {
34            state: self.state.new_domain(key),
35        }
36    }
37
38    #[inline]
39    fn new_domain_split(&self, key: i32, size: i32, index: i32) -> Self {
40        Self {
41            state: self.state.new_domain_split(key, size, index),
42        }
43    }
44
45    #[inline]
46    fn new_domain_distrib(&self, key: i32, index: i32) -> Self {
47        Self {
48            state: self.state.new_domain_distrib(key, index),
49        }
50    }
51
52    #[inline]
53    fn draw_block(&self) -> [u32; 4] {
54        shuffled_scrambled_sobol::<4>(
55            self.state.sample_id as u32,
56            pcg::output(self.state.pattern_id),
57        )
58    }
59
60    #[inline]
61    fn draw_rnd_block(&self) -> [u32; 4] {
62        self.state.draw_rnd::<4>()
63    }
64
65    #[inline]
66    fn rng(&self) -> pcg::Rng {
67        self.state.rng()
68    }
69}
70
71/// Owen-scrambled Sobol sampler (Burley 2020, Ahmed 2024), built on SZ
72/// sequences (Ahmed et al. 2025).
73///
74/// Cache-free; every sample is computed on the fly. Highest rate of integration
75/// for smooth functions of the six samplers, at the highest per-draw cost. See
76/// [`SobolBnSampler`](crate::SobolBnSampler) for the blue-noise variant.
77///
78/// ```
79/// use openqmc::SobolSampler;
80///
81/// let root = SobolSampler::new(12, 34, 0, 7);
82/// let [u, v] = root.new_domain(0).draw_sample_f32::<2>();
83/// assert!((0.0..1.0).contains(&u) && (0.0..1.0).contains(&v));
84/// ```
85pub type SobolSampler = Sampler<SobolImpl>;
86
87#[cfg(test)]
88mod tests {
89    use super::*;
90
91    #[test]
92    fn from_pixel_decorrelates_the_state() {
93        let imp = SobolImpl::from_pixel(3, 4, 5, 6);
94        assert_eq!(imp.state, State64Bit::new(3, 4, 5, 6).pixel_decorrelate());
95    }
96
97    #[test]
98    fn domain_methods_forward_to_the_state() {
99        let imp = SobolImpl::from_pixel(3, 4, 5, 6);
100        assert_eq!(imp.new_domain(1).state, imp.state.new_domain(1));
101        assert_eq!(
102            imp.new_domain_split(1, 2, 1).state,
103            imp.state.new_domain_split(1, 2, 1)
104        );
105        assert_eq!(
106            imp.new_domain_distrib(1, 2).state,
107            imp.state.new_domain_distrib(1, 2)
108        );
109    }
110
111    #[test]
112    fn draw_block_is_the_core_seeded_with_output_of_pattern() {
113        let imp = SobolImpl::from_pixel(3, 4, 5, 6).new_domain(2);
114        assert_eq!(
115            imp.draw_block(),
116            shuffled_scrambled_sobol::<4>(
117                imp.state.sample_id as u32,
118                pcg::output(imp.state.pattern_id)
119            )
120        );
121        assert_eq!(imp.draw_rnd_block(), imp.state.draw_rnd::<4>());
122        assert_eq!(imp.rng().next_u32(), imp.state.rng().next_u32());
123    }
124
125    #[test]
126    fn impl_is_eight_bytes() {
127        assert_eq!(std::mem::size_of::<SobolImpl>(), 8);
128        assert_eq!(std::mem::size_of::<SobolSampler>(), 8);
129    }
130}