Merge pull request #2 from tubs-alg/fix/hw01-ex03-python-timeout

HW01/ex03: add timeout to Python 2-opt variants

Author: d-krupke

homework/HW01/exercise03/README.md

@@ -3,6 +3,19 @@
 This exercise implements the 2-opt heuristic for the Traveling Salesman Problem
 using several move-selection strategies, in both Python and C++.
 
+## Updates
+
+Post-release fixes. Only changes that affect your workflow are listed here;
+see `git log` for the full history.
+
+- **2026-04-16** — Python variants (`first_improvement_two_opt`,
+  `full_scan_two_opt`, `best_improvement_two_opt`) now take an optional
+  `timeout: float = 10.0` parameter, matching the C++ API. If you already
+  started: add the parameter to your signature and check a deadline
+  (`time.perf_counter()`) in your outer loop — coarse-grained checks after
+  each restart or full sweep are enough. Without this, `benchmark.py` could
+  run for hours on large `n`. See issue #1.
+
 ## Project Structure
 
 ```
@@ -84,16 +97,17 @@ and prints a summary table comparing tour length and runtime.
 
 ## Function Signatures
 
-All single-run functions take a list of `(x, y)` tuples and an `initial_tour`
-(a permutation of `0..n-1`), and return the improved tour. The benchmark
-generates the initial tour in Python and passes it to every variant, so all
-start from the same permutation and results are directly comparable.
+All single-run functions take a list of `(x, y)` tuples, an `initial_tour`
+(a permutation of `0..n-1`), and an optional `timeout` in seconds, and
+return the improved tour. The benchmark generates the initial tour in
+Python and passes it to every variant, so all start from the same
+permutation and results are directly comparable.
 
 ```python
-# Part a: Python variants
-first_improvement_two_opt(points, initial_tour) -> list[int]
-full_scan_two_opt(points, initial_tour) -> list[int]
-best_improvement_two_opt(points, initial_tour) -> list[int]
+# Part a: Python variants (all take an optional timeout in seconds)
+first_improvement_two_opt(points, initial_tour, timeout=10.0) -> list[int]
+full_scan_two_opt(points, initial_tour, timeout=10.0) -> list[int]
+best_improvement_two_opt(points, initial_tour, timeout=10.0) -> list[int]
 
 # Part b: C++ variants (all take an optional timeout in seconds)
 cpp_first_improvement(points, initial_tour, timeout=10.0) -> list[int]
@@ -104,6 +118,11 @@ cpp_best_improvement(points, initial_tour, timeout=10.0) -> list[int]
 parallel_two_opt(points, num_threads=4, base_seed=0, timeout=10.0) -> list[int]
 ```
 
+When the timeout is reached, return the best tour found so far. Coarse-grained
+checks are fine: compare `time.perf_counter()` (Python) or `Clock::now()` (C++)
+against a precomputed deadline after each restart or full sweep, not inside
+the innermost loop.
+
 ## Build Troubleshooting
 
 **C++ changes not taking effect?**

homework/HW01/exercise03/benchmark.py

@@ -164,13 +164,13 @@ def main():
         # Python variants
         print(f"\n  Python:")
         res = run_multi_seed(first_improvement_two_opt, points, initial_tours,
-                             label="first-impr")
+                             label="first-impr", timeout=TIMEOUT)
         rows.append(("first-impr (py)", res))
         res = run_multi_seed(best_improvement_two_opt, points, initial_tours,
-                             label="best-impr")
+                             label="best-impr", timeout=TIMEOUT)
         rows.append(("best-impr (py)", res))
         res = run_multi_seed(full_scan_two_opt, points, initial_tours,
-                             label="full-scan")
+                             label="full-scan", timeout=TIMEOUT)
         rows.append(("full-scan (py)", res))
 
         if have_cpp:

homework/HW01/exercise03/src/tsp_two_opt/best_improvement.py

@@ -8,17 +8,24 @@ def _dist(points, a, b):
 
 
 def best_improvement_two_opt(
-    points: list[tuple[float, float]], initial_tour: list[int]
+    points: list[tuple[float, float]],
+    initial_tour: list[int],
+    timeout: float = 10.0,
 ) -> list[int]:
     """
     Best-improvement 2-opt: scan all pairs, apply only the best move per pass.
 
     Args:
         points: List of (x, y) coordinate tuples.
         initial_tour: Starting tour as a permutation of point indices.
+        timeout: Maximum runtime in seconds. If exceeded, return the best tour
+            found so far. Check ``time.perf_counter()`` against a precomputed
+            deadline after each full sweep (coarse-grained is fine).
 
     Returns:
         Tour as a list of point indices.
     """
     # TODO: Implement Variant 3 (best-improvement).
+    # Respect ``timeout``: compute ``deadline = time.perf_counter() + timeout``
+    # and break out of the outer loop once the deadline is reached.
     raise NotImplementedError

homework/HW01/exercise03/src/tsp_two_opt/first_improvement.py

@@ -8,17 +8,24 @@ def _dist(points, a, b):
 
 
 def first_improvement_two_opt(
-    points: list[tuple[float, float]], initial_tour: list[int]
+    points: list[tuple[float, float]],
+    initial_tour: list[int],
+    timeout: float = 10.0,
 ) -> list[int]:
     """
     First-improvement 2-opt (classical): find first improving move, apply, restart.
 
     Args:
         points: List of (x, y) coordinate tuples.
         initial_tour: Starting tour as a permutation of point indices.
+        timeout: Maximum runtime in seconds. If exceeded, return the best tour
+            found so far. Check ``time.perf_counter()`` against a precomputed
+            deadline after each restart (coarse-grained is fine).
 
     Returns:
         Tour as a list of point indices.
     """
     # TODO: Implement Variant 1 (first-improvement with restart).
+    # Respect ``timeout``: compute ``deadline = time.perf_counter() + timeout``
+    # and break out of the outer loop once the deadline is reached.
     raise NotImplementedError

homework/HW01/exercise03/src/tsp_two_opt/full_scan.py

@@ -8,17 +8,24 @@ def _dist(points, a, b):
 
 
 def full_scan_two_opt(
-    points: list[tuple[float, float]], initial_tour: list[int]
+    points: list[tuple[float, float]],
+    initial_tour: list[int],
+    timeout: float = 10.0,
 ) -> list[int]:
     """
     Full-scan 2-opt: apply improvements immediately, continue scanning.
 
     Args:
         points: List of (x, y) coordinate tuples.
         initial_tour: Starting tour as a permutation of point indices.
+        timeout: Maximum runtime in seconds. If exceeded, return the best tour
+            found so far. Check ``time.perf_counter()`` against a precomputed
+            deadline after each full sweep (coarse-grained is fine).
 
     Returns:
         Tour as a list of point indices.
     """
     # TODO: Implement Variant 2 (full-scan, continue after improvement).
+    # Respect ``timeout``: compute ``deadline = time.perf_counter() + timeout``
+    # and break out of the outer loop once the deadline is reached.
     raise NotImplementedError