github/concrete
1
1
Fork 0
mirror of https://github.com/zama-ai/concrete.git synced 2026-01-09 21:07:56 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs(frontend): edits

Browse Source
This commit is contained in:
yuxizama
2024-08-27 16:18:49 +02:00
committed by Benoit Chevallier-Mames
parent 3a9c2a1ffa
commit 591d98c0a7
3 changed files with 177 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/execution-analysis/formatting_and_drawing.md
View File

@@ -1,8 +1,9 @@
# Formatting and drawing # Formatting and drawing
This document explains how to format and draw a compiled circuit in Python.
## Formatting ## Formatting
You can convert your compiled circuit into its textual representation by converting it to string: To convert your compiled circuit into its textual representation, use the `str` function:
```python ```python
str(circuit) str(circuit)
@@ -15,24 +16,24 @@ print(circuit)
``` ```
{% hint style="warning" %} {% hint style="warning" %}
Formatting is just for debugging purposes. It's not possible to create the circuit back from its textual representation. See [How to Deploy](../guides/deploy.md) if that's your goal. Formatting is designed for debugging purpose only. It's not possible to create the circuit back from its textual representation. See [How to Deploy](../guides/deploy.md) if that's your goal.
{% endhint %} {% endhint %}
## Drawing ## Drawing
{% hint style="danger" %} {% hint style="danger" %}
Drawing functionality requires the installation of the package with the full feature set. See the [Installation](../get-started/installing.md) section to learn how to do that. Drawing functionality requires the installation of the package with the full feature set. See the [Installation](../get-started/installing.md) section for instructions.
{% endhint %} {% endhint %}
You can use the `draw` method of your compiled circuit to draw it: To draw your compiled circuit, use the `draw` method:
```python ```python
drawing = circuit.draw() drawing = circuit.draw()
``` ```
This method will draw the circuit on a temporary PNG file and return the path to this file. This method draws the circuit, saves it as a temporary PNG file and returns the file path.
You can show the drawing in a Jupyter notebook, like this: You can display the drawing in a Jupyter notebook:
```python ```python
from PIL import Image from PIL import Image
@@ -41,17 +42,17 @@ drawing.show()
drawing.close() drawing.close()
``` ```
Or, you can use the `show` option of the `draw` method to show the drawing with `matplotlib`. Alternatively, you can use the `show` option of the `draw` method to display the drawing with `matplotlib`:
```python ```python
circuit.draw(show=True) circuit.draw(show=True)
``` ```
{% hint style="danger" %} {% hint style="danger" %}
Beware that this will clear the matplotlib plots you have. Using this option will clear any existing matplotlib plots.
{% endhint %} {% endhint %}
Lastly, you can save the drawing to a specific path: Lastly, to save the drawing to a specific path, use the `save_to` option:
```python ```python
destination = "/tmp/path/of/your/choice.png" destination = "/tmp/path/of/your/choice.png"

11
docs/execution-analysis/gpu_acceleration.md
View File

