docstring run_cube_attack

src/tea3/cube_attack.py

@@ -194,6 +194,29 @@ def run_cube_attack(
     fixed_one_bits: Sequence[str] | None = None,
     model: Tea3Model | None = None,
 ):
+    """
+    Offline phase of the cube attack.
+    Search for candidate cubes in TEA-3 model.
+
+    Builds the ANF of a selected output bit after the specified number of rounds, optionally fixing some public variables to 0 or 1.
+    It then searches, exhaustively or randomly, for cubes with a cube sum (superpoly) of degree at most ``max_degree``.
+
+    Prints a summary of the search parameters and each candidate cube found:
+        variables, superpoly degree, monomial count, and superpoly.
+
+    Args:
+        rounds: Number of cipher rounds to analyze.
+        target_reg: Index of the target register.
+        target_bit: Bit of the target register whose ANF is analyzed.
+        cube_size: Number of public variables in each candidate cube.
+        mode: Search strategy, either ``"random"`` or ``"exhaustive"``.
+        samples: Number of random cubes to test when using random search.
+        limit: Maximum number of candidate cubes to display.
+        max_degree: Maximum accepted degree of the resulting superpoly.
+        fixed_zero_bits: Public variables to fix to 0 before analysis.
+        fixed_one_bits: Public variables to fix to 1 before analysis.
+        model: Optional precomputed ``Tea3Model``.
+    """
     fixed_bits: dict[str, int] = {}
 
     if fixed_zero_bits: