Version 0.1.0

.github/workflows/publish_to_pypi.yml

@@ -0,0 +1,41 @@
+name: Publish Python 🐍 distribution 📦 to PyPI
+
+on: push
+
+jobs:
+    build:
+        name: Build distribution 📦
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v4
+            - name: Set up Python
+              uses: actions/setup-python@v4
+              with:
+                python-version: "3.x"
+            - name: Install pypa/build
+              run: >-
+                python3 -m
+                pip install
+                build
+                --user
+            - name: Build a binary wheel and a source tarball
+              run: python3 -m build
+            - name: Store the distribution packages
+              uses: actions/upload-artifact@v3
+              with:
+                name: python-package-distributions
+                path: dist/
+
+    publish-to-pypi:
+        name: >-
+            Publish Python 🐍 distribution 📦 to PyPI
+        if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+        needs:
+        - build
+        runs-on: ubuntu-latest
+        environment:
+            name: pypi
+            url: https://pypi.org/p/oraqle
+        permissions:
+            id-token: write  # IMPORTANT: mandatory for trusted publishing

.github/workflows/python-app.yml

@@ -0,0 +1,40 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python application
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install ruff pytest
+        pip install -r requirements.txt
+        pip install -e .
+    - name: Lint with ruff
+      run: |
+        ruff check
+    - name: Test with pytest
+      run: |
+        pytest

.gitignore

@@ -1 +1,13 @@
 /venv
