Skip to content

Commit

Permalink
refactor: sage docstrings migration to python MQ
Browse files Browse the repository at this point in the history 
Applied changes discussed at
#169
to MQEstimator.
  • Loading branch information
@Dioprz
Dioprz committed Sep 18, 2024
1 parent 68d1aec commit e9698db
Show file tree
Hide file tree
Showing 21 changed files with 1,219 additions and 1,494 deletions.
10 changes: 5 additions & 5 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,11 +81,9 @@ docker-test: docker-build
@docker run --name container-for-test -d -it ${image_name} sh \
&& docker exec container-for-test sh -c " \
sage -t --long --timeout 3600 --force-lib \
# cryptographic_estimators/SDEstimator/ \
cryptographic_estimators/DummyEstimator/ \
cryptographic_estimators/LEEstimator/ \
cryptographic_estimators/MAYOEstimator/ \
cryptographic_estimators/MQEstimator/ \
cryptographic_estimators/MREstimator/ \
cryptographic_estimators/PEEstimator/ \
cryptographic_estimators/PKEstimator/ \
Expand All @@ -98,6 +96,8 @@ docker-test: docker-build
cryptographic_estimators/base_problem.py \
cryptographic_estimators/estimation_renderer.py \
cryptographic_estimators/helper.py \
# cryptographic_estimators/SDEstimator/ \
# cryptographic_estimators/MQEstimator/ \
" \
&& echo "All tests passed." \
|| echo "Some test have failed, please see previous lines."
Expand All @@ -113,11 +113,9 @@ docker-testfast: docker-build
@docker run --name container-for-test -d -it ${image_name} sh \
&& docker exec container-for-test sh -c " \
sage -t --timeout 3600 --force-lib \
# cryptographic_estimators/SDEstimator/ \
cryptographic_estimators/DummyEstimator/ \
cryptographic_estimators/LEEstimator/ \
cryptographic_estimators/MAYOEstimator/ \
cryptographic_estimators/MQEstimator/ \
cryptographic_estimators/MREstimator/ \
cryptographic_estimators/PEEstimator/ \
cryptographic_estimators/PKEstimator/ \
Expand All @@ -130,6 +128,8 @@ docker-testfast: docker-build
cryptographic_estimators/base_problem.py \
cryptographic_estimators/estimation_renderer.py \
cryptographic_estimators/helper.py \
# cryptographic_estimators/SDEstimator/ \
# cryptographic_estimators/MQEstimator/ \
" \
&& echo "All tests passed." \
|| echo "Some test have failed, please see previous lines."
Expand All @@ -148,10 +148,10 @@ docker-pytest:
&& docker exec pytest-estimators sh -c " \
pytest --doctest-modules -n auto -vv \
cryptographic_estimators/SDEstimator/ \
cryptographic_estimators/MQEstimator/ \
# cryptographic_estimators/DummyEstimator/ \
# cryptographic_estimators/LEEstimator/ \
# cryptographic_estimators/MAYOEstimator/ \
# cryptographic_estimators/MQEstimator/ \
# cryptographic_estimators/MREstimator/ \
# cryptographic_estimators/PEEstimator/ \
# cryptographic_estimators/PKEstimator/ \
Expand Down
137 changes: 62 additions & 75 deletions cryptographic_estimators/MQEstimator/MQAlgorithms/bjorklund.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,34 +20,29 @@
from ...MQEstimator.mq_problem import MQProblem
from ...MQEstimator.mq_helper import sum_of_binomial_coefficients
from ...base_algorithm import optimal_parameter
from math import log2, inf, floor, ceil
from math import log2, floor, ceil


class Bjorklund(MQAlgorithm):
r"""
Construct an instance of Bjorklund et al.'s estimator
Bjorklund et al.'s is a probabilistic algorithm to solve the MQ problem of GF(2) [BKW19]_. It finds a solution of a qudractic
system by computing the parity of it number of solutions.
INPUT:
- ``problem`` --MQProblem object including all necessary parameters
- ``h`` -- external hybridization parameter (default: 0)
- ``memory_access`` -- specifies the memory access cost model (default: 0, choices: 0 - constant, 1 - logarithmic, 2 - square-root, 3 - cube-root or deploy custom function which takes as input the logarithm of the total memory usage)
- ``complexity_type`` -- complexity type to consider (0: estimate, 1: tilde O complexity, default: 0)
EXAMPLES::
sage: from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
sage: from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
sage: E = Bjorklund(MQProblem(n=10, m=12, q=2))
sage: E
Björklund et al. estimator for the MQ problem with 10 variables and 12 polynomials
"""

