Struct ModulusPolynomialRingZq 

pub struct ModulusPolynomialRingZq { /* private fields */ }

ModulusPolynomialRingZq represents the modulus object for PolynomialRingZq

Attributes

• modulus: holds the specific content, i.e. the modulus q and f(X); it holds FLINT’s struct

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use qfall_math::integer_mod_q::PolyOverZq;
use std::str::FromStr;

// initialize X^2 + 1 mod 17, i.e. a polynomial with modulus
let poly_mod = PolyOverZq::from_str("3  1 0 1 mod 17").unwrap();
let modulus = ModulusPolynomialRingZq::from(poly_mod);

Implementations

impl ModulusPolynomialRingZq

pub fn get_q(&self) -> Z

Returns the context integer as a Z.

Examples

use qfall_math::integer::Z;
use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

let modulus_ring = ModulusPolynomialRingZq::from_str("4  1 0 0 1 mod 17").unwrap();

let modulus = modulus_ring.get_q();

let cmp_modulus = Z::from(17);
assert_eq!(cmp_modulus, modulus);

pub fn get_degree(&self) -> i64

Returns the degree of a polynomial ModulusPolynomialRingZq as a i64. The zero polynomial has degree -1.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

let poly = ModulusPolynomialRingZq::from_str("4  0 1 2 3 mod 7").unwrap();

let degree = poly.get_degree(); // This would only return 3

pub fn get_representative_least_nonnegative_residue(&self) -> PolyOverZ

Returns a representative polynomial of the ModulusPolynomialRingZq element.

The representation of the coefficients is in the range [0, modulus).

Examples

use qfall_math::integer::PolyOverZ;
use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

let modulus = ModulusPolynomialRingZq::from_str("4  -3 0 31 1 mod 17").unwrap();

let poly_z = modulus.get_representative_least_nonnegative_residue();

let cmp_poly = PolyOverZ::from_str("4  14 0 14 1").unwrap();
assert_eq!(cmp_poly, poly_z);

impl ModulusPolynomialRingZq

pub fn norm_eucl_sqrd(&self) -> Z

Returns the squared Euclidean norm or 2-norm of the given polynomial. The squared Euclidean norm for a polynomial is obtained by treating the coefficients of the polynomial as a vector and then applying the standard squared Euclidean norm.

Examples

use qfall_math::{integer::Z, integer_mod_q::ModulusPolynomialRingZq};
use std::str::FromStr;

let poly = ModulusPolynomialRingZq::from_str("3  1 2 3 mod 11").unwrap();

let sqrd_2_norm = poly.norm_eucl_sqrd();

// 1*1 + 2*2 + 3*3 = 14
assert_eq!(Z::from(14), sqrd_2_norm);

pub fn norm_infty(&self) -> Z

Returns the infinity norm or the maximal absolute value of a coefficient of the given polynomial. The infinity norm for a polynomial is obtained by treating the coefficients of the polynomial as a vector and then applying the standard infinity norm.

Examples

use qfall_math::{integer::Z, integer_mod_q::ModulusPolynomialRingZq};
use std::str::FromStr;

let poly = ModulusPolynomialRingZq::from_str("3  1 2 4 mod 7").unwrap();

let infty_norm = poly.norm_infty();

// max coefficient is 4 = -3
assert_eq!(Z::from(3), infty_norm);

impl ModulusPolynomialRingZq

pub fn set_ntt_unchecked(&mut self, root_of_unity: impl Into<Z>)

Initiates the NTT-basis for the ModulusPolynomialRingZq by providing a root of unity. It is not checked if it is actually a root of unity. Based on the constant coefficient, it will either be instantiated for cyclic or negacyclic convolution. If it is 1, then it will be interpreted as negacyclic and as cyclic otherwise. The rest of the modulus-polynomial will not be checked, whether it is suited, and it will not be checked if the provided root is actually a root of unity in the ring. Setting the basis only works if n is a power of two.

