From c777b4c225b7ba171ff2f0b206712e2b4f21af9f Mon Sep 17 00:00:00 2001 From: Benoit Chevallier-Mames Date: Wed, 17 Jul 2024 19:08:17 +0200 Subject: [PATCH] docs(frontend): massive modifications in the documentation refs #812 --- docs/SUMMARY.md | 13 +++++++------ docs/core-features/non_linear_operations.md | 2 +- docs/core-features/table_lookups.md | 4 ++-- docs/{get-started => dev}/compatibility.md | 14 -------------- docs/get-started/limitations.md | 13 +++++++++++++ docs/get-started/terminology.md | 3 +++ 6 files changed, 26 insertions(+), 23 deletions(-) rename docs/{get-started => dev}/compatibility.md (94%) create mode 100644 docs/get-started/limitations.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index b6aed9bad1..e4529e7ac6 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,15 +7,15 @@ * [What is Concrete?](get-started/readme.md) * [Installation](get-started/installing.md) * [Quick start](get-started/quick_start.md) -* [Compatibility](get-started/compatibility.md) +* [Limitations](get-started/limitations.md) * [Terminology](get-started/terminology.md) -## Core features +## Operations * [Overview](core-features/fhe_basics.md) -* [Table lookups (basics)](core-features/table_lookups.md) +* [Table Lookups basics](core-features/table_lookups.md) * [Non-linear operations](core-features/non_linear_operations.md) -* Advanced features +* Other operations * [Bit extraction](core-features/bit_extraction.md) * [Common tips](core-features/workarounds.md) * [Extensions](core-features/extensions.md) @@ -57,12 +57,13 @@ ## References * [API](dev/api/README.md) +* [Supported operations](dev/compatibility.md) ## Explanations * [Compiler workflow](dev/compilation/compiler_workflow.md) -* Compiler internals - * [Table lookups](core-features/table_lookups_advanced.md) +* Advanced features + * [Table Lookups advanced](core-features/table_lookups_advanced.md) * [Rounding](core-features/rounding.md) * [Truncating](core-features/truncating.md) * [Floating points](core-features/floating_points.md) diff --git a/docs/core-features/non_linear_operations.md b/docs/core-features/non_linear_operations.md index c065abc397..65ddebf71a 100644 --- a/docs/core-features/non_linear_operations.md +++ b/docs/core-features/non_linear_operations.md @@ -7,7 +7,7 @@ In Concrete, there are basically two types of operations: TLU are essential to be able to compile all functions, by keeping the semantic of user's program, but they can be slower, depending on the bitwidth of the inputs of the TLU. -In this document, we explain briefly, from a user point of view, how it works for non-linear operations as comparisons, min/max, bitwise operations, shifts. In [the poweruser documentation](table_lookups_advanced.md), we enter a bit more into the details. +In this document, we explain briefly, from a user point of view, how it works for non-linear operations as comparisons, min/max, bitwise operations, shifts. In [the TLU advanced documentation](table_lookups_advanced.md), we enter a bit more into the details. ## Changing bit width in the MLIR or dynamically with a TLU diff --git a/docs/core-features/table_lookups.md b/docs/core-features/table_lookups.md index 973b76b0e2..d701caac45 100644 --- a/docs/core-features/table_lookups.md +++ b/docs/core-features/table_lookups.md @@ -1,6 +1,6 @@ # Table lookup -In TFHE, there exists mainly two operations: the linear operations (additions, subtractions, multiplications by integers) and the rest. And the rest is done with table lookups (TLUs), which means that a lot of things are done with TLU. In this document, we explain briefly, from a user point of view, how TLU can be used. In [the poweruser documentation](table_lookups_advanced.md), we enter a bit more into the details. +In TFHE, there exists mainly two operations: the linear operations (additions, subtractions, multiplications by integers) and the rest. And the rest is done with table lookups (TLUs), which means that a lot of things are done with TLU. In this document, we explain briefly, from a user point of view, how TLU can be used. In [the TLU advanced documentation](table_lookups_advanced.md), we enter a bit more into the details. ## Performance @@ -133,7 +133,7 @@ As we said in the beginning of this document, bitsize of the inputs of TLU are c For lot of use-cases, like for example in Machine Learning, it is possible to replace the table lookup `y = T[i]` by some `y = T'[i']`, where `i'` only has the most significant bits of `i` and `T'` is a much shorter table, and still maintain a good accuracy of the function. The interest of such a method stands in the fact that, since the table `T'` is much smaller, the corresponding TLU will be done much more quickly. -There are different flavors of doing this in Concrete. We describe them quickly here, and refer the user to the [poweruser documentation](table_lookups_advanced.md) for more explanations. +There are different flavors of doing this in Concrete. We describe them quickly here, and refer the user to the [TLU advanced documentation](table_lookups_advanced.md) for more explanations. The first possibility is to set `i'` as the truncation of `i`: here, we just take the most significant bits of `i`. This is done with `fhe.truncate_bit_pattern`. diff --git a/docs/get-started/compatibility.md b/docs/dev/compatibility.md similarity index 94% rename from docs/get-started/compatibility.md rename to docs/dev/compatibility.md index 8c9132aa33..cdbe580617 100644 --- a/docs/get-started/compatibility.md +++ b/docs/dev/compatibility.md @@ -161,17 +161,3 @@ Some operations are not supported between two encrypted values. If attempted, a * [np.ndarray.ndim](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.ndim.html) * [np.ndarray.size](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.size.html) * [np.ndarray.T](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.T.html) - -## Limitations - -### Control flow constraints - -Concrete doesn not support some control flow statements, including the `if` and `while` statement when the condition depends on an encrypted value. However, control flow statements with constant values are allowed, for example, `for i in range(SOME_CONSTANT)`, `if os.environ.get("SOME_FEATURE") == "ON":`. - -### Type constraints - -Floating-point inputs or floating-point outputs are not supported. You can have floating-point intermediate values as long as they can be converted to an integer Table Lookup, for example, `(60 * np.sin(x)).astype(np.int64)`. - -### Bit width constraints - -Bit width of encrypted values has a limit. We are constantly working on increasing the bit width limit. Exceeding this limit will trigger an error. diff --git a/docs/get-started/limitations.md b/docs/get-started/limitations.md new file mode 100644 index 0000000000..3b2ebc4800 --- /dev/null +++ b/docs/get-started/limitations.md @@ -0,0 +1,13 @@ +# Limitations +This document outlines the current limitations of Concrete, concerning the control flow constraints, the encrypted type constraints, and the bit width constraints of encrypted values. +## Control flow constraints + +Concrete doesn not support some control flow statements, including the `if` and `while` statement when the condition depends on an encrypted value. However, control flow statements with constant values are allowed, for example, `for i in range(SOME_CONSTANT)`, `if os.environ.get("SOME_FEATURE") == "ON":`. + +## Type constraints + +Floating-point inputs or floating-point outputs are not supported. You can have floating-point intermediate values as long as they can be converted to an integer Table Lookup, for example, `(60 * np.sin(x)).astype(np.int64)`. + +## Bit width constraints + +Bit width of encrypted values has a limit. We are constantly working on increasing the bit width limit. Exceeding this limit will trigger an error. diff --git a/docs/get-started/terminology.md b/docs/get-started/terminology.md index 2816c4eda8..6e3fa97e65 100644 --- a/docs/get-started/terminology.md +++ b/docs/get-started/terminology.md @@ -10,3 +10,6 @@ This document provides clear definitions of key concepts used in **Concrete** fr * **Circuit:** The result of compilation. A circuit includes both client and server components. It has methods for various operations, such as printing and evaluation. +* **Table Lookup (TLU):** TLU stands for instructions in the form of y = T[i]. In FHE, this operation is performed with Programmable Bootstrapping, which is the equivalent operation on encrypted values." + +* **Programmable Bootstrapping (PBS):** PBS is equivalent to table lookup `y = T[i]` on encrypted values, which means that the inputs `i` and the outputs `y` are encrypted, but the table `T` is not encrypted.