This document provides clear definitions of key concepts used in Concrete framework.

Computation graph

A data structure to represent a computation. It takes the form of a directed acyclic graph where nodes represent inputs, constants, or operations.

Tracing

A method that takes a Python function provided by the user and generates a corresponding computation graph.

Bounds

The minimum and the maximum value that each node in the computation graph can take. Bounds are used to determine the appropriate data type (for example, uint3 or int5) for each node before the computation graphs are converted to MLIR. Concrete simulates the graph with the inputs in the inputset to record the minimum and the maximum value for each node.

Circuit

The result of compilation. A circuit includes both client and server components. It has methods for various operations, such as printing and evaluation.

Table Lookup (TLU)

Programmable Bootstrapping (PBS)

TFHE

Get started

Learn the basics of Concrete, set it up, and make it run with ease.

Build with Concrete

Start building with Concrete by exploring its core features, discovering essential guides, and learning more with step-by-step tutorials.

Explore more

Access to additional resources and join the Zama community.

Explanations

Refer to the API, review product architecture, and access additional resources for in-depth explanations while working with Concrete.

Support channels

Ask technical questions and discuss with the community. Our team of experts usually answers within 24 hours in working days.

Developers

Collaborate with us to advance the FHE spaces and drive innovation together.

In this document, we give a quick overview of the philosophy behind Concrete.

Functions

Available FHE-friendly functions

Levelled vs non-levelled operations

Basically, in the compiled circuit, there will be two kind of operations:

• levelled operations, which are the additions, subtractions or multiplications by a constant; these operations are also called the linear operations

• Table Lookup (TLU) operations, which are used to do anything which is not linear.

TLU are more costly that levelled operations, so we also explain how to limit their impact.

Remark that matrix multiplication (aka Gemm -- General Matrix multiplication) and convolutions are levelled operations, since they imply only additions and multiplications by constant.

Conditional branches and loops

Data

Integers

In Concrete, everything needs to be an integer. Users needing floats can quantize to integers before encryption, operate on integers and dequantize to floats after decryption: all of this is done for the user in Concrete ML. However, you can have floating-point intermediate values as long as they can be converted to an integer Table Lookup, for example, (60 * np.sin(x)).astype(np.int64).

Scalars and tensors

Functions can use scalar and tensors. As with Python, it is prefered to use tensorization, to make computations faster.

Inputs

Inputs of a compiled function can be either encrypted or clear. Use of clear inputs is however quite limited. Remark that constants can appear in the program without much constraints, they are different from clear inputs which are dynamic.

Bit width constraints

Bit width of encrypted values has a limit. We are constantly working on increasing the bit width limit. Exceeding this limit will trigger an error.

Concrete is an open source framework that simplifies the use of Fully Homomorphic Encryption (FHE).

FHE is a powerful technology that enables computations on encrypted data without needing to decrypt it. This capability ensures user privacy and provides robust protection against data breaches, as operations are performed on encrypted data, keeping sensitive information secure even if the server is compromised.

Overview of non-linear operations

In Concrete, there are two types of operations:

• Linear operations: These include additions, subtractions, and multiplications by an integer. They are computationally fast.

Changing bit width in the MLIR or dynamically with a TLU

Binary operations often require operands to have matching bit widths. This adjustment can be achieved in two ways: either directly within the MLIR or dynamically at execution time using a TLU. Each method has its own advantages and trade-offs, so Concrete provides multiple configuration options for non-linear functions.

MLIR adjustment: This method doesn't require an expensive TLU. However, it may affect other parts of your program if the adjusted operand is used elsewhere, potentially causing more changes.

Dynamic adjustment with TLU: This method is more localized and won’t impact other parts of your program, but it’s more expensive due to the cost of using a TLU.

General guidelines

In the following non-linear operations, we propose a certain number of configurations, using the two methods on the different operands. It’s not always clear which option will be the fastest, so we recommend trying out different configurations to see what works best for your circuit.

Note that you have the option to set show_mlir=True to view how the MLIR handles TLUs and bit width changes. However, it's not essential to understand these details. So we recommend just testing the configurations and pick the one that performs best for your case.

Comparisons

For comparison, there are 7 available methods. Here's the general principle:

import numpy as np
from concrete import fhe

configuration = fhe.Configuration(
    comparison_strategy_preference=config,
)

def f(x, y):
    return x < y

inputset = [
    (np.random.randint(0, 2**4), np.random.randint(0, 2**4))
    for _ in range(100)
]

compiler = fhe.Compiler(f, {"x": "encrypted", "y": "encrypted"})
circuit = compiler.compile(inputset, configuration, show_mlir=True)

The config can be one of the following:

• fhe.ComparisonStrategy.CHUNKED

• fhe.ComparisonStrategy.ONE_TLU_PROMOTED

• fhe.ComparisonStrategy.THREE_TLU_CASTED

• fhe.ComparisonStrategy.TWO_TLU_BIGGER_PROMOTED_SMALLER_CASTED

• fhe.ComparisonStrategy.TWO_TLU_BIGGER_CASTED_SMALLER_PROMOTED

• fhe.ComparisonStrategy.THREE_TLU_BIGGER_CLIPPED_SMALLER_CASTED

• fhe.ComparisonStrategy.TWO_TLU_BIGGER_CLIPPED_SMALLER_PROMOTED

Min / Max operations

For min / max operations, there are 3 available methods. Here's the general principle:

import numpy as np
from concrete import fhe

configuration = fhe.Configuration(
    min_max_strategy_preference=config,
)

def f(x, y):
    return np.minimum(x, y)

inputset = [
    (np.random.randint(0, 2**4), np.random.randint(0, 2**2))
    for _ in range(100)
]

compiler = fhe.Compiler(f, {"x": "encrypted", "y": "encrypted"})
circuit = compiler.compile(inputset, configuration, show_mlir=True)

The config can be one of the following:

• fhe.MinMaxStrategy.CHUNKED (default)

• fhe.MinMaxStrategy.ONE_TLU_PROMOTED

• fhe.MinMaxStrategy.THREE_TLU_CASTED

Bitwise operations

For bit wise operations (typically, AND, OR, XOR), there are 5 available methods. Here's the general principle:

import numpy as np
from concrete import fhe

configuration = fhe.Configuration(
    bitwise_strategy_preference=config,
)

def f(x, y):
    return x & y

inputset = [
    (np.random.randint(0, 2**4), np.random.randint(0, 2**4))
    for _ in range(100)
]

compiler = fhe.Compiler(f, {"x": "encrypted", "y": "encrypted"})
circuit = compiler.compile(inputset, configuration, show_mlir=True)

The config can be one of the following:

• fhe.BitwiseStrategy.CHUNKED

• fhe.BitwiseStrategy.ONE_TLU_PROMOTED

• fhe.BitwiseStrategy.THREE_TLU_CASTED

• fhe.BitwiseStrategy.TWO_TLU_BIGGER_PROMOTED_SMALLER_CASTED

• fhe.BitwiseStrategy.TWO_TLU_BIGGER_CASTED_SMALLER_PROMOTED

Shift operations

For shift operations, there are 2 available methods. Here's the general principle:

import numpy as np
from concrete import fhe

configuration = fhe.Configuration(
    shifts_with_promotion=shifts_with_promotion,
)

def f(x, y):
    return x << y

inputset = [
    (np.random.randint(0, 2**3), np.random.randint(0, 2**2))
    for _ in range(100)
]

compiler = fhe.Compiler(f, {"x": "encrypted", "y": "encrypted"})
circuit = compiler.compile(inputset, configuration, show_mlir=True)

The shifts_with_promotion is either True or False.

Relation with fhe.multivariate

import numpy as np
from concrete import fhe


def f(x, y):
    return fhe.multivariate(lambda x, y: x << y)(x, y)


inputset = [(np.random.randint(0, 2**3), np.random.randint(0, 2**2)) for _ in range(100)]

compiler = fhe.Compiler(f, {"x": "encrypted", "y": "encrypted"})
circuit = compiler.compile(inputset, show_mlir=True)

This document introduces some extensions of Concrete, including functions for wrapping univariate and multivariate functions, performing convolution and maxpool operations, creating encrypted arrays, and more.

fhe.univariate(function)

Wraps any univariate function into a single table lookup:

import numpy as np
from concrete import fhe

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)

@fhe.compiler({"x": "encrypted"})
def f(x):
    return fhe.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))

fhe.multivariate(function)

Wraps any multivariate function into a table lookup:

import numpy as np
from concrete import fhe

def value_if_condition_else_zero(value, condition):
    return value if condition else np.zeros_like(value, dtype=np.int64)

def function(x, y):
    return fhe.multivariate(value_if_condition_else_zero)(x, y)

inputset = [
    (
        np.random.randint(-2**4, 2**4, size=(2, 2)),
        np.random.randint(0, 2**1, size=()),
    )
    for _ in range(100)
]

compiler = fhe.Compiler(function, {"x": "encrypted", "y": "encrypted"})
circuit = compiler.compile(inputset)

sample = [np.array([[-2, 4], [0, 1]]), 0]
assert np.array_equal(circuit.encrypt_run_decrypt(*sample), function(*sample))

sample = [np.array([[3, -1], [2, 4]]), 1]
assert np.array_equal(circuit.encrypt_run_decrypt(*sample), function(*sample))

fhe.conv(...)

import numpy as np
from concrete import fhe

weight = np.array([[2, 1], [3, 2]]).reshape(1, 1, 2, 2)

@fhe.compiler({"x": "encrypted"})
def f(x):
    return fhe.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))

fhe.maxpool(...)

import numpy as np
from concrete import fhe

@fhe.compiler({"x": "encrypted"})
def f(x):
    return fhe.maxpool(x, kernel_shape=(2, 2), strides=(2, 2), dilations=(1, 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))

fhe.array(...)

Create encrypted arrays:

import numpy as np
from concrete import fhe