Parameters:

• root_of_unity: the nth or respectivley 2nth root of unity over the modulus

Defines the NTT-basis for the modulus ring without checking the context.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use qfall_math::integer_mod_q::PolyOverZq;
use crate::qfall_math::traits::SetCoefficient;

let n = 256;
let modulus = 2_i64.pow(23) - 2_i64.pow(13) + 1;

let mut mod_poly = PolyOverZq::from(modulus);
mod_poly.set_coeff(0, 1).unwrap();
mod_poly.set_coeff(n, 1).unwrap();

let mut polynomial_modulus = ModulusPolynomialRingZq::from(&mod_poly);

polynomial_modulus.set_ntt_unchecked(1753);

Safety

The caller is responsible in ensuring that the given root is actually a proper root, under the associated polynomial. For negacyclic polynomials, this means that the root must be a 2nth root of unity and for cyclic polynomials this means that it must be an nth root.

Panics

• if n is not a power of two.

impl ModulusPolynomialRingZq

pub unsafe fn get_fq_ctx_struct(&mut self) -> &mut fq_ctx_struct

Returns a mutable reference to the field modulus of type fq_ctx_struct.

WARNING: The returned struct is part of flint_sys. Any changes to this object are unsafe and may introduce memory leaks. Please be aware that most moduli are shared across multiple instances and all modifications of this struct will affect any other instance with a reference to this object.

This function is a passthrough to enable users of this library to use flint_sys and with that FLINT functions that might not be covered in our library yet. If this is the case, please consider contributing to this open-source project by opening a Pull Request at qfall_math to provide this feature in the future.

Safety

Any flint_sys struct and function is part of a FFI to the C-library FLINT. As FLINT is a C-library, it does not provide all memory safety features that Rust and our Wrapper provide. Thus, using functions of flint_sys can introduce memory leaks.

impl ModulusPolynomialRingZq

pub unsafe fn set_fq_ctx_struct(&mut self, flint_struct: fq_ctx_struct)

Sets a mutable reference to the field modulus of type ModulusPolynomialRingZq to a given fq_ctx_struct.

Parameters:

• flint_struct: value to set the attribute to

WARNING: The returned struct is part of flint_sys. Any changes to this object are unsafe and may introduce memory leaks. Please be aware that most moduli are shared across multiple instances and all modifications of this struct will affect any other instance with a reference to this object.

This function is a passthrough to enable users of this library to use flint_sys and with that FLINT functions that might not be covered in our library yet. If this is the case, please consider contributing to this open-source project by opening a Pull Request at qfall_math to provide this feature in the future.

Safety

Ensure that the old modulus does not share any memory with any moduli that might be used in the future. The memory of the old modulus is freed using this function.

Any flint_sys struct and function is part of a FFI to the C-library FLINT. As FLINT is a C-library, it does not provide all memory safety features that Rust and our Wrapper provide. Thus, using functions of flint_sys can introduce memory leaks.

Trait Implementations

impl Clone for ModulusPolynomialRingZq

fn clone(&self) -> Self

Clones the given element and returns another cloned reference to the fq_ctx_struct element.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

// initialize X^2 + 1 mod 17, i.e. a polynomial with modulus
let a = ModulusPolynomialRingZq::from_str("3  1 0 1 mod 17").unwrap();


let b = a.clone();

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ModulusPolynomialRingZq

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ModulusPolynomialRingZq

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Implements the deserialize option. This allows to create a ModulusPolynomialRingZq from a given Json-object.

impl Display for ModulusPolynomialRingZq

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Allows to convert a ModulusPolynomialRingZq into a String.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

let poly = ModulusPolynomialRingZq::from_str("3  1 0 1 mod 17").unwrap();
println!("{poly}");

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

let poly = ModulusPolynomialRingZq::from_str("3  1 0 1 mod 17").unwrap();
let poly_string = poly.to_string();

