Update ReadMe etc

Cargo.toml

@@ -1,22 +1,28 @@
 [package]
 name = "qfall-math"
 version = "0.1.0"
-edition = "2021"
+edition = "2024"
+rust-version = "1.85" # due to rand and rand_distr dependency
+description = "Prototyping Library for Lattice-Based Cryptography"
+readme = "README.md"
+homepage = "https://qfall.github.io"
+repository = "https://github.com/qfall/math"
+license = "MPL-2.0"
+keywords = ["math", "prototype", "lattice", "cryptography"]
+categories = ["cryptography", "mathematics", "development-tools::build-utils", "development-tools::testing", "development-tools::profiling"]
 autobenches = false
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
-criterion = { version = "0.7", features = ["html_reports"] }
+criterion = { version = "0.8", features = ["html_reports"] }
 flint-sys = "0.7.3"
 libc = "0.2"
 paste = "1.0"
-rand = "0.9.0"
-rand_distr = "0.5.0"
+rand = "0.9"
+rand_distr = "0.5"
 regex = "1"
 serde = {version="1.0", features=["derive"]}
 serde_json = "1.0"
-string-builder = "0.2.0"
+string-builder = "0.2"
 thiserror = "2.0"
 lazy_static = "1.4"
 probability = "0.20.3"

README.md

@@ -1,128 +1,106 @@
 # qFALL-math