def __init__(self, problem: MQProblem, **kwargs):
"""Construct an instance of Bjorklund et al.'s estimator.
Bjorklund et al.'s is a probabilistic algorithm to solve the MQ problem of GF(2) [BKW19]_. It finds a solution of a quadratic
system by computing the parity of its number of solutions.
Args:
problem (MQProblem): MQProblem object including all necessary parameters.
h (int, optional): External hybridization parameter (default: 0).
memory_access (int, optional): Specifies the memory access cost model (default: 0, choices: 0 - constant, 1 - logarithmic, 2 - square-root, 3 - cube-root or deploy custom function which takes as input the logarithm of the total memory usage).
complexity_type (int, optional): Complexity type to consider (0: estimate, 1: tilde O complexity, default: 0).
Examples:
>>> from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
>>> from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
>>> E = Bjorklund(MQProblem(n=10, m=12, q=2))
>>> E
Björklund et al. estimator for the MQ problem with 10 variables and 12 polynomials
"""
if problem.order_of_the_field() != 2:
raise TypeError("q must be equal to 2")
super().__init__(problem, **kwargs)
Expand All @@ -65,14 +60,13 @@ def __init__(self, problem: MQProblem, **kwargs):
@optimal_parameter
def lambda_(self):
"""
Return the optimal lambda_
Return the optimal lambda_.
EXAMPLES::
sage: from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
sage: from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
sage: E = Bjorklund(MQProblem(n=10, m=12, q=2))
sage: E.lambda_()
Examples:
>>> from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
>>> from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
>>> E = Bjorklund(MQProblem(n=10, m=12, q=2))
>>> E.lambda_()
3/10
"""

Expand All @@ -94,18 +88,16 @@ def _valid_choices(self):

def _compute_time_complexity(self, parameters: dict):
"""
Return the time complexity of the algorithm for a given set of parameters
INPUT:
- ``parameters`` -- dictionary including the parameters
TESTS::
sage: from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
sage: from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
sage: E = Bjorklund(MQProblem(n=10, m=12, q=2), bit_complexities=False)
sage: E.time_complexity(lambda_=7/10)
Return the time complexity of the algorithm for a given set of parameters.
Args:
parameters (dict): Dictionary including the parameters.
Tests:
>>> from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
>>> from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
>>> E = Bjorklund(MQProblem(n=10, m=12, q=2), bit_complexities=False)
>>> E.time_complexity(lambda_=7/10)
49.55664699444167
"""
lambda_ = parameters["lambda_"]
Expand All @@ -127,18 +119,16 @@ def _compute_time_complexity(self, parameters: dict):

def _compute_memory_complexity(self, parameters: dict):
"""
Return the memory complexity of the algorithm for a given set of parameters
INPUT:
- ``parameters`` -- dictionary including the parameters
TESTS::
sage: from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
sage: from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
sage: E = Bjorklund(MQProblem(n=10, m=12, q=2), bit_complexities=False)
sage: E.memory_complexity(lambda_=7/10)
Compute the memory complexity of the algorithm for a given set of parameters.
Args:
parameters (dict): A dictionary containing the relevant parameters.
Tests:
>>> from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
>>> from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
>>> E = Bjorklund(MQProblem(n=10, m=12, q=2), bit_complexities=False)
>>> E.memory_complexity(lambda_=7/10)
10.225233514599497
"""

Expand Down Expand Up @@ -167,12 +157,11 @@ def _compute_tilde_o_time_complexity(self, parameters: dict):
"""
Return the Ō time complexity of Bjorklund et al.'s algorithm
TESTS::
sage: from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
sage: from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
sage: E = Bjorklund(MQProblem(n=10, m=12, q=2), complexity_type=1)
sage: E.time_complexity(lambda_=7/10)
Tests:
>>> from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
>>> from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
>>> E = Bjorklund(MQProblem(n=10, m=12, q=2), complexity_type=1)
>>> E.time_complexity(lambda_=7/10)
8.03225
"""
n = self.nvariables_reduced()
Expand All @@ -183,12 +172,11 @@ def _compute_tilde_o_memory_complexity(self, parameters: dict):
"""
Return the Ō time complexity of Bjorklund et al.'s algorithm
TESTS::
sage: from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
sage: from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
sage: E = Bjorklund(MQProblem(n=10, m=12, q=2), complexity_type=1)
sage: E.memory_complexity(lambda_=7/10)
Tests:
>>> from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
>>> from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
>>> E = Bjorklund(MQProblem(n=10, m=12, q=2), complexity_type=1)
>>> E.memory_complexity(lambda_=7/10)
3
"""
n = self.nvariables_reduced()
Expand All @@ -199,25 +187,24 @@ def _find_optimal_tilde_o_parameters(self):
"""
Return the Ō time complexity of Bjorklund et al.'s algorithm
TESTS::
sage: from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
sage: from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
sage: E = Bjorklund(MQProblem(n=10, m=12, q=2), complexity_type=1)
sage: E.optimal_parameters()
Tests:
>>> from cryptographic_estimators.MQEstimator.MQAlgorithms.bjorklund import Bjorklund
>>> from cryptographic_estimators.MQEstimator.mq_problem import MQProblem
>>> E = Bjorklund(MQProblem(n=10, m=12, q=2), complexity_type=1)
>>> E.optimal_parameters()
{'lambda_': 0.19677}
"""
self._optimal_parameters["lambda_"] = 0.19677

@staticmethod
def _internal_time_complexity_(n: int, m: int, lambda_: float):
"""
Helper function. Computes the runtime of the algorithm for given n, m and lambda
Helper function. Computes the runtime of the algorithm for given n, m and lambda.
ALgorithm taken from: Stefano Barbero et al. Practical complexities of probabilistic algorithms for solving
Boolean polynomial systems. Cryptology ePrint Archive, Paper 2021/913. https://
eprint . iacr . org / 2021 / 913. 2021. doi: 10 . 1016 / j . dam . 2021 . 11 . 014. url:
https://eprint.iacr.org/2021/913
https://eprint.iacr.org/2021/913.
"""
# uses brute force
if n <= 1:
Expand Down
Loading

0 comments on commit e9698db

Please sign in to comment.