impl Drop for ModulusPolynomialRingZq

fn drop(&mut self)

Drops the given reference to the fq_ctx_struct element and frees the allocated memory if no references are left.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;
{
    let a = ModulusPolynomialRingZq::from_str("3  1 0 1 mod 17").unwrap();
} // as a's scope ends here, it get's dropped

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

let a = ModulusPolynomialRingZq::from_str("3  1 0 1 mod 17").unwrap();
drop(a); // explicitly drops a's value

impl From<&ModulusPolynomialRingZq> for ModulusPolynomialRingZq

fn from(value: &ModulusPolynomialRingZq) -> Self

Alias for ModulusPolynomialRingZq::clone.

impl From<&ModulusPolynomialRingZq> for PolyOverZq

fn from(modulus: &ModulusPolynomialRingZq) -> Self

Creates a PolyOverZq from a ModulusPolynomialRingZq.

Parameters:

• modulus: the context polynomial from which the coefficients are copied.

Examples

Returns a new PolyOverZq representing the modulus object.

use qfall_math::integer_mod_q::{ModulusPolynomialRingZq, PolyOverZq};
use std::str::FromStr;

let modulus = ModulusPolynomialRingZq::from_str("4  1 0 0 1 mod 17").unwrap();

let poly_zq = PolyOverZq::from(&modulus);

let poly_cmp = PolyOverZq::from_str("4  1 0 0 1 mod 17").unwrap();
assert_eq!(poly_cmp, poly_zq);

impl From<&ModulusPolynomialRingZq> for PolynomialRingZq

fn from(modulus: &ModulusPolynomialRingZq) -> Self

Creates a zero polynomial with a given ModulusPolynomialRingZq.

Parameters:

• modulus: the modulus that is applied to the polynomial ring element.

Returns a new constant PolynomialRingZq with the specified ModulusPolynomialRingZq.

Examples

use qfall_math::integer_mod_q::PolynomialRingZq;
use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use qfall_math::integer_mod_q::PolyOverZq;
use std::str::FromStr;

let modulus = ModulusPolynomialRingZq::from_str("4  1 0 0 1 mod 17").unwrap();
let poly = PolyOverZq::from_str("4  -1 0 1 1 mod 17").unwrap();
let poly_ring = PolynomialRingZq::from((poly, &modulus));

Panics …

• if the moduli mismatch.

impl From<&ModulusPolynomialRingZq> for String

fn from(value: &ModulusPolynomialRingZq) -> Self

Converts a ModulusPolynomialRingZq into its String representation.

Parameters:

• value: specifies the polynomial that will be represented as a String

Returns a String of the form "[#number of coefficients]⌴⌴[0th coefficient]⌴[1st coefficient]⌴...⌴mod⌴[q]".

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;
let modulus = ModulusPolynomialRingZq::from_str("2  2 1 mod 3").unwrap();

let string: String = modulus.into();

impl From<&PolyOverZq> for ModulusPolynomialRingZq

fn from(poly: &PolyOverZq) -> Self

Creates a Modulus object of type ModulusPolynomialRingZq for PolynomialRingZq

Parameters:

• poly: the polynomial which is used as the modulus.

Returns a new ModulusPolynomialRingZq object with the coefficients and modulus from the PolyOverZq instance.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use qfall_math::integer_mod_q::PolyOverZq;
use std::str::FromStr;

let poly = PolyOverZq::from_str("3  1 0 1 mod 17").unwrap();
let mod_poly = ModulusPolynomialRingZq::try_from(&poly).unwrap();

Panics …

• if modulus is smaller than 2, or
• if the modulus polynomial is of degree smaller than 1.

impl<Mod: Into<Modulus>> From<(&PolyOverZ, Mod)> for ModulusPolynomialRingZq

fn from((poly, modulus): (&PolyOverZ, Mod)) -> Self

Creates a ModulusPolynomialRingZq from a PolyOverZ and a value that implements Into<Modulus>.

