| What is Concrete ML | getstarted1.jpg | getting-started |
| Installation | getstarted2.jpg | pip_installing.md |
| Key concepts | getstarted3.jpg | concepts.md |
| Fundamentals | Explore core features and basics of Concrete ML. | fundamentals.jpg | ||
| Guides | Discover essential guides to work with Concrete ML. | guides.jpg | ||
| Tutorials | Learn more about Concrete ML with our tutorials. | tutorials.jpg |
Quantization aware training example](../advanced_examples/QuantizationAwareTraining.ipynb)
-
-This shows how to use Quantization Aware Training and pruning when starting out from a classical PyTorch network. This example uses a simple data-set and a small NN, which achieves good accuracy with low accumulator size.
-
-### 2. Custom convolutional NN on the [Digits](https://scikit-learn.org/stable/modules/generated/sklearn.datasets.load_digits.html) data-set
-
-[ Convolutional Neural Network](../advanced_examples/ConvolutionalNeuralNetwork.ipynb)
-
-Following the [Step-by-step guide](fhe_friendly_models.md), this notebook implements a Quantization Aware Training convolutional neural network on the MNIST data-set. It uses 3-bit weights and activations, giving a 7-bit accumulator.
diff --git a/docs/deep-learning/fhe_assistant.md b/docs/deep-learning/fhe_assistant.md
index 12a3111d8..924ab2de6 100644
--- a/docs/deep-learning/fhe_assistant.md
+++ b/docs/deep-learning/fhe_assistant.md
@@ -1,15 +1,14 @@
-# Debugging Models
+# Debugging models
-This section provides a set of tools and guidelines to help users build optimized FHE-compatible models. It discusses
-FHE simulation, the key-cache functionality that helps speed-up FHE result debugging, and gives a guide to evaluate circuit complexity.
+This section provides a set of tools and guidelines to help users build optimized FHE-compatible models. It discusses FHE simulation, the key-cache functionality that helps speed-up FHE result debugging, and gives a guide to evaluate circuit complexity.
## Simulation
-The [simulation functionality](../advanced-topics/compilation.md#fhe-simulation) of Concrete ML provides a way to evaluate, using clear data, the results that ML models produce on encrypted data. The simulation includes any probabilistic behavior FHE may induce. The simulation is implemented with [Concrete's simulation](https://docs.zama.ai/concrete/tutorials/simulation).
+The [simulation functionality](../explanations/compilation.md#fhe-simulation) of Concrete ML provides a way to evaluate, using clear data, the results that ML models produce on encrypted data. The simulation includes any probabilistic behavior FHE may induce. The simulation is implemented with [Concrete's simulation](https://docs.zama.ai/concrete/tutorials/simulation).
The simulation mode can be useful when developing and iterating on an ML model implementation. As FHE non-linear models work with integers up to 16 bits, with a trade-off between the number of bits and the FHE execution speed, the simulation can help to find the optimal model design.
-Simulation is much faster than FHE execution. This allows for faster debugging and model optimization. For example, this was used for the red/blue contours in the [Classifier Comparison notebook](../built-in-models/ml_examples.md), as computing in FHE for the whole grid and all the classifiers would take significant time.
+Simulation is much faster than FHE execution. This allows for faster debugging and model optimization. For example, this was used for the red/blue contours in the [Classifier Comparison notebook](../tutorials/ml_examples.md), as computing in FHE for the whole grid and all the classifiers would take significant time.
The following example shows how to use the simulation mode in Concrete ML.
@@ -32,8 +31,7 @@ y_preds_clear = concrete_clf.predict(X, fhe="simulate")
## Caching keys during debugging
-It is possible to avoid re-generating the keys of the models you are debugging. This feature is unsafe and
-should not be used in production. Here is an example that shows how to enable key-caching:
+It is possible to avoid re-generating the keys of the models you are debugging. This feature is unsafe and should not be used in production. Here is an example that shows how to enable key-caching:
```python
from sklearn.datasets import fetch_openml, make_circles
@@ -116,13 +114,13 @@ Function you are trying to compile cannot be compiled:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ this 17-bit value is used as an input to a table lookup
```
-The error `this 17-bit value is used as an input to a table lookup` indicates that the 16-bit limit on the input of the Table Lookup (TLU) operation has been exceeded. To pinpoint the model layer that causes the error, Concrete ML provides the [bitwidth_and_range_report](../developer-guide/api/concrete.ml.quantization.quantized_module.md#method-bitwidth_and_range_report) helper function. First, the model must be compiled so that it can be [simulated](#simulation).
+The error `this 17-bit value is used as an input to a table lookup` indicates that the 16-bit limit on the input of the Table Lookup (TLU) operation has been exceeded. To pinpoint the model layer that causes the error, Concrete ML provides the [bitwidth_and_range_report](../references/api/concrete.ml.quantization.quantized_module.md#method-bitwidth_and_range_report) helper function. First, the model must be compiled so that it can be [simulated](fhe_assistant.md#simulation).
### Fixing compilation errors
To make this network FHE-compatible one can apply several techniques:
-1. use [rounded accumulators](../advanced-topics/advanced_features.md#rounded-activations-and-quantizers) by specifying the `rounding_threshold_bits` parameter. Please evaluate the accuracy of the model using simulation if you use this feature, as it may impact accuracy. Setting a value 2-bit higher than the quantization `n_bits` should be a good start.
+1. use [rounded accumulators](../explanations/advanced_features.md#rounded-activations-and-quantizers) by specifying the `rounding_threshold_bits` parameter. Please evaluate the accuracy of the model using simulation if you use this feature, as it may impact accuracy. Setting a value 2-bit higher than the quantization `n_bits` should be a good start.
@@ -151,7 +149,7 @@ quantized_numpy_module = compile_torch_model(
)
```
-3. adjust the tolerance for one-off errors using the `p_error` parameter. See [this section for more explanation](../advanced-topics/advanced_features.md#approximate-computations) on this tolerance.
+3. adjust the tolerance for one-off errors using the `p_error` parameter. See [this section for more explanation](../explanations/advanced_features.md#approximate-computations) on this tolerance.
diff --git a/docs/deep-learning/fhe_friendly_models.md b/docs/deep-learning/fhe_friendly_models.md
index 1c7cd5929..5baee76fe 100644
--- a/docs/deep-learning/fhe_friendly_models.md
+++ b/docs/deep-learning/fhe_friendly_models.md
@@ -1,18 +1,18 @@
-# Step-by-step Guide
+# Step-by-step guide
This guide provides a complete example of converting a PyTorch neural network into its FHE-friendly, quantized counterpart. It focuses on Quantization Aware Training a simple network on a synthetic data-set.
In general, quantization can be carried out in two different ways: either during Quantization Aware Training (QAT) or after the training phase with Post-Training Quantization (PTQ).
-Regarding FHE-friendly neural networks, QAT is the best way to reach optimal accuracy under [FHE constraints](../README.md#current-limitations). This technique allows weights and activations to be reduced to very low bit-widths (e.g., 2-3 bits), which, combined with pruning, can keep accumulator bit-widths low.
+Regarding FHE-friendly neural networks, QAT is the best way to reach optimal accuracy under [FHE constraints](../getting-started/README.md#current-limitations). This technique allows weights and activations to be reduced to very low bit-widths (e.g., 2-3 bits), which, combined with pruning, can keep accumulator bit-widths low.
Concrete ML uses the third-party library [Brevitas](https://github.com/Xilinx/brevitas) to perform QAT for PyTorch NNs, but options exist for other frameworks such as Keras/Tensorflow.
-Several [demos and tutorials](../getting-started/showcase.md) that use Brevitas are available in the Concrete ML library, such as the [CIFAR classification tutorial](../../use_case_examples/cifar/cifar_brevitas_finetuning/CifarQuantizationAwareTraining.ipynb).
+Several [demos and tutorials](../tutorials/showcase.md) that use Brevitas are available in the Concrete ML library, such as the [CIFAR classification tutorial](../../use_case_examples/cifar/cifar_brevitas_finetuning/CifarQuantizationAwareTraining.ipynb).
This guide is based on a [notebook tutorial](../advanced_examples/QuantizationAwareTraining.ipynb), from which some code blocks are documented.
-For a more formal description of the usage of Brevitas to build FHE-compatible neural networks, please see the [Brevitas usage reference](../developer-guide/external_libraries.md#brevitas).
+For a more formal description of the usage of Brevitas to build FHE-compatible neural networks, please see the [Brevitas usage reference](../explanations/inner-workings/external_libraries.md#brevitas).
{% hint style="info" %}
For a formal explanation of the mechanisms that enable FHE-compatible neural networks, please see the the following paper.
@@ -51,7 +51,7 @@ class SimpleNet(nn.Module):
The [notebook tutorial](../advanced_examples/QuantizationAwareTraining.ipynb), example shows how to train a FCNN, similarly to the one above, on a synthetic 2D data-set with a checkerboard grid pattern of 100 x 100 points. The data is split into 9500 training and 500 test samples.
-Once trained, this PyTorch network can be imported using the [`compile_torch_model`](../developer-guide/api/concrete.ml.torch.compile.md#function-compile_torch_model) function. This function uses simple PTQ.
+Once trained, this PyTorch network can be imported using the [`compile_torch_model`](../references/api/concrete.ml.torch.compile.md#function-compile_torch_model) function. This function uses simple PTQ.
The network was trained using different numbers of neurons in the hidden layers, and quantized using 3-bits weights and activations. The mean accumulator size shown below is measured as the mean over 10 runs of the experiment. An accumulator of 6.6 means that 4 times out of 10 the accumulator measured was 6 bits while 6 times it was 7 bits.
@@ -69,7 +69,7 @@ Accumulator size is determined by Concrete as being the maximum bit-width encoun
## Quantization Aware Training:
-[Quantization Aware Training](../advanced-topics/quantization.md) using [Brevitas](https://github.com/Xilinx/brevitas) is the best way to guarantee a good accuracy for Concrete ML compatible neural networks.
+[Quantization Aware Training](../explanations/quantization.md) using [Brevitas](https://github.com/Xilinx/brevitas) is the best way to guarantee a good accuracy for Concrete ML compatible neural networks.
Brevitas provides a quantized version of almost all PyTorch layers (`Linear` layer becomes `QuantLinear`, `ReLU` layer becomes `QuantReLU` and so on), plus some extra quantization parameters, such as :
@@ -177,7 +177,7 @@ By default, Concrete ML uses symmetric quantization for model weights, with valu
In a typical setting, the weights will not all have the maximum or minimum values (e.g., $$-2^{n_{bits}-1}$$). Weights typically have a normal distribution around 0, which is one of the motivating factors for their symmetric quantization. A symmetric distribution and many zero-valued weights are desirable because opposite sign weights can cancel each other out and zero weights do not increase the accumulator size.
-This fact can be leveraged to train a network with more neurons, while not overflowing the accumulator, using a technique called [pruning](../advanced-topics/pruning.md) where the developer can impose a number of zero-valued weights. Torch [provides support for pruning](https://pytorch.org/tutorials/intermediate/pruning_tutorial.html) out of the box.
+This fact can be leveraged to train a network with more neurons, while not overflowing the accumulator, using a technique called [pruning](../explanations/pruning.md) where the developer can impose a number of zero-valued weights. Torch [provides support for pruning](https://pytorch.org/tutorials/intermediate/pruning_tutorial.html) out of the box.
The following code shows how to use pruning in the previous example:
diff --git a/docs/deep-learning/optimizing_inference.md b/docs/deep-learning/optimizing_inference.md
index 98d030f9a..496ad9937 100644
--- a/docs/deep-learning/optimizing_inference.md
+++ b/docs/deep-learning/optimizing_inference.md
@@ -1,26 +1,21 @@
-# Optimizing inference latency
+# Optimizing inference
-Neural networks pose unique challenges with regards to encrypted inference. Each neuron in a network applies an activation function that requires a PBS operation. The latency
-of a single PBS depends on the bit-width of the input of the PBS.
+Neural networks pose unique challenges with regards to encrypted inference. Each neuron in a network applies an activation function that requires a PBS operation. The latency of a single PBS depends on the bit-width of the input of the PBS.
Several approaches can be used to reduce the overall latency of a neural network.
## Circuit bit-width optimization
-[Quantization Aware Training](../advanced-topics/quantization.md) and [pruning](../advanced-topics/pruning.md) introduce specific hyper-parameters that influence the accumulator sizes.
-It is possible to chose quantization and pruning configurations that reduce the accumulator size. A trade-off between latency and accuracy can be obtained by varying these hyper-parameters as described in the [deep learning design guide](torch_support.md#configuring-quantization-parameters).
+[Quantization Aware Training](../explanations/quantization.md) and [pruning](../explanations/pruning.md) introduce specific hyper-parameters that influence the accumulator sizes. It is possible to chose quantization and pruning configurations that reduce the accumulator size. A trade-off between latency and accuracy can be obtained by varying these hyper-parameters as described in the [deep learning design guide](torch_support.md#configuring-quantization-parameters).
## Structured pruning
-While un-structured pruning is used to ensure the accumulator bit-width stays low, [structured pruning](https://pytorch.org/docs/stable/generated/torch.nn.utils.prune.ln_structured.html) can eliminate entire neurons from the network. Many neural networks are over-parametrized (since this enables easier training) and some neurons can be removed. Structured pruning, applied to a trained network as a fine-tuning step, can be applied to built-in neural networks using the [prune](../developer-guide/api/concrete.ml.sklearn.base.md#method-prune) helper function as shown in [this example](../advanced_examples/FullyConnectedNeuralNetworkOnMNIST.ipynb). To apply structured pruning to
-custom models, it is recommended to use the [torch-pruning](https://github.com/VainF/Torch-Pruning) package.
+While un-structured pruning is used to ensure the accumulator bit-width stays low, [structured pruning](https://pytorch.org/docs/stable/generated/torch.nn.utils.prune.ln_structured.html) can eliminate entire neurons from the network. Many neural networks are over-parametrized (since this enables easier training) and some neurons can be removed. Structured pruning, applied to a trained network as a fine-tuning step, can be applied to built-in neural networks using the [prune](../references/api/concrete.ml.sklearn.base.md#method-prune) helper function as shown in [this example](../advanced_examples/FullyConnectedNeuralNetworkOnMNIST.ipynb). To apply structured pruning to custom models, it is recommended to use the [torch-pruning](https://github.com/VainF/Torch-Pruning) package.
## Rounded activations and quantizers
-Reducing the bit-width of the inputs to the Table Lookup (TLU) operations is a major source of improvements in the latency. Post-training,
-it is possible to leverage some properties of the fused activation and quantization functions expressed in the TLUs to
-further reduce the accumulator. This is achieved through the _rounded PBS_ feature as described in the [rounded activations and quantizers reference](../advanced-topics/advanced_features.md#rounded-activations-and-quantizers). Adjusting the rounding amount, relative to the initial accumulator size, can bring large improvements in latency while maintaining accuracy.
+Reducing the bit-width of the inputs to the Table Lookup (TLU) operations is a major source of improvements in the latency. Post-training, it is possible to leverage some properties of the fused activation and quantization functions expressed in the TLUs to further reduce the accumulator. This is achieved through the _rounded PBS_ feature as described in the [rounded activations and quantizers reference](../explanations/advanced_features.md#rounded-activations-and-quantizers). Adjusting the rounding amount, relative to the initial accumulator size, can bring large improvements in latency while maintaining accuracy.
## TLU error tolerance adjustment
-Finally, the TFHE scheme exposes a TLU error tolerance parameter that has an impact on crypto-system parameters that influence latency. A higher tolerance of TLU off-by-one errors results in faster computations but may reduce accuracy. One can think of the error of obtaining $$T[x]$$ as a Gaussian distribution centered on $$x$$: $$TLU[x]$$ is obtained with probability of `1 - p_error`, while $$T[x-1]$$, $$T[x+1]$$ are obtained with much lower probability, etc. In Deep NNs, these type of errors can be tolerated up to some point. See the [`p_error` documentation for details](../advanced-topics/advanced_features.md#approximate-computations) and more specifically the usage example of [the API for finding the best `p_error`](../advanced-topics/advanced_features.md#searching-for-the-best-error-probability).
+Finally, the TFHE scheme exposes a TLU error tolerance parameter that has an impact on crypto-system parameters that influence latency. A higher tolerance of TLU off-by-one errors results in faster computations but may reduce accuracy. One can think of the error of obtaining $$T[x]$$ as a Gaussian distribution centered on $$x$$: $$TLU[x]$$ is obtained with probability of `1 - p_error`, while $$T[x-1]$$, $$T[x+1]$$ are obtained with much lower probability, etc. In Deep NNs, these type of errors can be tolerated up to some point. See the [`p_error` documentation for details](../explanations/advanced_features.md#approximate-computations) and more specifically the usage example of [the API for finding the best `p_error`](../explanations/advanced_features.md#searching-for-the-best-error-probability).
diff --git a/docs/deep-learning/torch_support.md b/docs/deep-learning/torch_support.md
index ebcae62dd..d63754114 100644
--- a/docs/deep-learning/torch_support.md
+++ b/docs/deep-learning/torch_support.md
@@ -2,12 +2,12 @@
In addition to the built-in models, Concrete ML supports generic machine learning models implemented with Torch, or [exported as ONNX graphs](onnx_support.md).
-As [Quantization Aware Training (QAT)](../advanced-topics/quantization.md) is the most appropriate method of training neural networks that are compatible with [FHE constraints](../getting-started/concepts.md#model-accuracy-considerations-under-fhe-constraints), Concrete ML works with [Brevitas](../developer-guide/external_libraries.md#brevitas), a library providing QAT support for PyTorch.
+As [Quantization Aware Training (QAT)](../explanations/quantization.md) is the most appropriate method of training neural networks that are compatible with [FHE constraints](../getting-started/concepts.md#model-accuracy-considerations-under-fhe-constraints), Concrete ML works with [Brevitas](../explanations/inner-workings/external_libraries.md#brevitas), a library providing QAT support for PyTorch.
The following example uses a simple QAT PyTorch model that implements a fully connected neural network with two hidden layers. Due to its small size, making this model respect FHE constraints is relatively easy.
{% hint style="info" %}
-Converting neural networks to use FHE can be done with `compile_brevitas_qat_model` or with `compile_torch_model` for post-training quantization. If the model can not be converted to FHE two types of errors can be raised: (1) crypto-parameters can not be found and, (2) table look-up bit-width limit is exceeded. See the [debugging section](./fhe_assistant.md#compilation-error-debugging) if you encounter these errors.
+Converting neural networks to use FHE can be done with `compile_brevitas_qat_model` or with `compile_torch_model` for post-training quantization. If the model can not be converted to FHE two types of errors can be raised: (1) crypto-parameters can not be found and, (2) table look-up bit-width limit is exceeded. See the [debugging section](fhe_assistant.md#compilation-error-debugging) if you encounter these errors.
{% endhint %}
```python
@@ -38,8 +38,7 @@ class QATSimpleNet(nn.Module):
```
-Once the model is trained, calling the [`compile_brevitas_qat_model`](../developer-guide/api/concrete.ml.torch.compile.md#function-compile_brevitas_qat_model) from Concrete ML will automatically perform conversion and compilation of a QAT network. Here, 3-bit quantization is used for both the weights and activations. The `compile_brevitas_qat_model` function automatically
-identifies the number of quantization bits used in the Brevitas model.
+Once the model is trained, calling the [`compile_brevitas_qat_model`](../references/api/concrete.ml.torch.compile.md#function-compile_brevitas_qat_model) from Concrete ML will automatically perform conversion and compilation of a QAT network. Here, 3-bit quantization is used for both the weights and activations. The `compile_brevitas_qat_model` function automatically identifies the number of quantization bits used in the Brevitas model.
@@ -58,14 +57,9 @@ quantized_module = compile_brevitas_qat_model(
## Configuring quantization parameters
-The PyTorch/Brevitas models, created following the example above, require the user to configure
-quantization parameters such as `bit_width` (activation bit-width) and `weight_bit_width`. The
-quantization parameters, along with the number of neurons on each layer, will determine the
-accumulator bit-width of the network. Larger accumulator bit-widths result in higher accuracy
-but slower FHE inference time.
+The PyTorch/Brevitas models, created following the example above, require the user to configure quantization parameters such as `bit_width` (activation bit-width) and `weight_bit_width`. The quantization parameters, along with the number of neurons on each layer, will determine the accumulator bit-width of the network. Larger accumulator bit-widths result in higher accuracy but slower FHE inference time.
-The following configurations were determined through experimentation for convolutional and
-dense layers.
+The following configurations were determined through experimentation for convolutional and dense layers.
| target accumulator bit-width | activation bit-width | weight bit-width | number of active neurons |
| ---------------------------- | -------------------- | ---------------- | ------------------------ |
@@ -75,23 +69,20 @@ dense layers.
| 14 | 6 | 6 | 110 |
| 16 | 7 | 6 | 120 |
-Using the templates above, the probability of obtaining the target accumulator
-bit-width, for a single layer, was determined experimentally by training 10 models for each of
-the following data-sets.
+Using the templates above, the probability of obtaining the target accumulator bit-width, for a single layer, was determined experimentally by training 10 models for each of the following data-sets.
-| probability of obtaining probability of obtaining
the accumulator bit-width
accuracy for target
accumulator bit-width
| Importing ONNX | onnx_pipeline.md |
| Quantization tools | quantization_internal.md |
| FHE op-graph design | fhe-op-graphs.md |
| External libraries | external_libraries.md |
| - | - | - | - | - |
|---|---|---|---|---|
| GPT-2 in FHE | -
-
- Privacy-preserving text generation based on a user's prompt - |
- - - | health.png | -use_case_examples/llm | - -
| Titanic | -
-
- Train an XGB classifier that can perform encrypted prediction for the Kaggle Titanic competition - |
- - - | titanic.png | -use_case_examples/titanic | - -
| Federated Learning and Private Inference | -
-
- Use federated learning to train a Logistic Regression while preserving training data confidentiality. - Import the model into Concrete ML and perform encrypted prediction - |
- - - | mnist.png | -use_case_examples/federated_learning | - -
| Neural Network Fine-tuning | -
-
- Fine-tune a VGG network to classify the CIFAR image data-sets and predict on encrypted data - |
- - - | nn.png | -use_case_examples/cifar/cifar_brevitas_finetuning | - -
| Neural Network Splitting for SaaS deployment | -
-
- Train a VGG-like CNN that classifies CIFAR10 encrypted images, and where an initial feature extractor is executed client-side - |
- - - | client-server-1.png | -use_case_examples/cifar/cifar_brevitas_with_model_splitting | - -
| Encrypted Image filtering | -
-
- A Hugging Face space that applies a variety of image filters to encrypted images - |
- - - | blurring.png | -use_case_examples/image_filtering | - -
| Encrypted sentiment analysis | -
-
- A Hugging Face space that securely analyzes the sentiment expressed in a short text - |
- - - | sentiment.png | -use_case_examples/sentiment_analysis_with_transformer | - -
| Credit Scoring | -
-
- Predict the chance of a given loan applicant defaulting on loan repayment - |
- - - | credit.png | -use_case_examples/credit_scoring | - -
| Healthcare diagnosis | -
-
- Give a diagnosis using FHE to preserve the privacy of the patient - |
- - - | health.png | -use_case_examples/disease_prediction | - -
Linear Regression example](../advanced_examples/LinearRegression.ipynb)
-[ Logistic Regression example](../advanced_examples/LogisticRegression.ipynb)
-[ Linear Support Vector Regression example](../advanced_examples/LinearSVR.ipynb)
-[ Linear SVM classification](../advanced_examples/SVMClassifier.ipynb)
+[ Linear Regression example](../advanced_examples/LinearRegression.ipynb) [ Logistic Regression example](../advanced_examples/LogisticRegression.ipynb) [ Linear Support Vector Regression example](../advanced_examples/LinearSVR.ipynb) [ Linear SVM classification](../advanced_examples/SVMClassifier.ipynb)
These examples show how to use the built-in linear models on synthetic data, which allows for easy visualization of the decision boundaries or trend lines. Executing these 1D and 2D models in FHE takes around 1 millisecond.
### 2. Generalized linear models
-[ Poisson Regression example](../advanced_examples/PoissonRegression.ipynb)
-[ Generalized Linear Models comparison](../advanced_examples/GLMComparison.ipynb)
+[ Poisson Regression example](../advanced_examples/PoissonRegression.ipynb) [ Generalized Linear Models comparison](../advanced_examples/GLMComparison.ipynb)
These two examples show generalized linear models (GLM) on the real-world [OpenML insurance](https://www.openml.org/d/41214) data-set. As the non-linear, inverse-link functions are computed, these models do not use [PBS](../getting-started/concepts.md#cryptography-concepts), and are, thus, very fast (~1ms execution time).
### 3. Decision tree
-[ Decision Tree Classifier](../advanced_examples/DecisionTreeClassifier.ipynb)
+[ Decision Tree Classifier](../advanced_examples/DecisionTreeClassifier.ipynb)
Using the [OpenML spams](https://www.openml.org/d/44) data-set, this example shows how to train a classifier that detects spam, based on features extracted from email messages. A grid-search is performed over decision-tree hyper-parameters to find the best ones.
-[ Decision Tree Regressor](../advanced_examples/DecisionTreeRegressor.ipynb)
+[ Decision Tree Regressor](../advanced_examples/DecisionTreeRegressor.ipynb)
Using the [House Price prediction](https://www.openml.org/search?type=data&sort=runs&id=537) data-set, this example shows how to train regressor that predicts house prices.
### 4. XGBoost and Random Forest classifier
-[ XGBoost/Random Forest example](../advanced_examples/XGBClassifier.ipynb)
+[ XGBoost/Random Forest example](../advanced_examples/XGBClassifier.ipynb)
This example shows how to train tree-ensemble models (either XGBoost or Random Forest), first on a synthetic data-set, and then on the [Diabetes](https://www.openml.org/d/37) data-set. Grid-search is used to find the best number of trees in the ensemble.
### 5. XGBoost regression
-[ XGBoost Regression example](../advanced_examples/XGBRegressor.ipynb)
+[ XGBoost Regression example](../advanced_examples/XGBRegressor.ipynb)
Privacy-preserving prediction of house prices is shown in this example, using the [House Prices](https://www.openml.org/d/43926) data-set. Using 50 trees in the ensemble, with 5 bits of precision for the input features, the FHE regressor obtains an $$R^2$$ score of 0.90 and an execution time of 7-8 seconds.
### 6. Fully connected neural network
-[ NN Iris example](../advanced_examples/FullyConnectedNeuralNetwork.ipynb)
-[ NN MNIST example](../advanced_examples/FullyConnectedNeuralNetworkOnMNIST.ipynb)
+[ NN Iris example](../advanced_examples/FullyConnectedNeuralNetwork.ipynb) [ NN MNIST example](../advanced_examples/FullyConnectedNeuralNetworkOnMNIST.ipynb)
Two different configurations of the built-in, fully-connected neural networks are shown. First, a small bit-width accumulator network is trained on [Iris](https://www.openml.org/d/61) and compared to a PyTorch floating point network. Second, a larger accumulator (>8 bits) is demonstrated on [MNIST](http://yann.lecun.com/exdb/mnist/).
### 7. Comparison of models
-[ Classifier comparison](../advanced_examples/ClassifierComparison.ipynb)
-[ Regressor comparison](../advanced_examples/RegressorComparison.ipynb)
+[ Classifier comparison](../advanced_examples/ClassifierComparison.ipynb) [ Regressor comparison](../advanced_examples/RegressorComparison.ipynb)
Based on three different synthetic data-sets, all the built-in classifiers are demonstrated in this notebook, showing accuracies, inference times, accumulator bit-widths, and decision boundaries.
diff --git a/docs/tutorials/showcase.md b/docs/tutorials/showcase.md
new file mode 100644
index 000000000..666350e8a
--- /dev/null
+++ b/docs/tutorials/showcase.md
@@ -0,0 +1,43 @@
+# See all tutorials
+
+## Start here
+
+- [Build-in model examples](ml_examples.md)
+- [Deep learning examples](dl_examples.md)
+
+## Go further
+
+### Live demos on Hugging Face:
+
+- [Credit card approval](https://huggingface.co/spaces/zama-fhe/credit_card_approval_prediction): Predicting credit scoring card approval application in which sensitive data can be shared and analyzed without exposing the actual information to neither the three parties involved, nor the server processing it.
+ - Check the code [here](https://huggingface.co/spaces/zama-fhe/credit_card_approval_prediction/tree/main)
+- [Sentiment analysis with transformers](https://huggingface.co/blog/sentiment-analysis-fhe): predicting if an encrypted tweet / short message is positive, negative or neutral, using FHE.
+ - Check the code [here](https://huggingface.co/spaces/zama-fhe/encrypted_sentiment_analysis/tree/main) and the [blog post](https://huggingface.co/blog/sentiment-analysis-fhe)
+- [Health diagnosis](https://huggingface.co/spaces/zama-fhe/encrypted_health_prediction): giving a diagnosis using FHE to preserve the privacy of the patient based on a patient's symptoms, history and other health factors.
+ - Check the code [here](https://huggingface.co/spaces/zama-fhe/encrypted_health_prediction/tree/main)
+- [Encrypted image filtering](https://huggingface.co/spaces/zama-fhe/encrypted_image_filtering): filtering encrypted images by applying filters such as black-and-white, ridge detection, or your own filter.
+ - Check the code [here](https://huggingface.co/spaces/zama-fhe/encrypted_image_filtering/tree/main)
+
+### Code examples on Github:
+
+- [GPT-2 in FHE](../../use_case_examples/llm/README.md): Privacy-preserving text generation based on a user's prompt
+- [Titanic](../../use_case_examples/titanic/README.md): Train an XGB classifier that can perform encrypted prediction for the [Kaggle Titanic competition](https://www.kaggle.com/c/titanic/)
+- [Federated learning and private inference](../../use_case_examples/federated_learning/README.md): Use federated learning to train a Logistic Regression while preserving training data confidentiality. Import the model into Concrete ML and perform encrypted prediction
+- [Neutral network fine-tuning](../../use_case_examples/cifar/cifar_brevitas_finetuning/README.md): Fine-tune a VGG network to classify the CIFAR image data-sets and predict on encrypted data
+- [Encrypted sentiment analysis](../../use_case_examples/sentiment_analysis_with_transformer/README.md):A Hugging Face space that securely analyzes the sentiment expressed in a short text
+- [Credit scoring](../../use_case_examples/credit_scoring/README.md): Predict the chance of a given loan applicant defaulting on loan repayment
+
+### Blog tutorials:
+
+- [Build an end-to-end encrypted Shazam application using Concrete ML](https://www.zama.ai/post/encrypted-shazam-using-fully-homomorphic-encryption-concrete-ml-tutorial) - February 2024
+- [Linear regression over encrypted data with homomorphic encryption](https://www.zama.ai/post/linear-regression-using-linear-svr-and-concrete-ml-homomorphic-encryption) - June 2023
+- [Comparison of Concrete ML regressors](https://www.zama.ai/post/comparison-of-concrete-ml-regressors) - June 2023
+- [How to deploy a machine learning model with Concrete ML](https://www.zama.ai/post/how-to-deploy-machine-learning-models-with-concrete-ml) - May 2023
+- [Encrypted image filtering using homomorphic encryption](https://www.zama.ai/post/encrypted-image-filtering-using-homomorphic-encryption) - February 2023
+- [Sentiment analysis over encrypted data](https://huggingface.co/blog/sentiment-analysis-fhe) - November 2022
+- [Titanic Competition with Privacy Preserving Machine Learning](https://www.zama.ai/post/titanic-competition-with-privacy-preserving-machine-learning-using-concrete-ml) - August 2022
+
+### Video tutorials
+
+- [Train a linear classifier on encrypted data using Concrete ML and Fully Homomorphic Encryption (FHE)](https://www.zama.ai/post/video-tutorial-train-a-linear-classifier-on-encrypted-data-using-concrete-ml-and-fully-homomorphic-encryption-fhe) - February 2024
+- [How to convert a scikit-learn model into its homomorphic equivalent](https://www.zama.ai/post/how-to-convert-a-scikit-learn-model-into-its-homomorphic-equivalent) - June 2023
diff --git a/script/doc_utils/check_apidocs.sh b/script/doc_utils/check_apidocs.sh
index 958e831c1..d507f23bd 100755
--- a/script/doc_utils/check_apidocs.sh
+++ b/script/doc_utils/check_apidocs.sh
@@ -2,11 +2,11 @@
set -e
-rm -rf docs/developer-guide/tmp.api_for_check
-APIDOCS_OUTPUT=./docs/developer-guide/tmp.api_for_check make apidocs
-rm -f docs/developer-guide/tmp.api_for_check/.pages
-rm -f docs/developer-guide/api/.pages
-diff ./docs/developer-guide/api ./docs/developer-guide/tmp.api_for_check
-rm -rf docs/developer-guide/tmp.api_for_check
+rm -rf docs/references/tmp.api_for_check
+APIDOCS_OUTPUT=./docs/references/tmp.api_for_check make apidocs
+rm -f docs/references/tmp.api_for_check/.pages
+rm -f docs/references/api/.pages
+diff ./docs/references/api ./docs/references/tmp.api_for_check
+rm -rf docs/references/tmp.api_for_check
diff --git a/script/doc_utils/check_forbidden_words.py b/script/doc_utils/check_forbidden_words.py
index f4903aa4e..11e7cc5b6 100644
--- a/script/doc_utils/check_forbidden_words.py
+++ b/script/doc_utils/check_forbidden_words.py
@@ -49,7 +49,7 @@ def process_file(file_str: str, do_open_problematic_files=False):
file_path = Path(file_str).resolve()
# Don't do it on API or advanced example data files
- if "docs/developer-guide/api" in file_str or "docs/advanced_examples/data" in file_str:
+ if "docs/references/api" in file_str or "docs/advanced_examples/data" in file_str:
return True, 0
# Don't do it for conventions.md file that explains what should or not be done
diff --git a/script/doc_utils/fix_api_readme_reference.py b/script/doc_utils/fix_api_readme_reference.py
new file mode 100644
index 000000000..5d0d164cb
--- /dev/null
+++ b/script/doc_utils/fix_api_readme_reference.py
@@ -0,0 +1,68 @@
+"""Helper script to replace Replace `references/api/README.md` with `_apidoc/modules.html`."""
+
+import argparse
+import multiprocessing
+import re
+import sys
+from pathlib import Path
+
+
+def process_file(file_str: str) -> bool:
+ """Replace `references/api/README.md` with `_apidoc/modules.html`.
+
+ Also changes "references/api" pattern to Sphinx's "_apidoc"
+
+ Args:
+ file_str (str): the path to the file to process.
+
+ Returns:
+ bool: True once done
+ """
+ verbose = False
+
+ file_path = Path(file_str).resolve()
+ file_path_output = Path(file_str).resolve()
+
+ if verbose:
+ print(f"Fix api reference problems for {str(file_path)} into {str(file_path_output)}")
+
+ api_pattern = "references/api/README.md"
+ apidoc_pattern = "_apidoc/modules.html"
+
+ processed_content = ""
+ with open(file_path, "r", encoding="utf-8") as f:
+
+ for line in f:
+ newline = re.sub(api_pattern, apidoc_pattern, line)
+ processed_content += newline
+
+ with open(file_path_output, "w", encoding="utf-8") as fout:
+ print(processed_content, file=fout, end="")
+
+ return True
+
+
+def main(args):
+ """Entry point.
+
+ Args:
+ args (List[str]): a list of arguments
+ """
+ with multiprocessing.Pool(multiprocessing.cpu_count()) as pool:
+ res = pool.map(process_file, args.files)
+ # Exit 0 if all went well as True == 1
+ sys.exit(not all(res))
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(
+ "Replace `references/api/README.md` with `_apidoc/modules.html`.",
+ allow_abbrev=False,
+ )
+
+ parser.add_argument(
+ "--files", type=str, nargs="+", required=True, help="The files to modify in place"
+ )
+
+ cli_args = parser.parse_args()
+ main(cli_args)
diff --git a/script/doc_utils/fix_gitbook_table.py b/script/doc_utils/fix_gitbook_table.py
deleted file mode 100644
index d538a84bf..000000000
--- a/script/doc_utils/fix_gitbook_table.py
+++ /dev/null
@@ -1,101 +0,0 @@
-"""Helper script to turn GitBook card boards into something sphinx-style."""
-
-import argparse
-import multiprocessing
-import sys
-from functools import partial
-from pathlib import Path
-
-
-def process_file(file_str: str):
- """Change table-car from gitbook-style to sphinx-style
-
- Args:
- file_str (str): the path to the file to process.
-
- Raises:
- ValueError: value error
-
- Returns:
- True if everything went alright.
- """
-
- file_path = Path(file_str).resolve()
- file_path_output = Path(file_str).resolve()
-
- processed_content = ""
- has_started = False
- which_line = 0
- how_many = 0
-
- with open(file_path, "r", encoding="utf-8") as f:
-
- for line in f:
-
- line = line.rstrip()
-
- if "" in line:
- assert not has_started
- has_started = True
- which_line = 0
-
- processed_content += line
-
- elif "" in line:
- assert has_started
- has_started = False
- how_many += 1
-
- processed_content += line
- elif has_started:
- if which_line == 0:
- # Find the png
- which_line += 1
- png = line.split(".gitbook/assets/")[1].split('"')[0]
- elif which_line == 1:
- # Find link
- link = line.split('a href="')[1].split('">')[0]
- # Add the line
- processed_content += (
- f'
