Struct UniformIntegerSampler 

pub struct UniformIntegerSampler {
    pub interval_size: Z,
    pub two_pow_32: u64,
    pub nr_iterations: u32,
    pub upper_modulo: u32,
    pub rng: SamplerRng,
}

Enables uniformly random sampling a Z in [0, interval_size).

Attributes:

• interval_size: defines the interval [0, interval_size), which we sample from
• two_pow_32: is a helper to shift bits by 32-bits left by multiplication
• nr_iterations: defines how many full samples of u32 are required
• upper_modulo: is a power of two to remove superfluously sampled bits to increase the probability of accepting a sample to at least 1/2
• rng: defines the ThreadRng or seeded StdRng that’s used to sample uniform u32 integers

Examples

use qfall_math::{utils::sample::uniform::UniformIntegerSampler, integer::Z};
let interval_size = Z::from(20);

let mut uis = UniformIntegerSampler::init(&interval_size, None).unwrap();

let sample = uis.sample();

assert!(Z::ZERO <= sample);
assert!(sample < interval_size);

Fields

interval_size: Z

two_pow_32: u64

nr_iterations: u32

upper_modulo: u32

rng: SamplerRng

Implementations

impl UniformIntegerSampler

pub fn init( interval_size: &Z, seed: Option<[u8; 32]>, ) -> Result<Self, MathError>

Initializes the UniformIntegerSampler with

• interval_size as interval_size,
• two_pow_32 as a u64 containing 2^32
• nr_iterations as (interval_size - 1).bits() / 32 floored
• upper_modulo as 2^{(interval_size - 1).bits() mod 32}
• rng as a StdRng seeded with seed if seed is provided, and as a fresh ThreadRng otherwise

Parameters:

• interval_size: specifies the interval [0, interval_size) from which the samples are drawn
• seed: specifies an optional 256-bit seed for the internal StdRng. If None is provided, a fresh ThreadRng is used instead.

Returns a UniformIntegerSampler or a MathError, if the interval size is chosen smaller than or equal to 1.

Examples

use qfall_math::{utils::sample::uniform::UniformIntegerSampler, integer::Z};
let interval_size = Z::from(20);

let uis = UniformIntegerSampler::init(&interval_size, None).unwrap();

let mut uis_seeded_0 = UniformIntegerSampler::init(&interval_size, Some([42; 32])).unwrap();
let mut uis_seeded_1 = UniformIntegerSampler::init(&interval_size, Some([42; 32])).unwrap();
assert_eq!(uis_seeded_0.sample(), uis_seeded_1.sample());

Errors and Failures

• Returns a MathError of type InvalidInterval if the interval is chosen smaller than 1.

pub fn sample(&mut self) -> Z

Computes a uniformly chosen Z sample in [0, interval_size) using rejection sampling that accepts samples with probability at least 1/2.

Examples

use qfall_math::{utils::sample::uniform::UniformIntegerSampler, integer::Z};
let interval_size = Z::from(20);

let mut uis = UniformIntegerSampler::init(&interval_size, None).unwrap();

let sample = uis.sample();

assert!(Z::ZERO <= sample);
assert!(sample < interval_size);

pub fn sample_bits_uniform(&mut self) -> Z

Computes self.nr_iterations * 32 + upper_modulo many uniformly chosen bits.

Returns a Z containing self.nr_iterations * 32 + upper_modulo-many uniformly chosen bits.

Examples

use qfall_math::{utils::sample::uniform::UniformIntegerSampler, integer::Z};
let interval = Z::from(u16::MAX) + 1;

let mut uis = UniformIntegerSampler::init(&interval, None).unwrap();

let sample = uis.sample_bits_uniform();

assert!(Z::ZERO <= sample);
assert!(sample < interval);