Parameters:

• poly: the coefficients of the polynomial.
• modulus: the modulus by which each entry is reduced.

Returns a new ModulusPolynomialRingZq with the coefficients from the PolyOverZ instance under the specified Modulus value.

Examples

use qfall_math::integer_mod_q::{ModulusPolynomialRingZq, Modulus};
use qfall_math::integer::PolyOverZ;
use std::str::FromStr;

let poly = PolyOverZ::from_str("4  0 1 102 3").unwrap();

let mod_poly = ModulusPolynomialRingZq::from((&poly, 100));

let poly_cmp = ModulusPolynomialRingZq::from_str("4  0 1 2 3 mod 100").unwrap();
assert_eq!(poly_cmp, mod_poly);

Panics …

• if modulus is smaller than 2, or
• if the degree of the polynomial is smaller than 1.

impl<Mod: Into<Modulus>> From<(PolyOverZ, Mod)> for ModulusPolynomialRingZq

fn from((poly, modulus): (PolyOverZ, Mod)) -> Self

Creates a ModulusPolynomialRingZq from a PolyOverZ and a value that implements Into<Modulus>.

Parameters:

• poly: the coefficients of the polynomial.
• modulus: the modulus by which each entry is reduced.

Returns a new ModulusPolynomialRingZq with the coefficients from the PolyOverZ instance under the specified Modulus value.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use qfall_math::integer::PolyOverZ;
use std::str::FromStr;

let poly = PolyOverZ::from_str("4  0 1 102 3").unwrap();

let mod_poly = ModulusPolynomialRingZq::from((poly, 100));

let poly_cmp = ModulusPolynomialRingZq::from_str("4  0 1 2 3 mod 100").unwrap();
assert_eq!(poly_cmp, mod_poly);

Panics …

• if modulus is smaller than 2, or
• if the modulus polynomial is of degree smaller than 1.

impl From<ModulusPolynomialRingZq> for PolyOverZq

fn from(value: ModulusPolynomialRingZq) -> Self

Documentation can be found at PolyOverZq::from for &ModulusPolynomialRingZq.

impl From<ModulusPolynomialRingZq> for PolynomialRingZq

fn from(value: ModulusPolynomialRingZq) -> Self

Documentation can be found at PolynomialRingZq::from for &ModulusPolynomialRingZq.

impl From<ModulusPolynomialRingZq> for String

fn from(value: ModulusPolynomialRingZq) -> Self

Documentation can be found at String::from for &ModulusPolynomialRingZq.

impl From<PolyOverZq> for ModulusPolynomialRingZq

fn from(value: PolyOverZq) -> Self

Documentation can be found at ModulusPolynomialRingZq::from for &PolyOverZq.

impl FromCoefficientEmbedding<&MatZq> for ModulusPolynomialRingZq

fn from_coefficient_embedding(embedding: &MatZq) -> Self

Computes a polynomial from a vector. The first i-th entry of the column vector is taken as the coefficient of the polynomial. It inverts the operation of ModulusPolynomialRingZq::into_coefficient_embedding.

Parameters:

• embedding: the column vector that encodes the embedding

Returns a polynomial that corresponds to the embedding.

Examples

use std::str::FromStr;
use qfall_math::{
    integer_mod_q::{MatZq, ModulusPolynomialRingZq},
    traits::FromCoefficientEmbedding,
};

let vector = MatZq::from_str("[[17],[3],[-5]] mod 19").unwrap();
let poly = ModulusPolynomialRingZq::from_coefficient_embedding(&vector);
let cmp_poly = ModulusPolynomialRingZq::from_str("3  17 3 -5 mod 19").unwrap();
assert_eq!(cmp_poly, poly);

Panics …

• if the provided embedding is not a column vector.

impl FromStr for ModulusPolynomialRingZq

fn from_str(s: &str) -> Result<Self, Self::Err>