+*.dot
+.idea/**
+__pycache__/**
+/build
+.DS_Store
+*.egg-info*
+instructions.txt
+.ipynb_checkpoints/
+*.pdf
+*.pkl
+.sphinx_build/
+/dist

README.md

@@ -1,2 +1,11 @@
 # Oraqle
-The first version of the oraqle compiler will be released in April 2024.
+The oraqle compiler lets you generate arithmetic circuits from high-level Python code. It also lets you generate code using HElib.
+
+This repository uses a fork of fhegen as a dependency and adapts some of the code from [fhegen](https://github.com/Crypto-TII/fhegen), which was written by Johannes Mono, Chiara Marcolla, Georg Land, Tim Güneysu, and Najwa Aaraj. You can read their theoretical work at: https://eprint.iacr.org/2022/706.
+
+## Setting up
+The best way to get things up and running is using a virtual environment:
+- Set up a virtualenv using `python3 -m venv venv` in the directory.
+- Enter the virtual environment using `source venv/bin/activate`.
+- Install the requirements using `pip install requirements.txt`.
+- *To overcome import problems*, run `pip install -e .`, which will create links to your files (so you do not need to re-install after every change).

docs/api/abstract_nodes_api.md

@@ -0,0 +1,5 @@
+# Abstract nodes API
+!!! warning
+    In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
+If you want to extend the oraqle compiler, or implement your own high-level nodes, it is easiest to extend one of the existing abstract node classes.

docs/api/addition_chains_api.md

@@ -0,0 +1,11 @@
+# Addition chains API
+!!! warning
+    In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
+The `add_chains` module contains tools for generating addition chains.
+
+::: oraqle.add_chains
+    options:
+      heading_level: 2
+      show_submodules: true
+      show_if_no_docstring: false

docs/api/circuits_api.md

@@ -0,0 +1,16 @@
+# Circuits API
+!!! warning
+    In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
+
+## High-level circuits
+::: oraqle.compiler.circuit.Circuit
+    options:
+      heading_level: 3
+
+
+## Arithmetic circuits
+::: oraqle.compiler.circuit.ArithmeticCircuit
+    options:
+      heading_level: 3
+

docs/api/code_generation_api.md

@@ -0,0 +1,56 @@
+# Code generation API
+!!! warning
+    In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
+The easiest way is using:
+```python3
+arithmetic_circuit.generate_code()
+```
+
+## Arithmetic instructions
+If you want to extend the oraqle compiler, or implement your own code generation, you can use the following instructions to do so.
+
+??? info "Abstract instruction"
+    ::: oraqle.compiler.instructions.ArithmeticInstruction
+        options:
+            heading_level: 3
+
+??? info "InputInstruction"
+    ::: oraqle.compiler.instructions.InputInstruction
+        options:
+            heading_level: 3
+
+??? info "AdditionInstruction"
+    ::: oraqle.compiler.instructions.AdditionInstruction
+        options:
+            heading_level: 3
+
+??? info "MultiplicationInstruction"
+    ::: oraqle.compiler.instructions.MultiplicationInstruction
+        options:
+            heading_level: 3
+
+??? info "ConstantAdditionInstruction"
+    ::: oraqle.compiler.instructions.ConstantAdditionInstruction
+        options:
+            heading_level: 3
+
+??? info "ConstantMultiplicationInstruction"
+    ::: oraqle.compiler.instructions.ConstantMultiplicationInstruction
+        options:
+            heading_level: 3
+
+??? info "OutputInstruction"
+    ::: oraqle.compiler.instructions.OutputInstruction
+        options:
+            heading_level: 3
+
+
+## Generating arithmetic programs
+::: oraqle.compiler.instructions.ArithmeticProgram
+    options:
+      heading_level: 3
+
+
+## Generating code for HElib
+...

docs/api/nodes_api.md

@@ -0,0 +1,53 @@
+# Nodes API
+!!! warning
+    In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
+## Boolean operations
+
+??? info "AND operation"
+    ::: oraqle.compiler.boolean.bool_and.And
+        options:
+            heading_level: 3
+
+??? info "OR operation"
+    ::: oraqle.compiler.boolean.bool_or.Or
+        options:
+            heading_level: 3
+
+??? info "NEG operation"
+    ::: oraqle.compiler.boolean.bool_neg.Neg
+        options:
+            heading_level: 3
+
+
+## Arithmetic operations
+These operations are fundamental arithmetic operations, so they will stay the same when they are arithmetized.
+
+
+## High-level arithmetic operations
+
+??? info "Subtraction"
+    ::: oraqle.compiler.arithmetic.subtraction.Subtraction
+        options:
+            heading_level: 3
+
+??? info "Exponentiation"
+    ::: oraqle.compiler.arithmetic.exponentiation.Power
+        options:
+            heading_level: 3
+
+
+## Polynomial evaluation
+
+??? info "Univariate polynomial evaluation"
+    ::: oraqle.compiler.polynomials.univariate.UnivariatePoly
+        options:
+            heading_level: 3
+
+
+## Control flow
+
+??? info "If-else statement"
+    ::: oraqle.compiler.control_flow.conditional.IfElse
+        options:
+            heading_level: 3

docs/api/pareto_fronts_api.md

@@ -0,0 +1,18 @@
+# Pareto fronts API
+!!! warning
+    In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
+If you are using depth-aware arithmetization, you will find that the compiler does not output one arithmetic circuit.
+Instead, it outputs a Pareto front, which represents the best circuits that it could generate trading off two metrics:
+The *multiplicative depth* and the *multiplicative size/cost*.
+This page briefly explains the API for interfacing with these Pareto fronts.
+
+## The abstract base class
+
+??? info "Abstract ParetoFront"
+    ::: oraqle.compiler.nodes.abstract.ParetoFront
+        options:
+            heading_level: 3
+
+## Depth-size and depth-cost fronts
+

docs/config.md

@@ -0,0 +1,7 @@
+# Configuration parameters
+
+::: oraqle.config
+    options:
+      heading_level: 2
+      show_submodules: true
+      show_if_no_docstring: false

docs/example_circuits.md

@@ -0,0 +1,7 @@
+!!! warning
+    Some of these example circuits are untested and may be incorrect.
+
+::: oraqle.circuits
+    options:
+      heading_level: 3
+      show_submodules: true

docs/getting_started.md

@@ -0,0 +1,85 @@
+# Getting started
+In 5 minutes, this page will guide you through how to install oraqle, how to specify high-level programs, and how to arithmetize your first circuit!
+
+## Installation
+Simply install the most recent version of the Oraqle compiler using:
+```
+pip install oraqle
+```
+
+We use continuous integration to test every build of the Oraqle compiler on Windows, MacOS, and Unix systems.
+If you do run into problems, feel free to [open an issue on GitHub]()!
+
+## Specifying high-level programs
+Let's start with importing `galois`, which represents our plaintext algebra.
+We will also immediately import the relevant oraqle classes for our little example:
+```python3
+from galois import GF
+
+from oraqle.compiler.circuit import Circuit
+from oraqle.compiler.nodes.leafs import Input
+```
+
+For this example, we will use 31 as our plaintext modulus. This algebra is denoted by `GF(31)`.
+Let's create a few inputs that represent elements in this algebra:
+```python3
+gf = GF(31)
+
+x = Input("x", gf)
+y = Input("y", gf)
+z = Input("z", gf)
+```
+
+We can now perform some operations on these elements, and they do not have to be arithmetic operations!
+For example, we can perform equality checks or comparisons:
+```
+comparison = x < y
+equality = y == z
+both = comparison & equality
+```
+
+While we have specified some operations, we have not yet established this as a circuit. We will do so now:
+```python3
+circuit = Circuit([both])
+```
+
+And that's it! We are done specifying our first high-level circuit.
+As you can see this is all very similar to writing a regular Python program.
+If you want to visualize this high-level circuit before we continue with arithmetizing it, you can run the following (if you have graphviz installed):
+```python3
+circuit.to_pdf("high_level_circuit.pdf")
+```
+
+!!! tip
+    If you do not have graphviz installed, you can instead call:
+    ```python3
+    circuit.to_dot("high_level_circuit.dot")
+    ```
+    After that, you can copy the file contents to [an online graphviz viewer](https://dreampuf.github.io/GraphvizOnline)!
+
+## Arithmetizing your first circuit
+At this point, arithmetization is a breeze, because the oraqle compiler takes care of these steps.
+We can create an arithmetic circuit and visualize it using the following snippet:
+```python3
+arithmetic_circuit = circuit.arithmetize()
+arithmetic_circuit.to_pdf("arithmetic_circuit.pdf")
+```
+
+You will notice that it's quite a large circuit. But how large is it exactly?
+This is a question that we can ask to the oraqle compiler:
+```python3
+print("Depth:", arithmetic_circuit.multiplicative_depth())
+print("Size:", arithmetic_circuit.multiplicative_size())
+print("Cost:", arithmetic_circuit.multiplicative_cost(0.7))
+```
+
+In the last line, we asked the compiler to output the multiplicative cost, considering that squaring operations are cheaper than regular multiplications.
+We weighed this cost with a factor 0.7.
+
+Now that we have an arithmetic circuit, we can use homomorphic encryption to evaluate it!
+If you are curious about executing these circuits for real, consider reading [the code generation tutorial](tutorial_running_exps.md).
+
+!!! warning
+    There are many homomorphic encryption libraries that do not support plaintext moduli that are not NTT-friendly. The plaintext modulus we chose (31) is not NTT-friendly.
+    In fact, only very few primes are NTT-friendly, and they are somewhat large. This is why, right now, the oraqle compiler only implements code generation for HElib.
+    HElib is (as far as we are aware) the only library that supports plaintext moduli that are not NTT-friendly.