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

FHE is a powerful cryptographic tool, allowing computation to be performed directly on encrypted data without needing to decrypt it. With FHE, you can build services that preserve privacy for all users. FHE also offers ideal protection against data breaches as everything is done on encrypted data. Even if the server is compromised, no sensitive data is leaked.

Organization of this documentation

This documentation is split into several sections:

• Getting Started gives you the basics,

• Tutorials provides essential examples on various features of the library,

• How to helps you perform specific tasks,

• Developer explains the inner workings of the library and everything related to contributing to the project.

Looking for support? Ask our team!

How is Concrete different from Concrete Numpy?

Concrete Numpy was the former name of the Python frontend of the Concrete Compiler. Concrete Compiler is now open source, and the package name is updated from concrete-numpy to concrete-python (as concrete is already booked for a non FHE-related project).

How is it different from the previous version of Concrete?

To compute on encrypted data, you first need to define the function you want to compute, then compile it into a Concrete Circuit, which you can use to perform homomorphic evaluation.

Here is the full example that we will walk through:

from concrete import fhe

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

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

inputset = [(2, 3), (0, 0), (1, 6), (7, 7), (7, 1)]
circuit = compiler.compile(inputset)

x = 4
y = 4

clear_evaluation = add(x, y)
homomorphic_evaluation = circuit.encrypt_run_decrypt(x, y)

print(x, "+", y, "=", clear_evaluation, "=", homomorphic_evaluation)

Importing the library

Everything you need to perform homomorphic evaluation is included in a single module:

from concrete import fhe

Defining the function to compile

In this example, we compile a simple addition function:

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

Creating a compiler

To compile the function, you 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": "clear"})

Defining an inputset

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

It should be in iterable, yielding tuples, of the same length as the number of arguments of the function being compiled:

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

Compiling the function

You can use the compile method of a Compiler class with an inputset to perform the compilation and get the resulting circuit back:

circuit = compiler.compile(inputset)

Performing homomorphic evaluation

You can use the encrypt_run_decrypt method of a Circuit class to perform homomorphic evaluation:

homomorphic_evaluation = circuit.encrypt_run_decrypt(4, 4)

Concrete is natively supported on Linux and macOS from Python 3.8 to 3.11 inclusive. If you have Docker in your platform, you can use the docker image to use Concrete.

Using PyPI

You can install Concrete from PyPI:

pip install -U pip wheel setuptools
pip install concrete-python

Using Docker

You can also get the Concrete docker image:

docker pull zamafhe/concrete-python:v2.0.0
docker run --rm -it zamafhe/concrete-python:latest /bin/bash

Operations on encrypted values

Noise and Bootstrap

FHE encrypts data as LWE ciphertexts. These ciphertexts can be visually represented as a bit vector with the encrypted message in the higher-order (yellow) bits as well as a random part (gray), that guarantees the security of the encrypted message, called noise.

Under the hood, each time you perform an operation on an encrypted value, the noise grows and at a certain point, it may overlap with the message and corrupt its value.

There is a way to decrease the noise of a ciphertext with the Bootstrap operation. The bootstrap operation takes as input a noisy ciphertext and generates a new ciphertext encrypting the same message, but with a lower noise. This allows additional operations to be performed on the encrypted message.

A typical FHE program will be made up of a series of operations followed by a Bootstrap, this is then repeated many times.

Probability of Error

The amount of noise in a ciphertext is not as bounded as it may appear in the above illustration. As the errors are drawn randomly from a Gaussian distribution, they can be of varying size. This means that we need to be careful to ensure the noise terms do not effect the message bits. If the error terms do overflow into the message bits, this can cause an incorrect output (failure) when bootstrapping.

Function evaluation

So far, we only introduced arithmetic operations but a typical program usually also involves functions (maximum, minimum, square root…)

During the Bootstrap operation, in TFHE, you could perform a table lookup simultaneously to reduce noise, turning the Bootstrap operation into a Programmable Bootstrap (PBS).

Concrete uses the PBS to support function evaluation:

Let's take a simple example. A function (or circuit) that takes a 4 bits input variable and output the maximum value between a clear constant and the encrypted input:

example:

import numpy as np

def encrypted_max(x: uint4):
    return np.maximum(5, x)

could be turned into a table lookup:

