Skip to content

Commit 84210cd

Browse files
jnsiemerjnsiemer
committed
First draft of new Readme containing todos
1 parent d47bf29 commit 84210cd

File tree

1 file changed

+55
-101
lines changed

1 file changed

+55
-101
lines changed

‎README.md‎

Lines changed: 55 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,128 +1,82 @@
11
# qFALL-math
2-
32
[![made-with-rust](https://img.shields.io/badge/Made%20with-Rust-1f425f.svg)](https://www.rust-lang.org/)
4-
[![CI](https://github.com/qfall/math/actions/workflows/push.yml/badge.svg?branch=dev)](https://github.com/qfall/math/actions/workflows/pull_request.yml)
5-
[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
6-
7-
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.
8-
9-
The main objective of this project is to develop a memory-safe and efficient usage of
10-
[FLINT](https://flintlib.org/) in [Rust](https://www.rust-lang.org/). Its main purpose
11-
is to use this library as a building block to build other projects on top of it.
3+
[![Pipeline](https://github.com/qfall/math/actions/workflows/push.yml/badge.svg)](https://github.com/qfall/math/actions/workflows/push.yml)
4+
[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0)
125

13-
## Disclaimer
14-
15-
Currently, we are in the development phase and interfaces might change.
16-
Feel free to check out the current progress, but be aware, that the content will
17-
change in the upcoming weeks and months. An official release will most likely be published in the second half of 2024.
6+
`qFALL` is a prototyping library for lattice-based constructions.
7+
The `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.
188

199
## Quick-Start
20-
21-
Please refer to [our website](https://qfall.github.io/) as a central information point.
22-
23-
To install and add our library to your project, please refer to [our tutorial](https://qfall.github.io/book/index.html).
24-
It provides a step-by-step guide to install the required libraries and gives further insights into the usage of our crates.
25-
26-
## What does qFALL-math offer?
27-
28-
Extensive documentation can be generated using
29-
10+
To use this crate, make sure that `m4`, a C-compiler such as `gcc`, and `make` are installed by running
3011
```bash
31-
cargo doc # suffix with --open to directly open the documentation
12+
sudo apt-get install m4 gcc make
3213
```
33-
34-
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).
35-
14+
Then, add you can add this crate to your project by executing the following command.
3615
```bash
37-
math
38-
├── ...
39-
├── src
40-
│ ├── integer # src folder containing implementations of integers
41-
│ ├── integer_mod_q # src folder containing implementations of integers
42-
│ │ # for which a certain modulus is applied
43-
│ └── rational # src folder containing implementations of rationals
44-
└── ...
16+
cargo add qfall-math
4517
```
18+
- Find further information on [our website](https://qfall.github.io/).
19+
- We recommend [our tutorial](https://qfall.github.io/book) to start working with qFALL.
20+
- Read the [documentation of this crate](TODO).
4621

47-
### Integers
48-
49-
- [`Z`](https://github.com/qfall/math/blob/dev/src/integer/z.rs): Represents $\mathbb Z$.
50-
- [`MatZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_z.rs): Represents matrices of $\mathbb Z$.
51-
- [`PolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/poly_over_z.rs): Represents polynomials with coefficients over $\mathbb Z$.
52-
- [`MatPolyOverZ`](https://github.com/qfall/math/blob/dev/src/integer/mat_poly_over_z.rs): Represents matrices of polynomials with coefficients over $\mathbb Z$.
53-
54-
```rust
55-
use qfall_math::integer::Z;
22+
## What does qFALL-math offer?
23+
We would like to point out a few supported features which are specifically important for lattice-based cryptography.
24+
- Uniform, discrete Gaussian, and binomial sampling
25+
- Support of several norms
26+
- Solving systems of linear equations
27+
- Support of the Number-Theoretic Transform (NTT)
5628

57-
let a = Z::from(24);
58-
let b = Z::from(42);
29+
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.
30+
Arithmetic operations, comparisons, and conversions are supported across several types. You can find all supported data-types below.
5931

60-
let res_add: Z = &a + &b;
61-
let res_sub: Z = a - 10;
62-
let res_mul: Z = 3 * b;
63-
```
32+
### Integers
33+
- [`Z`](TODO_Link_to_documentation): Represents $\mathbb Z$.
34+
- [`MatZ`](TODO_Link_to_documentation): Represents matrices over $\mathbb Z$.
35+
- [`PolyOverZ`](TODO_Link_to_documentation): Represents polynomials with coefficients over $\mathbb Z$.
36+
- [`MatPolyOverZ`](TODO_Link_to_documentation): Represents matrices of polynomials with coefficients over $\mathbb Z$.
6437

6538
### Integers mod q
66-
67-
- [`Zq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/zq.rs): Represents $\mathbb Z_q$.
68-
- [`MatZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/mat_zq.rs): Represents matrices of $\mathbb Z_q$.
69-
- [`PolyOverZq`](https://github.com/qfall/math/blob/dev/src/integer_mod_q/poly_over_zq.rs): Represents polynomials with coefficients over $\mathbb Z_q$.
70-
- [`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).
71-
- [`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).
72-
73-
```rust
74-
use qfall_math::integer_mod_q::Zq;
75-
use qfall_math::integer_mod_q::Modulus;
76-
77-
let modulus = Modulus::from(24);
78-
let a = Zq::from((42, &modulus));
79-
let b = Zq::from((17, &modulus));
80-
81-
let res_add: Zq = &a + &b;
82-
let res_sub: Zq = a - 10;
83-
let res_mul: Zq = 3 * b;
84-
```
39+
- [`Zq`](TODO_Link_to_documentation): Represents $\mathbb Z_q$.
40+
- [`MatZq`](TODO_Link_to_documentation): Represents matrices over $\mathbb Z_q$.
41+
- [`PolyOverZq`](TODO_Link_to_documentation): Represents polynomials with coefficients over $\mathbb Z_q$.
42+
- [`PolynomialRingZq`](TODO_Link_to_documentation): Represents quotient rings $\mathbb Z_q[X]/f(X)$.
43+
- [`MatPolynomialRingZq`](TODO_Link_to_documentation): Represents matrices over quotient rings $\mathbb Z_q[X]/f(X)$.
44+
- [`NTTPolynomialRingZq`](TODO_Link_to_documentation): Represents quotient rings $\mathbb Z_q[X]/f(X)$ in NTT form.
45+
- [`MatNTTPolynomialRingZq`](TODO_Link_to_documentation): Represents matrices over quotient rings $\mathbb Z_q[X]/f(X)$ in NTT form.
8546

8647
### Rationals
48+
- [`Q`](TODO_Link_to_documentation): Represents $\mathbb Q$.
49+
- [`MatQ`](TODO_Link_to_documentation): Represents matrices over $\mathbb Q$.
50+
- [`PolyOverQ`](TODO_Link_to_documentation): Represents polynomials with coefficients over $\mathbb Q$.
8751

88-
- [`Q`](https://github.com/qfall/math/blob/dev/src/rational/q.rs): Represents $\mathbb Q$.
89-
- [`MatQ`](https://github.com/qfall/math/blob/dev/src/rational/mat.rs): Represents matrices of $\mathbb Q$.
90-
- [`PolyOverQ`](https://github.com/qfall/math/blob/dev/src/rational/poly_over_q.rs): Represents polynomials with coefficients over $\mathbb Q$.
91-
92-
```rust
93-
use qfall_math::rational::Q;
94-
95-
let a = Q::from((17, 19));
96-
let b = Q::from(0.5);
52+
## Bugs
53+
Please report bugs through the [GitHub issue tracker](https://github.com/qfall/math/issues).
9754

98-
let res_add: Q = &a + &b;
99-
let res_sub: Q = a - 10.5;
100-
let res_mul: Q = 3 * b;
101-
```
102-
103-
## External Libraries
104-
105-
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/).
106-
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.
107-
108-
## License
55+
## Contributions
56+
Contributors are:
57+
- Marvin Beckmann
58+
- Phil Milewski
59+
- Sven Moog
60+
- Marcel Luca Schmidt
61+
- Jan Niklas Siemer
10962

110-
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).
111-
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.
63+
See [Contributing](TODO_Contribute_file) for details on how to contribute.
11264

11365
## Citing
11466

115-
Please use the following bibtex entry to cite [qFALL-math](https://github.com/qfall/math):
67+
Please use the following bibtex entry to cite [qFALL](https://qfall.github.io).
11668

11769
```text
118-
@software{Porzenheim_qFALL-math,
119-
author = {Porzenheim, Laurens and Beckmann, Marvin and Kramer, Paul and Milewski, Phil and Moog, Sven and Schmidt, Marcel and Siemer, Niklas},
120-
license = {MPL-2.0},
121-
title = {{qFALL-math}},
122-
url = {https://github.com/qfall/math}
123-
}
70+
Update to eprint
12471
```
12572

126-
## Get in Touch
73+
## Dependencies
74+
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.
75+
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.
76+
77+
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.
78+
79+
## License
12780

128-
To contact us, please refer to our mailing list `pg-qfall(at)lists.upb.de`.
81+
This library is distributed under the **Mozilla Public License Version 2.0** which can be found [here](https://github.com/qfall/math/blob/dev/LICENSE).
82+
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.

0 commit comments

Comments
 (0)