chore: Move to the mono repo layout

frontends/concrete-python/docs/tutorial/decorator.md

@@ -0,0 +1,20 @@
+# Decorator
+
+If you are trying to compile a regular function, you can use the decorator interface instead of the explicit `Compiler` interface to simplify your code:
+
+```python
+import concrete.numpy as cnp
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return x + 42
+
+inputset = range(10)
+circuit = f.compile(inputset)
+
+assert circuit.encrypt_run_decrypt(10) == f(10)
+```
+
+{% hint style="info" %}
+Think of this decorator as a way to add the `compile` method to the function object without changing its name elsewhere.
+{% endhint %}

frontends/concrete-python/docs/tutorial/direct_circuits.md

@@ -0,0 +1,83 @@
+# Direct Circuits
+
+{% hint style="warning" %}
+Direct circuits are still experimental, and it's very easy to shoot yourself in the foot (e.g., no overflow checks, no type coercion) while using them so utilize them with care.
+{% endhint %}
+
+For some applications, data types of inputs, intermediate values and outputs are known (e.g., for manipulating bytes, you would want to use uint8). For such cases, using inputsets to determine bounds are not necessary, or even error-prone. Therefore, another interface for defining such circuits, is introduced:
+
+```python
+import concrete.numpy as cnp
+
+@cnp.circuit({"x": "encrypted"})
+def circuit(x: cnp.uint8):
+    return x + 42
+
+assert circuit.encrypt_run_decrypt(10) == 52
+```
+
+There are a few differences between direct circuits and traditional circuits though:
+
+- You need to remember that resulting dtype for each operation will be determined by its inputs. This can lead to some unexpected results if you're not careful (e.g., if you do `-x` where `x: cnp.uint8`, you'll not get the negative value as the result will be `cnp.uint8` as well)
+- You need to use cnp types in `.astype(...)` calls (e.g., `np.sqrt(x).astype(cnp.uint4)`). This is because there are no inputset evaluation, so cannot determine the bit-width of the output.
+- You need to specify the resulting data type in [univariate](./extensions.md#cnpunivariatefunction) extension (e.g., `cnp.univariate(function, outputs=cnp.uint4)(x)`), because of the same reason as above.
+- You need to be careful with overflows. With inputset evaluation, you'll get bigger bit-widths but no overflows, with direct definition, you're responsible to ensure there aren't any overflows!
+
+Let's go over a more complicated example to see how direct circuits behave:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+def square(value):
+    return value ** 2
+
+@cnp.circuit({"x": "encrypted", "y": "encrypted"})
+def circuit(x: cnp.uint8, y: cnp.int2):
+    a = x + 10
+    b = y + 10
+
+    c = np.sqrt(a).round().astype(cnp.uint4)
+    d = cnp.univariate(square, outputs=cnp.uint8)(b)
+
+    return d - c
+
+print(circuit)
+```
+prints
+```
+%0 = x                       # EncryptedScalar<uint8>
+%1 = y                       # EncryptedScalar<int2>
+%2 = 10                      # ClearScalar<uint4>
+%3 = add(%0, %2)             # EncryptedScalar<uint8>
+%4 = 10                      # ClearScalar<uint4>
+%5 = add(%1, %4)             # EncryptedScalar<int4>
+%6 = subgraph(%3)            # EncryptedScalar<uint4>
+%7 = square(%5)              # EncryptedScalar<uint8>
+%8 = subtract(%7, %6)        # EncryptedScalar<uint8>
+return %8
+
+Subgraphs:
+
+    %6 = subgraph(%3):
+
+        %0 = input                         # EncryptedScalar<uint8>
+        %1 = sqrt(%0)                      # EncryptedScalar<float64>
+        %2 = around(%1, decimals=0)        # EncryptedScalar<float64>
+        %3 = astype(%2)                    # EncryptedScalar<uint4>
+        return %3
+```
+And here is the breakdown of assigned data types:
+```
+%0 is uint8 because it's specified in the definition
+%1 is  int2 because it's specified in the definition
+%2 is uint4 because it's the constant 10
+%3 is uint8 because it's the addition between uint8 and uint4
+%4 is uint4 because it's the constant 10
+%5 is  int4 because it's the addition between int2 and uint4
+%6 is uint4 because it's specified in astype
+%7 is uint8 because it's specified in univariate
+%8 is uint8 because it's subtraction between uint8 and uint4
+```
+
+As you can see, `%8` is subtraction of two unsigned values, and it's unsigned as well. In an overflow condition where `c > d`, it'll result in undefined behavior.

frontends/concrete-python/docs/tutorial/extensions.md

@@ -0,0 +1,153 @@
+# Extensions
+
+**Concrete-Numpy** tries to support **NumPy** as much as possible, but due to some technical limitations, not everything can be supported. On top of that, there are some things **NumPy** lack, which are useful. In some of these situations, we provide extensions in **Concrete-Numpy** to improve your experience.
+
+## cnp.zero()
+
+Allows you to create encrypted scalar zero:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    z = cnp.zero()
+    return x + z
+
+inputset = range(10)
+circuit = f.compile(inputset)
+
+for x in range(10):
+    assert circuit.encrypt_run_decrypt(x) == x
+```
+
+## cnp.zeros(shape)
+
+Allows you to create encrypted tensor of zeros:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    z = cnp.zeros((2, 3))
+    return x + z
+
+inputset = range(10)
+circuit = f.compile(inputset)
+
+for x in range(10):
+    assert np.array_equal(circuit.encrypt_run_decrypt(x), np.array([[x, x, x], [x, x, x]]))
+```
+
+## cnp.one()
+
+Allows you to create encrypted scalar one:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    z = cnp.one()
+    return x + z
+
+inputset = range(10)
+circuit = f.compile(inputset)
+
+for x in range(10):
+    assert circuit.encrypt_run_decrypt(x) == x + 1
+```
+
+## cnp.ones(shape)
+
+Allows you to create encrypted tensor of ones:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    z = cnp.ones((2, 3))
+    return x + z
+
+inputset = range(10)
+circuit = f.compile(inputset)
+
+for x in range(10):
+    assert np.array_equal(circuit.encrypt_run_decrypt(x), np.array([[x, x, x], [x, x, x]]) + 1)
+```
+
+## cnp.univariate(function)
+
+Allows you to wrap any univariate function into a single table lookup:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+def complex_univariate_function(x):
+
+    def per_element(element):
+        result = 0
+        for i in range(element):
+            result += i
+        return result
+
+    return np.vectorize(per_element)(x)
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return cnp.univariate(complex_univariate_function)(x)
+
+inputset = [np.random.randint(0, 5, size=(3, 2)) for _ in range(10)]
+circuit = f.compile(inputset)
+
+sample = np.array([
+    [0, 4],
+    [2, 1],
+    [3, 0],
+])
+assert np.array_equal(circuit.encrypt_run_decrypt(sample), complex_univariate_function(sample))
+```
+
+{% hint style="danger" %}
+The wrapped function shouldn't have any side effects, and it should be deterministic.
+{% endhint %}
+
+## coonx.conv(...)
+
+Allows you to perform a convolution operation, with the same semantic of [onnx.Conv](https://github.com/onnx/onnx/blob/main/docs/Operators.md#Conv):
+
+```python
+import concrete.numpy as cnp
+import concrete.onnx as connx
+import numpy as np
+
+weight = np.array([[2, 1], [3, 2]]).reshape(1, 1, 2, 2)
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return connx.conv(x, weight, strides=(2, 2), dilations=(1, 1), group=1)
+
+inputset = [np.random.randint(0, 4, size=(1, 1, 4, 4)) for _ in range(10)]
+circuit = f.compile(inputset)
+
+sample = np.array(
+    [
+        [3, 2, 1, 0],
+        [3, 2, 1, 0],
+        [3, 2, 1, 0],
+        [3, 2, 1, 0],
+    ]
+).reshape(1, 1, 4, 4)
+assert np.array_equal(circuit.encrypt_run_decrypt(sample), f(sample))
+```
+
+{% hint style="danger" %}
+Only 2D convolutions with one groups and without padding are supported for the time being.
+{% endhint %}

frontends/concrete-python/docs/tutorial/floating_points.md

@@ -0,0 +1,79 @@
+# Floating Points
+
+**Concrete-Numpy** partly supports floating points:
+
+* They cannot be inputs
+* They cannot be outputs
+* They can be intermediate values under certain constraints
+
+## As intermediate values
+
+**Concrete-Compile**, which is used for compiling the circuit, doesn't support floating points at all. However, it supports table lookups. They take an integer and map it to another integer. It does not care how the lookup table is calculated. Further, the constraints of this operation are such that there should be a single integer input and it should result in a single integer output.
+
+As long as your floating point operations comply with those constraints, **Concrete-Numpy** automatically converts your operations to a table lookup operation:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    a = x + 1.5
+    b = np.sin(x)
+    c = np.around(a + b)
+    d = c.astype(np.int64)
+    return d
+
+inputset = range(8)
+circuit = f.compile(inputset)
+
+for x in range(8):
+    assert circuit.encrypt_run_decrypt(x) == f(x)
+```
+
+In the example above, `a`, `b`, and `c` are all floating point intermediates. However, they are just used to calculate `d`, which is an integer and value of `d` dependent upon `x` , which is another integer. **Concrete-Numpy** detects this and fuses all of those operations into a single table lookup from `x` to `d`.
+
+This approach works for a variety of use cases, but it comes up short for some:
+
+<!--pytest-codeblocks:skip-->
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted", "y": "encrypted"})
+def f(x, y):
+    a = x + 1.5
+    b = np.sin(y)
+    c = np.around(a + b)
+    d = c.astype(np.int64)
+    return d
+
+inputset = [(1, 2), (3, 0), (2, 2), (1, 3)]
+circuit = f.compile(inputset)
+
+for x in range(8):
+    assert circuit.encrypt_run_decrypt(x) == f(x)
+```
+
+... results in:
+
+```
+RuntimeError: Function you are trying to compile cannot be converted to MLIR
+
+%0 = x                             # EncryptedScalar<uint2>
+%1 = 1.5                           # ClearScalar<float64>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only integer constants are supported
+%2 = y                             # EncryptedScalar<uint2>
+%3 = add(%0, %1)                   # EncryptedScalar<float64>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only integer operations are supported
+%4 = sin(%2)                       # EncryptedScalar<float64>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only integer operations are supported
+%5 = add(%3, %4)                   # EncryptedScalar<float64>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only integer operations are supported
+%6 = around(%5)                    # EncryptedScalar<float64>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only integer operations are supported
+%7 = astype(%6, dtype=int_)        # EncryptedScalar<uint3>
+return %7
+```
+
+The reason for this is that `d` no longer depends solely on `x`, it depends on `y` as well. **Concrete-Numpy** cannot fuse these operations, so it raises an exception instead.

frontends/concrete-python/docs/tutorial/formatting.md

@@ -0,0 +1,19 @@
+# Formatting
+
+You can convert your compiled circuit into its textual representation by converting it to string:
+
+<!--pytest-codeblocks:skip-->
+```python
+str(circuit)
+```
+
+If you just want to see the output on your terminal, you can directly print it as well:
+
+<!--pytest-codeblocks:skip-->
+```python
+print(circuit)
+```
+
+{% hint style="warning" %}
+Formatting is just for debugging. It's not possible to serialize the circuit back from its textual representation. See [How to Deploy](../howto/deploy.md) if that's your goal.
+{% endhint %}

frontends/concrete-python/docs/tutorial/key_value_database.md

@@ -0,0 +1,3 @@
+# Key Value Database
+
+This is an interactive tutorial written as a Jupyter Notebook, which you can find [here](https://github.com/zama-ai/concrete-numpy/blob/main/docs/tutorial/key_value_database.ipynb).

frontends/concrete-python/docs/tutorial/rounded_table_lookups.md

@@ -0,0 +1,183 @@
+# Rounded Table Lookups
+
+{% hint style="warning" %}
+Rounded table lookups are not compilable yet. API is stable and will not change so it's documented, but you might not be able to run the code samples in this document.
+{% endhint %}
+
+Table lookups have a strict constraint on number of bits they support. This can be quite limiting, especially if you don't need the exact precision.
+
+To overcome such shortcomings, rounded table lookup operation is introduced. It's a way to extract most significant bits of a large integer and then applying the table lookup to those bits.
+
+Imagine you have an 8-bit value, but you want to have a 5-bit table lookup, you can call `cnp.round_bit_pattern(input, lsbs_to_remove=3)` and use the value you get in the table lookup.
+
+In Python, evaluation will work like the following:
+```
+0b_0000_0000 => 0b_0000_0000
+0b_0000_0001 => 0b_0000_0000
+0b_0000_0010 => 0b_0000_0000
+0b_0000_0011 => 0b_0000_0000
+0b_0000_0100 => 0b_0000_1000
+0b_0000_0101 => 0b_0000_1000
+0b_0000_0110 => 0b_0000_1000
+0b_0000_0111 => 0b_0000_1000
+
+0b_1010_0000 => 0b_1010_0000
+0b_1010_0001 => 0b_1010_0000
+0b_1010_0010 => 0b_1010_0000
+0b_1010_0011 => 0b_1010_0000
+0b_1010_0100 => 0b_1010_1000
+0b_1010_0101 => 0b_1010_1000
+0b_1010_0110 => 0b_1010_1000
+0b_1010_0111 => 0b_1010_1000
+
+0b_1010_1000 => 0b_1010_1000
+0b_1010_1001 => 0b_1010_1000
+0b_1010_1010 => 0b_1010_1000
+0b_1010_1011 => 0b_1010_1000
+0b_1010_1100 => 0b_1011_0000
+0b_1010_1101 => 0b_1011_0000
+0b_1010_1110 => 0b_1011_0000
+0b_1010_1111 => 0b_1011_0000
+
+0b_1011_1000 => 0b_1011_1000
+0b_1011_1001 => 0b_1011_1000
+0b_1011_1010 => 0b_1011_1000
+0b_1011_1011 => 0b_1011_1000
+0b_1011_1100 => 0b_1100_0000
+0b_1011_1101 => 0b_1100_0000
+0b_1011_1110 => 0b_1100_0000
+0b_1011_1111 => 0b_1100_0000
+```
+
+and during homomorphic execution, it'll be converted like this:
+```
+0b_0000_0000 => 0b_00000
+0b_0000_0001 => 0b_00000
+0b_0000_0010 => 0b_00000
+0b_0000_0011 => 0b_00000
+0b_0000_0100 => 0b_00001
+0b_0000_0101 => 0b_00001
+0b_0000_0110 => 0b_00001
+0b_0000_0111 => 0b_00001
+
+0b_1010_0000 => 0b_10100
+0b_1010_0001 => 0b_10100
+0b_1010_0010 => 0b_10100
+0b_1010_0011 => 0b_10100
+0b_1010_0100 => 0b_10101
+0b_1010_0101 => 0b_10101
+0b_1010_0110 => 0b_10101
+0b_1010_0111 => 0b_10101
+
+0b_1010_1000 => 0b_10101
+0b_1010_1001 => 0b_10101
+0b_1010_1010 => 0b_10101
+0b_1010_1011 => 0b_10101
+0b_1010_1100 => 0b_10110
+0b_1010_1101 => 0b_10110
+0b_1010_1110 => 0b_10110
+0b_1010_1111 => 0b_10110
+
+0b_1011_1000 => 0b_10111
+0b_1011_1001 => 0b_10111
+0b_1011_1010 => 0b_10111
+0b_1011_1011 => 0b_10111
+0b_1011_1100 => 0b_11000
+0b_1011_1101 => 0b_11000
+0b_1011_1110 => 0b_11000
+0b_1011_1111 => 0b_11000
+```
+
+and then a modified table lookup would be applied to the resulting 5-bits.
+
+Here is a concrete example, let's say you want to apply ReLU to an 18-bit value. Let's see what the original ReLU looks like first:
+
+```python
+import matplotlib.pyplot as plt
+
+def relu(x):
+    return x if x >= 0 else 0
+
+xs = range(-100_000, 100_000)
+ys = [relu(x) for x in xs]
+
+plt.plot(xs, ys)
+plt.show()
+```
+
+![](../_static/rounded-tlu/relu.png)
+
+Input range is [-100_000, 100_000), which means 18-bit table lookups are required, but they are not supported yet, you can apply rounding operation to the input before passing it to `ReLU` function:
+
+```python
+import concrete.numpy as cnp
+import matplotlib.pyplot as plt
+import numpy as np
+
+def relu(x):
+    return x if x >= 0 else 0
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    x = cnp.round_bit_pattern(x, lsbs_to_remove=10)
+    return cnp.univariate(relu)(x)
+
+inputset = [-100_000, (100_000 - 1)]
+circuit = f.compile(inputset)
+
+xs = range(-100_000, 100_000)
+ys = [circuit.simulate(x) for x in xs]
+
+plt.plot(xs, ys)
+plt.show()
+```
+
+in this case we've removed 10 least significant bits of the input and then applied ReLU function to this value to get:
+
+![](../_static/rounded-tlu/10-bits-removed.png)
+
+which is close enough to original ReLU for some cases. If your application is more flexible, you could remove more bits, let's say 12 to get:
+
+![](../_static/rounded-tlu/12-bits-removed.png)
+
+This is very useful, but in some cases, you don't know how many bits your input have, so it's not reliable to specify `lsbs_to_remove` manually. For this reason, `AutoRounder` class is introduced.
+
+```python
+import concrete.numpy as cnp
+import matplotlib.pyplot as plt
+import numpy as np
+
+rounder = cnp.AutoRounder(target_msbs=6)
+
+def relu(x):
+    return x if x >= 0 else 0
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    x = cnp.round_bit_pattern(x, lsbs_to_remove=rounder)
+    return cnp.univariate(relu)(x)
+
+inputset = [-100_000, (100_000 - 1)]
+cnp.AutoRounder.adjust(f, inputset)  # alternatively, you can use `auto_adjust_rounders=True` below
+circuit = f.compile(inputset)
+
+xs = range(-100_000, 100_000)
+ys = [circuit.simulate(x) for x in xs]
+
+plt.plot(xs, ys)
+plt.show()
+```
+
+`AutoRounder`s allow you to set how many of the most significant bits to keep, but they need to be adjusted using an inputset to determine how many of the least significant bits to remove. This can be done manually using `cnp.AutoRounder.adjust(function, inputset)`, or by setting `auto_adjust_rounders` to `True` during compilation.
+
+In the example above, `6` of the most significant bits are kept to get:
+
+![](../_static/rounded-tlu/6-bits-kept.png)
+
+You can adjust `target_msbs` depending on your requirements. If you set it to `4` for example, you'd get:
+
+![](../_static/rounded-tlu/4-bits-kept.png)
+
+{% hint style="warning" %}
+`AutoRounder`s should be defined outside the function being compiled. They are used to store the result of adjustment process, so they shouldn't be created each time the function is called.
+{% endhint %}

frontends/concrete-python/docs/tutorial/simulation.md

@@ -0,0 +1,37 @@
+# Simulation
+
+During development, speed of homomorphic execution is a big blocker for fast prototyping.
+You could call the function you're trying to compile directly of course, but it won't be exactly the same as FHE execution, which has a certain probability of error (see [Exactness](../getting-started/exactness.md)).
+
+Considering these, simulation is introduced:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return (x + 1) ** 2
+
+inputset = [np.random.randint(0, 10, size=(10,)) for _ in range(10)]
+circuit = f.compile(inputset, p_error=0.1)
+
+sample = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+
+actual = f(sample)
+simulation = circuit.simulate(sample)
+
+print(actual.tolist())
+print(simulation.tolist())
+```
+
+prints
+
+```
+[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
+[1, 4, 9, 16, 16, 36, 49, 64, 81, 100]
+```
+
+{% hint style="warning" %}
+Currently, simulation is better than directly calling from Python, but it's not exactly the same with FHE execution. The reason is that it is implemented in Python. Imagine you have an identity table lookup, it might be ommitted from the generated FHE code by the compiler, but it'll be present in Python as optimizations are not done in Python. This will result in a bigger error in simulation. Furthermore, some operations have multiple table lookups within them, and those cannot be simulated unless the actual implementations of said operations are ported to Python. In the future, simulation functionality will be provided by the compiler so all of these issues would be addressed. Until then, keep these in mind.
+{% endhint %}

frontends/concrete-python/docs/tutorial/table_lookups.md

@@ -0,0 +1,178 @@
+# Table Lookups
+
+In this tutorial, we will review the ways to perform direct table lookups in **Concrete-Numpy**.
+
+## Direct table lookup
+
+**Concrete-Numpy** provides a `LookupTable` class for you to create your own tables and apply them in your circuits.
+
+{% hint style="info" %}
+`LookupTable`s can have any number of elements. Let's call them **N**. As long as the lookup variable is in range \[-**N**, **N**), table lookup is valid.
+
+If you go out of bounds of this range, you will get the following error:
+
+```
+IndexError: index 10 is out of bounds for axis 0 with size 6
+```
+{% endhint %}
+
+{% hint style="info" %}
+The number of elements in the lookup table doesn't affect performance in any way.
+{% endhint %}
+
+### With scalars.
+
+You can create the lookup table using a list of integers and apply it using indexing:
+
+```python
+import concrete.numpy as cnp
+
+table = cnp.LookupTable([2, -1, 3, 0])
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return table[x]
+
+inputset = range(4)
+circuit = f.compile(inputset)
+
+assert circuit.encrypt_run_decrypt(0) == table[0] == 2
+assert circuit.encrypt_run_decrypt(1) == table[1] == -1
+assert circuit.encrypt_run_decrypt(2) == table[2] == 3
+assert circuit.encrypt_run_decrypt(3) == table[3] == 0
+```
+
+### With tensors.
+
+When you apply the table lookup to a tensor, you apply the scalar table lookup to each element of the tensor:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+table = cnp.LookupTable([2, -1, 3, 0])
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return table[x]
+
+inputset = [np.random.randint(0, 4, size=(2, 3)) for _ in range(10)]
+circuit = f.compile(inputset)
+
+sample = [
+    [0, 1, 3],
+    [2, 3, 1],
+]
+expected_output = [
+    [2, -1, 0],
+    [3, 0, -1],
+]
+actual_output = circuit.encrypt_run_decrypt(np.array(sample))
+
+for i in range(2):
+    for j in range(3):
+        assert actual_output[i][j] == expected_output[i][j] == table[sample[i][j]]
+```
+
+### With negative values.
+
+`LookupTable` mimics array indexing in Python, which means if the lookup variable is negative, the table is looked up from the back:
+
+```python
+import concrete.numpy as cnp
+
+table = cnp.LookupTable([2, -1, 3, 0])
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return table[-x]
+
+inputset = range(1, 5)
+circuit = f.compile(inputset)
+
+assert circuit.encrypt_run_decrypt(1) == table[-1] == 0
+assert circuit.encrypt_run_decrypt(2) == table[-2] == 3
+assert circuit.encrypt_run_decrypt(3) == table[-3] == -1
+assert circuit.encrypt_run_decrypt(4) == table[-4] == 2
+```
+
+## Direct multi table lookup
+
+In case you want to apply a different lookup table to each element of a tensor, you can have a `LookupTable` of `LookupTable`s:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+squared = cnp.LookupTable([i ** 2 for i in range(4)])
+cubed = cnp.LookupTable([i ** 3 for i in range(4)])
+
+table = cnp.LookupTable([
+    [squared, cubed],
+    [squared, cubed],
+    [squared, cubed],
+])
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return table[x]
+
+inputset = [np.random.randint(0, 4, size=(3, 2)) for _ in range(10)]
+circuit = f.compile(inputset)
+
+sample = [
+    [0, 1],
+    [2, 3],
+    [3, 0],
+]
+expected_output = [
+    [0, 1],
+    [4, 27],
+    [9, 0]
+]
+actual_output = circuit.encrypt_run_decrypt(np.array(sample))
+
+for i in range(3):
+    for j in range(2):
+        if j == 0:
+            assert actual_output[i][j] == expected_output[i][j] == squared[sample[i][j]]
+        else:
+            assert actual_output[i][j] == expected_output[i][j] == cubed[sample[i][j]]
+```
+
+In this example, we applied a `squared` table to the first column and a `cubed` table to the second one.
+
+## Fused table lookup
+
+**Concrete-Numpy** tries to fuse some operations into table lookups automatically, so you don't need to create the lookup tables manually:
+
+```python
+import concrete.numpy as cnp
+import numpy as np
+
+@cnp.compiler({"x": "encrypted"})
+def f(x):
+    return (42 * np.sin(x)).astype(np.int64) // 10
+
+inputset = range(8)
+circuit = f.compile(inputset)
+
+for x in range(8):
+    assert circuit.encrypt_run_decrypt(x) == f(x)
+```
+
+{% hint style="info" %}
+All lookup tables need to be from integers to integers. So, without `.astype(np.int64)`, **Concrete-Numpy** will not be able to fuse.
+{% endhint %}
+
+The function is first traced into:
+
+![](../\_static/tutorials/table-lookup/1.initial.graph.png)
+
+Then, **Concrete-Numpy** fuses appropriate nodes:
+
+![](../\_static/tutorials/table-lookup/3.final.graph.png)
+
+{% hint style="info" %}
+Fusing makes the code more readable and easier to modify, so try to utilize it over manual `LookupTable`s as much as possible.
+{% endhint %}

frontends/concrete-python/docs/tutorial/tagging.md

@@ -0,0 +1,56 @@
+# Tagging
+
+When you have big circuits, keeping track of which node corresponds to which part of your code becomes very hard. Tagging system could simplify such situations: 
+
+```python
+def g(z):
+    with cnp.tag("def"):
+        a = 120 - z
+        b = a // 4
+    return b
+
+
+def f(x):
+    with cnp.tag("abc"):
+        x = x * 2
+        with cnp.tag("foo"):
+            y = x + 42
+        z = np.sqrt(y).astype(np.int64)
+
+    return g(z + 3) * 2
+```
+
+when you compile `f` with inputset of `range(10)`, you get the following graph:
+
+```
+ %0 = x                            # EncryptedScalar<uint4>        ∈ [0, 9]
+ %1 = 2                            # ClearScalar<uint2>            ∈ [2, 2]            @ abc
+ %2 = multiply(%0, %1)             # EncryptedScalar<uint5>        ∈ [0, 18]           @ abc
+ %3 = 42                           # ClearScalar<uint6>            ∈ [42, 42]          @ abc.foo
+ %4 = add(%2, %3)                  # EncryptedScalar<uint6>        ∈ [42, 60]          @ abc.foo
+ %5 = subgraph(%4)                 # EncryptedScalar<uint3>        ∈ [6, 7]            @ abc
+ %6 = 3                            # ClearScalar<uint2>            ∈ [3, 3]
+ %7 = add(%5, %6)                  # EncryptedScalar<uint4>        ∈ [9, 10]
+ %8 = 120                          # ClearScalar<uint7>            ∈ [120, 120]        @ def
+ %9 = subtract(%8, %7)             # EncryptedScalar<uint7>        ∈ [110, 111]        @ def
+%10 = 4                            # ClearScalar<uint3>            ∈ [4, 4]            @ def
+%11 = floor_divide(%9, %10)        # EncryptedScalar<uint5>        ∈ [27, 27]          @ def
+%12 = 2                            # ClearScalar<uint2>            ∈ [2, 2]
+%13 = multiply(%11, %12)           # EncryptedScalar<uint6>        ∈ [54, 54]
+return %13
+
+Subgraphs:
+
+    %5 = subgraph(%4):
+
+        %0 = input                         # EncryptedScalar<uint2>          @ abc.foo
+        %1 = sqrt(%0)                      # EncryptedScalar<float64>        @ abc
+        %2 = astype(%1, dtype=int_)        # EncryptedScalar<uint1>          @ abc
+        return %2
+```
+
+and if you get an error, you'll precisely see where the error occurred (e.g., which layer of the neural network, if you tag layers).
+
+{% hint style="info" %}
+In the future, we're planning to use tags for other features as well (e.g., to measure performance of tagged regions), so it's a good idea to start utilizing them for big circuits.
+{% endhint %}