Creates a Modulus object of type ModulusPolynomialRingZq for PolynomialRingZq. This first converts the provided string into a PolyOverZq and then into the Modulus object.

Warning: If the input string starts with a correctly formatted PolyOverZ object, the rest of the string until the "mod" is ignored. This means that the input string "4 0 1 2 3 mod 13" is the same as "4 0 1 2 3 4 5 6 7 mod 13".

Parameters:

• s: has to be a valid string to create a PolyOverZq. For further information see PolyOverZq::from_str.

Note that the [#number of coefficients] and [0th coefficient] are divided by two spaces and the string for the polynomial is trimmed, i.e. all whitespaces before around the polynomial and the modulus are ignored.

Returns a ModulusPolynomialRingZq or an error if the provided string was not formatted correctly or the modulus was smaller than 2.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;

let poly_mod = ModulusPolynomialRingZq::from_str("3  1 0 1 mod 17").unwrap();

Errors and Failures

• Returns a MathError of type StringConversionError
  • if the provided first half of the string was not formatted correctly to create a PolyOverZ,
  • if the provided second half of the string was not formatted correctly to create a Modulus,
  • if the number of coefficients was smaller than the number provided at the start of the provided string,
  • if the provided value did not contain two whitespaces, or
  • if the delimiter mod could not be found.
  • For further information see PolyOverZq::from_str.
• Returns a MathError of type InvalidModulus
  • if modulus is smaller than 2, or
  • if the modulus polynomial is of degree smaller than 1.

type Err = MathError

The associated error which can be returned from parsing.

impl GetCoefficient<Z> for ModulusPolynomialRingZq

unsafe fn get_coeff_unchecked(&self, index: i64) -> Z

Returns the coefficient of a polynomial ModulusPolynomialRingZq as a Z.

If an index is provided which exceeds the highest set coefficient, 0 is returned.

Parameters:

• index: the index of the coefficient to get (has to be positive)

Returns the coefficient as a Z, or a MathError if the provided index is negative and therefore invalid, or it does not fit into an i64.

Examples

use qfall_math::traits::*;
use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use qfall_math::integer::Z;
use std::str::FromStr;

let poly = ModulusPolynomialRingZq::from_str("4  0 1 2 3 mod 17").unwrap();

let coeff_0: Z = poly.get_coeff(0).unwrap();
let coeff_1: Z = unsafe{ poly.get_coeff_unchecked(1) };
let coeff_4: Z = poly.get_coeff(4).unwrap();

assert_eq!(Z::ZERO, coeff_0);
assert_eq!(Z::ONE, coeff_1);
assert_eq!(Z::ZERO, coeff_4);

Safety

To use this function safely, make sure that the selected index is greater or equal than 0.

fn get_coeff(&self, index: impl TryInto<i64> + Display) -> Result<T, MathError>

Returns a coefficient of the given object, e.g. a polynomial, for a given index.

impl GetCoefficient<Zq> for ModulusPolynomialRingZq

unsafe fn get_coeff_unchecked(&self, index: i64) -> Zq

Returns the coefficient of a polynomial ModulusPolynomialRingZq as a Zq.

If an index is provided which exceeds the highest set coefficient, 0 is returned.

Parameters:

• index: the index of the coefficient to get (has to be positive)

Returns the coefficient as a Zq.

Examples

use qfall_math::traits::*;
use qfall_math::integer_mod_q::{Zq, ModulusPolynomialRingZq};
use std::str::FromStr;

let poly = ModulusPolynomialRingZq::from_str("4  0 1 2 3 mod 17").unwrap();

let coeff_0: Zq = poly.get_coeff(0).unwrap();
let coeff_1: Zq = unsafe{ poly.get_coeff_unchecked(1) };
let coeff_4: Zq = poly.get_coeff(4).unwrap();

assert_eq!(Zq::from((0, 17)), coeff_0);
assert_eq!(Zq::from((1, 17)), coeff_1);
assert_eq!(Zq::from((0, 17)), coeff_4);

Safety

To use this function safely, make sure that the selected index is greater or equal than 0.

fn get_coeff(&self, index: impl TryInto<i64> + Display) -> Result<T, MathError>

Returns a coefficient of the given object, e.g. a polynomial, for a given index.

impl IntoCoefficientEmbedding<MatZq> for &ModulusPolynomialRingZq

fn into_coefficient_embedding(self, size: impl Into<i64>) -> MatZq

Computes the coefficient embedding of the polynomial in a MatZq as a column vector, where the i-th entry of the vector corresponds to the i-th coefficient. It inverts the operation of ModulusPolynomialRingZq::from_coefficient_embedding.

Parameters:

• size: determines the number of rows of the embedding. It has to be larger than the degree of the polynomial.

Returns a coefficient embedding as a column vector if size is large enough.

Examples

use std::str::FromStr;
use qfall_math::{
    integer_mod_q::{MatZq, ModulusPolynomialRingZq},
    traits::IntoCoefficientEmbedding,
};

let poly = ModulusPolynomialRingZq::from_str("3  17 3 -5 mod 19").unwrap();
let vector = poly.into_coefficient_embedding(4);
let cmp_vector = MatZq::from_str("[[17],[3],[-5],[0]] mod 19").unwrap();
assert_eq!(cmp_vector, vector);

Panics …

• if size is not larger than the degree of the polynomial, i.e. not all coefficients can be embedded.

impl PartialEq<PolyOverZq> for ModulusPolynomialRingZq

fn eq(&self, other: &PolyOverZq) -> bool

Checks if an integer matrix and a rational matrix are equal. Used by the == and != operators. PartialEq is also implemented for PolyOverZq using ModulusPolynomialRingZq.

Parameters:

• other: the other value that is used to compare the elements

Returns true if the elements are equal, otherwise false.

Examples

use qfall_math::integer_mod_q::{PolyOverZq, ModulusPolynomialRingZq};
use std::str::FromStr;
let a: ModulusPolynomialRingZq = ModulusPolynomialRingZq::from_str("3  1 2 3 mod 17").unwrap();
let b: PolyOverZq = PolyOverZq::from_str("3  1 2 3 mod 17").unwrap();

// These are all equivalent and return true.
let compared: bool = (a == b);
let compared: bool = (b == a);
let compared: bool = (&a == &b);
let compared: bool = (&b == &a);
let compared: bool = (a.eq(&b));
let compared: bool = (b.eq(&a));
let compared: bool = (ModulusPolynomialRingZq::eq(&a, &b));
let compared: bool = (PolyOverZq::eq(&b, &a));

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for ModulusPolynomialRingZq

fn eq(&self, other: &Self) -> bool

Checks if two modulus objects of type over ModulusPolynomialRingZq are equal. They are considered equal, if their representation as a PolyOverZq match: i.e. the modulus q and the coefficients of the polynomial under modulus q. Used by the == and != operators.

Parameters:

• other: the other value that is used to compare the elements

Returns true if the elements are equal, otherwise false.

Examples

use qfall_math::integer_mod_q::ModulusPolynomialRingZq;
use std::str::FromStr;
let a: ModulusPolynomialRingZq = ModulusPolynomialRingZq::from_str("2  24 1 mod 17").unwrap();
let b: ModulusPolynomialRingZq = ModulusPolynomialRingZq::from_str("2  42 1 mod 17").unwrap();

// These are all equivalent and return false.
let compared: bool = (a == b);
let compared: bool = (&a == &b);
let compared: bool = (a.eq(&b));
let compared: bool = (ModulusPolynomialRingZq::eq(&a, &b));

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ModulusPolynomialRingZq

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Implements the serialize option. This allows to create a Json-object from a given ModulusPolynomialRingZq.

impl Eq for ModulusPolynomialRingZq