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:

Operations on encrypted values

The idea of homomorphic encryption is that you can compute on ciphertexts without knowing the messages they encrypt. A scheme is said to be fully homomorphic, if an unlimited number of additions and multiplications are supported ($x$ is a plaintext and $E[x]$ is the corresponding ciphertext):

• homomorphic addition:

• homomorphic multiplication:

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.

The default failure probability in Concrete is set for the whole program and is by default. This means that 1 execution of every 100,000 may result in an incorrect output. To have a lower probability of error, you need to change the cryptographic parameters, likely resulting in worse performance. On the other side of this trade-off, allowing a higher probability of error will likely speed-up operations.

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:

• homomorphic univariate 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:

could be turned into a table lookup:

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

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.

For more information on deployment, see

📁 Github | 💛 Community support | 🟨 Zama Bounty Program

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.

Since writing FHE programs is a difficult task, Concrete framework contains a TFHE Compiler based on LLVM to make this process easier for developers.

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,

Looking for support? Ask our team!

• Support forum: (we answer in less than 24 hours).

• Live discussion on the FHE.org discord server: (inside the #concrete channel).

• Do you have a question about Zama? Write us on or send us an email at: [email protected]

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

Users from Concrete Numpy can safely update to Concrete, with a few required changes, as explained in the .

How is it different from the previous version of Concrete?

Before v1.0, Concrete was a set of Rust libraries implementing Zama's variant of TFHE. Starting with v1, Concrete is now Zama's TFHE Compiler framework only. The Rust library is now called .

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:

Importing the library

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

Defining the function to compile

In this example, we compile a simple addition function:

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:

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:

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:

Performing homomorphic evaluation

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

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.

This is an interactive tutorial written as a Jupyter Notebook, which you can find here.

This is an interactive tutorial written as a Jupyter Notebook, which you can find here.

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

str(circuit)

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

print(circuit)

During development, the speed of homomorphic execution can be a blocker for fast prototyping. You could call the function you're trying to compile directly, of course, but it won't be exactly the same as FHE execution, which has a certain probability of error (see Exactness).

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]

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:

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)

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

Fusing is the act of combining multiple nodes into a single node, which is converted to a table lookup.

How is it done?

Code related to fusing is in the frontends/concrete-python/concrete/fhe/compilation/utils.py file. Fusing can be performed using the fuse function.

There are two ways to contribute to Concrete. You can:

• Open issues to report bugs and typos or suggest ideas;

• Request to become an official contributor by emailing [email protected]. Only approved contributors can send pull requests (PRs), so get in touch before you do.

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:

from concrete import fhe

@fhe.compiler({"x": "encrypted", "y": "encrypted"})
def add(x, y):
    return x + y

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

sample_y = 4
_, encrypted_y = circuit.encrypt(None, sample_y)

for sample_x in range(3, 6):
    encrypted_x, _ = circuit.encrypt(sample_x, None)

    encrypted_result = circuit.run(encrypted_x, encrypted_y)
    result = circuit.decrypt(encrypted_result)

    assert result == sample_x + sample_y

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.

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:

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

Feel free to play with these configuration options to pick the one best suited for your needs! See to learn how you can set a custom p_error and/or global_p_error.

The concrete backends are implementations of the cryptographic primitives of the Zama variant of TFHE. The compiler emits code which combines call into these backends to perform more complex homomorphic operations.

There are client and server features.

Client features are:

• private (G)LWE key generation (currently random bits)

• encryption of ciphertexts using a private key

• public key generation from private keys for keyswitch, bootstrap or private packing

• (de)serialization of ciphertexts and public keys (also needed server side)

Server features are homomorphic operations on ciphertexts:

• linear operations (multisums with plain weights)

• keyswitch

• simple PBS

There are currently 2 backends:

• concrete-cpu which implements both client and server features targeting the CPU.

• concrete-cuda which implements only server features targeting GPUs to accelerate homomorphic circuit evalutation.

The compiler uses concrete-cpu for the client and can use either concrete-cpu or concrete-cuda for the server.

Concrete is a modular framework composed by sub-projects using different technologies, all having theirs own build system and test suite. Each sub-project have is own README that explain how to setup the developer environment, how to build it and how to run tests commands.

Concrete is made of 4 main categories of sub-project that are organized in subdirectories from the root of the concrete repo:

• frontends contains high-level transpilers that target end users developers who want to use the Concrete stack easily from their usual environment. There are for now only one frontend provided by the Concrete project: a Python frontend named concrete-python.