+[<img alt="github" src="https://img.shields.io/badge/qfall--math-github?style=for-the-badge&logo=github&label=github&color=8da0cb" height="20">](https://github.com/qfall/math)
+[<img alt="crates.io" src="https://img.shields.io/badge/qfall--math-cratesio?style=for-the-badge&logo=rust&label=crates&color=fc8d62" height="20">](https://crates.io/crates/qfall-math)
+[<img alt="docs.rs" src="https://img.shields.io/badge/qfall--math-docs?style=for-the-badge&logo=docs.rs&label=docs.rs&color=66c2a5" height="20">](https://docs.rs/qfall-math)
+[<img alt="tutorial" src="https://img.shields.io/badge/book-tutorial?style=for-the-badge&logo=mdBook&label=Tutorial&color=ffd92f" height="20">](https://qfall.github.io/book)
+[<img alt="build" src="https://img.shields.io/github/actions/workflow/status/qfall/math/push.yml?branch=main&style=for-the-badge" height="20">](https://github.com/qfall/math/actions/workflows/push.yml)
+[<img alt="license" src="https://img.shields.io/badge/License-MPL_2.0-blue.svg?style=for-the-badge" height="20">](https://github.com/qfall/math/blob/dev/LICENSE)
 
-[![made-with-rust](https://img.shields.io/badge/Made%20with-Rust-1f425f.svg)](https://www.rust-lang.org/)
-[![CI](https://github.com/qfall/math/actions/workflows/push.yml/badge.svg?branch=dev)](https://github.com/qfall/math/actions/workflows/pull_request.yml)
-[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
-
-This repository is currently being developed by the project group [qFALL - quantum resistant fast lattice library](https://cs.uni-paderborn.de/cuk/lehre/veranstaltungen/ws-2022-23/project-group-qfall) in the winter term 2022 and summer term 2023 by the Codes and Cryptography research group in Paderborn.
-
-The main objective of this project is to develop a memory-safe and efficient usage of
-[FLINT](https://flintlib.org/) in [Rust](https://www.rust-lang.org/). Its main purpose
-is to use this library as a building block to build other projects on top of it.
-
-## Disclaimer
-
-Currently, we are in the development phase and interfaces might change.
-Feel free to check out the current progress, but be aware, that the content will
-change in the upcoming weeks and months. An official release will most likely be published in the second half of 2024.
+`qFALL` is a prototyping library for lattice-based constructions.
+This `math`-crate is a memory-safe wrapper of [FLINT](https://flintlib.org/) in Rust, which provides several additional features often used in lattice-based cryptography. This crate is the foundation of the [qFALL project](https://qfall.github.io) containing further crates for prototyping of lattice-based cryptography.
 
 ## Quick-Start
+First, ensure that you use a Unix-like distribution (Linux or MacOS). Setup [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) if you're using Windows. This is required due to this crate's dependency on FLINT.
+Then, make sure your `rustc --version` is `1.85` or newer. 
 
-Please refer to [our website](https://qfall.github.io/) as a central information point.
-
-To install and add our library to your project, please refer to [our tutorial](https://qfall.github.io/book/index.html).
-It provides a step-by-step guide to install the required libraries and gives further insights into the usage of our crates.
-
-## What does qFALL-math offer?
-
-Extensive documentation can be generated using
-
+Furthermore, it's required that `m4`, a C-compiler such as `gcc`, and `make` are installed.
 ```bash
-cargo doc               # suffix with --open to directly open the documentation
+sudo apt-get install m4 gcc make
 ```
-
-once the project is cloned. Following, there is a small overview containing the general types of our library [qFALL-math](https://github.com/qfall/math).
-
+Then, add you can add this crate to your project by executing the following command.
 ```bash
-math
-├── ...
-├── src
-│   ├── integer         # src folder containing implementations of integers
-│   ├── integer_mod_q   # src folder containing implementations of integers
-│   │                   # for which a certain modulus is applied
-│   └── rational        # src folder containing implementations of rationals
-└── ...
+cargo add qfall-math
 ```
+- Find further information on [our website](https://qfall.github.io/). Also check out [`qfall-tools`](https://github.com/qfall/tools) and [`qfall-schemes`](https://github.com/qfall/schemes).
+- Read the [documentation of this crate](https://docs.rs/qfall-math).
+- We recommend [our tutorial](https://qfall.github.io/book) to start working with qFALL.
 
-### Integers
-
-- [`Z`](https://github.com/qfall/math/blob/dev/src/integer/z.rs): Represents $\mathbb Z$.
-- [`MatZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_z.rs): Represents matrices of $\mathbb Z$.
-- [`PolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/poly_over_z.rs): Represents polynomials with coefficients over $\mathbb Z$.
-- [`MatPolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_poly_over_z.rs): Represents matrices of polynomials with coefficients over $\mathbb Z$.
-
-```rust
-use qfall_math::integer::Z;
+## What does qFALL-math offer?
+We would like to point out a few supported features which are specifically important for lattice-based cryptography.
+- Uniform, discrete Gaussian, and binomial sampling
+- Support of several norms
+- Solving systems of linear equations
+- Support of the Number-Theoretic Transform (NTT)
 
-let a = Z::from(24);
-let b = Z::from(42);
+Furthermore, this crate simplifies the implementation of your prototype by supporting a wide range of functions such as tensor multiplication, serialisation, matrix concatenations and many more.
+Arithmetic operations, comparisons, and conversions are supported across several types. You can find all supported data-types below.
 
-let res_add: Z = &a + &b;
-let res_sub: Z = a - 10;
-let res_mul: Z = 3 * b;
-```
+### Integers
+- [`Z`](https://docs.rs/qfall-math/latest/qfall_math/integer/struct.Z.html): Represents $\mathbb Z$.
+- [`MatZ`](https://docs.rs/qfall-math/latest/qfall_math/integer/struct.MatZ.html): Represents matrices over $\mathbb Z$.
+- [`PolyOverZ`](https://docs.rs/qfall-math/latest/qfall_math/integer/struct.PolyOverZ.html): Represents polynomials with coefficients over $\mathbb Z$.
+- [`MatPolyOverZ`](https://docs.rs/qfall-math/latest/qfall_math/integer/struct.MatPolyOverZ.html): Represents matrices of polynomials with coefficients over $\mathbb Z$.
 
 ### Integers mod q
+- [`Zq`](https://docs.rs/qfall-math/latest/qfall_math/integer_mod_q/struct.Zq.html): Represents $\mathbb Z_q$.
+- [`MatZq`](https://docs.rs/qfall-math/latest/qfall_math/integer_mod_q/struct.MatZq.html): Represents matrices over $\mathbb Z_q$.
+- [`PolyOverZq`](https://docs.rs/qfall-math/latest/qfall_math/integer_mod_q/struct.PolyOverZq.html): Represents polynomials with coefficients over $\mathbb Z_q$.
+- [`PolynomialRingZq`](https://docs.rs/qfall-math/latest/qfall_math/integer_mod_q/struct.PolynomialRingZq.html): Represents quotient rings $\mathbb Z_q[X]/f(X)$.
+- [`MatPolynomialRingZq`](https://docs.rs/qfall-math/latest/qfall_math/integer_mod_q/struct.MatPolynomialRingZq.html): Represents matrices over quotient rings $\mathbb Z_q[X]/f(X)$.
+- [`NTTPolynomialRingZq`](https://docs.rs/qfall-math/latest/qfall_math/integer_mod_q/struct.NTTPolynomialRingZq.html): Represents quotient rings $\mathbb Z_q[X]/f(X)$ in NTT form.
+- [`MatNTTPolynomialRingZq`](https://docs.rs/qfall-math/latest/qfall_math/integer_mod_q/struct.MatNTTPolynomialRingZq.html): Represents matrices over quotient rings $\mathbb Z_q[X]/f(X)$ in NTT form.
 
-- [`Zq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/zq.rs): Represents $\mathbb Z_q$.
-- [`MatZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/mat_zq.rs): Represents matrices of $\mathbb Z_q$.
-- [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs): Represents polynomials with coefficients over $\mathbb Z_q$.
-- [`PolynomialRingZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/polynomial_ring_zq.rs): Represents quotient rings of $\mathbb Z_q[X]/f(X)$ where $q$ is an integer modulus and $f(X)$ is a [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs).
-- [`MatPolynomialRingZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/mat_polynomial_ring_zq.rs): Represents matrices of quotient rings of $\mathbb Z_q[X]/f(X)$ where $q$ is an integer modulus and $f(X)$ is a [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs).
+### Rationals
+- [`Q`](https://docs.rs/qfall-math/latest/qfall_math/rational/struct.Q.html): Represents $\mathbb Q$.
+- [`MatQ`](https://docs.rs/qfall-math/latest/qfall_math/rational/struct.MatQ.html): Represents matrices over $\mathbb Q$.
+- [`PolyOverQ`](https://docs.rs/qfall-math/latest/qfall_math/rational/struct.PolyOverQ.html): Represents polynomials with coefficients over $\mathbb Q$.
 
+## Quick Example
 ```rust
-use qfall_math::integer_mod_q::Zq;
-use qfall_math::integer_mod_q::Modulus;
+use qfall_math::{integer_mod_q::MatZq, integer::MatZ};
 
-let modulus = Modulus::from(24);
-let a = Zq::from((42, &modulus));
-let b = Zq::from((17, &modulus));
+let (n, m, q) = (256, 1024, 3329);
+let (center, sigma) = (0.0, 8.0);
 
-let res_add: Zq = &a + &b;
-let res_sub: Zq = a - 10;
-let res_mul: Zq = 3 * b;
-```
-
-### Rationals
+let mat_a = MatZq::sample_uniform(n, m, q);
+let vec_s = MatZ::sample_uniform(n, 1, 0, 2).unwrap();
+let vec_e = MatZ::sample_discrete_gauss(m, 1, center, sigma).unwrap();
 
-- [`Q`](https://github.com/qfall/math/blob/dev/src/rational/q.rs): Represents $\mathbb Q$.
-- [`MatQ`](https://github.com/qfall/math/blob/dev/src/rational/mat.rs): Represents matrices of $\mathbb Q$.
-- [`PolyOverQ`](https://github.com/qfall/math/blob/dev/src/rational/poly_over_q.rs): Represents polynomials with coefficients over $\mathbb Q$.
+// SIS-Instance: t = A * e mod q
+let vec_t = &mat_a * &vec_e;
 
-```rust
-use qfall_math::rational::Q;
-
-let a = Q::from((17, 19));
-let b = Q::from(0.5);
-
-let res_add: Q = &a + &b;
-let res_sub: Q = a - 10.5;
-let res_mul: Q = 3 * b;
+// LWE-Instance: b^T = s^T * A + e^T mod q
+let vec_b = vec_s.transpose() * mat_a + vec_e.transpose();
 ```
 
-## External Libraries
+## Bugs
+Please report bugs through the [GitHub issue tracker](https://github.com/qfall/math/issues).
 
-This project uses the C-based, optimized math library [FLINT](https://flintlib.org/). To use a C-library in Rust, there has to be an FFI (Foreign Function Interface) which allows to call the methods from [FLINT](https://flintlib.org/) in Rust. This project uses the crate [flint-sys](https://github.com/alex-ozdemir/flint-rs/tree/master/flint-sys) as a binding for [FLINT](https://flintlib.org/).
-Furthermore, we utilized [serde](https://crates.io/crates/serde) and [serde_json](https://crates.io/crates/serde_json) to (de-)serialize objects to and from JSON. Last, but not least, our sampling algorithms heavily rely on the [rand-crate](https://crates.io/crates/rand). An extensive list can be found in our `Cargo.toml` file.
-
-## License
+## Contributions
+Contributors are:
+- Marvin Beckmann
+- Phil Milewski
+- Sven Moog
+- Marcel Luca Schmidt
+- Jan Niklas Siemer
 
-This library is distributed under the **Mozilla Public License Version 2.0** which can be found here [License](https://github.com/qfall/math/blob/dev/LICENSE).
-Permissions of this weak copyleft license are conditioned on making available the source code of licensed files and modifications of those files under the same license (or in certain cases, one of the GNU licenses). Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work may be distributed under different terms and without source code for files added to the larger work.
+See [Contributing](https://github.com/qfall/math/blob/dev/CONTRIBUTING.md) for details on how to contribute.
 
 ## Citing
 
-Please use the following bibtex entry to cite [qFALL-math](https://github.com/qfall/math):
+Please use the following bibtex entry to cite [qFALL](https://qfall.github.io).
 
 ```text
-@software{Porzenheim_qFALL-math,
-    author = {Porzenheim, Laurens and Beckmann, Marvin and Kramer, Paul and Milewski, Phil and Moog, Sven and Schmidt, Marcel and Siemer, Niklas},
-    license = {MPL-2.0},
-    title = {{qFALL-math}},
-    url = {https://github.com/qfall/math}
-}
+TODO: Update to eprint
 ```
 
-## Get in Touch
+## Dependencies
+This project uses the C-based, optimized math-library [FLINT](https://flintlib.org/). We tested our use of FLINT extensively to ensure that you can not introduce memory-leaks by using our library.
+If you need a function supported by FLINT that is not supported by this crate, we have created an `unsafe` passthrough to access and operate on FLINT's structs directly.
+
+Furthermore, we utilized [serde](https://crates.io/crates/serde) and [serde_json](https://crates.io/crates/serde_json) to (de-)serialize objects to and from JSON. Last, but not least, our sampling algorithms use the [rand](https://crates.io/crates/rand)-crate to generate uniformly random bits. An extensive list can be found in our `Cargo.toml` file.
+
+## License
 
-To contact us, please refer to our mailing list `pg-qfall(at)lists.upb.de`.
+This library is distributed under the [Mozilla Public License Version 2.0](https://github.com/qfall/math/blob/dev/LICENSE).
+Permissions of this weak copyleft license are conditioned on making the source code of licensed files and modifications of those files available under the same license (or in certain cases, under one of the GNU licenses). Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work may be distributed under different terms and without source code for files added to the larger work.