@@ -26,31 +26,30 @@ By default the compiler and runtime will use all available system resources, inc
- **Type**: Integer - **Type**: Integer
- **Default value**: The number of hardware threads on the system (including hyperthreading) minus the number of GPUs in use. - **Default value**: The number of hardware threads on the system (including hyperthreading) minus the number of GPUs in use.
- **Description:** This variable determines the number of CPU threads that execute in paralelle with the GPU for offloadable workloads. GPU scheduler threads (including CUDA threads and those used within Concrete) are necessary but can block or interfere with worker thread execution. Therefore, it is recommended to undersubscribe the CPU hardware threads by the number of GPU devices used. - **Description:** This variable determines the number of CPU threads that execute in paralelle with the GPU for offloadable workloads. GPU scheduler threads (including CUDA threads and those used within Concrete) are necessary but can block or interfere with worker thread execution. Therefore, it is recommended to undersubscribe the CPU hardware threads by the number of GPU devices used.
- **Required**: No
### SDFG_NUM_GPUS ### SDFG_NUM_GPUS
- **Type**: Integer - **Type**: Integer
- **Default value**: The number of GPUs available. - **Default value**: The number of GPUs available.
- **Description**: This value determines the number of GPUs to use for offloading. This can be set to any value between 1 and the total number of GPUs on the system. - **Description**: This value determines the number of GPUs to use for offloading. This can be set to any value between 1 and the total number of GPUs on the system.
- **Required**: No
### SDFG_MAX_BATCH_SIZE** ### SDFG_MAX_BATCH_SIZE**
- **Type**: Integer (default: LLONG_MAX) - **Type**: Integer
- **Default value**: LLONG_MAX (no batch size limit) - **Default value**: LLONG_MAX (no batch size limit)
- **Description**: This value limits the maximum batch size for offloading in cases where the GPU memory is insufficient. - **Description**: This value limits the maximum batch size for offloading in cases where the GPU memory is insufficient.
- **Required**: No
### SDFG_DEVICE_TO_CORE_RATIO ### SDFG_DEVICE_TO_CORE_RATIO
- **Type**: Integer - **Type**: Integer
- **Default value**: The ratio between the compute capability of the GPU (at index 0) and a CPU core. - **Default value**: The ratio between the compute capability of the GPU (at index 0) and a CPU core.
- **Description**: This ratio is used to balance the load between the CPU and GPU. If the GPU is underutilized, set this value higher to increase the amount of work offloaded to the GPU. - **Description**: This ratio is used to balance the load between the CPU and GPU. If the GPU is underutilized, set this value higher to increase the amount of work offloaded to the GPU.
- **Required**: No
### OMP_NUM_THREADS ### OMP_NUM_THREADS
- **Type**: Integer - **Type**: Integer
- **Default value**: The number of hardware threads on the system, including hyperthreading. - **Default value**: The number of hardware threads on the system, including hyperthreading.
- **Description**: This value specifies the portions of program execution that are not yet supported for GPU offload, which will be parallelized using OpenMP on the CPU. - **Description**: This value specifies the portions of program execution that are not yet supported for GPU offload, which will be parallelized using OpenMP on the CPU.
- **Required**: No

265
docs/guides/configure.md
View File

