qfall_math/integer_mod_q/z_q/sample/
binomial.rs

1// Copyright © 2023 Niklas Siemer
2//
3// This file is part of qFALL-math.
4//
5// qFALL-math is free software: you can redistribute it and/or modify it under
6// the terms of the Mozilla Public License Version 2.0 as published by the
7// Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
8
9//! This module contains algorithms for sampling
10//! according to the binomial distribution.
11
12use crate::{
13    error::MathError,
14    integer::Z,
15    integer_mod_q::{Modulus, Zq},
16    rational::Q,
17    utils::sample::binomial::BinomialSampler,
18};
19
20impl Zq {
21    /// Chooses a [`Zq`] instance according to the binomial distribution
22    /// parameterized by `n` and `p`.
23    ///
24    /// Parameters:
25    /// - `modulus`: specifies the [`Modulus`] of the new [`Zq`] instance
26    /// - `n`: specifies the number of trials
27    /// - `p`: specifies the probability of success
28    ///
29    /// Returns a fresh [`Zq`] instance with a value sampled
30    /// according to the binomial distribution or a [`MathError`]
31    /// if `n < 0`, `p ∉ (0,1)`, or `n` does not fit into an [`i64`].
32    ///
33    /// # Examples
34    /// ```
35    /// use qfall_math::integer_mod_q::Zq;
36    ///
37    /// let sample = Zq::sample_binomial(7, 2, 0.5).unwrap();
38    /// ```
39    ///
40    /// # Errors and Failures
41    /// - Returns a [`MathError`] of type [`InvalidIntegerInput`](MathError::InvalidIntegerInput)
42    ///   if `n < 0`.
43    /// - Returns a [`MathError`] of type [`InvalidInterval`](MathError::InvalidInterval)
44    ///   if `p ∉ (0,1)`.
45    /// - Returns a [`MathError`] of type [`ConversionError`](MathError::ConversionError)
46    ///   if `n` does not fit into an [`i64`].
47    ///
48    /// # Panics ...
49    /// - if `modulus` is smaller than `2`.
50    pub fn sample_binomial(
51        modulus: impl Into<Modulus>,
52        n: impl Into<Z>,
53        p: impl Into<Q>,
54    ) -> Result<Self, MathError> {
55        let modulus: Modulus = modulus.into();
56        let mut bin_sampler = BinomialSampler::init(n, p)?;
57
58        let sample = bin_sampler.sample();
59        Ok(Zq::from((sample, modulus)))
60    }
61}
62
63#[cfg(test)]
64mod test_sample_binomial {
65    use super::{Q, Z, Zq};
66
67    // As all major tests regarding an appropriate binomial distribution,
68    // whether the correct interval is kept, and if the errors are thrown correctly,
69    // are performed in the `utils` module, we omit these tests here.
70
71    /// Checks whether `sample_binomial` is available for all types
72    /// implementing [`Into<Zq>`], i.e. u8, u16, u32, u64, i8, ...
73    /// and [`Into<Q>`], i.e. u8, u16, i8, i16, f32, f64, ...
74    /// and [`Into<Modulus>`], i.e. u8, u16, u32, u64, i8, ...
75    #[test]
76    fn availability() {
77        let _ = Zq::sample_binomial(7u8, 1u16, 7u8);
78        let _ = Zq::sample_binomial(7u16, 1u32, 7u16);
79        let _ = Zq::sample_binomial(7u32, 1u64, 7u32);
80        let _ = Zq::sample_binomial(7u64, 1i8, 7u64);
81        let _ = Zq::sample_binomial(7i8, 1i16, 7i8);
82        let _ = Zq::sample_binomial(7i16, 1i32, 7i16);
83        let _ = Zq::sample_binomial(7i32, 1i64, 7i32);
84        let _ = Zq::sample_binomial(7i64, Z::ONE, 7i64);
85        let _ = Zq::sample_binomial(7, 1u8, 0.5f32);
86        let _ = Zq::sample_binomial(7, 1u8, 0.5f64);
87        let _ = Zq::sample_binomial(7, 1, Q::from((1, 2)));
88    }
89}
qfall_math/integer_mod_q/z_q/sample/binomial.rs

qfall_math/integer_mod_q/z_q/sample/
binomial.rs