@fhe.compiler({"x": "encrypted", "y": "encrypted"})
def f(x, y):
    return fhe.array([x, y])

inputset = [(3, 2), (7, 0), (0, 7), (4, 2)]
circuit = f.compile(inputset)

sample = (3, 4)
assert np.array_equal(circuit.encrypt_run_decrypt(*sample), f(*sample))

fhe.zero()

Create an encrypted scalar zero:

from concrete import fhe
import numpy as np

@fhe.compiler({"x": "encrypted"})
def f(x):
    z = fhe.zero()
    return x + z

inputset = range(10)
circuit = f.compile(inputset)

for x in range(10):
    assert circuit.encrypt_run_decrypt(x) == x

fhe.zeros(shape)

Create an encrypted tensor of zeros:

from concrete import fhe
import numpy as np

@fhe.compiler({"x": "encrypted"})
def f(x):
    z = fhe.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]]))

fhe.one()

Create an encrypted scalar one:

from concrete import fhe
import numpy as np

@fhe.compiler({"x": "encrypted"})
def f(x):
    z = fhe.one()
    return x + z

inputset = range(10)
circuit = f.compile(inputset)

for x in range(10):
    assert circuit.encrypt_run_decrypt(x) == x + 1

fhe.ones(shape)

Create an encrypted tensor of ones:

from concrete import fhe
import numpy as np

@fhe.compiler({"x": "encrypted"})
def f(x):
    z = fhe.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)

fhe.constant(value)

Allows you to create an encrypted constant of a given value.

from concrete import fhe
import numpy as np

@fhe.compiler({"x": "encrypted", "a":"clear"})
def f(x, a):
    z = fhe.constant(a)
    return x + z

inputset = range(10)
circuit = f.compile(inputset)

for x in range(10):
    assert circuit.encrypt_run_decrypt(x, 5) == x + 5

This extension is also compatible with constant arrays.

fhe.hint(value, **kwargs)

Hint properties of a value. Imagine you have this circuit:

from concrete import fhe
import numpy as np

@fhe.compiler({"x": "encrypted"})
def f(x, y, z):
    a = x | y
    b = y & z
    c = a ^ b
    return c

inputset = [
    (np.random.randint(0, 2**8), np.random.randint(0, 2**8), np.random.randint(0, 2**8))
    for _ in range(3)
]
circuit = f.compile(inputset)

print(circuit)

You'd expect all of a, b, and c to be 8-bits, but because inputset is very small, this code could print:

%0 = x                          # EncryptedScalar<uint8>        ∈ [173, 240]
%1 = y                          # EncryptedScalar<uint8>        ∈ [52, 219]
%2 = z                          # EncryptedScalar<uint8>        ∈ [36, 252]
%3 = bitwise_or(%0, %1)         # EncryptedScalar<uint8>        ∈ [243, 255]
%4 = bitwise_and(%1, %2)        # EncryptedScalar<uint7>        ∈ [0, 112] 
                                                  ^^^^^ this can lead to bugs
%5 = bitwise_xor(%3, %4)        # EncryptedScalar<uint8>        ∈ [131, 255]
return %5

The first solution in these cases should be to use a bigger inputset, but it can still be tricky to solve with the inputset. That's where the hint extension comes into play. Hints are a way to provide extra information to compilation process:

• Bit-width hints are for constraining the minimum number of bits in the encoded value. If you hint a value to be 8-bits, it means it should be at least uint8 or int8.

To fix f using hints, you can do:

@fhe.compiler({"x": "encrypted", "y": "encrypted", "z": "encrypted"})
def f(x, y, z):
    # hint that inputs should be considered at least 8-bits
    x = fhe.hint(x, bit_width=8)
    y = fhe.hint(y, bit_width=8)
    z = fhe.hint(z, bit_width=8)

    # hint that intermediates should be considered at least 8-bits
    a = fhe.hint(x | y, bit_width=8)
    b = fhe.hint(y & z, bit_width=8)
    c = fhe.hint(a ^ b, bit_width=8)

    return c

you'll always see:

%0 = x                          # EncryptedScalar<uint8>        ∈ [...]
%1 = y                          # EncryptedScalar<uint8>        ∈ [...]
%2 = z                          # EncryptedScalar<uint8>        ∈ [...]
%3 = bitwise_or(%0, %1)         # EncryptedScalar<uint8>        ∈ [...]
%4 = bitwise_and(%1, %2)        # EncryptedScalar<uint8>        ∈ [...] 
%5 = bitwise_xor(%3, %4)        # EncryptedScalar<uint8>        ∈ [...]
return %5

regardless of the bounds.

Alternatively, you can use it to make sure a value can store certain integers:

@fhe.compiler({"x": "encrypted", "y": "encrypted"})
def is_vectors_same(x, y):
    assert x.ndim != 1
    assert y.ndim != 1
    
    assert len(x) == len(y)
    n = len(x)
    
    number_of_same_elements = np.sum(x == y)
    fhe.hint(number_of_same_elements, can_store=n)  # hint that number of same elements can go up to n
    is_same = number_of_same_elements == n

    return is_same

fhe.relu(value)

Perform ReLU operation, with the same semantic as x if x >= 0 else 0:

import numpy as np
from concrete import fhe

@fhe.compiler({"x": "encrypted"})
def f(x):
    return fhe.relu(x)

inputset = [np.random.randint(-10, 10) for _ in range(10)]
circuit = f.compile(inputset)

assert circuit.encrypt_run_decrypt(0) == 0
assert circuit.encrypt_run_decrypt(1) == 1
assert circuit.encrypt_run_decrypt(-1) == 0
assert circuit.encrypt_run_decrypt(-3) == 0
assert circuit.encrypt_run_decrypt(5) == 5

ReLU Conversion methods

The ReLU operation can be implemented in two ways:

• Single TLU (Table Lookup Unit) on the original bit-width: Suitable for small bit-widths, as it requires fewer resources.

• Multiple TLUs on smaller bit-widths: Better for large bit-widths, avoiding the high cost of a single large TLU.

Configuration options

The method of conversion is controlled by the relu_on_bits_threshold: int = 7 option. For example, setting relu_on_bits_threshold=5 means:

• Bit-widths from 1 to 4 will use a single TLU.

• Bit-widths of 5 and above will use multiple TLUs.

Here is a script showing how execution cost is impacted when changing these values:

from concrete import fhe
import numpy as np
import matplotlib.pyplot as plt

chunk_sizes = np.array(range(1, 6), dtype=int)
bit_widths = np.array(range(5, 17), dtype=int)

data = []
for bit_width in bit_widths:
    title = f"{bit_width=}:"
    print(title)
    print("-" * len(title))

    inputset = range(-2**(bit_width-1), 2**(bit_width-1))
    configuration = fhe.Configuration(relu_on_bits_threshold=17)

    compiler = fhe.Compiler(lambda x: fhe.relu((fhe.relu(x) - (2**(bit_width-2))) * 2), {"x": "encrypted"})
    circuit = compiler.compile(inputset, configuration)

    print(f"    Complexity: {circuit.complexity} # tlu")
    data.append((bit_width, 0, circuit.complexity))

    for chunk_size in chunk_sizes:
        configuration = fhe.Configuration(
            relu_on_bits_threshold=1,
            relu_on_bits_chunk_size=int(chunk_size),
        )
        circuit = compiler.compile(inputset, configuration)

        print(f"    Complexity: {circuit.complexity} # {chunk_size=}")
        data.append((bit_width, chunk_size, circuit.complexity))

    print()

data = np.array(data)

plt.title(f"ReLU using TLU vs using bits")
plt.xlabel("Input/Output precision")
plt.ylabel("Cost")

for i, chunk_size in enumerate([0] + list(chunk_sizes)):
    costs = [
        cost
        for _, candidate_chunk_size, cost in data
        if candidate_chunk_size == chunk_size
    ]
    assert len(costs) == len(bit_widths)

    label = "Single TLU" if i == 0 else f"Bits extract + multiples {chunk_size + 1} bits TLUs"
    width_bar = 0.8 / (len(chunk_sizes) + 1)

    if i == 0:
        plt.hlines(
            costs,
            bit_widths - 0.45,
            bit_widths + 0.45,
            label=label,
            linestyle="--",
        )
    else:
        plt.bar(
            np.array(bit_widths) + width_bar * (i - (len(chunk_sizes) + 1) / 2),
            height=costs,
            width=width_bar,
            label=label,
        )

plt.xticks(bit_widths)
plt.legend(loc="upper left")

plt.show()

The script will show the following figure:

fhe.if_then_else(condition, x, y)

Perform ternary if operation, with the same semantic as x if condition else y:

import numpy as np
from concrete import fhe

@fhe.compiler({"condition": "encrypted", "x": "encrypted", "y": "encrypted"})
def f(condition, x, y):
    return fhe.if_then_else(condition, x, y)

inputset = [
    (
        np.random.randint(0, 2**1),
        np.random.randint(0, 2**5),
        np.random.randint(-2**3, 2**3),
    )
    for _ in range(10)
]
circuit = f.compile(inputset)

assert circuit.encrypt_run_decrypt(1, 3, 5) == 3
assert circuit.encrypt_run_decrypt(0, 3, 5) == 5
assert circuit.encrypt_run_decrypt(1, 3, -5) == 3
assert circuit.encrypt_run_decrypt(0, 3, -5) == -5

fhe.identity(value)

Copy the value:

import numpy as np
from concrete import fhe

@fhe.compiler({"x": "encrypted"})
def f(x):
    return fhe.identity(x)

inputset = [np.random.randint(-10, 10) for _ in range(10)]
circuit = f.compile(inputset)

assert circuit.encrypt_run_decrypt(0) == 0
assert circuit.encrypt_run_decrypt(1) == 1
assert circuit.encrypt_run_decrypt(-1) == -1
assert circuit.encrypt_run_decrypt(-3) == -3
assert circuit.encrypt_run_decrypt(5) == 5

