Concrete is natively supported on Linux and macOS from Python 3.8 to 3.10 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:

Using Docker

You can also get the Concrete docker image:

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)

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)

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)

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:

from concrete import fhe

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

inputset = range(2 ** 4)
circuit = f.compile(inputset)

is exactly the same as

from concrete import fhe

table = fhe.LookupTable([x ** 2 for x in range(2 ** 4)])

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

inputset = range(2 ** 4)
circuit = f.compile(inputset)

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.

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:

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

And you perform a Table Lookup using 4. The result you should get is 16, but because of the possibility of error, you can 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 How to Configure to learn how you can set a custom p_error and/or global_p_error.

Supported operations

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

Supported Python operators.

• __abs__

• __add__

• __and__

• __eq__

• __floordiv__

• __ge__

• __getitem__

• __gt__

• __invert__

• __le__

• __lshift__

• __lt__

• __matmul__

• __mod__

• __mul__

• __ne__

• __neg__

• __or__

• __pos__

• __pow__

• __radd__

• __rand__

• __rfloordiv__

• __rlshift__

• __rmatmul__

• __rmod__

• __rmul__

• __ror__

• __round__

• __rpow__

• __rrshift__

• __rshift__

• __rsub__

• __rtruediv__

• __rxor__

• __sub__

• __truediv__

• __xor__

Supported NumPy functions.

• np.absolute

• np.add

• np.arccos

• np.arccosh

• np.arcsin

• np.arcsinh

• np.arctan

• np.arctan2

• np.arctanh

• np.around

• np.bitwise_and

• np.bitwise_or

• np.bitwise_xor

• np.broadcast_to

• np.cbrt

• np.ceil

• np.clip

• np.concatenate

• np.copysign

• np.cos

• np.cosh

• np.deg2rad

• np.degrees

• np.dot

• np.equal

• np.exp

• np.exp2

• np.expand_dims

• np.expm1

• np.fabs

• np.float_power

• np.floor

• np.floor_divide

• np.fmax

• np.fmin

• np.fmod

• np.gcd

• np.greater

• np.greater_equal

• np.heaviside

• np.hypot

• np.invert

• np.isfinite

• np.isinf

• np.isnan

• np.lcm

• np.ldexp

• np.left_shift

• np.less

• np.less_equal

• np.log

• np.log10

• np.log1p

• np.log2

• np.logaddexp

• np.logaddexp2

• np.logical_and

• np.logical_not

• np.logical_or

• np.logical_xor

• np.matmul

• np.maximum

• np.minimum

• np.multiply

• np.negative

• np.nextafter

• np.not_equal

• np.ones_like

• np.positive

• np.power

• np.rad2deg

• np.radians

• np.reciprocal

• np.remainder

• np.reshape

• np.right_shift

• np.rint

• np.round_

• np.sign

• np.signbit

• np.sin

• np.sinh

• np.spacing

• np.sqrt

• np.square

• np.subtract

• np.sum

• np.tan

• np.tanh

• np.transpose

• np.true_divide

• np.trunc

• np.where

• np.zeros_like

Supported ndarray methods.

• np.ndarray.astype

• np.ndarray.clip

• np.ndarray.dot

• np.ndarray.flatten

• np.ndarray.reshape

• np.ndarray.transpose

Supported ndarray properties.

• np.ndarray.shape

• np.ndarray.ndim

• np.ndarray.size

• np.ndarray.T

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.

In this tutorial, we will review the ways 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 the table lookup to a tensor, you apply the scalar table lookup 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

In case 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 one.

Fused table lookup

Concrete tries to fuse some operations into table lookups automatically, so you don't need to create the lookup tables manually:

The function is first traced into:

Concrete then fuses appropriate nodes:

For some applications, 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 are not necessary, or even 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'll fail to get the negative value as the result will be fhe.uint8 as well)

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

• Specify the resulting data type in extension (e.g., fhe.univariate(function, outputs=fhe.uint4)(x)), for the same reason as above.

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

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

This prints:

Here is the breakdown of assigned data types:

As you can see, %8 is subtraction of two unsigned values, and it's unsigned as well. In an overflow condition where c > d, it results in undefined behavior.