• compilers contains the sub-projects in charge of actually solving the compilation problem of an high-level abstraction of FHE to an actual executable. concrete-optimizer is a Rust based project that solves the optimization problems of an FHE dag to a TFHE dag and concrete-compiler which use concrete-optimizer is an end-to-end MLIR-based compiler that takes a crypto free FHE dialect and generates compilation artifacts both for the client and the server. concrete-compiler project provide in addition of the compilation engine, a client and server library in order to easily play with the compilation artifacts to implement a client and server protocol.

• backends contains CAPI that can be called by the concrete-compiler runtime to perform the cryptographic operations. There are currently two backends:

  • concrete-cpu, using TFHE-rs that implement the fastest implementation of TFHE on CPU.

• tools are basically every other sub-projects that cannot be classified in the three previous categories and which are used as a common support by the others.

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)

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.

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

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:

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

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

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:

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.

concrete-optimizer is a tool that selects appropriate cryptographic parameters for a given fully homomorphic encryption (FHE) computation. These parameters have an impact on the security, correctness, and efficiency of the computation.

The computation is guaranteed to be secure with the given level of security (see here for details) which is typically 128 bits. The correctness of the computation is guaranteed up to a given failure probability. A surrogate of the execution time is minimized which allows for efficient FHE computation.

The cryptographic parameters are degrees of freedom in the FHE algorithms (bootstrapping, keyswitching, etc.) that need to be fixed. The search space for possible crypto-parameters is finite but extremely large. The role of the optimizer is to quickly find the most efficient crypto-parameters possible while guaranteeing security and correctness.

Security, Correctness, and Efficiency

Security

The security level is chosen by the user. We typically operate at a fixed security level, such as 128 bits, to ensure that there is never a trade-off between security and efficiency. This constraint imposes a minimum amount of noise in all ciphertexts.

An independent public research tool, the , is used to estimate the security level. The lattice estimator is maintained by FHE experts. For a given set of crypto-parameters, this tool considers all possible attacks and returns a security level.

For each security level, a parameter curve of the appropriate minimal error level is pre-computed using the lattice estimator, and is used as an input to the optimizer. Learn more about the parameter curves .

Correctness

Correctness decreases as the level of noise increases. Noise accumulates during homomorphic computation until it is actively reduced via bootstrapping. Too much noise can lead to the result of a computation being inaccurate or completely incorrect.

Before optimization, we compute a noise bound that guarantees a given error level (under the assumption that noise growth is correctly managed via bootstrapping). The noise growth depends on a critical quantity: the 2-norm of any dot product (or equivalent) present in the calculus. This 2-norm changes the scale of the noise, so we must reduce it sufficiently for the next dot product operation whenever we reduce the noise.

The user can control error probability in two ways: via the PBS error probability and the global error probability.

The PBS error probability controls correctness locally (i.e., represents the error probability of a single PBS operation), while the global error probability focuses on the overall computation result (i.e., represents the error probability of the entire computation). These probabilities are related, and choosing which one to use may depend on the specific use case.

Efficiency

Efficiency decreases as more precision is required, e.g. 7-bits versus 8-bits. The larger the 2-norm is, the bigger the noise will be after a dot product. To remain below the noise bound, we must ensure that the inputs to the dot product have a sufficiently small noise level. The smaller this noise is, the slower the previous bootstrapping will be. Therefore, the larger the 2norm is, the slower the computation will be.

How are the parameters optimized

The optimization prioritizes security and correctness. This means that the security level (or the probability of correctness) could, in practice, be a bit higher than the level which is requested by the user.

In the simplest case, the optimizer performs an exhaustive search in the full parameter space and selects the best solution. While the space to explore is huge, exact lower bound cuts are used to avoid exploring regions which are guaranteed to not contain an optimal point. This makes the process both fast and exhaustive. This case is called mono-parameter, where all parameters are shared by the whole computation graph.

In more complex cases, the optimizer iteratively performs an exhaustive search, with lower bound cuts in a wide subspace of the full parameter space, until it converges to a locally optimal solution. Since the wide subspace is large and multi-dimensional, it should not be trapped in a poor locally optimal solution. The more complex case is called multi-parameter, where different calculus operations have tailored parameters.

How can I determine, understand, and explore crypto-parameters

One can have a look at for each security level (but for a given correctness). This provides insight between the calcululs content (i.e. maximum precision, maximum dot 2-norm, etc.,) and the cost.