fhe.refresh(value)

It is similar to fhe.identity but with the extra guarantee that encryption noise is refreshed.

fhe.inputset(...)

Create a random inputset with the given specifications:

inputset = fhe.inputset(fhe.uint4, fhe.tensor[fhe.int3, 3, 2], lambda index: custom_value(index))
assert isinstance(inputset, list)
assert all(isinstance(sample, tuple) and len(sample) == 3 for sample in inputset)

The result will have 100 inputs by default which can be customized using the size keyword argument:

inputset = fhe.inputset(fhe.uint4, fhe.uint4, size=10)
assert len(inputset) == 10

Retrieving a value within an encrypted array with an encrypted index

This example demonstrates how to retrieve a value from an array using an encrypted index. The method creates a "selection" array filled with 0s except for the requested index, which will be 1. It then sums the products of all array values with this selection array:

Filter an array with comparison (>)

This example filters an encrypted array with an encrypted condition, in this case a greater than comparison with an encrypted value. It packs all values with a selection bit that results from the comparison, allowing the unpacking of only the filtered values:

Matrix Row/Col means

This example introduces a key concept when using Concrete: maximizing parallelization. Instead of sequentially summing all values to compute a mean, the values are split into sub-groups, and the mean of these sub-group means is computed:

In TFHE, there exists mainly two operations: the linear operations, such as additions, subtractions, multiplications by integer, and the non-linear operations. Non-linear operations are achieved with Table Lookups (TLUs).

Performance

When using TLUs in Concrete, the most crucial factor for speed is the bit-width of the TLU. The smaller the bit width, the faster the corresponding FHE operation. Therefore, you should reduce the size of inputs to the lookup tables whenever possible. At the end of this document, we discuss methods for truncating or rounding entries to decrease the effective input size, further improving TLU performance.

Direct TLU

A direct TLU performs operations in the form of y = T[i], where T is a table and i is an index. You can define the table using fhe.LookupTable and apply it to scalars or tensors.

Scalar lookup

Tensor lookup

The LookupTable behaves like Python's array indexing, where negative indices access elements from the end of the table.

Multi TLU

A multi TLU is used to apply different elements of the input to different tables (e.g., square the first column, cube the second column):

Transparent TLU

In many cases, you won't need to define your own TLUs, as Concrete will set them for you.

Note that this kind of TLU is compatible with the TLU options, particularly with rounding and truncating which are explained below.

Optimizing input size

Truncating

The first option is to set i' as the truncation of i. In this method, we just take the most significant bits of i. This is done with fhe.truncate_bit_pattern.

Rounding

The second option is to set i as the rounded value of i. In this method, we take the most significant bits of i and round up by 1 if the most significant ignored bit is 1. This is done with fhe.round_bit_pattern.

However, this approach can be slightly more complex, as rounding might result in an index that exceeds the original table's bounds. To handle this, we expand the original table by one additional index:

Approximate rounding

For further optimizations, the fhe.round_bit_pattern function has an exactness=fhe.Exactness.APPROXIMATE option, which allows for faster computations at the cost of minor differences between cleartext and encrypted results:

This document explains how to compile Fully Homomorphic Encryption (FHE) modules containing multiple functions using Concrete.

Deploying a server that contains many compatible functions is important for some use cases. With Concrete, you can compile FHE modules containing as many functions as needed.

Single inputs / outputs

The following example demonstrates how to create an FHE module:

Then, to compile the Counter module, use the compile method with a dictionary of input-sets for each function:

After the module is compiled, you can encrypt and call the different functions as follows:

You can generate the keyset beforehand by calling keygen() method on the compiled module:

Multi inputs / outputs

Composition is not limited to single input / single output. Here is an example that computes the 10 first elements of the Fibonacci sequence in FHE:

Executing this script will provide the following output:

Iterations

Modules support iteration with cleartext iterands to some extent, particularly for loops structured like this:

This script prints the following output:

In this example, a while loop iterates until the decrypted value equals 1. The loop body is implemented in FHE, but the iteration control must be in cleartext.

Runtime optimization

By default, when using modules, all inputs and outputs of every function are compatible, sharing the same precision and crypto-parameters. This approach applies the crypto-parameters of the most costly code path to all code paths. This simplicity may be costly and unnecessary for some use cases.

To optimize runtime, we provide finer-grained control over the composition policy via the composition module attribute. Here is an example:

You have 3 options for the composition attribute:

1. fhe.AllComposable (default): This policy ensures that all ciphertexts used in the module are compatible. It is the least restrictive policy but the most costly in terms of performance.

2. fhe.NotComposable: This policy is the most restrictive but the least costly. It is suitable when you do not need any composition and only want to pack multiple functions in a single artifact.

3. fhe.Wired: This policy allows you to define custom composition rules. You can specify which outputs of a function can be forwarded to which inputs of another function.