Concrete supports native Python and NumPy operations as much as possible, but not everything is available in Python or NumPy. So, 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 encrypted scalar zero:

fhe.zeros(shape)

Allows you to create encrypted tensor of zeros:

fhe.one()

Allows you to create encrypted scalar one:

fhe.ones(shape)

Allows you to create encrypted tensor of ones:

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

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

Considering this, simulation is introduced:

After the simulation runs, it prints this:

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

Table lookups have a strict constraint on the number of bits they support. This can limiting, especially if you don't need exact precision.

To overcome this, a rounded table lookup operation is introduced. It's a way to extract the most significant bits of a large integer and then apply the table lookup to those bits.

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

In Python, evaluation will work like this:

During homomorphic execution, it'll be converted like this:

A modified table lookup would be applied to the resulting 5 bits.

If you want to apply ReLU to an 18-bit value., first look at the original ReLU:

The input range is [-100_000, 100_000), which means 18-bit table lookups are required, but they are not yet supported. You can apply a rounding operation to the input before passing it to the ReLU function:

We've removed the 10 least significant bits of the input and then applied the ReLU function to this value to get:

This is close enough to original ReLU for some cases. If your application is more flexible, you could remove more bits, let's say 12, to get:

This is very useful but, in some cases, you don't know how many bits your input contains, so it's not reliable to specify lsbs_to_remove manually. For this reason, AutoRounder class is introduced.

AutoRounders allow you to set how many of the most significant bits to keep, but they need to be adjusted using an inputset to determine how many of the least significant bits to remove. This can be done manually using fhe.AutoRounder.adjust(function, inputset), or by setting auto_adjust_rounders to True during compilation.

In this case, 6 of the most significant bits are kept to get:

You can adjust target_msbs depending on your requirements. If you set it to 4, you get:

Concrete partly supports floating points:

• They cannot be inputs

• They cannot be outputs

• They can be intermediate values under certain constraints

As intermediate values

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

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

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 , another 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 some:

This results in:

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.

In this section, you will learn how to debug the compilation process easily and get help in case 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

You can seek help with your issue by asking a question directly in the community forum.

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.

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 hello@zama.ai. Only approved contributors can send pull requests (PRs), so get in touch before you do.

Concrete generates keys for you implicitly when they are needed and if they are not generated already. 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:

from concrete import fhe

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

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

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:

circuit.keys.generate()

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

circuit.keys.generate(seed=420)

Serialization

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

serialized_keys: bytes = circuit.keys.serialize()

Deserialization

To deserialize the keys back, after receiving serialized keys:

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

Assignment

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

circuit.keys = keys

Saving

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

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

Loading

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

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

Automatic Management

Lastly, if you want to generate keys in the first run and reuse the keys in consecutive runs:

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

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

    • extensions: custom functionality (see Extensions)

    • mlir: computation graph to mlir conversion

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

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

Development of the circuit

You can develop your circuit like we've discussed in the previous chapters. Here is a simple example:

from concrete import fhe

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

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

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

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

Then, send server.zip to your computation server.

Setting up a server

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

from concrete import fhe

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

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:

serialized_client_specs: str = server.client_specs.serialize()

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:

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

Generating keys (on the client)

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

client.keys.generate()

This method generates encryption/decryption keys and evaluation keys.

The server requires evaluation keys linked to the encryption keys that you just generated. You can serialize your evaluation keys as shown:

serialized_evaluation_keys: bytes = client.evaluation_keys.serialize()

After serialization, send the evaluation keys to the server.

Encrypting inputs (on the client)

Now encrypt your inputs and request the server to perform the computation. You can do it like so:

serialized_args: bytes = client.encrypt(7).serialize()

Then, send serialized args to the server.

Performing computation (on the server)

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

deserialized_evaluation_keys = fhe.EvaluationKeys.deserialize(serialized_evaluation_keys)
deserialized_args  = server.client_specs.deserialize_public_args(serialized_args)

You can perform the computation, as well:

public_result = server.run(deserialized_args, deserialized_evaluation_keys)
serialized_public_result: bytes = public_result.serialize()

Then, send the serialized public result back to the client, so they can decrypt it and get the result of the computation.