@@ -1,6 +1,8 @@
# Configure # Configure
**Concrete** can be customized using `Configuration`s: This document provides instructions on how to customize the compilation pipeline using `Configuration`s in Python and describes various configuration options available.
You can customize **Concrete** using the `fhe.Configuration` :
```python ```python
from concrete import fhe from concrete import fhe
@@ -16,7 +18,7 @@ inputset = range(10)
circuit = f.compile(inputset, configuration=configuration) circuit = f.compile(inputset, configuration=configuration)
``` ```
You can overwrite individual options as kwargs to the `compile` method: You can overwrite individual configuration options by specifying kwargs in the `compile` method:
```python ```python
from concrete import fhe from concrete import fhe
@@ -30,7 +32,7 @@ inputset = range(10)
circuit = f.compile(inputset, p_error=0.01, dataflow_parallelize=True) circuit = f.compile(inputset, p_error=0.01, dataflow_parallelize=True)
``` ```
Or you can combine both: You can also combine both ways:
```python ```python
from concrete import fhe from concrete import fhe
@@ -47,107 +49,164 @@ circuit = f.compile(inputset, configuration=configuration, loop_parallelize=True
``` ```
{% hint style="info" %} {% hint style="info" %}
Additional kwargs to `compile` functions take higher precedence. So if you set the option in both `configuration` and `compile` methods, the value in the `compile` method will be used.
When options are specified both in the `configuration` and as kwargs in the `compile` method, the kwargs take precedence.
{% endhint %} {% endhint %}
## Options ## Options
* **show\_graph**: Optional\[bool] = None #### approximate_rounding_config: ApproximateRoundingConfig = fhe.ApproximateRoundingConfig()
* Print computation graph during compilation. `True` means always print, `False` means never print, `None` means print depending on verbose configuration below. - Provide fine control for [approximate rounding](../core-features/rounding.md#approximate-rounding-features):
* **show\_mlir**: Optional\[bool] = None - To enable exact clipping,
* Print MLIR during compilation. `True` means always print, `False` means never print, `None` means print depending on verbose configuration below. - Or/and approximate clipping, which makes overflow protection faster.
* **show\_optimizer**: Optional\[bool] = None
* Print optimizer output during compilation. `True` means always print, `False` means never print, `None` means print depending on verbose configuration below. #### auto_adjust_rounders: bool = False
* **show\_statistics**: Optional\[bool] = None - Adjust rounders automatically.
* Print circuit statistics during compilation. `True` means always print, `False` means never print, `None` means print depending on verbose configuration below.
* **verbose**: bool = False #### auto_parallelize: bool = False
* Print details related to compilation. - Enable auto parallelization in the compiler.
* **dump\_artifacts\_on\_unexpected\_failures**: bool = True
* Export debugging artifacts automatically on compilation failures. #### bitwise_strategy_preference: Optional[Union[BitwiseStrategy, str, List[Union[BitwiseStrategy, str]]]] = None
* **auto\_adjust\_rounders**: bool = False - Specify preference for bitwise strategies, can be a single strategy or an ordered list of strategies. See [Bitwise](../core-features/bitwise.md) to learn more.
* Adjust rounders automatically.
* **p\_error**: Optional\[float] = None #### compiler_debug_mode: bool = False
* 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](../core-features/table\_lookups.md#table-lookup-exactness) to learn more. - Enable or disable the debug mode of the compiler. This can show a lot of information, including passes and pattern rewrites.
* **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](../core-features/table\_lookups.md#table-lookup-exactness) to learn more. #### compiler_verbose_mode: bool = False
* **single\_precision**: bool = False - Enable or disable verbose mode of the compiler. This mainly shows logs from the compiler and is less verbose than the debug mode.
* Use single precision for the whole circuit.
* **parameter\_selection\_strategy**: (fhe.ParameterSelectionStrategy) = fhe.ParameterSelectionStrategy.MULTI #### comparison_strategy_preference: Optional[Union[ComparisonStrategy, str, List[Union[ComparisonStrategy, str]]]] = None
* Set how cryptographic parameters are selected. - Specify preference for comparison strategies. Can be a single strategy or an ordered list of strategies. See [Comparisons](../core-features/comparisons.md) to learn more.
* **multi\_parameter\_strategy**: fhe.MultiParameterStrategy = fhe.MultiParameterStrategy.PRECISION
* Set the level of circuit partionning when using `fhe.ParameterSelectionStrategy.MULTI`. #### compress_evaluation_keys: bool = False
* `PRECISION`: all TLU with same input precision have their own parameters. - Specify that serialization takes the compressed form of evaluation keys.
* `PRECISION_AND_NORM2`: all TLU with same input precision and output [norm2](../../compilers/concrete-optimizer/v0-parameters/) have their own parameters.
* **loop\_parallelize**: bool = True #### compress_input_ciphertexts: bool = False
* Enable loop parallelization in the compiler. - Specify that serialization takes the compressed form of input ciphertexts.
* **dataflow\_parallelize**: bool = False
* Enable dataflow parallelization in the compiler. #### composable: bool = False
* **auto\_parallelize**: bool = False - Specify that the function must be composable with itself.
* Enable auto parallelization in the compiler. - Only used when compiling a single circuit; when compiling modules, use the [composition policy](../compilation/composing_functions_with_modules.md#optimizing_runtimes_with_composition_policies).
* **use_gpu**: bool = False
* Enable generating code for GPU in the compiler. #### dataflow_parallelize: bool = False
* **enable\_unsafe\_features**: bool = False - Enable dataflow parallelization in the compiler.
* Enable unsafe features.
* **use\_insecure\_key\_cache**: bool = False _(Unsafe)_ #### dump_artifacts_on_unexpected_failures: bool = True
* Use the insecure key cache. - Export debugging artifacts automatically on compilation failures.
* **insecure\_key\_cache\_location**: Optional\[Union\[Path, str]] = None
* Location of insecure key cache. #### enable_tlu_fusing: bool = True
* **show\_progress**: bool = False, - Enables Table Lookups(TLU) fusing to reduce the number of TLUs.
* Display a progress bar during circuit execution
* **progress\_title**: str = "", #### enable_unsafe_features: bool = False
* Title of the progress bar - Enable unsafe features.
* **progress\_tag**: Union\[bool, int] = False,
* How many nested tag elements to display with the progress bar. `True` means all tag elements and `False` disables the display. `2` will display `elmt1.elmt2` #### fhe_execution: bool = True
* **fhe\_simulation**: bool = False - Enable FHE execution. Can be enabled later using `circuit.enable_fhe_execution()`.
* Enable FHE simulation. Can be enabled later using `circuit.enable_fhe_simulation()`.
* **fhe\_execution**: bool = True #### fhe_simulation: bool = False
* Enable FHE execution. Can be enabled later using `circuit.enable_fhe_execution()`. - Enable FHE simulation. Can be enabled later using `circuit.enable_fhe_simulation()`.
* **compiler\_debug\_mode**: bool = False,
* Enable/disable debug mode of the compiler. This can show a lot of information, including passes and pattern rewrites. #### global_p_error: Optional[float] = None
* **compiler\_verbose\_mode**: bool = False, - Global error probability for the whole circuit.
* Enable/disable verbose mode of the compiler. This mainly shows logs from the compiler, and is less verbose than the debug mode. - If set, the whole circuit will have the probability of a non-exact result smaller than the set value. See [Exactness](../core-features/table_lookups_advanced.md#table-lookup-exactness) to learn more.
* **comparison\_strategy\_preference**: Optional\[Union\[ComparisonStrategy, str, List\[Union\[ComparisonStrategy, str]]]] = None
* Specify preference for comparison strategies, can be a single strategy or an ordered list of strategies. See [Comparisons](../core-features/comparisons.md) to learn more. #### if_then_else_chunk_size: int = 3
* **bitwise\_strategy\_preference**: Optional\[Union\[BitwiseStrategy, str, List\[Union\[BitwiseStrategy, str]]]] = None - Chunk size to use when converting the `fhe.if_then_else extension`.
* Specify preference for bitwise strategies, can be a single strategy or an ordered list of strategies. See [Bitwise](../core-features/bitwise.md) to learn more.
* **shifts\_with\_promotion**: bool = True, #### insecure_key_cache_location: Optional[Union[Path, str]] = None
* Enable promotions in encrypted shifts instead of casting in runtime. See [Bitwise#Shifts](../core-features/bitwise.md#Shifts) to learn more. - Location of insecure key cache.
* **composable**: bool = False,
* Specify that the function must be composable with itself. Only used when compiling a single circuit; when compiling modules use the [composition policy](../compilation/composing_functions_with_modules.md#optimizing_runtimes_with_composition_policies). #### loop_parallelize: bool = True
* **relu\_on\_bits\_threshold**: int = 7, - Enable loop parallelization in the compiler.
* Bit-width to start implementing the ReLU extension with [fhe.bits](../core-features/bit\_extraction.md).
* **relu\_on\_bits\_chunk\_size**: int = 3, #### multi_parameter_strategy: fhe.MultiParameterStrategy = fhe.MultiParameterStrategy.PRECISION
* Chunk size of the ReLU extension when [fhe.bits](../core-features/bit\_extraction.md) implementation is used. - Set the level of circuit partitioning when using `fhe.ParameterSelectionStrategy.MULTI`.
* **if\_then\_else\_chunk\_size**: int = 3 - `PRECISION`: all TLUs with the same input precision have their own parameters.
* Chunk size to use when converting `fhe.if_then_else` extension. - `PRECISION_AND_NORM2`: all TLUs with the same input precision and output [norm2](../../compilers/concrete-optimizer/v0-parameters/) have their own parameters.
* **rounding\_exactness** : Exactness = `fhe.Exactness.EXACT`
* Set default exactness mode for the rounding operation: #### optimize_tlu_based_on_measured_bounds: bool = False
* `EXACT`: threshold for rounding up or down is exactly centered between upper and lower value, - Enables TLU optimizations based on measured bounds.
* `APPROXIMATE`: faster but threshold for rounding up or down is approximately centered with pseudo-random shift. - Not enabled by default, as it could result in unexpected overflows during runtime.
* Precise and more complete behavior is described in [fhe.rounding\_bit\_pattern](../core-features/rounding.md).
* **approximate\_rounding\_config** : ApproximateRoundingConfig = `fhe.ApproximateRoundingConfig()`: #### optimize_tlu_based_on_original_bit_width: Union[bool, int] = 8
* Provide more fine control on [approximate rounding](../core-features/rounding.md#approximate-rounding-features): - Configures whether to convert values to their original precision before doing a table lookup on them.
* to enable exact cliping, - `True` enables it for all cases.
* or/and approximate clipping which make overflow protection faster. - `False` disables it for all cases.
* **optimize_tlu_based_on_measured_bounds** : bool = False - Integer value enables or disables it depending on the original bit width. With the default value of 8, only the values with original bit width ≤ 8 will be converted to their original precision.
* Enables TLU optimizations based on measured bounds.
* Not enabled by default as it could result in unexpected overflows during runtime. #### p_error: Optional[float] = None
* **enable_tlu_fusing** : bool = True - Error probability for individual table lookups.
* Enables TLU fusing to reduce the number of table lookups. - If set, all table lookups will have the probability of a non-exact result smaller than the set value. See [Exactness](../core-features/table_lookups_advanced.md#table-lookup-exactness) to learn more.
* **print_tlu_fusing** : bool = False
* Enables printing TLU fusing to see which table lookups are fused. #### parameter_selection_strategy: fhe.ParameterSelectionStrategy = fhe.ParameterSelectionStrategy.MULTI
* **compress\_evaluation\_keys**: bool = False, - Set how cryptographic parameters are selected.
* This specifies that serialization takes the compressed form of evaluation keys.
* **compress\_input\_ciphertexts**: bool = False, #### print_tlu_fusing: bool = False
* This specifies that serialization takes the compressed form of input ciphertexts. - Enables printing of TLU fusing to see which table lookups are fused.
* **optimize\_tlu\_based\_on\_original\_bit\_width**: Union\[bool, int] = 8,
* Configures whether to convert values to their original precision before doing a table lookup on them. #### progress_tag: Union[bool, int] = False
* True enables it for all cases. - How many nested tag elements to display with the progress bar.
* False disables it for all cases. - `True` means all tag elements
* Integer value enables or disables it depending on the original bit width. - `False` disables the display.
* With the default value of 8, only the values with original bit width <= 8 will be converted to their original precision. - `2` will display `elmt1.elmt2`.
* **simulate\_encrypt\_run\_decrypt**: bool = False #### progress_title: str = ""
* Whether to use simulate encrypt/run/decrypt methods of the circuit/module instead of doing the actual encryption/evaluation/decryption. - Title of the progress bar.
* When this option is set to `True`, encrypt and decrypt are identity functions, and run is a wrapper around simulation. In other words, this option allows to switch off the encryption to quickly test if a function has expected semantic (without paying the price of FHE execution).
* This is extremely unsafe and should only be used during development. #### rounding_exactness: Exactness = fhe.Exactness.EXACT
* For this reason, it requires **enable\_unsafe\_features** to be set to `True`. - Set default exactness mode for the rounding operation:
- `EXACT`: threshold for rounding up or down is exactly centered between the upper and lower value.
- `APPROXIMATE`: faster but threshold for rounding up or down is approximately centered with a pseudo-random shift. Precise behavior is described in [`fhe.rounding_bit_pattern`](../core-features/rounding.md).
#### relu_on_bits_chunk_size: int = 3
- Chunk size of the ReLU extension when [fhe.bits](../core-features/bit_extraction.md) implementation is used.
#### relu_on_bits_threshold: int = 7
- Bit-width to start implementing the ReLU extension with [fhe.bits](../core-features/bit_extraction.md).
#### shifts_with_promotion: bool = True
- Enable promotions in encrypted shifts instead of casting at runtime. See [Bitwise#Shifts](../core-features/bitwise.md#shifts) to learn more.
#### show_graph: Optional[bool] = None
- Print computation graph during compilation.
- `True` means always print
- `False` means never print
- `None` means print depending on verbose configuration.
#### show_mlir: Optional[bool] = None
- Print MLIR during compilation.
- `True` means always print
- `False` means never print
- `None` means print depending on verbose configuration.
#### show_optimizer: Optional[bool] = None
- Print optimizer output during compilation.
- `True` means always print
- `False` means never print
- `None` means print depending on verbose configuration.
#### show_progress: bool = False
- Display a progress bar during circuit execution.
#### show_statistics: Optional[bool] = None
- Print circuit statistics during compilation.
- `True` means always print
- `False` means never print
- `None` means print depending on verbose configuration.
#### simulate_encrypt_run_decrypt: bool = False
- Whether to use the simulate encrypt/run/decrypt methods of the circuit/module instead of actual encryption/evaluation/decryption.
- When this option is set to `True`, encrypt and decrypt are identity functions, and run is a wrapper around simulation. In other words, this option allows switching off encryption to quickly test if a function has the expected semantic (without paying the price of FHE execution).
- This is extremely unsafe and should only be used during development.
- For this reason, it requires `enable_unsafe_features` to be set to `True`.
#### single_precision: bool = False
- Use single precision for the whole circuit.
#### use_gpu: bool = False
- Enable generating code for GPU in the compiler.
#### use_insecure_key_cache: bool = False (Unsafe)
- Use the insecure key cache.
#### verbose: bool = False
- Print details related to compilation.