def encrypted_max(x: uint4):
    lut = [5, 5, 5, 5, 5, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
    return lut[x]

The Lookup table lut being applied during the Programmable Bootstrap.

PBS management

You should not worry about PBS, they are completely managed by Concrete during the compilation process. Each function evaluation will be turned into a Lookup table and evaluated by a PBS.

See this in action with the previous example, if you dump the MLIR code produced by the frontend, you will see (forget about MLIR syntax, just see the Lookup table value on the 4th line):

module {
  func.func @main(%arg0: !FHE.eint<4>) -> !FHE.eint<4> {
    %cst = arith.constant dense<[5, 5, 5, 5, 5, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]> : tensor<16xi64>
    %0 = "FHE.apply_lookup_table"(%arg0, %cst) : (!FHE.eint<4>, tensor<16xi64>) -> !FHE.eint<4>
    return %0 : !FHE.eint<4>
  }
}

The only thing you should keep in mind is that it adds a constraint on the input type, and that is the reason behind having a maximum bit-width supported in Concrete.

Second takeaway is that PBS are the most costly operations in FHE, the less PBS in your circuit the faster it will run. It is an interesting metrics to optimize (you will see that Concrete could give you the number of PBS used in your circuit).

Note also that PBS cost varies with the input variable precision (a circuit with 8 bit PBS will run faster than one with 16 bits PBS).

Development Workflow

Allowing computation on encrypted data is particularly interesting in the client/server model, especially when the client data are sensitive and the server not trusted. You could split the workflow in two main steps: development and deployment.

Development

During development, you will turn your program into its FHE equivalent. Concrete automates this task with the compilation process but you can make this process even easier by reducing the precision required, reducing the number of PBSs or allowing more parallelization in your code (e.g. working on bit chunks instead of high bit-width variables).

Once happy with the code, the development process is over and you will create the compiler artifact that will be used during deployment.

Deployment

A typical Concrete deployment will host on a server the compilation artifact: Client specifications required by the compiled circuits and the fhe executable itself. Client will ask for the circuit requirements, generate keys accordingly, then it will send an encrypted payload and receive an encrypted result.

Terminology

Some terms used throughout the project include:

• computation graph: A data structure to represent a computation. This is basically a directed acyclic graph in which nodes are either inputs, constants, or operations on other nodes.

• tracing: A technique that takes a Python function from the user and generates a corresponding computation graph.

• bounds: Before computation graphs are converted to MLIR, we need to know which value should have which type (e.g., uint3 vs int5). We use inputsets for this purpose. We simulate the graph with the inputs in the inputset to remember the minimum and the maximum value for each node, which is what we call bounds, and use bounds to determine the appropriate type for each node.

• circuit: The result of compilation. A circuit is made of the client and server components. It has methods for everything from printing to evaluation.

Module structure

In this section, we briefly discuss the module structure of Concrete Python. You are encouraged to check individual .py files to learn more.

• concrete

  • fhe

    • dtypes: data type specifications (e.g., int4, uint5, float32)

    • values: value specifications (i.e., data type + shape + encryption status)

    • representation: representation of computation (e.g., computation graphs, nodes)

    • tracing: tracing of python functions

    • mlir: computation graph to mlir conversion

    • compilation: configuration, compiler, artifacts, circuit, client/server, and anything else related to compilation

Supported operations

Here are the operations you can use inside the function you are compiling:

Supported Python operators.

Supported NumPy functions.

Supported ndarray methods.

Supported ndarray properties.

Limitations

Control flow constraints.

Some Python control flow statements are not supported. You cannot have an if statement or a while statement for which the condition depends on an encrypted value. However, such statements are supported with constant values (e.g., for i in range(SOME_CONSTANT), if os.environ.get("SOME_FEATURE") == "ON":).

Type constraints.

You cannot have floating-point inputs or floating-point outputs. You can have floating-point intermediate values as long as they can be converted to an integer Table Lookup (e.g., (60 * np.sin(x)).astype(np.int64)).

Bit width constraints.

There is a limit on the bit width of encrypted values. We are constantly working on increasing this bit width. If you go above the limit, you will get an error.

Big circuits can take a long time to execute, and waiting for execution to finish without having any indication of its progress can be frustrating. For this reason, progressbar feature is introduced:

import time

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

configuration = fhe.Configuration(
    enable_unsafe_features=True,
    use_insecure_key_cache=True,
    insecure_key_cache_location=".keys",

    # To enable displaying progressbar
    show_progress=True,
    # To enable showing tags in the progressbar (does not work in notebooks)
    progress_tag=True,
    # To give a title to the progressbar
    progress_title="Evaluation:",
)

@fhe.compiler({"image": "encrypted"})
def to_grayscale(image):
    with fhe.tag("scaling.r"):
        r = image[:, :, 0]
        r = (r * 0.30).astype(np.int64)

    with fhe.tag("scaling.g"):
        g = image[:, :, 1]
        g = (g * 0.59).astype(np.int64)

    with fhe.tag("scaling.b"):
        b = image[:, :, 2]
        b = (b * 0.11).astype(np.int64)

    with fhe.tag("combining.rgb"):
        gray = r + g + b
        
    with fhe.tag("creating.result"):
        gray = np.expand_dims(gray, axis=2)
        result = np.concatenate((gray, gray, gray), axis=2)
    
    return result

image_size = (16, 16)
image_data = (randimage.get_random_image(image_size) * 255).round().astype(np.int64)

print()

print(f"Compilation started @ {time.strftime('%H:%M:%S', time.localtime())}")
start = time.time()
inputset = [np.random.randint(0, 256, size=image_data.shape) for _ in range(100)]
circuit = to_grayscale.compile(inputset, configuration)
end = time.time()
print(f"(took {end - start:.3f} seconds)")

print()

print(f"Key generation started @ {time.strftime('%H:%M:%S', time.localtime())}")
start = time.time()
circuit.keygen()
end = time.time()
print(f"(took {end - start:.3f} seconds)")

print()

print(f"Evaluation started @ {time.strftime('%H:%M:%S', time.localtime())}")
start = time.time()
grayscale_image_data = circuit.encrypt_run_decrypt(image_data)
end = time.time()
print(f"(took {end - start:.3f} seconds)")

fig, axs = plt.subplots(1, 2)
axs = axs.flatten()

axs[0].set_title("Original")
axs[0].imshow(image_data)
axs[0].axis("off")

axs[1].set_title("Grayscale")
axs[1].imshow(grayscale_image_data)
axs[1].axis("off")

plt.show()

When you run this code, you will see a progressbar like:

Evaluation:  10% |█████.............................................|  10% (scaling.r)
^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^
Title        Progressbar                                                   Tag

And as the circuit progresses, this progressbar would fill:

Evaluation:  30% |███████████████...................................|  30% (scaling.g)

Evaluation:  50% |█████████████████████████.........................|  50% (scaling.b)

Once the progressbar fills and execution completes, you will see the following figure:

One of the most common operations in Concrete is 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:

is exactly the same as

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.

When you have big circuits, keeping track of which node corresponds to which part of your code becomes difficult. A tagging system can simplify such situations:

When you compile f with inputset of range(10), you get the following graph:

If you get an error, you'll see exactly where the error occurred (e.g., which layer of the neural network, if you tag layers).

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:

One of the most common operations in Concrete is Table Lookups (TLUs). TLUs are performed with an FHE operation called Programmable Bootstrapping (PBS). PBS's have a certain probability of error, which, when triggered, result in inaccurate results.

Let's say you have the table:

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 of being exact with a 1% probability of error. If you have a single TLU in the circuit, global_p_error would be 1% as well. But if you have 2 TLUs for example, global_p_error would be almost 2% (1 - (0.99 * 0.99)).

However, if you set global_p_error to 0.01, the whole circuit will have 1% probability of error, no matter how many Table Lookups are included.

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 is set to None, which results in a global_p_error of 1 / 100_000 being used.

Concrete supports native Python and NumPy operations as much as possible, but not everything in Python or NumPy is available. Therefore, we provide some extensions ourselves to improve your experience.

fhe.univariate(function)

Allows you to wrap any univariate function into a single table lookup:

fhe.conv(...)

fhe.maxpool(...)

fhe.array(...)

Allows you to create encrypted arrays:

fhe.zero()

Allows you to create an encrypted scalar zero:

fhe.zeros(shape)

Allows you to create an encrypted tensor of zeros:

fhe.one()

Allows you to create an encrypted scalar one:

fhe.ones(shape)

Allows you to create an encrypted tensor of ones:

fhe.hint(value, **kwargs)

Allows you to hint properties of a value. Imagine you have this circuit:

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

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 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 the 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:

you'll always see:

regardless of the bounds.

You can convert your compiled circuit into its textual representation by converting it to string:

If you just want to see the output on your terminal, you can directly print it as well:

Comparisons are not native operations in Concrete, so they need to be implemented using existing native operations (i.e., additions, clear multiplications, negations, table lookups). Concrete offers three different implementations for performing comparisons.

Chunked

This is the most general implementation that can be used in any situation. The idea is:

Notes

• Signed comparisons are a bit more complex to explain, but they are supported!

• Optimal chunk size is selected automatically to reduce the number of table lookups.

• Chunked comparisons result in at least 5 and at most 13 table lookups.

• It is used if no other implementation can be used.

• == and != is using a different chunk comparison and reduction strategy with less table lookups.

Pros

• Can be used with any integers.

Cons

• Very expensive.

Example

produces

Subtraction Trick

This implementation uses the fact that x [<,<=,==,!=,>=,>] y is equal to x - y [<,<=,==,!=,>=,>] 0, which is just a subtraction and a table lookup!

There are two major problems with this implementation though:

1. subtraction before the TLU requires up to 2 additional bits to avoid overflows (it is 1 in most cases).

2. subtraction requires the same bit-width across operands.

What this means is if we are comparing uint3 and uint6, we need to convert both of them to uint7 in some way to do the subtraction and proceed with the TLU in 7-bits. There are 4 ways to achieve this behavior.

Requirements

1. fhe.ComparisonStrategy.ONE_TLU_PROMOTED

This strategy makes sure that during bit-width assignment, both operands are assigned the same bit-width, and that bit-width contains at least the amount of bits required to store x - y. The idea is:

Pros

• It will always result in a single table lookup.

Cons

• It will increase the bit-width of both operands and lock them to each other across the whole circuit, which can result in significant slowdowns if the operands are used in other costly operations.

Example

produces

2. fhe.ComparisonStrategy.THREE_TLU_CASTED

This strategy will not put any constraint in bit-widths during bit-width assignment, instead operands are cast to a bit-width that can store x - y during runtime using table lookups. The idea is:

Notes

• It can result in a single table lookup as well, if x and y are assigned (because of other operations) the same bit-width, and that bit-width can store x - y.

• Or in two table lookups if only one of the operands is assigned a bit-width bigger than or equal to the bit width that can store x - y.

Pros

• It will not put any constraints on bit-widths of the operands, which is amazing if they are used in other costly operations.

• It will result in at most 3 table lookups, which is still good.

Cons

• If you are not doing anything else with the operands, or doing less costly operations compared to comparison, it will introduce up to two unnecessary table lookups and slow down execution compared to fhe.ComparisonStrategy.ONE_TLU_PROMOTED.

Example

produces

3. fhe.ComparisonStrategy.TWO_TLU_BIGGER_PROMOTED_SMALLER_CASTED

This strategy is like the middle ground between the two strategies described above. With this strategy, only the bigger operand will be constrained to have at least the required bit-width to store x - y, and the smaller operand will be cast to that bit-width during runtime. The idea is:

Notes

• It can result in a single table lookup as well, if the smaller operand is assigned (because of other operations) the same bit-width as the bigger operand.

Pros

• It will only put constraint on the bigger operand, which is great if the smaller operand is used in other costly operations.

• It will result in at most 2 table lookups, which is great.

Cons

• It will increase the bit-width of the bigger operand which can result in significant slowdowns if the bigger operand is used in other costly operations.

• If you are not doing anything else with the smaller operand, or doing less costly operations compared to comparison, it could introduce an unnecessary table lookup and slow down execution compared to fhe.ComparisonStrategy.THREE_TLU_CASTED.

Example

produces

4. fhe.ComparisonStrategy.TWO_TLU_BIGGER_CASTED_SMALLER_PROMOTED

This strategy is like the exact opposite of the strategy above. With this, only the smaller operand will be constrained to have at least the required bit-width, and the bigger operand will be cast during runtime. The idea is:

Notes

• It can result in a single table lookup as well, if the bigger operand is assigned (because of other operations) the same bit-width as the smaller operand.

Pros

• It will only put constraint on the smaller operand, which is great if the bigger operand is used in other costly operations.

• It will result in at most 2 table lookups, which is great.

Cons

• It will increase the bit-width of the smaller operand which can result in significant slowdowns if the smaller operand is used in other costly operations.

• If you are not doing anything else with the bigger operand, or doing less costly operations compared to comparison, it could introduce an unnecessary table lookup and slow down execution compared to fhe.ComparisonStrategy.THREE_TLU_CASTED.

Example

produces

Clipping Trick

This implementation uses the fact that the subtraction trick is not optimal in terms of the required intermediate bit width. Comparison result does not change if we compare(3, 40) or compare(3, 4), so why not clipping the bigger operand and then doing the subtraction to use less bits!

There are two major problems with this implementation as well though:

1. it can not be used when bit-widths are the same (for some cases even when they differ by only one bit)

2. subtraction still requires the same bit-width across operands.

What this means is if we are comparing uint3 and uint6, we need to convert both of them to uint4 in some way to do the subtraction and proceed with the TLU in 7-bits. There are 2 ways to achieve this behavior.

Requirements

1. fhe.ComparisonStrategy.THREE_TLU_BIGGER_CLIPPED_SMALLER_CASTED

This strategy will not put any constraint in bit-widths during bit-width assignment, instead the smaller operand is cast to a bit-width that can store clipped(bigger) - smaller or smaller - clipped(bigger) during runtime using table lookups. The idea is:

Notes

• This is a fallback implementation, so if there is a difference of 1-bit (or in some cases 2-bits) and subtraction trick cannot be used optimally, this implementation will be used instead of fhe.ComparisonStrategy.CHUNKED.

• It can result in two table lookups if the smaller operand is assigned a bit-width bigger than or equal to the bit width that can store clipped(bigger) - smaller or smaller - clipped(bigger).

Pros

• It will not put any constraints on bit-widths of the operands, which is amazing if they are used in other costly operations.

• It will result in at most 3 table lookups, which is still good.

• And those table lookups will be on smaller bit-widths, which is great.

Cons

• Cannot be used to compare integers with the same bit-width, which is very common.

Example

produces

2. fhe.ComparisonStrategy.TWO_TLU_BIGGER_CLIPPED_SMALLER_PROMOTED

This strategy is similar to the strategy described above. The difference is that with this strategy, the smaller operand will be constrained to have at least the required bit-width to store clipped(bigger) - smaller or smaller - clipped(bigger). The bigger operand will still be clipped to that bit-width during runtime. The idea is:

Pros

• It will only put constraint on the smaller operand, which is great if the bigger operand is used in other costly operations.

• It will result in exactly 2 table lookups, which is great.

Cons

• It will increase the bit-width of the bigger operand which can result in significant slowdowns if the bigger operand is used in other costly operations.

Example

produces

Summary

Integers in Concrete are encrypted and processed according to a set of cryptographic parameters. By default, multiple of such parameters are selected by Concrete Optimizer. This might not be the best approach for every use case and there is the option to use mono parameters.

When multi parameters are enabled, a different set of parameters are selected for each bit-width in the circuit, which results in:

• Faster execution (generally).

• Slower key generation.

• Larger keys.

• Larger memory usage during execution.

To disable it, you can use parameter_selection_strategy=fhe.ParameterSelectionStrategy.MONO configuration option.

Concrete partly supports floating points. There is no support for floating point inputs or outputs. However, there is support for intermediate values to be floating points (under certain constraints).

Floating points as intermediate values

Concrete-Compile, which is used for compiling the circuit, doesn't support floating points at all. However, it supports table lookups which take an integer and map it to another integer. The constraints of this operation are that there should be a single integer input, and a single integer output.

As long as your floating point operations comply with those constraints, Concrete automatically converts them to a table lookup operation:

from concrete import fhe
import numpy as np

@fhe.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 floating point intermediates. They are used to calculate d, which is an integer with a value dependent upon x, which is also an integer. Concrete detects this and fuses all of these 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 others:

from concrete import fhe
import numpy as np

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

This 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 the error is that d no longer depends solely on x; it depends on y as well. Concrete cannot fuse these operations, so it raises an exception instead.

Each integer in the circuit has a certain bit-width, which is determined by the inputset. These bit-widths can be observed when graphs are printed:

%0 = x                  # EncryptedScalar<uint3>              ∈ [0, 7]
%1 = y                  # EncryptedScalar<uint4>              ∈ [0, 15]
%2 = add(%0, %1)        # EncryptedScalar<uint5>              ∈ [2, 22]
return %2                                     ^ these are       ^^^^^^^
                                                the assigned    based on
                                                bit-widths      these bounds

However, it's not possible to add 3-bit and 4-bit numbers together because their encoding is different:

D: data
N: noise

3-bit number
------------
D2 D1 D0 0 0 0 ... 0 0 0 N N N N

4-bit number
------------
D3 D2 D1 D0 0 0 0 ... 0 0 0 N N N N

The result of such an addition is a 5-bit number, which also has a different encoding:

5-bit number
------------
D4 D3 D2 D1 D0 0 0 0 ... 0 0 0 N N N N

Because of these encoding differences, we perform a graph processing step called bit-width assignment, which takes the graph and updates the bit-widths to be compatible with FHE.

After this graph processing step, the graph would look like:

%0 = x                  # EncryptedScalar<uint5>
%1 = y                  # EncryptedScalar<uint5>
%2 = add(%0, %1)        # EncryptedScalar<uint5>
return %2

Most operations cannot change the encoding, which means that the input and output bit-widths need to be the same. However, there is an operation which can change the encoding: the table lookup operation.

Let's say you have this graph:

%0 = x                    # EncryptedScalar<uint2>        ∈ [0, 3]
%1 = y                    # EncryptedScalar<uint5>        ∈ [0, 31]
%2 = 2                    # ClearScalar<uint2>            ∈ [2, 2]
%3 = power(%0, %2)        # EncryptedScalar<uint4>        ∈ [0, 9]
%4 = add(%3, %1)          # EncryptedScalar<uint6>        ∈ [1, 39]
return %4

This is the graph for (x**2) + y where x is 2-bits and y is 5-bits. If the table lookup operation wasn't able to change the encoding, we'd need to make everything 6-bits. However, since the encoding can be changed, the bit-widths can be assigned like so:

%0 = x                    # EncryptedScalar<uint2>        ∈ [0, 3]
%1 = y                    # EncryptedScalar<uint6>        ∈ [0, 31]
%2 = 2                    # ClearScalar<uint2>            ∈ [2, 2]
%3 = power(%0, %2)        # EncryptedScalar<uint6>        ∈ [0, 9]
%4 = add(%3, %1)          # EncryptedScalar<uint6>        ∈ [1, 39]
return %4

In this case, we kept x as 2-bits, but set the table lookup result and y to be 6-bits, so that the addition can be performed.

This style of bit-width assignment is called multi-precision, and it is enabled by default. To disable it and use a single precision across the circuit, you can use the single_precision=True configuration option.

In this tutorial, we will review how to perform direct table lookups in Concrete.

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:

To overcome this issue, simulation is introduced:

from concrete import fhe
import numpy as np

@fhe.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, fhe_simulation=True)

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())