Decrypting the result (on the client)

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

deserialized_public_result = client.specs.deserialize_public_result(serialized_public_result)

Then, decrypt the result:

result = client.decrypt(deserialized_public_result)
assert result == 49

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:

from concrete import fhe
import numpy as np

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

inputset = range(10)
circuit = f.compile(inputset, p_error=0.01, dataflow_parallelize=True)

Or you can combine both:

from concrete import fhe
import numpy as np

configuration = fhe.Configuration(p_error=0.01)

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

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

Options

• show_graph: Optional[bool] = None

  • Whether to 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

  • Whether to 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

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

• verbose: bool = False

  • Whether to print details related to compilation.

• dump_artifacts_on_unexpected_failures: bool = True

  • Whether to export debugging artifacts automatically on compilation failures.

• auto_adjust_rounders: bool = False

  • Whether to adjust rounders automatically.

• p_error: Optional[float] = None

  • Error probability for individual table lookups. If set, all table lookups will have the probability of a non-exact result smaller than the set value. See Exactness to learn more.

• global_p_error: Optional[float] = None

  • Global error probability for the whole circuit. If set, the whole circuit will have the probability of a non-exact result smaller than the set value. See Exactness to learn more.

• single_precision: bool = True

  • Whether to use single precision for the whole circuit.

• jit: bool = False

  • Whether to use JIT compilation.

• loop_parallelize: bool = True

  • Whether to enable loop parallelization in the compiler.

• dataflow_parallelize: bool = False

  • Whether to enable dataflow parallelization in the compiler.

• auto_parallelize: bool = False

  • Whether to enable auto parallelization in the compiler.

• enable_unsafe_features: bool = False

  • Whether to enable unsafe features.

• use_insecure_key_cache: bool = False (Unsafe)

  • Whether to use the insecure key cache.

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

  • Location of insecure key cache.

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.

Within fuse:

1. We loop until there are no more subgraphs to fuse.

2. Within each iteration: 2.1. We find a subgraph to fuse.

   2.2. We search for a terminal node that is appropriate for fusing.

   2.3. We crawl backwards to find the closest integer nodes to this node.

   2.4. If there is a single node as such, we return the subgraph from this node to the terminal node.

   2.5. Otherwise, we try to find the lowest common ancestor (lca) of this list of nodes.

   2.6. If an lca doesn't exist, we say this particular terminal node is not fusable, and we go back to search for another subgraph.

   2.7. Otherwise, we use this lca as the input of the subgraph and continue with subgraph node creation below.

   2.8. We convert the subgraph into a subgraph node by checking fusability status of the nodes of the subgraph in this step.

   2.9. We substitute the subgraph node to the original graph.

Limitations

With the current implementation, we cannot fuse subgraphs that depend on multiple encrypted values where those values don't have a common lca (e.g., np.round(np.sin(x) + np.cos(y))).

Compilation begins with tracing to get an easy-to-manipulate representation of the function. We call this representation a Computation Graph, which is basically a Directed Acyclic Graph (DAG) containing nodes representing computations done in the function. Working with graphs is good because they have been studied extensively and there are a lot of available algorithms to manipulate them. Internally, we use , 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 they will be discussed in their own sections. The result of transformations is just 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 currently allows limited precision for computations. Bound measurement helps determine the required precision for the function.

The final step is to transform the computation graph to equivalent MLIR code. Once the MLIR is generated, our Compiler backend compiles it down to native binaries.

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 after this chapter.

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, it 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

• *: 4

• 3: 3

• +: 7

New bounds:

• x: [2, 2]

• 2: [2, 2]

• *: [4, 4]

• 3: [3, 3]

• +: [7, 7]

Evaluation result of 3:

• x: 3

• 2: 2

• *: 6

• 3: 3

• +: 9

New bounds:

• x: [2, 3]

• 2: [2, 2]

• *: [4, 6]

• 3: [3, 3]

• +: [7, 9]

Evaluation result of 1:

• x: 1

• 2: 2

• *: 2

• 3: 3

• +: 5

New bounds:

• x: [1, 3]

• 2: [2, 2]

• *: [2, 6]

• 3: [3, 3]

• +: [5, 9]