qfall_math/integer/z/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::{error::MathError, integer::Z, rational::Q, utils::sample::binomial::BinomialSampler};
13
14impl Z {
15    /// Chooses a [`Z`] instance according to the binomial distribution
16    /// parameterized by `n` and `p`.
17    ///
18    /// Parameters:
19    /// - `n`: specifies the number of trials
20    /// - `p`: specifies the probability of success
21    ///
22    /// Returns a fresh [`Z`] instance with a value sampled
23    /// according to the binomial distribution or a [`MathError`]
24    /// if `n < 0`, `p ∉ (0,1)`, or `n` does not fit into an [`i64`].
25    ///
26    /// # Examples
27    /// ```
28    /// use qfall_math::integer::Z;
29    ///
30    /// let sample = Z::sample_binomial(2, 0.5).unwrap();
31    /// ```
32    ///
33    /// # Errors and Failures
34    /// - Returns a [`MathError`] of type [`InvalidIntegerInput`](MathError::InvalidIntegerInput)
35    ///   if `n < 0`.
36    /// - Returns a [`MathError`] of type [`InvalidInterval`](MathError::InvalidInterval)
37    ///   if `p ∉ (0,1)`.
38    /// - Returns a [`MathError`] of type [`ConversionError`](MathError::ConversionError)
39    ///   if `n` does not fit into an [`i64`].
40    pub fn sample_binomial(n: impl Into<Z>, p: impl Into<Q>) -> Result<Self, MathError> {
41        let mut bin_sampler = BinomialSampler::init(n, p)?;
42
43        Ok(bin_sampler.sample())
44    }
45}
46
47#[cfg(test)]
48mod test_sample_binomial {
49    use super::{Q, Z};
50
51    // As all major tests regarding an appropriate binomial distribution,
52    // whether the correct interval is kept, and if the errors are thrown correctly,
53    // are performed in the `utils` module, we omit these tests here.
54
55    /// Checks whether `sample_binomial` is available for all types
56    /// implementing [`Into<Z>`], i.e. u8, u16, u32, u64, i8, ...
57    /// and [`Into<Q>`], i.e. u8, u16, i8, i16, f32, f64, ...
58    #[test]
59    fn availability() {
60        let _ = Z::sample_binomial(1u16, 7u8);
61        let _ = Z::sample_binomial(1u32, 7u16);
62        let _ = Z::sample_binomial(1u64, 7u32);
63        let _ = Z::sample_binomial(1i8, 7u64);
64        let _ = Z::sample_binomial(1i16, 7i8);
65        let _ = Z::sample_binomial(1i32, 7i16);
66        let _ = Z::sample_binomial(1i64, 7i32);
67        let _ = Z::sample_binomial(Z::ONE, 7i64);
68        let _ = Z::sample_binomial(1u8, 0.5f32);
69        let _ = Z::sample_binomial(1u8, 0.5f64);
70        let _ = Z::sample_binomial(1, Q::from((1, 2)));
71    }
72}
qfall_math/integer/z/sample/binomial.rs

qfall_math/integer/z/sample/
binomial.rs
