qfall-math 0.1.1

Mathematical foundations for rapid prototyping of lattice-based cryptography
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

// Copyright © 2023 Niklas Siemer
//
// This file is part of qFALL-math.
//
// qFALL-math is free software: you can redistribute it and/or modify it under
// the terms of the Mozilla Public License Version 2.0 as published by the
// Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.

//! This module contains algorithms for sampling
//! according to the binomial distribution.

use crate::{
    error::MathError,
    integer::Z,
    integer_mod_q::{Modulus, Zq},
    rational::Q,
    utils::sample::binomial::BinomialSampler,
};

impl Zq {
    /// Chooses a [`Zq`] instance according to the binomial distribution
    /// parameterized by `n` and `p`.
    ///
    /// Parameters:
    /// - `modulus`: specifies the [`Modulus`] of the new [`Zq`] instance
    /// - `n`: specifies the number of trials
    /// - `p`: specifies the probability of success
    ///
    /// Returns a fresh [`Zq`] instance with a value sampled
    /// according to the binomial distribution or a [`MathError`]
    /// if `n < 0`, `p ∉ (0,1)`, or `n` does not fit into an [`i64`].
    ///
    /// # Examples
    /// ```
    /// use qfall_math::integer_mod_q::Zq;
    ///
    /// let sample = Zq::sample_binomial(7, 2, 0.5).unwrap();
    /// ```
    ///
    /// # Errors and Failures
    /// - Returns a [`MathError`] of type [`InvalidIntegerInput`](MathError::InvalidIntegerInput)
    ///   if `n < 0`.
    /// - Returns a [`MathError`] of type [`InvalidInterval`](MathError::InvalidInterval)
    ///   if `p ∉ (0,1)`.
    /// - Returns a [`MathError`] of type [`ConversionError`](MathError::ConversionError)
    ///   if `n` does not fit into an [`i64`].
    ///
    /// # Panics ...
    /// - if `modulus` is smaller than `2`.
    pub fn sample_binomial(
        modulus: impl Into<Modulus>,
        n: impl Into<Z>,
        p: impl Into<Q>,
    ) -> Result<Self, MathError> {
        let modulus: Modulus = modulus.into();
        let mut bin_sampler = BinomialSampler::init(n, p)?;

        let sample = bin_sampler.sample();
        Ok(Zq::from((sample, modulus)))
    }
}

#[cfg(test)]
mod test_sample_binomial {
    use super::{Q, Z, Zq};

    // As all major tests regarding an appropriate binomial distribution,
    // whether the correct interval is kept, and if the errors are thrown correctly,
    // are performed in the `utils` module, we omit these tests here.

    /// Checks whether `sample_binomial` is available for all types
    /// implementing [`Into<Zq>`], i.e. u8, u16, u32, u64, i8, ...
    /// and [`Into<Q>`], i.e. u8, u16, i8, i16, f32, f64, ...
    /// and [`Into<Modulus>`], i.e. u8, u16, u32, u64, i8, ...
    #[test]
    fn availability() {
        let _ = Zq::sample_binomial(7u8, 1u16, 7u8);
        let _ = Zq::sample_binomial(7u16, 1u32, 7u16);
        let _ = Zq::sample_binomial(7u32, 1u64, 7u32);
        let _ = Zq::sample_binomial(7u64, 1i8, 7u64);
        let _ = Zq::sample_binomial(7i8, 1i16, 7i8);
        let _ = Zq::sample_binomial(7i16, 1i32, 7i16);
        let _ = Zq::sample_binomial(7i32, 1i64, 7i32);
        let _ = Zq::sample_binomial(7i64, Z::ONE, 7i64);
        let _ = Zq::sample_binomial(7, 1u8, 0.5f32);
        let _ = Zq::sample_binomial(7, 1u8, 0.5f64);
        let _ = Zq::sample_binomial(7, 1, Q::from((1, 2)));
    }
}