TheAlgorithms-Python

1
from __future__ import annotations
2

3
from math import gcd
4

5

6
def pollard_rho(
7
    num: int,
8
    seed: int = 2,
9
    step: int = 1,
10
    attempts: int = 3,
11
) -> int | None:
12
    """
13
    Use Pollard's Rho algorithm to return a nontrivial factor of ``num``.
14
    The returned factor may be composite and require further factorization.
15
    If the algorithm will return None if it fails to find a factor within
16
    the specified number of attempts or within the specified number of steps.
17
    If ``num`` is prime, this algorithm is guaranteed to return None.
18
    https://en.wikipedia.org/wiki/Pollard%27s_rho_algorithm
19

20
    >>> pollard_rho(18446744073709551617)
21
    274177
22
    >>> pollard_rho(97546105601219326301)
23
    9876543191
24
    >>> pollard_rho(100)
25
    2
26
    >>> pollard_rho(17)
27
    >>> pollard_rho(17**3)
28
    17
29
    >>> pollard_rho(17**3, attempts=1)
30
    >>> pollard_rho(3*5*7)
31
    21
32
    >>> pollard_rho(1)
33
    Traceback (most recent call last):
34
        ...
35
    ValueError: The input value cannot be less than 2
36
    """
37
    # A value less than 2 can cause an infinite loop in the algorithm.
38
    if num < 2:
39
        raise ValueError("The input value cannot be less than 2")
40

41
    # Because of the relationship between ``f(f(x))`` and ``f(x)``, this
42
    # algorithm struggles to find factors that are divisible by two.
43
    # As a workaround, we specifically check for two and even inputs.
44
    #   See: https://math.stackexchange.com/a/2856214/165820
45
    if num > 2 and num % 2 == 0:
46
        return 2
47

48
    # Pollard's Rho algorithm requires a function that returns pseudorandom
49
    # values between 0 <= X < ``num``.  It doesn't need to be random in the
50
    # sense that the output value is cryptographically secure or difficult
51
    # to calculate, it only needs to be random in the sense that all output
52
    # values should be equally likely to appear.
53
    # For this reason, Pollard suggested using ``f(x) = (x**2 - 1) % num``
54
    # However, the success of Pollard's algorithm isn't guaranteed and is
55
    # determined in part by the initial seed and the chosen random function.
56
    # To make retries easier, we will instead use ``f(x) = (x**2 + C) % num``
57
    # where ``C`` is a value that we can modify between each attempt.
58
    def rand_fn(value: int, step: int, modulus: int) -> int:
59
        """
60
        Returns a pseudorandom value modulo ``modulus`` based on the
61
        input ``value`` and attempt-specific ``step`` size.
62

63
        >>> rand_fn(0, 0, 0)
64
        Traceback (most recent call last):
65
            ...
66
        ZeroDivisionError: integer division or modulo by zero
67
        >>> rand_fn(1, 2, 3)
68
        0
69
        >>> rand_fn(0, 10, 7)
70
        3
71
        >>> rand_fn(1234, 1, 17)
72
        16
73
        """
74
        return (pow(value, 2) + step) % modulus
75

76
    for _ in range(attempts):
77
        # These track the position within the cycle detection logic.
78
        tortoise = seed
79
        hare = seed
80

81
        while True:
82
            # At each iteration, the tortoise moves one step and the hare moves two.
83
            tortoise = rand_fn(tortoise, step, num)
84
            hare = rand_fn(hare, step, num)
85
            hare = rand_fn(hare, step, num)
86

87
            # At some point both the tortoise and the hare will enter a cycle whose
88
            # length ``p`` is a divisor of ``num``.  Once in that cycle, at some point
89
            # the tortoise and hare will end up on the same value modulo ``p``.
90
            # We can detect when this happens because the position difference between
91
            # the tortoise and the hare will share a common divisor with ``num``.
92
            divisor = gcd(hare - tortoise, num)
93

94
            if divisor == 1:
95
                # No common divisor yet, just keep searching.
96
                continue
97
            # We found a common divisor!
98
            elif divisor == num:
99
                # Unfortunately, the divisor is ``num`` itself and is useless.
100
                break
101
            else:
102
                # The divisor is a nontrivial factor of ``num``!
103
                return divisor
104

105
        # If we made it here, then this attempt failed.
106
        # We need to pick a new starting seed for the tortoise and hare
107
        # in addition to a new step value for the random function.
108
        # To keep this example implementation deterministic, the
109
        # new values will be generated based on currently available
110
        # values instead of using something like ``random.randint``.
111

112
        # We can use the hare's position as the new seed.
113
        # This is actually what Richard Brent's the "optimized" variant does.
114
        seed = hare
115

116
        # The new step value for the random function can just be incremented.
117
        # At first the results will be similar to what the old function would
118
        # have produced, but the value will quickly diverge after a bit.
119
        step += 1
120

121
    # We haven't found a divisor within the requested number of attempts.
122
    # We were unlucky or ``num`` itself is actually prime.
123
    return None
124

125

126
if __name__ == "__main__":
127
    import argparse
128

129
    parser = argparse.ArgumentParser()
130
    parser.add_argument(
131
        "num",
132
        type=int,
133
        help="The value to find a divisor of",
134
    )
135
    parser.add_argument(
136
        "--attempts",
137
        type=int,
138
        default=3,
139
        help="The number of attempts before giving up",
140
    )
141
    args = parser.parse_args()
142

143
    divisor = pollard_rho(args.num, attempts=args.attempts)
144
    if divisor is None:
145
        print(f"{args.num} is probably prime")
146
    else:
147
        quotient = args.num // divisor
148
        print(f"{args.num} = {divisor} * {quotient}")
149