update with comments

README.rst

@@ -16,14 +16,15 @@ Quick Start
 
 We currently provide evaluators for the security of the `LWE`, `NTRU`, and `SIS` problems. 
 Our estimator integrates simulators for the best known attacks against these problems, and provides
-bit-security estimates relying on heuristics to predict the cost of lattice reduction algorithms, the default being
-using `[MATZOV22] <https://zenodo.org/record/6412487>` for lattice reduction cost, and the GSA assumption 
-`[Schnorr03] <http://dx.doi.org/10.1007/3-540-36494-3_14>` for the reduction shape. 
+bit-security estimates relying on heuristics to predict the cost and shape of lattice reduction algorithms. The default
+models are configured in `conf.py <https://github.com/malb/lattice-estimator/blob/main/estimator/conf.py>`.
 
 It is possible to evaluate attacks cost individually, or using the helper functions:
 - `*.estimator.rough`: fast routine that evaluates the security of the problem only against the usually most efficient
-   attacks. In this case, note that the concrete lattice reduction cost is evaluated using the non-default "Core-SVP" method
-   from `[USENIX:ADPS16] <https://www.usenix.org/system/files/conference/usenixsecurity16/sec16_paper_alkim.pdf>`.
+   attacks. Note that it uses a non-default cost model for lattice reduction, most often used in the literature for ease of 
+   comparison, and will thus return different numbers than the rest of the API. Refer to 
+   `its documentation <https://lattice-estimator.readthedocs.io/en/latest/_apidoc/estimator.lwe/estimator.lwe.Estimate/estimator.lwe.Estimate.rough.html>` 
+   for details.
 - `*.estimator`: extended routine that evaluates the security of the problem against all supported attacks. This uses the
    default cost and shape model for lattice reduction.
 

docs/algorithms/lwe-dual.rst

@@ -22,6 +22,6 @@ Further improvements are possible using a meet-in-the-middle approach [EPRINT:CH
 
    dual_hybrid(params, mitm_optimization=True)
 
-We consider the variant fron [MATZOV22]_::
+We consider the variant from [MATZOV22]_::
 
    matzov(params)

docs/algorithms/sis-lattice.rst

@@ -32,5 +32,5 @@ Another option is to simulate a rerandomization of the basis, such that the q-ve
 
     SIS.lattice(params.updated(length_bound=70), red_shape_model=Simulator.LGSA)
 
-**Note:** Currently, lattice attack estimation is only avalailable for euclidean (``2``) and infinity (``oo``) norms. ``SIS.lattice()`` will return a ``NotImplementedError`` if one of these two norms are not selected.
+**Note:** Currently, lattice attack estimation is only available for euclidean (``2``) and infinity (``oo``) norms. ``SIS.lattice()`` will return a ``NotImplementedError`` if one of these two norms are not selected.
 

estimator/conf.py

@@ -7,10 +7,15 @@
 from .reduction import RC
 from sage.all import exp
 
+"""
+Default models used to evaluate the cost and shape of lattice reduction.
+This influences the concrete estimated cost of attacks.
+"""
 red_cost_model = RC.MATZOV
 red_cost_model_classical_poly_space = RC.ABLR21
 red_shape_model = "gsa"
 red_simulator = GSA
+
 mitm_opt = "analytical"
 max_n_cache = 10000
 

estimator/lwe.py

@@ -25,21 +25,21 @@ class Estimate:
 
     def rough(self, params, jobs=1, catch_exceptions=True):
         """
-        This function makes the following somewhat routine assumptions:
+        This function makes the following (non-default) somewhat routine assumptions to evaluate the cost of lattice 
+        reduction, and to provide comparable numbers with most of the literature:
 
         - The GSA holds.
         - The Core-SVP model holds.
 
+        Provided numbers are notably not directly comparable with the rest of our API, when using the default cost models.
+
         This function furthermore assumes the following heuristics:
 
         - The primal hybrid attack only applies to sparse secrets.
         - The dual hybrid MITM attack only applies to sparse secrets.
         - Arora-GB only applies to bounded noise with at least `n^2` samples.
         - BKW is not competitive.
 
-        Lattice reduction cost is evaluated based on the non-default "Core-SVP" method from
-        [USENIX:ADPS16].
-
         :param params: LWE parameters.
         :param jobs: Use multiple threads in parallel.
         :param catch_exceptions: When an estimate fails, just print a warning.
@@ -96,7 +96,7 @@ def __call__(
         catch_exceptions=True,
     ):
         """
-        Run all estimates.
+        Run all estimates, based on the default cost and shape models for lattice reduction.
 
         :param params: LWE parameters.
         :param red_cost_model: How to cost lattice reduction.

estimator/ntru.py

@@ -22,20 +22,20 @@ class Estimate:
 
     def rough(self, params, jobs=1, catch_exceptions=True):
         """
-        This function makes the following somewhat routine assumptions:
+        This function makes the following (non-default) somewhat routine assumptions to evaluate the cost of lattice 
+        reduction, and to provide comparable numbers with most of the literature:
 
         - The ZGSA holds.
         - The Core-SVP model holds.
 
+        Provided numbers are notably not directly comparable with the rest of our API, when using the default cost models.
+
         This function furthermore assumes the following heuristics:
 
         - The primal hybrid attack only applies to sparse secrets.
         - The dual hybrid MITM attack only applies to sparse secrets.
         - The dense sublattice attack only applies to possibly overstretched parameters
 
-        Lattice reduction cost is evaluated based on the non-default "Core-SVP" method from
-        [USENIX:ADPS16].
-
         :param params: NTRU parameters.
         :param jobs: Use multiple threads in parallel.
         :param catch_exceptions: When an estimate fails, just print a warning.
@@ -94,7 +94,7 @@ def __call__(
         catch_exceptions=True,
     ):
         """
-        Run all estimates.
+        Run all estimates, based on the default cost and shape models for lattice reduction.
 
         :param params: NTRU parameters.
         :param red_cost_model: How to cost lattice reduction.

estimator/sis.py

@@ -19,17 +19,17 @@
 class Estimate:
     def rough(self, params, jobs=1, catch_exceptions=True):
         """
-        This function makes the following somewhat routine assumptions:
+        This function makes the following (non-default) somewhat routine assumptions to evaluate the cost of lattice 
+        reduction, and to provide comparable numbers with most of the literature:
 
         - The LGSA holds.
         - The Core-SVP model holds.
 
+        Provided numbers are notably not directly comparable with the rest of our API, when using the default cost models.
+
         This function furthermore assumes the following heuristics:
         - None at the moment. May change as more algorithms are added.
 
-        Lattice reduction cost is evaluated based on the non-default "Core-SVP" method from
-        [USENIX:ADPS16].
-
         :param params: SIS parameters.
         :param jobs: Use multiple threads in parallel.
         :param catch_exceptions: When an estimate fails, just print a warning.
@@ -77,7 +77,7 @@ def __call__(
         catch_exceptions=True,
     ):
         """
-        Run all estimates.
+        Run all estimates, based on the default cost and shape models for lattice reduction.
 
         :param params: SIS parameters.
         :param red_cost_model: How to cost lattice reduction.