Then one can manually explore crypto-parameters space using a .

Citing

If you use this tool in your work, please cite:

Bergerat, Loris and Boudi, Anas and Bourgerie, Quentin and Chillotti, Ilaria and Ligier, Damien and Orfila Jean-Baptiste and Tap, Samuel, Parameter Optimization and Larger Precision for (T)FHE, Journal of Cryptology, 2023, Volume 36

A pre-print is available as Cryptology ePrint Archive

Context

The concrete backends are implementations of the cryptographic primitives of the Zama variant of TFHE.

There are client features (private and public key generation, encryption and decryption) and server features (homomorphic operations on ciphertexts using public keys).

Considering that

• performance improvements are mostly beneficial for the server operations

• the client needs to be portable for the variety of clients that may exist, we expect mostly server backend to be added to the compiler to improve performance (e.g. by using specialized hardware)

What is needed in the server backend

The server backend should expose C or C++ functions to do TFHE operations using the current ciphertext and key memory representation (or functions to change representation). A backend can support only a subset of the current TFHE operations.

The most common operations one would be expected to add are WP-PBS (standard TFHE programmable bootstrap), keyswitch and WoP (without padding bootsrap).

Linear operations may also be supported but may need more work since their introduction may interfere with other compilation passes. The following example does not include this.

Concrete-cuda example

We will detail how concrete-cuda is integrated in the compiler. Adding a new server feature backend (for non linear operations) should be quite similar. However, if you want to integrate a backend but it does not fit with this description, please open an issue or contact us to discuss the integration.

In compilers/concrete-compiler/Makefile

• the variable CUDA_SUPPORT has been added and set to OFF (CUDA_SUPPORT?=OFF) by default

• the variables CUDA_SUPPORT and CUDA_PATH are passed to CMake