Note that, in case of complex composition logic another option is to rely on [[composing_functions_with_modules#Automatic module tracing]] to automatically derive the composition from examples.

In this case, the policy states that the first output of the collatz function can be forwarded to the first input of collatz, but not the second output (which is decrypted every time, and used for control flow).

You can use the fhe.Wire between any two functions. It is also possible to define wires with fhe.AllInputs and fhe.AllOutputs ends. For instance, in the previous example:

This policy would be equivalent to using the fhe.AllComposable policy.

Automatic module tracing

When a module's composition logic is static and straightforward, declaratively defining a Wired policy is usually the simplest approach. However, in cases where modules have more complex or dynamic composition logic, deriving an accurate list of Wire components to be used in the policy can become challenging.

Another related problem is defining different function input-sets. When the composition logic is simple, these can be provided manually. But as the composition gets more convoluted, computing a consistent ensemble of inputsets for a module may become intractable.

For those advanced cases, you can derive the composition rules and the input-sets automatically from user-provided examples. Consider the following module:

You can use the wire_pipeline context manager to activate the module tracing functionality:

Note that any dynamic branching is possible during module tracing. However, for complex runtime logic, ensure that the input set provides sufficient examples to cover all potential code paths.

Current Limitations

Depending on the functions, composition may add a significant overhead compared to a non-composable version.

To be composable, a function must meet the following condition: every output that can be forwarded as input (according to the composition policy) must contain a noise-refreshing operation. Since adding a noise refresh has a noticeable impact on performance, Concrete does not automatically include it.

For instance, to implement a function that doubles an encrypted value, you might write:

This function is valid with the fhe.NotComposable policy. However, if compiled with the fhe.AllComposable policy, it will raise a RuntimeError: Program cannot be composed: ..., indicating that an extra Programmable Bootstrapping (PBS) step must be added.

To resolve this and make the circuit valid, add a PBS at the end of the circuit:

This document explains how to combine compiled functions in Concrete, focusing on scenarios where multiple functions need to work together seamlessly. The goal is to ensure that outputs from certain functions can be used as inputs for others without decryption, including in recursive functions.

Concrete offers two methods to achieve this:

This document explains how to combine compiled functions with the composable flag in Concrete.

By setting the composable flag to True, you can compile a function such that its outputs can be reused as inputs. For example, you can then easily compute f(f(x)) or f**i(x) = f(f(...(f(x) ..)) for a non-encrypted integer i variable, which is usually required for recursions.

Here is an example:

This document covers how to compute on encrypted data homomorphically using the Concrete framework. We will walk you through a complete example step-by-step.

The basic workflow of computation is as follows:

1. Define the function you want to compute

2. Compile the function into a Concrete Circuit

3. Use the Circuit to perform homomorphic evaluation

Here is the complete example, which we will explain step by step in the following paragraphs.

from concrete import fhe

def add(x, y):
    return x + y

compiler = fhe.Compiler(add, {"x": "encrypted", "y": "encrypted"})

inputset = [(2, 3), (0, 0), (1, 6), (7, 7), (7, 1), (3, 2), (6, 1), (1, 7), (4, 5), (5, 4)]

print(f"Compilation...")
circuit = compiler.compile(inputset)

print(f"Key generation...")
circuit.keygen()

print(f"Homomorphic evaluation...")
encrypted_x, encrypted_y = circuit.encrypt(2, 6)
encrypted_result = circuit.run(encrypted_x, encrypted_y)
result = circuit.decrypt(encrypted_result)

assert result == add(2, 6)

Decorator

Another simple way to compile a function is to use a decorator.

from concrete import fhe

@fhe.compiler({"x": "encrypted"})
def f(x):
    return x + 42

inputset = range(10)
circuit = f.compile(inputset)

assert circuit.encrypt_run_decrypt(10) == f(10)

Importing the library

Import the fhe module, which includes everything you need to perform homomorphic evaluation:

from concrete import fhe

Defining the function to compile

Here we define a simple addition function:

def add(x, y):
    return x + y

Creating a compiler

To compile the function, you first need to create a Compiler by specifying the function to compile and the encryption status of its inputs:

compiler = fhe.Compiler(add, {"x": "encrypted", "y": "encrypted"})

For instance, to set the input y as clear:

compiler = fhe.Compiler(add, {"x": "encrypted", "y": "clear"})

Defining an inputset

An inputset is a collection representing the typical inputs of the function. It is used to determine the bit widths and shapes of the variables within the function.

The inputset should be an iterable that yields tuples of the same length as the number of arguments of the compiled function.

For example:

inputset = [(2, 3), (0, 0), (1, 6), (7, 7), (7, 1), (3, 2), (6, 1), (1, 7), (4, 5), (5, 4)]

Here, our inputset consists of 10 integer pairs, ranging from a minimum of (0, 0) to a maximum of (7, 7).

Compiling the function

Use the compile method of the Compiler class with an inputset to perform the compilation and get the resulting circuit:

print(f"Compilation...")
circuit = compiler.compile(inputset)

Generating the keys

Use the keygen method of the Circuit class to generate the keys (public and private):

print(f"Key generation...")
circuit.keygen()

Performing homomorphic evaluation

Now you can easily perform the homomorphic evaluation using the encrypt, run and decrypt methods of the Circuit:

print(f"Homomorphic evaluation...")
encrypted_x, encrypted_y = circuit.encrypt(2, 6)
encrypted_result = circuit.run(encrypted_x, encrypted_y)
result = circuit.decrypt(encrypted_result)

This document explains the most common errors and provides solutions to fix them.

1. Could not find a version that satisfies the requirement concrete-python (from versions: none)

Error message: Could not find a version that satisfies the requirement concrete-python (from versions: none)

Cause: The installation does not work fine for you.

Possible solutions:

• Be sure that you use a supported Python version (currently from 3.8 to 3.11, included).

• Check that you have done pip install -U pip wheel setuptools before.

• Consider adding a --extra-index-url https://pypi.zama.ai/cpu or --extra-index-url https://pypi.zama.ai/gpu, depending on whether you want the CPU or the GPU wheel.

• Concrete requires glibc>=2.28, be sure to have a sufficiently recent version.

2. Only integers are supported

Error message: RuntimeError: Function you are trying to compile cannot be compiled with extra information only integers are supported

Cause: Parts of your program contain graphs that are not from integer to integer

Possible solutions:

3. No parameters found

Error message: NoParametersFound

Cause: The optimizer can't find cryptographic parameters for the circuit that are both secure and correct.

Possible solutions:

• Try to simplify your circuit.

• Use smaller weights.

• Add intermediate PBS to reduce the noise, with identity function fhe.refresh(lambda x: x).

4. Too long inputs for table looup

Error message: RuntimeError: Function you are trying to compile cannot be compiled, with extra information as this [...]-bit value is used as an input to a table lookup with but only up to 16-bit table lookups are supported

Cause: The program uses a Table Lookup that contains oversized inputs exceeding the current 16-bit limit.

Possible solutions:

• Try to simplify your circuit.

• Use smaller weights.

• Look to the graph to understand where this oversized input comes from and ensure that the input size for Table Lookup operations does not exceed 16 bits.

• Use show_bit_width_constraints=True to understand bit widths are assigned the way they are.

5. Impossible to fuse multiple-nodes

Error message: RuntimeError: A subgraph within the function you are trying to compile cannot be fused because it has multiple input nodes

Cause: A subgraph in your program uses two or more input nodes. It is impossible to fuse such a graph, meaning replace it by a table lookup. Concrete will indicate the input nodes with this is one of the input nodes printed in the circuit.

Possible solutions:

• Try to simplify your circuit.

• Have a look to fhe.multivariate.

6. Function is not supported

Error message: RuntimeError: Function '[...]' is not supported

Cause: The function used is not currently supported by Concrete.

Possible solutions:

• Try to change your program.

• Check the corresponding documentation to see if there are ways to implement the function differently.

7. Branching is not allowed

Error message: RuntimeError: Branching within circuits is not possible

Cause: Branching operations, such as if statements or non-constant loops, are not supported in Concrete's FHE programs.

Possible solutions:

• Change your program.

• Consider using tricks to replace ternary-if, as c ? t : f = f + c * (t-f).

8. Unfeasible noise constraint

Error message: Unfeasible noise constraint encountered

Cause: The optimizer can't find cryptographic parameters for the circuit that are both secure and correct.

Possible solutions:

• Try to simplify your circuit.

• Use smaller weights.

• Add intermediate PBS to reduce the noise, with identity function fhe.refresh(x).

9. Non composable circuit

Error message: Program can not be composed

Cause: Some circuit outputs are contaminated by unrefreshed input noise.

Possible solutions:

• Add intermediate PBS to refresh the noise with fhe.refresh(x).

This document explains the compression feature in Concrete and its performance impact.

Fully Homomorphic Encryption (FHE) needs both ciphertexts (encrypted data) and evaluation keys to carry out the homomorphic evaluation of a function. Both elements are large, which may critically affect the application's performance depending on the use case, application deployment, and the method for transmitting and storing ciphertexts and evaluation keys.

Enabling compression

During compilation, you can enable compression options to enforce the use of compression features. The two available compression options are:

• compress_evaluation_keys: bool = False,

  • This specifies that serialization takes the compressed form of evaluation keys.

• compress_input_ciphertexts: bool = False,

  • This specifies that serialization takes the compressed form of input ciphertexts.

You can see the impact of compression by comparing the size of the serialized form of input ciphertexts and evaluation keys with a sample code:

Compression algorithms

The compression factor largely depends on the cryptographic parameters identified and the compression algorithms selected during the compilation.

Currently, Concrete uses the seeded compression algorithms. These algorithms rely on the fact that CSPRNGs are deterministic. Consequently, the chain of random values can be replaced by the seed and later recalculated using the same seed.

Typically, the size of a ciphertext is (lwe dimension + 1) * 8 bytes, while the size of a seeded ciphertext is constant, equal to 3 * 8 bytes. Thus, the compression factor ranges from a hundred to thousands. Understanding the compression factor of evaluation keys is complex. The compression factor of evaluation keys typically ranges between 0 and 10.

This document shows some basic things you can do to improve the performance of your circuit.

Here are some quick tips to reduce the execution time of your circuit:

• Use tensors as much as possible in your circuits.

• Tweak p_error configuration option until you get optimal exactness vs performance tradeoff for your application.

This document explains how to use simulation to speed up the development, enabling faster prototyping while accounting for the inherent probability of errors in Fully Homomorphic Encryption (FHE) execution.

Using simulation for faster prototyping

To overcome this issue, simulation is introduced:

After the simulation runs, it prints the following results:

Overflow detection in simulation

Overflow can happen during an FHE computation, leading to unexpected behaviors. Using simulation can help you detect these events by printing a warning whenever an overflow happens. This feature is disabled by default, but you can enable it by setting detect_overflow_in_simulation=True during compilation.

To demonstrate, we will compile the previous circuit with overflow detection enabled and trigger an overflow:

You will see the following warning after the simulation call:

If you look at the MLIR (circuit.mlir), you will see that the input type is supposed to be eint4 represented in 4 bits with a maximum value of 15. Since there's an addition of the input, we used the maximum value (15) here to trigger an overflow (15 + 1 = 16 which needs 5 bits). The warning specifies the operation that caused the overflow and its location. Similar warnings will be displayed for all basic FHE operations such as add, mul, and lookup tables.

This document explains how to use GPU accelerations with Concrete.

Concrete supports acceleration using one or more GPUs.

pip install concrete-python --extra-index-url https://pypi.zama.ai/gpu.

GPU execution configuration

By default the compiler and runtime will use all available system resources, including all CPU cores and GPUs. You can adjust this by using the following environment variables:

SDFG_NUM_THREADS

• Type: Integer

• Default value: The number of hardware threads on the system (including hyperthreading) minus the number of GPUs in use.

• Description: This variable determines the number of CPU threads that execute in paralelle with the GPU for offloadable workloads. GPU scheduler threads (including CUDA threads and those used within Concrete) are necessary but can block or interfere with worker thread execution. Therefore, it is recommended to undersubscribe the CPU hardware threads by the number of GPU devices used.

SDFG_NUM_GPUS

• Type: Integer

• Default value: The number of GPUs available.

• Description: This value determines the number of GPUs to use for offloading. This can be set to any value between 1 and the total number of GPUs on the system.

SDFG_MAX_BATCH_SIZE**

• Type: Integer

• Default value: LLONG_MAX (no batch size limit)

• Description: This value limits the maximum batch size for offloading in cases where the GPU memory is insufficient.

SDFG_DEVICE_TO_CORE_RATIO

• Type: Integer

• Default value: The ratio between the compute capability of the GPU (at index 0) and a CPU core.

• Description: This ratio is used to balance the load between the CPU and GPU. If the GPU is underutilized, set this value higher to increase the amount of work offloaded to the GPU.

OMP_NUM_THREADS

• Type: Integer

• Default value: The number of hardware threads on the system, including hyperthreading.

• Description: This value specifies the portions of program execution that are not yet supported for GPU offload, which will be parallelized using OpenMP on the CPU.

This document explains how to manage keys when using Concrete, introducing the key management API for generating, reusing, and securely handling keys.

Concrete generates keys lazily when needed. While this is convenient for development, it's not ideal for the production environment. The explicit key management API is available for you to easily generate and reuse keys as needed.

Definition

Let's start by defining a circuit with the following example:

from concrete import fhe

@fhe.compiler({"x": "encrypted"})
def f(x):
    return x ** 2

inputset = range(10)
circuit = f.compile(inputset)

Circuits have a keys property of type fhe.Keys, which includes several utilities for key management.

Generation

To explicitly generate keys for a circuit, use:

circuit.keys.generate()

You can also set a custom seed for reproducibility:

circuit.keys.generate(seed=420)

Serialization

To serialize keys, for tasks such as sending them across a network, use:

serialized_keys: bytes = circuit.keys.serialize()

Deserialization

To deserialize the keys back after receiving serialized keys, use:

keys: fhe.Keys = fhe.Keys.deserialize(serialized_keys)

Assignment

Once you have a valid fhe.Keys object, you can directly assign it to the circuit:

circuit.keys = keys

Saving

You can also use the filesystem to store the keys directly, without managing serialization and file management manually:

circuit.keys.save("/path/to/keys")

Loading

After saving keys to disk, you can load them back using:

circuit.keys.load("/path/to/keys")

Automatic Management

If you want to generate keys in the first run and reuse the keys in consecutive runs, use:

circuit.keys.load_if_exists_generate_and_save_otherwise("/path/to/keys")

This document explains how to serialize and deserialize ciphertexts and secret keys when working with TFHE-rs in Rust.

Concrete already has its serilization functions (e.g. tfhers_bridge.export_value, tfhers_bridge.import_value, tfhers_bridge.keygen_with_initial_keys, tfhers_bridge.serialize_input_secret_key). However, when implementing a TFHE-rs computation in Rust, we must use a compatible serialization.

Ciphertexts

We can deserialize FheUint8 (and similarly other types) using bincode

use tfhe::FheUint8;

/// ...

fn load_fheuint8(path: &String) -> FheUint8 {
    let path_fheuint: &Path = Path::new(path);
    let serialized_fheuint = fs::read(path_fheuint).unwrap();
    let mut serialized_data = Cursor::new(serialized_fheuint);
    bincode::deserialize_from(&mut serialized_data).unwrap()
}

To serialize

fn save_fheuint8(fheuint: FheUint8, path: &String) {
    let mut serialized_ct = Vec::new();
    bincode::serialize_into(&mut serialized_ct, &fheuint).unwrap();
    let path_ct: &Path = Path::new(path);
    fs::write(path_ct, serialized_ct).unwrap();
}

Secret Key

We can deserialize LweSecretKey using bincode

use tfhe::core_crypto::prelude::LweSecretKey;

/// ...

fn load_lwe_sk(path: &String) -> LweSecretKey<Vec<u64>> {
    let path_sk: &Path = Path::new(path);
    let serialized_lwe_key = fs::read(path_sk).unwrap();
    let mut serialized_data = Cursor::new(serialized_lwe_key);
    bincode::deserialize_from(&mut serialized_data).unwrap()
}

To serialize

fn save_lwe_sk(lwe_sk: LweSecretKey<Vec<u64>>, path: &String) {
    let mut serialized_lwe_key = Vec::new();
    bincode::serialize_into(&mut serialized_lwe_key, &lwe_sk).unwrap();
    let path_sk: &Path = Path::new(path);
    fs::write(path_sk, serialized_lwe_key).unwrap();
}

This document provides guidance on debugging the compilation process.

Compiler debug and verbose modes

• compiler_verbose_mode: Prints the compiler passes and shows the transformations applied. It can help identify the crash location if a crash occurs.

• compiler_debug_mode: A more detailed version of the verbose mode, providing additional information, particularly useful for diagnosing crashes.

Debug artifacts

Concrete includes an artifact system that simplifies the debugging process by automatically or manually exporting detailed information during compilation failures.

Automatic export

When a compilation fails, artifacts are automatically exported to the .artifacts directory in the working directory. Here's an example of what gets exported when a function fails to compile:

def f(x):
    return np.sin(x)

This function fails to compile because Concrete does not support floating-point outputs. When you try to compile it, an exception will be raised and the artifacts will be exported automatically. The following files will be generated in the .artifacts directory:

• environment.txt: Information about your system setup, including the operating system and Python version.

Linux-5.12.13-arch1-2-x86_64-with-glibc2.29 #1 SMP PREEMPT Fri, 25 Jun 2021 22:56:51 +0000
Python 3.8.10

• requirements.txt: The installed Python packages and their versions.

astroid==2.15.0
attrs==22.2.0
auditwheel==5.3.0
...
wheel==0.40.0
wrapt==1.15.0
zipp==3.15.0

• function.txt: The code of the function that failed to compile.

def f(x):
    return np.sin(x)

• parameters.txt: Information about the encryption status function's parameters.

x :: encrypted

• 1.initial.graph.txt: The textual representation of the initial computation graph right after tracing.

%0 = x              # EncryptedScalar<uint3>
%1 = sin(%0)        # EncryptedScalar<float64>
return %1

• final.graph.txt: The textual representation of the final computation graph right before MLIR conversion.

%0 = x              # EncryptedScalar<uint3>
%1 = sin(%0)        # EncryptedScalar<float64>
return %1

• traceback.txt: Details of the error occurred.

Traceback (most recent call last):
  File "/path/to/your/script.py", line 9, in <module>
    circuit = f.compile(inputset)
  File "/usr/local/lib/python3.10/site-packages/concrete/fhe/compilation/decorators.py", line 159, in compile
    return self.compiler.compile(inputset, configuration, artifacts, **kwargs)
  File "/usr/local/lib/python3.10/site-packages/concrete/fhe/compilation/compiler.py", line 437, in compile
    mlir = GraphConverter.convert(self.graph)
  File "/usr/local/lib/python3.10/site-packages/concrete/fhe/mlir/graph_converter.py", line 677, in convert
    GraphConverter._check_graph_convertibility(graph)
  File "/usr/local/lib/python3.10/site-packages/concrete/fhe/mlir/graph_converter.py", line 240, in _check_graph_convertibility
    raise RuntimeError(message)
RuntimeError: Function you are trying to compile cannot be converted to MLIR

%0 = x              # EncryptedScalar<uint3>          ∈ [3, 5]
%1 = sin(%0)        # EncryptedScalar<float64>        ∈ [-0.958924, 0.14112]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only integer operations are supported
                                                                             /path/to/your/script.py:6
return %1

Manual exports

Manual exports are mostly used for visualization and demonstrations. Here is how to perform one:

from concrete import fhe
import numpy as np

artifacts = fhe.DebugArtifacts("/tmp/custom/export/path")

@fhe.compiler({"x": "encrypted"})
def f(x):
    return 127 - (50 * (np.sin(x) + 1)).astype(np.int64)

inputset = range(2 ** 3)
circuit = f.compile(inputset, artifacts=artifacts)

artifacts.export()

After running the code, you will find the following files under /tmp/custom/export/path directory:

• 1.initial.graph.txt: The textual representation of the initial computation graph right after tracing.

%0 = x                             # EncryptedScalar<uint1>
%1 = sin(%0)                       # EncryptedScalar<float64>
%2 = 1                             # ClearScalar<uint1>
%3 = add(%1, %2)                   # EncryptedScalar<float64>
%4 = 50                            # ClearScalar<uint6>
%5 = multiply(%4, %3)              # EncryptedScalar<float64>
%6 = astype(%5, dtype=int_)        # EncryptedScalar<uint1>
%7 = 127                           # ClearScalar<uint7>
%8 = subtract(%7, %6)              # EncryptedScalar<uint1>
return %8

• 2.after-fusing.graph.txt: The textual representation of the intermediate computation graph after fusing.

%0 = x                       # EncryptedScalar<uint1>
%1 = subgraph(%0)            # EncryptedScalar<uint1>
%2 = 127                     # ClearScalar<uint7>
%3 = subtract(%2, %1)        # EncryptedScalar<uint1>
return %3

Subgraphs:

    %1 = subgraph(%0):

        %0 = input                         # EncryptedScalar<uint1>
        %1 = sin(%0)                       # EncryptedScalar<float64>
        %2 = 1                             # ClearScalar<uint1>
        %3 = add(%1, %2)                   # EncryptedScalar<float64>
        %4 = 50                            # ClearScalar<uint6>
        %5 = multiply(%4, %3)              # EncryptedScalar<float64>
        %6 = astype(%5, dtype=int_)        # EncryptedScalar<uint1>
        return %6

• 3.final.graph.txt: The textual representation of the final computation graph right before MLIR conversion.

%0 = x                       # EncryptedScalar<uint3>        ∈ [0, 7]
%1 = subgraph(%0)            # EncryptedScalar<uint7>        ∈ [2, 95]
%2 = 127                     # ClearScalar<uint7>            ∈ [127, 127]
%3 = subtract(%2, %1)        # EncryptedScalar<uint7>        ∈ [32, 125]
return %3

Subgraphs:

    %1 = subgraph(%0):

        %0 = input                         # EncryptedScalar<uint1>
        %1 = sin(%0)                       # EncryptedScalar<float64>
        %2 = 1                             # ClearScalar<uint1>
        %3 = add(%1, %2)                   # EncryptedScalar<float64>
        %4 = 50                            # ClearScalar<uint6>
        %5 = multiply(%4, %3)              # EncryptedScalar<float64>
        %6 = astype(%5, dtype=int_)        # EncryptedScalar<uint1>
        return %6

• mlir.txt: Information about the MLIR of the function which was compiled using the provided input-set.

module {
  func.func @main(%arg0: !FHE.eint<7>) -> !FHE.eint<7> {
    %c127_i8 = arith.constant 127 : i8
    %cst = arith.constant dense<"..."> : tensor<128xi64>
    %0 = "FHE.apply_lookup_table"(%arg0, %cst) : (!FHE.eint<7>, tensor<128xi64>) -> !FHE.eint<7>
    %1 = "FHE.sub_int_eint"(%c127_i8, %0) : (i8, !FHE.eint<7>) -> !FHE.eint<7>
    return %1 : !FHE.eint<7>
  }
}

• client\_parameters.json: Information about the client parameters chosen by Concrete.

{
    "bootstrapKeys": [
        {
            "baseLog": 22,
            "glweDimension": 1,
            "inputLweDimension": 908,
            "inputSecretKeyID": 1,
            "level": 1,
            "outputSecretKeyID": 0,
            "polynomialSize": 8192,
            "variance": 4.70197740328915e-38
        }
    ],
    "functionName": "main",
    "inputs": [
        {
            "encryption": {
                "encoding": {
                    "isSigned": false,
                    "precision": 7
                },
                "secretKeyID": 0,
                "variance": 4.70197740328915e-38
            },
            "shape": {
                "dimensions": [],
                "sign": false,
                "size": 0,
                "width": 7
            }
        }
    ],
    "keyswitchKeys": [
        {
            "baseLog": 3,
            "inputSecretKeyID": 0,
            "level": 6,
            "outputSecretKeyID": 1,
            "variance": 1.7944329123150665e-13
        }
    ],
    "outputs": [
        {
            "encryption": {
                "encoding": {
                    "isSigned": false,
                    "precision": 7
                },
                "secretKeyID": 0,
                "variance": 4.70197740328915e-38
            },
            "shape": {
                "dimensions": [],
                "sign": false,
                "size": 0,
                "width": 7
            }
        }
    ],
    "packingKeyswitchKeys": [],
    "secretKeys": [
        {
            "dimension": 8192
        },
        {
            "dimension": 908
        }
    ]
}

Asking the community

Submitting an issue

• Avoid randomness to ensure reproductibility of the bug

• Minimize your function while keeping the bug to expedite the fix

• Include your input-set in the issue

• Provide clear reproduction steps

• Include debug artifacts in the issue

• Give a minimal example of the desired behavior

• Explain your use case

Deploy

This document explains how to deploy a circuit after the development. After developing your circuit, you may want to deploy it without sharing the circuit's details with every client or hosting computations on dedicated servers. In this scenario, you can use the Client and Server features of Concrete.

Deployment process

In a typical Concrete deployment:

• The server hosts the compilation artifact, including client specifications and the FHE executable.

• The client requests circuit requirements, generates keys, sends an encrypted payload, and receives an encrypted result.

Example

Follow these steps to deploy your circuit:

1. Develop the circuit: You can develop your own circuit using the techniques discussed in previous chapters. Here is an example.

from concrete import fhe

@fhe.compiler({"x": "encrypted"})
def function(x):
    return x + 42

inputset = range(10)
circuit = function.compile(inputset)

1. Save the server files: Once you have your circuit, save the necessary server files.

circuit.server.save("server.zip")

1. Send the server files: Send server.zip to your computation server.

Setting up a server

1. Load the server files: To set up the server, load the server.zip file received from the development machine.

from concrete import fhe

server = fhe.Server.load("server.zip")

1. Prepare for client requests: The server needs to wait for the requests from clients.

2. Serialize ClientSpecs: The requests typically starts with ClientSpecs as clients need ClientSpecs to generate keys and request computation.

serialized_client_specs: str = server.client_specs.serialize()

1. Send serialized ClientSpecs to clients.

Setting up clients

1. Create the client object: After receiving the serialized ClientSpecs from a server, create the Client object.

client_specs = fhe.ClientSpecs.deserialize(serialized_client_specs)
client = fhe.Client(client_specs)

Generating keys (client-side)

1. Generate keys: Once you have the Client object, perform key generation. This method generates encryption/decryption keys and evaluation keys.

client.keys.generate()

1. Serialize the evaluation keys: The server needs access to the evaluation keys. You can serialize your evaluation keys as below.

serialized_evaluation_keys: bytes = client.evaluation_keys.serialize()

1. Send the evaluation keys to the server.

Encrypting inputs (client-side)

1. Encrypt inputs: Encrypt your inputs and request the server to perform some computation. This can be done in the following way.

arg: fhe.Value = client.encrypt(7)
serialized_arg: bytes = arg.serialize()

1. Send the serialized arguments to the server.

Performing computation (server-side)

1. Deserialize received data: On the server, deserialize the received evaluation keys and arguments received from the client.

deserialized_evaluation_keys = fhe.EvaluationKeys.deserialize(serialized_evaluation_keys)
deserialized_arg = fhe.Value.deserialize(serialized_arg)

1. Run the computation: Perform the computation and serialize the result.

result: fhe.Value = server.run(deserialized_arg, evaluation_keys=deserialized_evaluation_keys)
serialized_result: bytes = result.serialize()

1. Send the serialized result to the client:

Decrypting the result (on the client)

1. Deserialize the result: Once you receive the serialized result from the server, deserialize it.

deserialized_result = fhe.Value.deserialize(serialized_result)

1. Decrypt the deserialized result:

decrypted_result = client.decrypt(deserialized_result)
assert decrypted_result == 49

Deployment of modules

For example, consider a module compiled in the following way:

from concrete import fhe

@fhe.module()
class MyModule:
    @fhe.function({"x": "encrypted"})
    def inc(x):
        return x + 1

    @fhe.function({"x": "encrypted"})
    def dec(x):
        return x - 1

inputset = list(range(20))
my_module = MyModule.compile({"inc": inputset, "dec": inputset})
)

You can extract the server from the module and save it in a file:

my_module.server.save("server.zip")

The only noticeable difference between the deployment of modules and the deployment of circuits is that the methods Client::encrypt, Client::decrypt and Server::run must contain an extra function_name argument specifying the name of the targeted function.

For example, to encrypt an argument for the inc function of the module:

arg = client.encrypt(7, function_name="inc")
serialized_arg = arg.serialize()

To execute the inc function:

result = server.run(deserialized_arg, evaluation_keys=deserialized_evaluation_keys, function_name="inc")
serialized_result = result.serialize()

To decrypt a result from the execution of dec:

decrypted_result = client.decrypt(deserialized_result, function_name="dec")

This guide explains how to optimize Concrete circuits extensively.

It's split in 3 sections:

This guide introduces the different options for parallelism in Concrete and how to utilize them to improve the execution time of Concrete circuits.

Modern CPUs have multiple cores to perform computation and utilizing multiple cores is a great way to boost performance.

There are two kinds of parallelism in Concrete:

Loop parallelism is enabled by default, as it's supported on all platforms. Dataflow parallelism however is only supported on Linux, hence not enabled by default.

Overview

There are differences between Concrete and TFHE-rs, so ensuring compatibility between them involves more than just data serialization. To achieve compatibility, we need to consider two main aspects.

Encoding differences

Both TFHE-rs and Concrete libraries use Learning with errors(LWE) ciphertexts, but integers are encoded differently:

• In Concrete, integers are simply encoded in a single ciphertext

• In TFHE-rs, integers are encoded into multiple ciphertext using radix decomposition

Converting between Concrete and TFHE-rs encrypted integers then require doing an encrypted conversion between the two different encodings.

When working with a TFHE-rs integer type in Concrete, you can use the .encode(...) and .decode(...) functions to see this in practice:

from concrete.fhe import tfhers

# don't worry about the API, we will have better examples later.
# we just want to show the encoding here
tfhers_params = tfhers.CryptoParams(
lwe_dimension=909,
glwe_dimension=1,
polynomial_size=4096,
pbs_base_log=15,
pbs_level=2,
lwe_noise_distribution=9.743962418842052e-07,
glwe_noise_distribution=2.168404344971009e-19,
encryption_key_choice=tfhers.EncryptionKeyChoice.BIG,
)

# TFHERSInteger using this type will be represented as a vector of 8/2=4 integers
tfhers_type = tfhers.TFHERSIntegerType(
    is_signed=False,
    bit_width=8,
    carry_width=3,
    msg_width=2,
    params=tfhers_params,
)

assert (tfhers_type.encode(123) == [3, 2, 3, 1]).all()

assert tfhers_type.decode([3, 2, 3, 1]) == 123

Parameter match

The Concrete Optimizer may find parameters which are not in TFHE-rs's pre-computed list. To ensure compatibility, you need to either fix or constrain the search space in parts of the circuit where compatibility is required. This ensures that compatible parameters are used consistently.

Scenarios

There are 2 different approaches to using Concrete and THFE-rs depending on the situation.

Serialization of ciphertexts and keys

This guide teaches how to improve the execution time of Concrete circuits by reducing the amount of table lookups.

Reducing the amount of table lookups is probably the most complicated guide in this section as it's not automated. The idea is to use mathematical properties of operations to reduce the amount of table lookups needed to achieve the result.

One great example is in adding big integers in bitmap representation. Here is the basic implementation:

There are two table lookups within the loop body, one for >> and one for %.

This implementation is not optimal though, since the same output can be achieved with just a single table lookup:

It was possible to do this because the original operations had a mathematical equivalence with the optimized operations and optimized operations achieved the same output with less table lookups!

Here is the full code example and some numbers for this optimization:

prints:

which is almost half the amount of table lookups and ~2x less complexity for the same operation!

This guide explains how setting p_error configuration option can affect the performance of Concrete circuits.

For example:

import numpy as np
from concrete import fhe

def f(x, y):
    return (x // 2) * (y // 3)

inputset = fhe.inputset(fhe.uint4, fhe.uint4)
for p_error in [(1 / 1_000_000), (1 / 100_000), (1 / 10_000), (1 / 1_000), (1 / 100)]:
    compiler = fhe.Compiler(f, {"x": "encrypted", "y": "encrypted"})
    circuit = compiler.compile(inputset, p_error=p_error)
    print(f"p_error of {p_error:.6f} -> {int(circuit.complexity):_} complexity")

This prints:

p_error of 0.000001 -> 294_773_524 complexity
p_error of 0.000010 -> 286_577_520 complexity
p_error of 0.000100 -> 275_887_080 complexity
p_error of 0.001000 -> 265_196_640 complexity
p_error of 0.010000 -> 184_144_972 complexity

This guide teaches how to improve the execution time of Concrete circuits by using some special operations that reduce the bit width of the input of the table lookup.

For example the following code:

import numpy as np
from concrete import fhe

inputset = fhe.inputset(fhe.uint10)
for lsbs_to_remove in range(0, 10):
    def f(x):
        return fhe.round_bit_pattern(x, lsbs_to_remove) // 2

    compiler = fhe.Compiler(f, {"x": "encrypted"})
    circuit = compiler.compile(inputset)

    print(f"{lsbs_to_remove=} -> {int(circuit.complexity):>13_} complexity")

prints:

lsbs_to_remove=0 -> 9_134_406_574 complexity
lsbs_to_remove=1 -> 3_209_430_092 complexity
lsbs_to_remove=2 -> 1_536_476_735 complexity
lsbs_to_remove=3 -> 1_588_749_586 complexity
lsbs_to_remove=4 ->   848_133_081 complexity
lsbs_to_remove=5 ->   525_987_801 complexity
lsbs_to_remove=6 ->   358_276_023 complexity
lsbs_to_remove=7 ->   373_311_341 complexity
lsbs_to_remove=8 ->   400_596_351 complexity
lsbs_to_remove=9 ->   438_681_996 complexity

This guide explains dataflow parallelism and how it can improve the execution time of Concrete circuits.

Dataflow parallelism is particularly useful when the circuit performs computations that are neither completely independent (such as loop/doall parallelism) nor fully dependent (e.g. sequential, non-parallelizable code). In such cases dataflow tasks can execute as soon as their inputs are available and thus minimizing over-synchronization.

Without dataflow parallelism, circuit is executed operation by operation, like an imperative language. If the operations themselves are not tensorized, loop parallelism would not be utilized and the entire execution would happen in a single thread. Dataflow parallelism changes this by analyzing the operations and their dependencies within the circuit to determine what can be done in parallel and what cannot. Then it distributes the tasks that can be done in parallel to different threads.

For example:

import time

import numpy as np
from concrete import fhe

def f(x, y, z):
    # normally, you'd use fhe.array to construct a concrete tensor
    # but for this example, we just create a simple numpy array
    # so the matrix multiplication can happen on a cellular level
    a = np.array([[x, y], [z, 2]])
    b = np.array([[1, x], [z, y]])
    return fhe.array(a @ b)

inputset = fhe.inputset(fhe.uint3, fhe.uint3, fhe.uint3)

for dataflow_parallelize in [False, True]:
    compiler = fhe.Compiler(f, {"x": "encrypted", "y": "encrypted", "z": "encrypted"})
    circuit = compiler.compile(inputset, dataflow_parallelize=dataflow_parallelize)

    circuit.keygen()
    for sample in inputset[:3]:  # warmup
        circuit.encrypt_run_decrypt(*sample)

    timings = []
    for sample in inputset[3:13]:
        start = time.time()
        result = circuit.encrypt_run_decrypt(*sample)
        end = time.time()

        assert np.array_equal(result, f(*sample))
        timings.append(end - start)

    if not dataflow_parallelize:
        print(f"without dataflow parallelize -> {np.mean(timings):.03f}s")
    else:
        print(f"   with dataflow parallelize -> {np.mean(timings):.03f}s")

This prints:

without dataflow parallelize -> 0.609s
   with dataflow parallelize -> 0.414s

The reason for that is:

// this is the generated MLIR for the circuit
// without dataflow, every single line would be executed one after the other

module {
  func.func @main(%arg0: !FHE.eint<7>, %arg1: !FHE.eint<7>, %arg2: !FHE.eint<7>) -> tensor<2x2x!FHE.eint<7>> {
  
    // but if you look closely, you can see that this multiplication
    %c1_i2 = arith.constant 1 : i2
    %0 = "FHE.mul_eint_int"(%arg0, %c1_i2) : (!FHE.eint<7>, i2) -> !FHE.eint<7>
    
    // is completely independent of this one, so dataflow makes them run in parallel
    %1 = "FHE.mul_eint"(%arg1, %arg2) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    
    // however, this addition needs the first two operations
    // so dataflow waits until both are done before performing this one
    %2 = "FHE.add_eint"(%0, %1) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    
    // lastly, this multiplication is completely independent from the first three operations
    // so its execution starts in parallel when execution starts with dataflow
    %3 = "FHE.mul_eint"(%arg0, %arg0) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    
    // similar logic can be applied to the remaining operations...
    %4 = "FHE.mul_eint"(%arg1, %arg1) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    %5 = "FHE.add_eint"(%3, %4) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    %6 = "FHE.mul_eint_int"(%arg2, %c1_i2) : (!FHE.eint<7>, i2) -> !FHE.eint<7>
    %c2_i3 = arith.constant 2 : i3
    %7 = "FHE.mul_eint_int"(%arg2, %c2_i3) : (!FHE.eint<7>, i3) -> !FHE.eint<7>
    %8 = "FHE.add_eint"(%6, %7) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    %9 = "FHE.mul_eint"(%arg2, %arg0) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    %10 = "FHE.mul_eint_int"(%arg1, %c2_i3) : (!FHE.eint<7>, i3) -> !FHE.eint<7>
    %11 = "FHE.add_eint"(%9, %10) : (!FHE.eint<7>, !FHE.eint<7>) -> !FHE.eint<7>
    %from_elements = tensor.from_elements %2, %5, %8, %11 : tensor<2x2x!FHE.eint<7>>
    return %from_elements : tensor<2x2x!FHE.eint<7>>
    
  }
}

To summarize, dataflow analyzes the circuit to determine which parts of the circuit can be run at the same time, and tries to run as many operations as possible in parallel.

One of the most common operations in Concrete are Table Lookups (TLUs). All operations except addition, subtraction, multiplication with non-encrypted values, tensor manipulation operations, and a few operations built with those primitive operations (e.g. matmul, conv) are converted to Table Lookups under the hood.

Table Lookups are very flexible. They allow Concrete to support many operations, but they are expensive. The exact cost depends on many variables (hardware used, error probability, etc.), but they are always much more expensive compared to other operations. You should try to avoid them as much as possible. It's not always possible to avoid them completely, but you might remove the number of TLUs or replace some of them with other primitive operations.

Direct table lookup

Concrete provides a LookupTable class to create your own tables and apply them in your circuits.

IndexError: index 10 is out of bounds for axis 0 with size 6

With scalars.

You can create the lookup table using a list of integers and apply it using indexing:

from concrete import fhe

table = fhe.LookupTable([2, -1, 3, 0])

@fhe.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 a table lookup to a tensor, the scalar table lookup is applied to each element of the tensor:

from concrete import fhe
import numpy as np

table = fhe.LookupTable([2, -1, 3, 0])

@fhe.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:

from concrete import fhe

table = fhe.LookupTable([2, -1, 3, 0])

@fhe.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

If you want to apply a different lookup table to each element of a tensor, you can have a LookupTable of LookupTables:

from concrete import fhe
import numpy as np

squared = fhe.LookupTable([i ** 2 for i in range(4)])
cubed = fhe.LookupTable([i ** 3 for i in range(4)])

table = fhe.LookupTable([
    [squared, cubed],
    [squared, cubed],
    [squared, cubed],
])

@fhe.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 column.

Fused table lookup

Concrete tries to fuse some operations into table lookups automatically so that lookup tables don't need to be created manually:

from concrete import fhe
import numpy as np

@fhe.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)

The function is first traced into:

Concrete then fuses appropriate nodes:

Using automatically created table lookup

Table lookup exactness

TLUs are performed with an FHE operation called Programmable Bootstrapping (PBS). PBSs have a certain probability of error: when these errors happen, it results in inaccurate results.

Let's say you have the table:

lut = [0, 1, 4, 9, 16, 25, 36, 49, 64]

And you perform a Table Lookup using 4. The result you should get is lut[4] = 16, but because of the possibility of error, you could get any other value in the table.

The probability of this error can be configured through the p_error and global_p_error configuration options. The difference between these two options is that, p_error is for individual TLUs but global_p_error is for the whole circuit.

If you set p_error to 0.01, for example, it means every TLU in the circuit will have a 99% chance (or more) of being exact. If there is a single TLU in the circuit, it corresponds to global_p_error = 0.01 as well. But if we have 2 TLUs, then global_p_error would be higher: that's 1 - (0.99 * 0.99) ~= 0.02 = 2%.

If you set global_p_error to 0.01, the whole circuit will have at most 1% probability of error, no matter how many Table Lookups are included (which means that p_error will be smaller than 0.01 if there are more than a single TLU).

If you set both of them, both will be satisfied. Essentially, the stricter one will be used.

By default, both p_error and global_p_error are set to None, which results in a global_p_error of 1 / 100_000 being used.

Table lookup performance

This document explains how to set up a shared secret key between Concrete and TFHE-rs to perform computations.

In this scenario, a shared secret key will be used, while different keysets will be held for Concrete and TFHE-rs. There are two ways to generate keys, outlined with the following steps

From Concrete (1.1)

1. Perform a classical key generation in Concrete, which generates a set of secret and public keys.

2. Use this secret key to perform a partial key generation in TFHE-rs, starting from the shared secret key and generating the rest of the necessary keys.

From TFHE-rs (1.2)

1. Perform a classical key generation in TFHE-rs, generating a single secret key and corresponding public keys.

2. Use the secret key from TFHE-rs to perform a partial keygen in Concrete.

After the key generation is complete and we have both keysets, we can perform computations, encryption, and decryption on both ends.

Setup and configuration

In short, we first determine a suitable set of parameters from TFHE-rs and then apply them in Concrete. This ensures that the ciphertexts generated in both systems will be compatible by using the same cryptographic parameters.

from functools import partial
from concrete.fhe import tfhers

tfhers_params = tfhers.CryptoParams(
    lwe_dimension=909,
    glwe_dimension=1,
    polynomial_size=4096,
    pbs_base_log=15,
    pbs_level=2,
    lwe_noise_distribution=9.743962418842052e-07,
    glwe_noise_distribution=2.168404344971009e-19,
    encryption_key_choice=tfhers.EncryptionKeyChoice.BIG,
)
# creating a TFHE-rs ciphertext type with crypto and encoding params
tfhers_type = tfhers.TFHERSIntegerType(
    is_signed=False,
    bit_width=8,
    carry_width=3,
    msg_width=2,
    params=tfhers_params,
)
# this partial will help us create TFHERSInteger with the given type instead of calling
# tfhers.TFHERSInteger(tfhers_type, value) every time
tfhers_int = partial(tfhers.TFHERSInteger, tfhers_type)

Defining the circuit and compiling

We will now define a simple modular addition function. This function takes TFHE-rs inputs, converts them to Concrete format (to_native), runs a computation, and then converts them back to TFHE-rs. The circuit below is a common example that takes and produces TFHE-rs ciphertexts. However, there are other scenarios where you might not convert back to TFHE-rs, or you might convert to a different type than the input. Another possibility is to take one native ciphertext and one TFHE-rs ciphertext.

def compute(tfhers_x, tfhers_y):
    ####### TFHE-rs to Concrete #########

    # x and y are supposed to be TFHE-rs values.
    # to_native will use type information from x and y to do
    # a correct conversion from TFHE-rs to Concrete
    concrete_x = tfhers.to_native(tfhers_x)
    concrete_y = tfhers.to_native(tfhers_y)
    ####### TFHE-rs to Concrete #########

    ####### Concrete Computation ########
    concrete_res = (concrete_x + concrete_y) % 213
    ####### Concrete Computation ########

    ####### Concrete to TFHE-rs #########
    tfhers_res = tfhers.from_native(
        concrete_res, tfhers_type
    )  # we have to specify the type we want to convert to
    ####### Concrete to TFHE-rs #########
    return tfhers_res

We can compile the circuit as usual.

compiler = fhe.Compiler(compute, {"tfhers_x": "encrypted", "tfhers_y": "encrypted"})
inputset = [(tfhers_int(120), tfhers_int(120))]
circuit = compiler.compile(inputset)

You could optionally try the full execution in Concrete

# encode/encrypt
encrypted_x, encrypted_y = circuit.encrypt(tfhers_type.encode(7), tfhers_type.encode(9))
# run
encrypted_result = circuit.run(encrypted_x, encrypted_y)
# decrypt
result = circuit.decrypt(encrypted_result)
# decode
decoded = tfhers_type.decode(result)

Connecting Concrete and TFHE-rs

We are going to create a TFHE-rs bridge that facilitates the seamless transfer of ciphertexts and keys between Concrete and TFHE-rs.

tfhers_bridge = tfhers.new_bridge(circuit=circuit)

Key generation

In order to establish a shared secret key between Concrete and TFHE-rs, there are two possible methods for key generation. The first method (use case 1.1) involves generating the Concrete keyset first and then using the shared secret key in TFHE-rs to partially generate the TFHE-rs keyset. The second method (use case 1.2) involves doing the opposite. You should only run one of the two following methods.

KeyGen starts in Concrete (use case 1.1)

First, we generate the Concrete keyset and then serialize the shared secret key that will be used to encrypt the inputs. In our case, this shared secret key is the same for all inputs and outputs.

# generate all keys from scratch (not using initial secret keys)
circuit.keygen()
# since both inputs have the same type, they will use the same secret key, thus we serialize it once
secret_key: bytes = tfhers_bridge.serialize_input_secret_key(input_idx=0)
# we write it to a file to be used by TFHE-rs
with open("secret_key_from_concrete", "wb") as f:
    f.write(secret_key)

use tfhe::core_crypto::prelude::LweSecretKey;
use tfhe::ClientKey;

/// ...

let lwe_sk: LweSecretKey<Vec<u64>> = load_lwe_sk("secret_key_from_concrete");
let shortint_key =
    tfhe::shortint::ClientKey::try_from_lwe_encryption_key(
        lwe_sk,
        // Concrete uses this parameters to define the TFHE-rs ciphertext type
        tfhe::shortint::prelude::PARAM_MESSAGE_2_CARRY_3_KS_PBS
    ).unwrap();
let client_key = ClientKey::from_raw_parts(shortint_key.into(), None, None);
let server_key = client_key.generate_server_key();

KeyGen starts in TFHE-rs (use case 1.2)

First, we generate the TFHE-rs keyset and then serialize the shared secret key that will be used to encrypt the inputs

use tfhe::{prelude::*, ConfigBuilder};
use tfhe::generate_keys;

/// ...

// Concrete uses this parameters to define the TFHE-rs ciphertext type
let config = ConfigBuilder::with_custom_parameters(
        tfhe::shortint::prelude::PARAM_MESSAGE_2_CARRY_3_KS_PBS,
    )
.build();

let (client_key, server_key) = generate_keys(config);
let (integer_ck, _, _) = client_key.clone().into_raw_parts();
let shortint_ck = integer_ck.into_raw_parts();
let (glwe_secret_key, _, _) = shortint_ck.into_raw_parts();
let lwe_secret_key = glwe_secret_key.into_lwe_secret_key();

save_lwe_sk(lwe_secret_key, "secret_key_from_tfhers");

Next, we generate a Concrete keyset using the shared secret key from TFHE-rs.

# this was generated from TFHE-rs
with open("secret_key_from_tfhers", "rb") as f:
    sk_buff = f.read()
# maps input indices to their secret key
input_idx_to_key = {0: sk_buff, 1: sk_buff}
# we do a Concrete keygen starting with an initial set of secret keys
tfhers_bridge.keygen_with_initial_keys(input_idx_to_key_buffer=input_idx_to_key)

Using ciphertexts

At this point, we have everything necessary to encrypt, compute, and decrypt on both Concrete and TFHE-rs. Whether you began key generation in Concrete or in TFHE-rs, the keysets on both sides are compatible.

Now, we'll walk through an encryption and computation process in TFHE-rs, transition to Concrete to run the circuit, and then return to TFHE-rs for decryption.

let x = FheUint8::encrypt(162, &client_key);
let y = FheUint8::encrypt(73, &client_key);
// we will add two encrypted integers in TFHE-rs to showcase
// that we are doing some part of the computation in TFHE-rs
// and the rest in Concrete
let z = FheUint8::encrypt(9, &client_key);
y += z;

save_fheuint8(x, "tfhers_x");
save_fheuint8(y, "tfhers_y");

Next, we can load these ciphertexts in Concrete and then run our compiled circuit as usual.

with open("tfhers_x", "rb") as f:
    buff_x = f.read()
with open("tfhers_y", "rb") as f:
    buff_y = f.read()
tfhers_uint8_x = tfhers_bridge.import_value(buff_x, input_idx=0)
tfhers_uint8_y = tfhers_bridge.import_value(buff_y, input_idx=1)

encrypted_result = circuit.run(tfhers_uint8_x, tfhers_uint8_y)

Finally, we can decrypt and decode in Concrete

result = circuit.decrypt(encrypted_result)
decoded = tfhers_type.decode(result)

assert decoded == (162 + 73 + 9) % 213

... or export it to TFHE-rs for computation/decryption

buff_out = tfhers_bridge.export_value(encrypted_result, output_idx=0)
# write it to file
with open("tfhers_out", "wb") as f:
    f.write(buff_out)

let fheuint = load_fheuint8("tfhers_out");
// you can do computation before decryption as well
let result: u8 = fheuint.decrypt(&client_key);

assert!(result == (162 + 73 + 9) % 213)

This document explains the different passes happening in the compilation process, from the Concrete Python frontend to the Concrete MLIR compiler.

The next step in compilation is transforming the computation graph. There are many transformations we perform, and these are discussed in their own sections. The result of a transformation is another computation graph.

After transformations are applied, we need to determine the bounds (i.e., the minimum and the maximum values) of each intermediate node. This is required because FHE allows limited precision for computations. Measuring these bounds helps determine the required precision for the function.

The frontend is almost done at this stage and only needs to transform the computation graph to equivalent MLIR code. Once the MLIR is generated, our Compiler backend takes over. Any other frontend wishing to use the Compiler needs to plugin at this stage.

Tracing

We start with a Python function f, such as this one:

def f(x):
    return (2 * x) + 3

The goal of tracing is to create the following computation graph without requiring any change from the user.

(Note that the edge labels are for non-commutative operations. To give an example, a subtraction node represents (predecessor with edge label 0) - (predecessor with edge label 1))

To do this, we make use of Tracers, which are objects that record the operation performed during their creation. We create a Tracer for each argument of the function and call the function with those Tracers. Tracers make use of the operator overloading feature of Python to achieve their goal:

def f(x, y):
    return x + 2 * y

x = Tracer(computation=Input("x"))
y = Tracer(computation=Input("y"))

resulting_tracer = f(x, y)

2 * y will be performed first, and * is overloaded for Tracer to return another tracer: Tracer(computation=Multiply(Constant(2), self.computation)), which is equal to Tracer(computation=Multiply(Constant(2), Input("y"))).

x + (2 * y) will be performed next, and + is overloaded for Tracer to return another tracer: Tracer(computation=Add(self.computation, (2 * y).computation)), which is equal to Tracer(computation=Add(Input("x"), Multiply(Constant(2), Input("y"))).

In the end, we will have output tracers that can be used to create the computation graph. The implementation is a bit more complex than this, but the idea is the same.

Tracing is also responsible for indicating whether the values in the node would be encrypted or not. The rule for that is: if a node has an encrypted predecessor, it is encrypted as well.

Topological transforms

The goal of topological transforms is to make more functions compilable.

With the current version of Concrete, floating-point inputs and floating-point outputs are not supported. However, if the floating-point operations are intermediate operations, they can sometimes be fused into a single table lookup from integer to integer, thanks to some specific transforms.

Let's take a closer look at the transforms we can currently perform.

Fusing.

Bounds measurement

Given a computation graph, the goal of the bounds measurement step is to assign the minimal data type to each node in the graph.

If we have an encrypted input that is always between 0 and 10, we should assign the type EncryptedScalar<uint4> to the node of this input as EncryptedScalar<uint4>. This is the minimal encrypted integer that supports all values between 0 and 10.

If there were negative values in the range, we could have used intX instead of uintX.

Bounds measurement is necessary because FHE supports limited precision, and we don't want unexpected behaviour while evaluating the compiled functions.

Let's take a closer look at how we perform bounds measurement.

Inputset evaluation

This is a simple approach that requires an inputset to be provided by the user.

The inputset is not to be confused with the dataset, which is classical in ML, as it doesn't require labels. Rather, the inputset is a set of values which are typical inputs of the function.

The idea is to evaluate each input in the inputset and record the result of each operation in the computation graph. Then we compare the evaluation results with the current minimum/maximum values of each node and update the minimum/maximum accordingly. After the entire inputset is evaluated, we assign a data type to each node using the minimum and maximum values it contains.

Here is an example, given this computation graph where x is encrypted:

and this inputset:

[2, 3, 1]

Evaluation result of 2:

• x: 2

• 2: 2

• *: 4

• 3: 3

• +: 7