Remove duplicate implementation of Collatz sequence

DIRECTORY.md

@@ -167,7 +167,7 @@
  * Arrays
  * [Permutations](data_structures/arrays/permutations.py)
  * [Prefix Sum](data_structures/arrays/prefix_sum.py)
- * [Product Sum Array](data_structures/arrays/product_sum.py)
+ * [Product Sum](data_structures/arrays/product_sum.py)
  * Binary Tree
  * [Avl Tree](data_structures/binary_tree/avl_tree.py)
  * [Basic Binary Tree](data_structures/binary_tree/basic_binary_tree.py)
@@ -522,7 +522,6 @@
  * [Xgboost Regressor](machine_learning/xgboost_regressor.py)
 
 ## Maths
- * [3N Plus 1](maths/3n_plus_1.py)
  * [Abs](maths/abs.py)
  * [Add](maths/add.py)
  * [Addition Without Arithmetic](maths/addition_without_arithmetic.py)

maths/collatz_sequence.py

@@ -1,43 +1,66 @@
+"""
+The Collatz conjecture is a famous unsolved problem in mathematics. Given a starting
+positive integer, define the following sequence:
+- If the current term n is even, then the next term is n/2.
+- If the current term n is odd, then the next term is 3n + 1.
+The conjecture claims that this sequence will always reach 1 for any starting number.
+
+Other names for this problem include the 3n + 1 problem, the Ulam conjecture, Kakutani's
+problem, the Thwaites conjecture, Hasse's algorithm, the Syracuse problem, and the
+hailstone sequence.
+
+Reference: https://en.wikipedia.org/wiki/Collatz_conjecture
+"""
+
 from __future__ import annotations
 
+from collections.abc import Generator
 
-def collatz_sequence(n: int) -> list[int]:
+
+def collatz_sequence(n: int) -> Generator[int, None, None]:
  """
- Collatz conjecture: start with any positive integer n. The next term is
- obtained as follows:
- If n term is even, the next term is: n / 2 .
- If n is odd, the next term is: 3 * n + 1.
-
- The conjecture states the sequence will always reach 1 for any starting value n.
- Example:
- >>> collatz_sequence(2.1)
+ Generate the Collatz sequence starting at n.
+ >>> tuple(collatz_sequence(2.1))
  Traceback (most recent call last):
  ...
- Exception: Sequence only defined for natural numbers
- >>> collatz_sequence(0)
+ Exception: Sequence only defined for positive integers
+ >>> tuple(collatz_sequence(0))
  Traceback (most recent call last):
  ...
- Exception: Sequence only defined for natural numbers
- >>> collatz_sequence(43) # doctest: +NORMALIZE_WHITESPACE
- [43, 130, 65, 196, 98, 49, 148, 74, 37, 112, 56, 28, 14, 7,
- 22, 11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1]
+ Exception: Sequence only defined for positive integers
+ >>> tuple(collatz_sequence(4))
+ (4, 2, 1)
+ >>> tuple(collatz_sequence(11))
+ (11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1)
+ >>> tuple(collatz_sequence(31)) # doctest: +NORMALIZE_WHITESPACE
+ (31, 94, 47, 142, 71, 214, 107, 322, 161, 484, 242, 121, 364, 182, 91, 274, 137,
+ 412, 206, 103, 310, 155, 466, 233, 700, 350, 175, 526, 263, 790, 395, 1186, 593,
+ 1780, 890, 445, 1336, 668, 334, 167, 502, 251, 754, 377, 1132, 566, 283, 850, 425,
+ 1276, 638, 319, 958, 479, 1438, 719, 2158, 1079, 3238, 1619, 4858, 2429, 7288, 3644,
+ 1822, 911, 2734, 1367, 4102, 2051, 6154, 3077, 9232, 4616, 2308, 1154, 577, 1732,
+ 866, 433, 1300, 650, 325, 976, 488, 244, 122, 61, 184, 92, 46, 23, 70, 35, 106, 53,
+ 160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1)
+ >>> tuple(collatz_sequence(43)) # doctest: +NORMALIZE_WHITESPACE
+ (43, 130, 65, 196, 98, 49, 148, 74, 37, 112, 56, 28, 14, 7, 22, 11, 34, 17, 52, 26,
+ 13, 40, 20, 10, 5, 16, 8, 4, 2, 1)
  """
-
  if not isinstance(n, int) or n < 1:
- raise Exception("Sequence only defined for natural numbers")
+ raise Exception("Sequence only defined for positive integers")
 
-sequence = [n]
+yield n
  while n != 1:
- n = 3 * n + 1 if n & 1 else n // 2
- sequence.append(n)
- return sequence
+ if n % 2 == 0:
+ n //= 2
+ else:
+ n = 3 * n + 1
+ yield n
 
 
 def main():
  n = 43
- sequence = collatz_sequence(n)
+ sequence = tuple(collatz_sequence(n))
  print(sequence)
- print(f"collatz sequence from {n} took {len(sequence)} steps.")
+ print(f"Collatz sequence from {n} took {len(sequence)} steps.")
 
 
 if __name__ == "__main__":