docs(frontend): document parameter restrictions

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

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__](<parameter_compatibility_with_restrictions#Keyset restriction>) : Restricts the crypto-parameters to an existing keyset.
++ [__Ranges restriction__](<parameter_compatibility_with_restrictions#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.

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.
 

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()