In compilers/concrete-compiler/compiler/include/concretelang/Runtime/context.h, the RuntimeContext struct is enriched with state to manage the backend ressources (behind a #ifdef CONCRETELANG_CUDA_SUPPORT).

In compilers/concrete-compiler/compiler/lib/Runtime/wrappers.cpp, the cuda backend server functions are added (behind a #ifdef CONCRETELANG_CUDA_SUPPORT)

The pass ConcreteToCAPI is modified to have a flag to insert calls to these new wrappers instead of the cpu ones (the code calling this pass is modified accordingly).

It may be possible to replace the cpu wrappers (with a compilation flag) instead of adding new ones to avoid having to change the pass.

In compilers/concrete-compiler/CMakeLists.txt a Section #Concrete Cuda Configuration has been added Other CMakeLists.txt have also been modified (or added) with if(CONCRETELANG_CUDA_SUPPORT) guard to handle header includes, linking...

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:

To select secure cryptographic parameters for usage in Concrete, we utilize the . In particular, we use the following workflow:

1. Data Acquisition

   • For a given value of we obtain raw data from the Lattice Estimator, which ultimately leads to a security level . All relevant attacks in the Lattice Estimator are considered.

Tracing dialect A dialect to print program values at runtime.

Operation definition

After doing a compilation, we endup with a couple of artifacts, including crypto parameters and a binary file containing the executable circuit. In order to be able to encrypt and run the circuit properly, we need to know how to interpret these artifacts, and there are a couple of utility functions to load them. These utility functions can be accessed through a variety of languages, including Python, Cpp, and Rust. (built on top of the ) can be a good example for someone who wants to build bindings for another language.

Calling from Rust

bindgen is used to generate Rust FFI bindings to the CAPI

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.

With scalars.

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

With tensors.

When you apply a table lookup to a tensor, the scalar table lookup is applied to each element of the tensor:

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:

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:

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:

The function is first traced into:

Concrete then fuses appropriate nodes:

Concrete analyzes all compiled circuits and calculates some statistics. These statistics can be used to find bottlenecks and compare circuits. Statistics are calculated in terms of basic operations. There are 6 basic operations in Concrete:

• clear addition: x + y where x is encrypted and y is clear

• encrypted addition: x + y where both x and y are encrypted

• clear multiplication: x * y where x is encrypted and y is clear

• encrypted negation: -x where x is encrypted

• key switch: building block for table lookups

• packing key switch: building block for table lookups

• programmable bootstrapping: building block for table lookups

You can print all statistics using show_statistics configuration option:

This code will print:

Tags

Circuit analysis also considers !

Imagine you have a neural network with 10 layers, each of them tagged. You can easily see the amount of additions and multiplications required for matrix multiplications per layer:

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:

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:

Concrete can be customized using Configurations:

from concrete import fhe
import numpy as np

configuration = fhe.Configuration(p_error=0.01, dataflow_parallelize=True)

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

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

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.

There are two main entry points to the Concrete Compiler. The first is to use the Concrete Python frontend. The second is to use the Compiler directly, which takes MLIR as input. Concrete Python is more high level and uses the Compiler under the hood.

Compilation begins in the frontend with tracing to get an easy-to-manipulate representation of the function. We call this representation a Computation Graph, which is a Directed Acyclic Graph (DAG) containing nodes representing computations done in the function. Working with graphs is useful because they have been studied extensively and there are a lot of available algorithms to manipulate them. Internally, we use networkx, which is an excellent graph library for Python.

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.

The Compiler takes MLIR code that makes use of both the FHE and FHELinalg for scalar and tensor operations respectively.

Compilation then ends with a series of that generates a native binary which contains executable code. Crypto parameters are generated along the way as well.

Tracing

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

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:

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.

We have allocated a whole new chapter to explaining fusing. You can find it .

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:

Evaluation result of 2:

• x: 2

• 2: 2

• *

New bounds:

• x: [2, 2]

• 2: [2, 2]

Evaluation result of 3:

• x: 3

• 2: 2

• *

New bounds:

• x: [2, 3]

• 2: [2, 2]

• *

Evaluation result of 1:

• x: 1

• 2: 2

• *

New bounds:

• x: [1, 3]

• 2: [2, 2]

• *

Assigned data types:

• x: EncryptedScalar<uint2>

• 2: ClearScalar<uint2>

• *

MLIR Compiler Passes

We describe below some of the main passes in the compilation pipeline.

FHE to TFHE

This pass converts high level operations which are not crypto specific to lower level operations from the TFHE scheme. Ciphertexts get introduced in the code as well. TFHE operations and ciphertexts require some parameters which need to be chosen, and the pass does just that.

TFHE Parameterization

TFHE Parameterization takes care of introducing the chosen parameters in the Intermediate Representation (IR). After this pass, you should be able to see the dimension of ciphertexts, as well as other parameters in the IR.

TFHE to Concrete

This pass lowers TFHE operations to low level operations that are closer to the backend implementation, working on tensors and memory buffers (after a bufferization pass).

Concrete to LLVM

This pass lowers everything to LLVM-IR in order to generate the final binary.

Dialect for the construction of static data flow graphs A dialect for the construction of static data flow graphs. The data flow graph is composed of a set of processes, connected through data streams. Special streams allow for data to be injected into and to be retrieved from the data flow graph.

Operation definition

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:

As explained in the , the challenge for developers is to adapt their code to fit FHE constraints. In this document we have collected some common examples to illustrate the kind of optimization one can do to get better performance.

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.

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:

prints:

Runtime dialect A dialect for representation the abstraction needed for the runtime.

Operation definition

RT.await_future (::mlir::concretelang::RT::AwaitFutureOp)

Wait for a future and access its data.

The results of a dataflow task are always futures which could be further used as inputs to subsequent tasks. When the result of a task is needed in the outer execution context, the result future needs to be synchronized and its data accessed using RT.await_future.

Operands:

Results:

RT.build_return_ptr_placeholder (::mlir::concretelang::RT::BuildReturnPtrPlaceholderOp)

Results:

RT.clone_future (::mlir::concretelang::RT::CloneFutureOp)

Interfaces: AllocationOpInterface, MemoryEffectOpInterface

Operands:

Results:

RT.create_async_task (::mlir::concretelang::RT::CreateAsyncTaskOp)

Create a dataflow task.

Attributes:

Operands:

RT.dataflow_task (::mlir::concretelang::RT::DataflowTaskOp)

Dataflow task operation

RT.dataflow_task allows to specify a task that will be concurrently executed when their operands are ready. Operands are either the results of computation in other RT.dataflow_task (dataflow dependences) or obtained from the execution context (immediate operands). Operands are synchronized using futures and, in the case of immediate operands, copied when the task is created. Caution is required when the operand is a pointer as no deep copy will occur.

Example:

Traits: AutomaticAllocationScope, SingleBlockImplicitTerminator

Interfaces: AllocationOpInterface, MemoryEffectOpInterface, RegionBranchOpInterface

Operands: