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,80 @@
+# Parameters compatibility with restrictions
+
+When compiling a module, the optimizer analyzes the circuits and the expected probability of error, to find the fastest crypto-parameters suiting those constraints. Depending on the crypto-parameters found, the size of the keys (and the ciphertexts) will differ. This means that if an existing module is used in production (using a certain set of crypto-parameters), there is no guarantee that a compilation of a second (different) module will yield compatible crypto-parameters.
+
+Concrete provides a way to ensure that a compilation is going to yield compatible crypto-parameters, thanks to _restrictions_. Restrictions are going to restrict the search-space walked by the optimizer to ensure that only compatible parameters can be returnedyielded. As of now, we support two major restrictions:
+
++ __Keyset restriction__ : Restricts the crypto-parameters to an existing keyset. This restriction is suited for users that already have a module in production, and want to compile a compatible module.
++ __Ranges restriction__ : Restricts the crypto-parameters ranges allowed in the optimizer. This restriction is suited to users targetting a specific backend which does not support the breadth of parameters available on CPU.
+
+## Keyset restriction
+
+The keyset restriction can be generated 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()
+
+# 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
+```
+
+## Ranges restriction
+
+A ranges restriction can be built 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()