From 0157734473f02b8a24a60c48d3eb857f09b5ccce Mon Sep 17 00:00:00 2001 From: yuxizama <157474013+yuxizama@users.noreply.github.com> Date: Tue, 14 May 2024 16:11:27 +0200 Subject: [PATCH] docs(frontend): language edits --- docs/get-started/compatibility.md | 16 ++++++------- docs/get-started/installing.md | 16 +++++++------ docs/get-started/quick_start.md | 37 ++++++++++++++++++------------- docs/get-started/readme.md | 9 ++++---- docs/get-started/terminology.md | 13 ++++++----- 5 files changed, 51 insertions(+), 40 deletions(-) diff --git a/docs/get-started/compatibility.md b/docs/get-started/compatibility.md index b3489d84c..8c9132aa3 100644 --- a/docs/get-started/compatibility.md +++ b/docs/get-started/compatibility.md @@ -2,10 +2,10 @@ ## Supported operations -Here are the operations you can use inside the function you are compiling: +This document lists the operations you can use inside the function that you are compiling. {% hint style="info" %} -Some of these operations are not supported between two encrypted values. A detailed error will be raised if you try to do something that is not supported. +Some operations are not supported between two encrypted values. If attempted, a detailed error message will be raised. {% endhint %} ### Supported Python operators. @@ -164,14 +164,14 @@ Some of these operations are not supported between two encrypted values. A detai ## Limitations -### Control flow constraints. +### 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":`). +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. +### 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)`). +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 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. +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/installing.md b/docs/get-started/installing.md index aca1053e3..d5df595e3 100644 --- a/docs/get-started/installing.md +++ b/docs/get-started/installing.md @@ -1,10 +1,12 @@ # Installation -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. +This document explains the steps to install **Concrete** into your project. + +**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: +Install **Concrete** from PyPI using the following commands: ```shell pip install -U pip wheel setuptools @@ -14,7 +16,7 @@ pip install concrete-python Not all versions are available on PyPI. If you need a version that is not on PyPI (including nightly releases), you can install it from our package index by adding `--extra-index-url https://pypi.zama.ai`. {% endhint %} -There are some optional features which can be enabled by installing the `full` version: +To enable all the optional features, install the `full` version of **Concrete**: ```shell pip install -U pip wheel setuptools @@ -22,13 +24,13 @@ pip install concrete-python[full] ``` {% hint style="info" %} -Full version depends on [pygraphviz](https://pygraphviz.github.io/), which needs [graphviz](https://graphviz.org/) to be installed in the operating system so please [install](https://pygraphviz.github.io/documentation/stable/install.html) the operating system dependencies before installing `concrete-python[full]`. +The full version requires [pygraphviz](https://pygraphviz.github.io/), which depends on [graphviz](https://graphviz.org/). Make sure to [install](https://pygraphviz.github.io/documentation/stable/install.html) all the dependencies on your operating system before installing `concrete-python[full]`. {% endhint %} {% hint style="info" %} -Installing `pygraphviz` on macOS can be problematic (see https://github.com/pygraphviz/pygraphviz/issues/11). +Installing `pygraphviz` on macOS can be problematic (see more details [here](https://github.com/pygraphviz/pygraphviz/issues/11)). -If you're using homebrew, you may try the following: +If you're using homebrew, you can try the following way: ```shell brew install graphviz CFLAGS=-I$(brew --prefix graphviz)/include LDFLAGS=-L$(brew --prefix graphviz)/lib pip --no-cache-dir install pygraphviz @@ -41,7 +43,7 @@ pip install concrete-python[full] ## Using Docker -You can also get the Concrete docker image (replace "v2.4.0" below by the correct version you want): +You can also get the **Concrete** docker image. Replace `v2.4.0` below by the version you want to install: ```shell docker pull zamafhe/concrete-python:v2.4.0 diff --git a/docs/get-started/quick_start.md b/docs/get-started/quick_start.md index b0b9ddfa7..7befe5fee 100644 --- a/docs/get-started/quick_start.md +++ b/docs/get-started/quick_start.md @@ -1,8 +1,14 @@ # Quick Start -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. +This document covers how to compute on encrypted data homomorphically using the **Concrete** framework. We will walk you through a complete example step-by-step. -Here is the full example that we will walk through: + +The basic workflow of computation is as follows: +1. Define the function you want to compute +2. Compile the function into a Concrete `Circuit` +3. Use the `Circuit` to perform homomorphic evaluation + +Here is the complete example, which we will explain step by step in the following paragraphs. ```python from concrete import fhe @@ -30,7 +36,7 @@ assert result == add(2, 6) ## Importing the library -Everything you need to perform homomorphic evaluation is included in a single module: +Import the `fhe` module, which includes everything you need to perform homomorphic evaluation: ```python @@ -39,7 +45,7 @@ from concrete import fhe ## Defining the function to compile -In this example, we compile a simple addition function: +Here we define a simple addition function: ```python @@ -49,14 +55,14 @@ def add(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: +To compile the function, you first need to create a `Compiler` by specifying the function to compile and the encryption status of its inputs: ```python compiler = fhe.Compiler(add, {"x": "encrypted", "y": "encrypted"}) ``` -To set that e.g. `y` is in the clear, it would be +For instance, to set the input y as clear: ```python @@ -65,29 +71,30 @@ 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. +An inputset is a collection representing the typical inputs of the function. It is used to determine the bit widths and shapes of the variables within the function. -It should be in iterable, yielding tuples, of the same length as the number of arguments of the function being compiled: +The inputset should be an iterable that yields tuples of the same length as the number of arguments of the compiled function. + +For example: ```python inputset = [(2, 3), (0, 0), (1, 6), (7, 7), (7, 1), (3, 2), (6, 1), (1, 7), (4, 5), (5, 4)] ``` -Here, our inputset is made of 10 pairs of integers, whose the minimum pair is `(0, 0)` and the maximum is `(7, 7)`. +Here, our inputset consists of 10 integer pairs, ranging from a minimum of `(0, 0)` to a maximum of `(7, 7)`. {% hint style="warning" %} -Choosing a representative inputset is critical to allow the compiler to find accurate bounds of all the intermediate values (find more details [here](https://docs.zama.ai/concrete/explanations/compilation#bounds-measurement). Later if you evaluate the circuit with values that make under or overflows it results to an undefined behavior. +Choosing a representative inputset is critical to allow the compiler to find accurate bounds of all the intermediate values (see more details [here](https://docs.zama.ai/concrete/explanations/compilation#bounds-measurement)). Evaluating the circuit with input values under or over the bounds may result in undefined behavior. {% endhint %} {% hint style="warning" %} -There is a utility function called `fhe.inputset(...)` for easily creating random inputsets, see its -[documentation](../core-features/extensions.md#fheinputset) to learn more! +You can use the `fhe.inputset(...)` function to easily create random inputsets, see more details in [this documentation](../core-features/extensions.md#fheinputset). {% endhint %} ## Compiling the function -You can use the `compile` method of the `Compiler` class with an inputset to perform the compilation and get the resulting circuit back: +Use the `compile` method of the `Compiler` class with an inputset to perform the compilation and get the resulting circuit: ```python @@ -97,7 +104,7 @@ circuit = compiler.compile(inputset) ## Generating the keys -You can use the `keygen` method of the `Circuit` class to generate the keys (public and private): +Use the `keygen` method of the `Circuit` class to generate the keys (public and private): ```python @@ -106,7 +113,7 @@ circuit.keygen() ``` {% hint style="info" %} -If you don't call the key generation explicitly keys will be generated lazily when it needed. +If you don't call the key generation explicitly, keys will be generated lazily when needed. {% endhint %} ## Performing homomorphic evaluation diff --git a/docs/get-started/readme.md b/docs/get-started/readme.md index 43354f67e..75da31f89 100644 --- a/docs/get-started/readme.md +++ b/docs/get-started/readme.md @@ -2,10 +2,11 @@
-**Concrete** is an open source framework which simplifies the use of Fully Homomorphic Encryption (FHE). +**Concrete** is an open source framework that simplifies the use of Fully Homomorphic Encryption (FHE). -Fully Homomorphic Encryption (FHE) enables performing computations on encrypted data directly without the need to decrypt it first. FHE allows developers to build services that ensure privacy for all users. FHE is also an excellent solution against data breaches as everything is performed on encrypted data. Even if the server is compromised, no sensitive data will be leaked. +FHE is a powerful technology that enables computations on encrypted data without needing to decrypt it. This capability ensures user privacy and provides robust protection against data breaches, as operations are performed on encrypted data, keeping sensitive information secure even if the server is compromised. -Since writing FHE programs is difficult, the Concrete framework contains a TFHE Compiler based on [LLVM](https://en.wikipedia.org/wiki/LLVM) to make this process easier for developers. +The **Concrete** framework makes writing FHE programs easy for developers by incorporating a Fully Homomorphic Encryption over the Torus (TFHE) Compiler based on [LLVM](https://en.wikipedia.org/wiki/LLVM). -Concrete is a versatile library that can be used for a variety of purposes. For instance, [Concrete ML](https://github.com/zama-ai/concrete-ml) is built on top of Concrete to simplify Machine-Learning oriented use cases. + +**Concrete** enables developers to efficiently develop privacy-preserving applications for various use cases. For instance, [Concrete ML](https://github.com/zama-ai/concrete-ml) is built on top of Concrete to integrate privacy-preserving features of FHE into machine learning use cases. diff --git a/docs/get-started/terminology.md b/docs/get-started/terminology.md index 5787c45eb..2816c4eda 100644 --- a/docs/get-started/terminology.md +++ b/docs/get-started/terminology.md @@ -1,11 +1,12 @@ # Terminology and Structure -## Terminology +This document provides clear definitions of key concepts used in **Concrete** framework. -Some terms used throughout the project include: +* **Computation graph:** A data structure to represent a computation. It takes the form of a directed acyclic graph where nodes represent inputs, constants, or operations. -* **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. +* **Tracing:** A method that takes a Python function provided by the user and generates a corresponding computation graph. + +* **Bounds:** The minimum and the maximum value that each node in the computation graph can take. Bounds are used to determine the appropriate data type (for example, uint3 or int5) for each node before the computation graphs are converted to MLIR. **Concrete** simulates the graph with the inputs in the inputset to record the minimum and the maximum value for each node. + +* **Circuit:** The result of compilation. A circuit includes both client and server components. It has methods for various operations, such as printing and evaluation.