From 6159c065a938359370bdebe946a0db4171519293 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexandre=20P=C3=A9r=C3=A9?= Date: Mon, 18 Nov 2024 11:08:39 +0100 Subject: [PATCH] docs(frontend): document parameter restrictions --- docs/README.md | 7 -- docs/SUMMARY.md | 1 + ...rameter_compatibility_with_restrictions.md | 88 +++++++++++++++++++ docs/guides/configure.md | 6 ++ .../tests/compilation/test_restrictions.py | 11 +-- 5 files changed, 97 insertions(+), 16 deletions(-) create mode 100644 docs/compilation/parameter_compatibility_with_restrictions.md diff --git a/docs/README.md b/docs/README.md index f4b14889d5..96968f660c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,15 +61,8 @@ Collaborate with us to advance the FHE spaces and drive innovation together. *** {% hint style="success" %} -<<<<<<< HEAD -**Zama 5-Question Developer Survey** -We want to hear from you! Take 1 minute to share your thoughts and helping us enhance our documentation and libraries. **👉** [**Click here**](https://zvajd6l0ngk.typeform.com/to/I7mXXanI) to participate. -{% endhint %} -======= **Zama 5-Question Developer Survey** We want to hear from you! Take 1 minute to share your thoughts and helping us enhance our documentation and libraries. **👉** [**Click here**](https://www.zama.ai/developer-survey) to participate. {% endhint %} - ->>>>>>> origin/main diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 5ecb2fedf2..17f6329e46 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -29,6 +29,7 @@ * [Multi parameters](compilation/multi_parameters.md) * [Compression](compilation/compression.md) * [Reusing arguments](compilation/reuse_arguments.md) +* [Parameter compatibility with restrictions](compilation/parameter_compatibility_with_restrictions.md) * [Common errors](compilation/common_errors.md) ## Execution / Analysis diff --git a/docs/compilation/parameter_compatibility_with_restrictions.md b/docs/compilation/parameter_compatibility_with_restrictions.md new file mode 100644 index 0000000000..4698f6137a --- /dev/null +++ b/docs/compilation/parameter_compatibility_with_restrictions.md @@ -0,0 +1,88 @@ +# Parameters compatibility with restrictions + +This document explains how to use restrictions to limit the possible crypto-parameters used for the keys. + +When compiling a module, the optimizer analyzes the circuits and the expected probability of error, to identify the fastest crypto-parameters that meet the specific constraints. The chosen crypto-parameters determine the size of the keys and the ciphertexts. This means that if an existing module is used in production with a specific set of crypto-parameters, there is no guarantee that a compilation of a second, different module will yield compatible crypto-parameters. + +With _restrictions_, Concrete provides a way to ensure that a compilation generates compatible crypto-parameters. Restrictions will limit the search-space walked by the optimizer to ensure that only compatible parameters can be returned. As of now, we support two major restrictions: + ++ [__Keyset restriction__](#keyset-restriction) : Restricts the crypto-parameters to an existing keyset. ++ [__Ranges restriction__](#ranges-restriction) : Restricts the crypto-parameters ranges allowed in the optimizer. + +## Keyset restriction + +You can generate keyset restriction directly form an existing keyset: + +```python +@fhe.module() +class Big: + @fhe.function({"x": "encrypted"}) + def inc(x): + return (x + 1) % 200 + +big_inputset = [np.random.randint(1, 200, size=()) for _ in range(100)] +big_module = Big.compile( + {"inc": big_inputset}, +) +big_keyset_info = big_module.keys.specs.program_info.get_keyset_info() +big_module.keygen() + +# We get the restriction from the existing keyset +restriction = big_keyset_info.get_restriction() + +@fhe.module() +class Small: + @fhe.function({"x": "encrypted"}) + def inc(x): + return (x + 1) % 20 + +small_inputset = [np.random.randint(1, 20, size=()) for _ in range(100)] +small_module = Small.compile( + {"inc": small_inputset}, + # We pass the keyset restriction as an extra compilation option + keyset_restriction=restriction +) +restricted_keyset_info = restricted_module.keys.specs.program_info.get_keyset_info() +assert big_keyset_info == restricted_keyset_info + +small_module.keys = big_module.keys + +x = 5 +x_enc = small_module.inc.encrypt(x) +``` + +## Ranges restriction + +You can build a ranges restriction by adding available values: +```python +@fhe.module() +class Module: + @fhe.function({"x": "encrypted"}) + def inc(x): + return (x + 1) % 20 + +inputset = [np.random.randint(1, 20, size=()) for _ in range(100)] + +## We generate a range restriction +range_restriction = RangeRestriction() + +## Make 999 and 200 available as internal lwe dimensions +range_restriction.add_available_internal_lwe_dimension(999) +range_restriction.add_available_internal_lwe_dimension(200) + +## Setting other restrictions +range_restriction.add_available_glwe_log_polynomial_size(12) +range_restriction.add_available_glwe_dimension(2) +range_restriction.add_available_pbs_level_count(3) +range_restriction.add_available_pbs_base_log(11) +range_restriction.add_available_ks_level_count(3) +range_restriction.add_available_ks_base_log(6) + +module = Module.compile( + {"inc": inputset}, + # We pass the range restriction as an extra compilation option. + range_restriction=range_restriction +) +``` + +Note that if no available parameters are set for one of the parameter ranges (say `ks_base_log`), it is assumed that the default range is available. diff --git a/docs/guides/configure.md b/docs/guides/configure.md index c7238d097e..ea7626c03a 100644 --- a/docs/guides/configure.md +++ b/docs/guides/configure.md @@ -201,6 +201,12 @@ When options are specified both in the `configuration` and as kwargs in the `com #### single_precision: bool = False - Use single precision for the whole circuit. +#### range_restriction: Optional[RangeRestriction] = None +- A range restriction to pass to the optimizer to restrict the available crypto-parameters. + +#### keyset_restriction: Optional[KeysetRestriction] = None +- A keyset restriction to pass to the optimizer to restrict the available crypto-parameters. + #### use_gpu: bool = False - Enable generating code for GPU in the compiler. diff --git a/frontends/concrete-python/tests/compilation/test_restrictions.py b/frontends/concrete-python/tests/compilation/test_restrictions.py index 4e06ef97f1..327d0bdc17 100644 --- a/frontends/concrete-python/tests/compilation/test_restrictions.py +++ b/frontends/concrete-python/tests/compilation/test_restrictions.py @@ -45,9 +45,7 @@ def inc(x): range_restriction.add_available_ks_level_count(ks_level_count) ks_base_log = 6 range_restriction.add_available_ks_base_log(ks_base_log) - module = Module.compile( - {"inc": inputset}, enable_unsafe_features=True, range_restriction=range_restriction - ) + module = Module.compile({"inc": inputset}, range_restriction=range_restriction) keyset_info = module.keys.specs.program_info.get_keyset_info() assert keyset_info.bootstrap_keys()[0].polynomial_size() == 2**glwe_log_polynomial_size assert keyset_info.bootstrap_keys()[0].input_lwe_dimension() == internal_lwe_dimension @@ -83,21 +81,17 @@ def inc(x): big_module = Big.compile( {"inc": big_inputset}, - enable_unsafe_features=True, ) big_keyset_info = big_module.keys.specs.program_info.get_keyset_info() small_module = Small.compile( {"inc": small_inputset}, - enable_unsafe_features=True, ) small_keyset_info = small_module.keys.specs.program_info.get_keyset_info() assert big_keyset_info != small_keyset_info restriction = big_keyset_info.get_restriction() - restricted_module = Small.compile( - {"inc": small_inputset}, enable_unsafe_features=True, keyset_restriction=restriction - ) + restricted_module = Small.compile({"inc": small_inputset}, keyset_restriction=restriction) restricted_keyset_info = restricted_module.keys.specs.program_info.get_keyset_info() assert big_keyset_info == restricted_keyset_info assert small_keyset_info != restricted_keyset_info @@ -121,7 +115,6 @@ def inc(x): inputset = [np.random.randint(1, 200, size=()) for _ in range(100)] restricted_module = Module.compile( {"inc": inputset}, - enable_unsafe_features=True, keyset_restriction=generic_keyset_info.get_restriction(), ) compiled_keyset_info = restricted_module.keys.specs.program_info.get_keyset_info()