Skip to main content

Crate openqmc

Crate openqmc 

Source
Expand description

§openqmc

A faithful Rust port of AcademySoftwareFoundation/openqmc (Apache-2.0), the quasi-Monte Carlo sampling library. It provides three base samplers — Owen-scrambled SobolSampler, rank-1 LatticeSampler, and progressive multi-jittered PmjSampler — each with a blue-noise variant (SobolBnSampler, LatticeBnSampler, PmjBnSampler), all behind a single pass-by-value domain-tree API (Sampler).

§Domain-tree usage

Construct a root sampler per (pixel, frame, sample-index), derive independent 4-dimensional sub-patterns with Sampler::new_domain (padding), and draw up to four dimensions per domain:

use openqmc::SobolSampler;

let root = SobolSampler::new(/* x */ 12, /* y */ 34, /* frame */ 0, /* index */ 7);
let camera = root.new_domain(0);
let [jitter_x, jitter_y, lens_u, lens_v] = camera.draw_sample_f32::<4>();
let bounce = root.new_domain(1);
let dir = bounce.draw_sample_f32::<2>();

Use Sampler::draw_sample for the high-quality stratified dimensions and Sampler::draw_rnd / Sampler::rng for incidental or unbounded random draws (Russian roulette, delta tracking) where stratification does not apply.

§Relationship to the C++ headers

Modules map one-to-one to the upstream oqmc/*.h headers, with the same algorithms and (bit-for-bit) the same sample values. Two idiomatic adaptations: the caller-allocated void* cache — a GPU memory-management concern — becomes a lazily-initialised process global, so every Sampler stays a small Copy + Send value; and the sequential PRNG (pcg::Rng) is surfaced as a named type. The bundled blue-noise tables under src/data/ are the upstream optimised tables converted verbatim to little-endian blobs.

Re-exports§

pub use sampler::Sampler;
pub use sampler::SamplerImpl;
pub use state::State64Bit;
pub use lattice::LatticeSampler;
pub use latticebn::LatticeBnSampler;
pub use pmj::PmjSampler;
pub use pmjbn::PmjBnSampler;
pub use sobol::SobolSampler;
pub use sobolbn::SobolBnSampler;

Modules§

bntables
Port of oqmc/bntables.h — pre-computed, optimised blue-noise key/rank tables used to give the base samplers a spatial blue-noise error distribution (generalising Belcour & Heitz). A single table pair serves all domains: the lookup is shifted toroidally per domain by a random offset.
encode
Port of oqmc/encode.h — pack/unpack a 3-axis integer coordinate key into a single 16-bit value. Used to store pixel coordinates compactly. The sum of the per-axis bit precisions must not exceed 16.
float
Port of oqmc/float.h — integer to [0, 1) float conversion.
lattice
Port of oqmc/lattice.h — the rank-1 lattice sampler.
latticebn
Port of oqmc/latticebn.h — the blue-noise variant of the rank-1 lattice sampler. Same sequence as LatticeSampler, plus spatial blue-noise dithering between pixels. State is not pixel-decorrelated (the table lookup does that).
lookup
Port of oqmc/lookup.h — randomised table lookups. A single pre-computed table (PMJ samples, blue-noise ranks) can be re-used across domains by shuffling the index and XOR-scrambling the value (random digit scramble, Kollig & Keller).
owen
Port of oqmc/owen.h — Owen-scrambled SZ sequences via Brent Burley’s hash-based construction (“Practical Hash-based Owen Scrambling”).
pcg
Port of oqmc/pcg.h — the PCG-RXS-M-XS-32 PRNG by Melissa O’Neill, used both as a classic sequential PRNG and (via hash) as a stateless parallel hash function per Jarzynski & Olano, “Hash Functions for GPU Rendering”. Constants are taken from https://github.com/imneme/pcg-c.
permute
Port of oqmc/permute.h — hash-based permutations. A Laine & Karras style permutation (from “Stratified Sampling for Stochastic Transparency”), with the improved constants from Nathan Vegdahl’s “Building a Better LK Hash”. Combined with bit reversal before and after, this forms an efficient hash-based Owen scramble.
pmj
Port of oqmc/pmj.h — the progressive multi-jittered (0,2) sampler.
pmjbn
Port of oqmc/pmjbn.h — the blue-noise variant of the PMJ sampler. Same sequence as PmjSampler, plus spatial blue-noise dithering between pixels. It shares the PMJ sample cache and adds the blue-noise key/rank tables. State is not pixel-decorrelated (the table lookup does that).
range
Port of oqmc/range.h — map a full-range 32-bit integer into a bounded range using the high-bits-preserving multiplication method (Lemire 2019), which keeps the good high-order bits of QMC sequences and weak PRNGs alike. Prefer this over modulo. A small bias remains at large non-power-of-two ranges (no rejection loop, by design).
rank1
Port of oqmc/rank1.h — a rank-1 lattice (Hickernell et al., “Weighted Compound Integration Rules with Higher Order Convergence for all N”) made progressive with a radical inversion of the sample index, randomised with toroidal shifts.
reverse
Port of oqmc/reverse.h — bit reversal (radical inversion / Van der Corput).
rotate
Port of oqmc/rotate.h — bit/byte rotation, used to extract fresh random values from an existing hash or RNG number.
sampler
Port of oqmc/sampler.h — the public, static-polymorphic sampler interface.
sobol
Port of oqmc/sobol.h — the Owen-scrambled Sobol sampler.
sobolbn
Port of oqmc/sobolbn.h — the blue-noise variant of the Sobol sampler. Same sequence as SobolSampler, plus spatial blue-noise dithering between pixels (progressive pixel sampling). Note it does not pixel-decorrelate the state; the per-pixel (key, rank) table lookup provides the decorrelation.
state
Port of oqmc/state.h — the generic 8-byte sampler state shared by all sampler implementations. Small enough to pass by value; carries the pattern/sample/pixel identifiers and the domain-tree mutations.
stochastic
Port of oqmc/stochastic.h — progressive multi-jittered (0,2) sequence construction (Helmer et al., “Stochastic Generation of (t,s) Sample Sequences”). Builds the first pair of dimensions; the second pair is a randomisation of the first. Used to fill the PMJ sampler’s cache.