After the simulation runs, it prints the following:

[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
[1, 4, 9, 16, 16, 36, 49, 64, 81, 100]

For some applications, the data types of inputs, intermediate values, and outputs are known (e.g., for manipulating bytes, you would want to use uint8). Using inputsets to determine bounds in these cases is not necessary, and can even be error-prone. Therefore, another interface for defining such circuits is introduced:

There are a few differences between direct circuits and traditional circuits:

• Remember that the 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: fhe.uint8, you won't receive a negative value as the result will be fhe.uint8 as well)

• There is no inputset evaluation when using fhe types in .astype(...) calls (e.g., np.sqrt(x).astype(fhe.uint4)), so the bit width of the output cannot be determined.

• Be careful with overflows. With inputset evaluation, you'll get bigger bit widths but no overflows. With direct definition, you must ensure that there aren't any overflows manually.

Let's review a more complicated example to see how direct circuits behave:

This prints:

Here is the breakdown of the assigned data types:

As you can see, %8 is subtraction of two unsigned values, and the result is unsigned as well. In the case that c > d, we have an overflow, and this results in undefined behavior.

Concrete can be customized using Configurations:

You can overwrite individual options as kwargs to the compile method:

Or you can combine both:

Options

• show_graph: Optional[bool] = None

  • Print computation graph during compilation. True means always print, False means never print, None means print depending on verbose configuration below.

• show_mlir: Optional[bool] = None

  • Print MLIR during compilation. True means always print, False means never print, None means print depending on verbose configuration below.

• show_optimizer: Optional[bool] = None

  • Print optimizer output during compilation. True means always print, False means never print, None means print depending on verbose configuration below.

• show_statistics: Optional[bool] = None

  • Print circuit statistics during compilation. True means always print, False means never print, None means print depending on verbose configuration below.

• verbose: bool = False

  • Print details related to compilation.

• dump_artifacts_on_unexpected_failures: bool = True

  • Export debugging artifacts automatically on compilation failures.

• auto_adjust_rounders: bool = False

  • Adjust rounders automatically.

• p_error: Optional[float] = None
• global_p_error: Optional[float] = None
• single_precision: bool = False

  • Use single precision for the whole circuit.

• parameter_selection_strategy: (fhe.ParameterSelectionStrategy) = fhe.ParameterSelectionStrategy.MULTI

  • Set how cryptographic parameters are selected.

• jit: bool = False

  • Enable JIT compilation.

• loop_parallelize: bool = True

  • Enable loop parallelization in the compiler.

• dataflow_parallelize: bool = False

  • Enable dataflow parallelization in the compiler.

• auto_parallelize: bool = False

  • Enable auto parallelization in the compiler.

• enable_unsafe_features: bool = False

  • Enable unsafe features.

• use_insecure_key_cache: bool = False (Unsafe)

  • Use the insecure key cache.

• insecure_key_cache_location: Optional[Union[Path, str]] = None

  • Location of insecure key cache.

• show_progress: bool = False,

  • Display a progress bar during circuit execution

• progress_title: str = "",

  • Title of the progress bar

• progress_tag: Union[bool, int] = False,

  • How many nested tag elements to display with the progress bar. True means all tag elements and False disables the display. 2 will display elmt1.elmt2

• fhe_simulation: bool = False

  • Enable FHE simulation. Can be enabled later using circuit.enable_fhe_simulation().

• fhe_execution: bool = True

  • Enable FHE execution. Can be enabled later using circuit.enable_fhe_execution().

• compiler_debug_mode: bool = False,

  • Enable/disable debug mode of the compiler. This can show a lot of information, including passes and pattern rewrites.

• compiler_verbose_mode: bool = False,

  • Enable/disable verbose mode of the compiler. This mainly show logs from the compiler, and is less verbose than the debug mode.

• comparison_strategy_preference: Optional[Union[ComparisonStrategy, str, List[Union[ComparisonStrategy, str]]]] = None

Concrete generates keys for you implicitly when they are needed and if they have not already been generated. This is useful for development, but it's not flexible (or secure!) for production. Explicit key management API is introduced to be used in such cases to easily generate and re-use keys.

Definition

Let's start by defining a circuit:

Circuits have a property called keys of type fhe.Keys, which has several utility functions dedicated to key management!

Generation

To explicitly generate keys for a circuit, you can use:

And it's possible to set a custom seed for reproducibility:

Serialization

To serialize keys, say to send it across the network:

Deserialization

To deserialize the keys back, after receiving serialized keys:

Assignment

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

Saving

You can also use the filesystem to store the keys directly, without needing to deal with serialization and file management yourself:

Loading

After keys are saved to disk, you can load them back via:

Automatic Management

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

After developing your circuit, you may want to deploy it. However, sharing the details of your circuit with every client might not be desirable. As well as this, you might want to perform the computation on dedicated servers. In this case, you can use the Client and Server features of Concrete.

Development of the circuit

You can develop your circuit using the techniques discussed in previous chapters. Here is a simple example:

Once you have your circuit, you can save everything the server needs:

Then, send server.zip to your computation server.

Setting up a server

You can load the server.zip you get from the development machine:

You will need to wait for requests from clients. The first likely request is for ClientSpecs.

Clients need ClientSpecs to generate keys and request computation. You can serialize ClientSpecs:

Then, you can send it to the clients requesting it.

Setting up clients

After getting the serialized ClientSpecs from a server, you can create the client object:

Generating keys (on the client)

Once you have the Client object, you can perform key generation:

This method generates encryption/decryption keys and evaluation keys.

The server needs access to the evaluation keys that were just generated. You can serialize your evaluation keys as shown:

After serialization, send the evaluation keys to the server.

Encrypting inputs (on the client)

The next step is to encrypt your inputs and request the server to perform some computation. This can be done in the following way:

Then, send the serialized arguments to the server.

Performing computation (on the server)

Once you have serialized evaluation keys and serialized arguments, you can deserialize them:

You can perform the computation, as well:

Then, send the serialized result back to the client. After this, the client can decrypt to receive the result of the computation.

Decrypting the result (on the client)

Once you have received the serialized result of the computation from the server, you can deserialize it:

Then, decrypt the result:

Encryption can take quite some time, memory, and network bandwidth if encrypted data is to be transported. Some applications use the same argument, or a set of arguments as one of the inputs. In such applications, it doesn't make sense to encrypt and transfer the arguments each time. Instead, arguments can be encrypted separately, and reused:

If you have multiple arguments, the encrypt method would return a tuple, and if you specify None as one of the arguments, None is placed at the same location in the resulting tuple (e.g., circuit.encrypt(a, None, b, c, None) would return (encrypted_a, None, encrypted_b, encrypted_c, None)). Each value returned by encrypt can be stored and reused anytime.

In this section, you will learn how to debug the compilation process easily and find help in the case that you cannot resolve your issue.

Debug artifacts

Concrete has an artifact system to simplify the process of debugging issues.

Automatic export.

In case of compilation failures, artifacts are exported automatically to the .artifacts directory under the working directory. Let's intentionally create a compilation failure to show what is exported.

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. If you go to the .artifacts directory under the working directory, you'll see the following files:

environment.txt

This file contains information about your setup (i.e., your 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

This file contains information about Python packages and their versions installed on your system.

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

This file contains information about the function you tried to compile.

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

parameters.txt

This file contains information about the encryption status of the parameters of the function you tried to compile.

x :: encrypted

1.initial.graph.txt

This file contains the textual representation of the initial computation graph right after tracing.

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

2.final.graph.txt

This file contains 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

This file contains information about the error you received.

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. They can be very useful for 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()

If you go to the /tmp/custom/export/path directory, you'll see the following files:

1.initial.graph.txt

This file contains 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

This file contains 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

This file contains 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

This file contains information about the MLIR of the function you compiled using the inputset you provided.

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

This file contains 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

If you cannot find a solution in the community forum, or you found a bug in the library, you could create an issue in our GitHub repository.

In case of a bug, try to:

• minimize randomness;

• minimize your function as much as possible while keeping the bug - this will help to fix the bug faster;

• include your inputset in the issue;

• include reproduction steps in the issue;

• include debug artifacts in the issue.

In case of a feature request, try to:

• give a minimal example of the desired behavior;

• explain your use case.

Table lookups have a strict constraint on the number of bits they support. This can be limiting, especially if you don't need exact precision. As well as this, using larger bit-widths leads to slower table lookups.

To overcome these issues, rounded table lookups are introduced. This operation provides a way to round the least significant bits of a large integer and then apply the table lookup on the resulting (smaller) value.

Imagine you have a 5-bit value, but you want to have a 3-bit table lookup. You can call fhe.round_bit_pattern(input, lsbs_to_remove=2) and use the 3-bit value you receive as input to the table lookup.

Let's see how rounding works in practice:

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

original_bit_width = 5
lsbs_to_remove = 2

assert 0 < lsbs_to_remove < original_bit_width

original_values = list(range(2**original_bit_width))
rounded_values = [
    fhe.round_bit_pattern(value, lsbs_to_remove)
    for value in original_values
]

previous_rounded = rounded_values[0]
for original, rounded in zip(original_values, rounded_values):
    if rounded != previous_rounded:
        previous_rounded = rounded
        print()

    original_binary = np.binary_repr(original, width=(original_bit_width + 1))
    rounded_binary = np.binary_repr(rounded, width=(original_bit_width + 1))

    print(
        f"{original:2} = 0b_{original_binary[:-lsbs_to_remove]}[{original_binary[-lsbs_to_remove:]}] "
        f"=> "
        f"0b_{rounded_binary[:-lsbs_to_remove]}[{rounded_binary[-lsbs_to_remove:]}] = {rounded}"
    )

fig = plt.figure()
ax = fig.add_subplot()

plt.plot(original_values, original_values, label="original", color="black")
plt.plot(original_values, rounded_values, label="rounded", color="green")
plt.legend()

ax.set_aspect("equal", adjustable="box")
plt.show()