Struct UniformIntegerSampler 

pub struct UniformIntegerSampler { /* private fields */ }

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 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).unwrap();

let sample = uis.sample();

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

Implementations

impl UniformIntegerSampler

pub fn init(interval_size: &Z) -> 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 fresh ThreadRng

Parameters:

• interval_size: specifies the interval [0, interval_size) from which the samples are drawn

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 mut uis = UniformIntegerSampler::init(&interval_size).unwrap();

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).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).unwrap();

let sample = uis.sample_bits_uniform();

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