algorithm-discovery-engine 1.0.0__py3-none-any.whl

ads/__init__.py

@@ -0,0 +1,85 @@
+"""Algorithms & Data Structures solving engine (Python).
+
+Two tiers are provided for every problem:
+
+* :mod:`ads.problems` / :mod:`ads.structures` — the *regular* tier:
+  readable, deliberately simple implementations that mirror the Java, C++
+  and Rust ports 1:1.
+* :mod:`ads.problems_advanced` / :mod:`ads.structures_advanced` — the
+  *advanced* tier: memory- and speed-optimized variants (rolling DP,
+  in-place sorts, slot-allocated nodes, manual heaps).
+
+A single catalogue (``catalog/problems.json`` at the repo root) holds the
+shared test vectors used by all four languages.
+"""
+
+from ads.problems import (
+    binary_search,
+    edit_distance,
+    graph_bfs,
+    graph_dfs,
+    knapsack_01,
+    lcs,
+    max_subarray,
+    merge_sort,
+    quick_sort,
+    two_sum,
+)
+from ads.problems_advanced import (
+    binary_search_advanced,
+    edit_distance_advanced,
+    graph_bfs_advanced,
+    graph_dfs_advanced,
+    knapsack_01_advanced,
+    lcs_advanced,
+    max_subarray_advanced,
+    merge_sort_advanced,
+    quick_sort_advanced,
+    two_sum_advanced,
+)
+from ads.structures import BST, LinkedList, MinHeap, Queue, Stack, Trie
+from ads.structures_advanced import (
+    BSTAdvanced,
+    LinkedListAdvanced,
+    MinHeapAdvanced,
+    QueueAdvanced,
+    StackAdvanced,
+    TrieAdvanced,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BST",
+    "BSTAdvanced",
+    "LinkedList",
+    "LinkedListAdvanced",
+    "MinHeap",
+    "MinHeapAdvanced",
+    "Queue",
+    "QueueAdvanced",
+    "Stack",
+    "StackAdvanced",
+    "Trie",
+    "TrieAdvanced",
+    "binary_search",
+    "binary_search_advanced",
+    "edit_distance",
+    "edit_distance_advanced",
+    "graph_bfs",
+    "graph_bfs_advanced",
+    "graph_dfs",
+    "graph_dfs_advanced",
+    "knapsack_01",
+    "knapsack_01_advanced",
+    "lcs",
+    "lcs_advanced",
+    "max_subarray",
+    "max_subarray_advanced",
+    "merge_sort",
+    "merge_sort_advanced",
+    "quick_sort",
+    "quick_sort_advanced",
+    "two_sum",
+    "two_sum_advanced",
+]

ads/benchmark.py

@@ -0,0 +1,84 @@
+"""Cross-language benchmark workload (mirrors Java/C++/Rust benches).
+
+Fixed seed + fixed sizes so `engine/runner.py bench` can tabulate per-algorithm
+wall time. Run directly with `python -m ads.benchmark`.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Callable
+
+from ads import problems, problems_advanced
+
+
+def _random_ints(count: int, seed: int) -> list[int]:
+    rng = random.Random(seed)
+    return [rng.randrange(1_000_000_000) for _ in range(count)]
+
+
+def _random_string(length: int, seed: int) -> str:
+    rng = random.Random(seed)
+    return "".join(rng.choice("abcdefgh") for _ in range(length))
+
+
+def _chain_graph(size: int) -> list[list[int]]:
+    return [
+        [neighbor for neighbor in (i - 1, i + 1) if 0 <= neighbor < size]
+        for i in range(size)
+    ]
+
+
+def _time_it(label: str, task: Callable[[], object]) -> None:
+    started = time.perf_counter()
+    task()
+    elapsed_us = (time.perf_counter() - started) * 1_000_000
+    print(f"{label}: {elapsed_us:.0f} us")
+
+
+def run() -> None:
+    data = _random_ints(200_000, 42)
+    sorted_data = list(range(1_000_000))
+
+    _time_it("merge_sort", lambda: problems.merge_sort(data))
+    _time_it("quick_sort", lambda: problems.quick_sort(_random_ints(200_000, 42)))
+    _time_it(
+        "max_subarray",
+        lambda: problems_advanced.max_subarray_advanced(_random_ints(500_000, 7)),
+    )
+    _time_it("two_sum", lambda: problems.two_sum(_random_ints(50_000, 9), -1))
+    _time_it(
+        "binary_search",
+        lambda: problems.binary_search(sorted_data, sorted_data[len(sorted_data) // 2]),
+    )
+    _time_it(
+        "lcs",
+        lambda: problems_advanced.lcs_advanced(
+            _random_string(2_000, 11), _random_string(2_000, 13)
+        ),
+    )
+    _time_it(
+        "knapsack_01",
+        lambda: problems_advanced.knapsack_01_advanced(
+            5_000, _random_ints(1_000, 21), _random_ints(1_000, 31)
+        ),
+    )
+    _time_it(
+        "edit_distance",
+        lambda: problems_advanced.edit_distance_advanced(
+            _random_string(1_000, 41), _random_string(1_000, 43)
+        ),
+    )
+    _time_it(
+        "graph_bfs",
+        lambda: problems_advanced.graph_bfs_advanced(_chain_graph(100_000), 0, 99_999),
+    )
+    _time_it(
+        "graph_dfs",
+        lambda: problems_advanced.graph_dfs_advanced(_chain_graph(100_000), 0, 99_999),
+    )
+
+
+if __name__ == "__main__":
+    run()

ads/problems.py

@@ -0,0 +1,190 @@
+"""Regular Python tier: readable baseline implementations.
+
+These mirror the Java / C++ / Rust ports 1:1 and favour clarity over raw
+performance. The advanced tier (:mod:`ads.problems_advanced`) provides the
+memory/speed-optimized variants.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+
+def two_sum(nums: list[int], target: int) -> list[int]:
+    """Indices of the two numbers summing to *target* (or ``[-1, -1]``)."""
+    seen: dict[int, int] = {}
+    for i, value in enumerate(nums):
+        complement = target - value
+        if complement in seen:
+            j = seen[complement]
+            return [j, i] if j < i else [i, j]
+        seen[value] = i
+    return [-1, -1]
+
+
+def binary_search(sorted_nums: list[int], target: int) -> int:
+    """Index of the first occurrence of *target* (lower bound), or ``-1``."""
+    low, high = 0, len(sorted_nums)
+    while low < high:
+        mid = (low + high) // 2
+        if sorted_nums[mid] < target:
+            low = mid + 1
+        else:
+            high = mid
+    if low < len(sorted_nums) and sorted_nums[low] == target:
+        return low
+    return -1
+
+
+def _merge(left: list[int], right: list[int]) -> list[int]:
+    merged: list[int] = []
+    i = j = 0
+    while i < len(left) and j < len(right):
+        if left[i] <= right[j]:
+            merged.append(left[i])
+            i += 1
+        else:
+            merged.append(right[j])
+            j += 1
+    merged.extend(left[i:])
+    merged.extend(right[j:])
+    return merged
+
+
+def merge_sort(nums: list[int]) -> list[int]:
+    """Return a new array sorted ascending (classic merge sort)."""
+    if len(nums) <= 1:
+        return list(nums)
+    mid = len(nums) // 2
+    return _merge(merge_sort(nums[:mid]), merge_sort(nums[mid:]))
+
+
+def _partition(nums: list[int], low: int, high: int) -> int:
+    pivot = nums[high]
+    i = low
+    for j in range(low, high):
+        if nums[j] < pivot:
+            nums[i], nums[j] = nums[j], nums[i]
+            i += 1
+    nums[i], nums[high] = nums[high], nums[i]
+    return i
+
+
+def quick_sort(nums: list[int]) -> list[int]:
+    """Return a new array sorted ascending (in-place quick sort behind the scenes)."""
+    values = list(nums)
+
+    def sort_region(low: int, high: int) -> None:
+        if low >= high:
+            return
+        split = _partition(values, low, high)
+        sort_region(low, split - 1)
+        sort_region(split + 1, high)
+
+    sort_region(0, len(values) - 1)
+    return values
+
+
+def max_subarray(nums: list[int]) -> int:
+    """Maximum contiguous subarray sum (Kadane). Empty -> 0."""
+    best = 0 if not nums else nums[0]
+    running = 0
+    for value in nums:
+        running = max(value, running + value)
+        best = max(best, running)
+    return best
+
+
+def lcs(a: str, b: str) -> int:
+    """Longest common subsequence length (full-table DP)."""
+    rows, cols = len(a) + 1, len(b) + 1
+    table = [[0] * cols for _ in range(rows)]
+    for i in range(1, rows):
+        for j in range(1, cols):
+            if a[i - 1] == b[j - 1]:
+                table[i][j] = table[i - 1][j - 1] + 1
+            else:
+                table[i][j] = max(table[i - 1][j], table[i][j - 1])
+    return table[rows - 1][cols - 1]
+
+
+def knapsack_01(capacity: int, weights: list[int], values: list[int]) -> int:
+    """Maximum value with the 0/1 knapsack constraint (full-table DP)."""
+    dp = [[0] * (capacity + 1) for _ in range(len(weights) + 1)]
+    for item in range(1, len(weights) + 1):
+        weight, value = weights[item - 1], values[item - 1]
+        row_before, row_now = dp[item - 1], dp[item]
+        for cap in range(capacity + 1):
+            if weight <= cap:
+                row_now[cap] = max(row_before[cap], row_before[cap - weight] + value)
+            else:
+                row_now[cap] = row_before[cap]
+    return dp[len(weights)][capacity]
+
+
+def edit_distance(a: str, b: str) -> int:
+    """Levenshtein distance (full-table DP): insert/delete/substitute."""
+    rows, cols = len(a) + 1, len(b) + 1
+    table = [[0] * cols for _ in range(rows)]
+    for i in range(rows):
+        table[i][0] = i
+    for j in range(cols):
+        table[0][j] = j
+    for i in range(1, rows):
+        for j in range(1, cols):
+            cost = 0 if a[i - 1] == b[j - 1] else 1
+            table[i][j] = min(
+                table[i - 1][j] + 1,
+                table[i][j - 1] + 1,
+                table[i - 1][j - 1] + cost,
+            )
+    return table[rows - 1][cols - 1]
+
+
+def _parse_adjacency(encoded: str) -> list[list[int]]:
+    adj: list[list[int]] = []
+    for row in encoded.split(";"):
+        parts = row.split(":")
+        neighbors: list[int] = []
+        if parts[1].strip():
+            neighbors = [int(n) for n in filter(None, parts[1].split())]
+        adj.append(neighbors)
+    return adj
+
+
+def graph_bfs(adj: list[list[int]], start: int, target: int) -> int:
+    """Shortest path length in edges from *start* to *target*, ``-1`` unreachable."""
+    if start == target:
+        return 0
+    if start >= len(adj):
+        return -1
+    distances = [-1] * len(adj)
+    distances[start] = 0
+    pending = deque([start])
+    while pending:
+        node = pending.popleft()
+        for neighbor in adj[node]:
+            if distances[neighbor] != -1:
+                continue
+            distances[neighbor] = distances[node] + 1
+            if neighbor == target:
+                return distances[neighbor]
+            pending.append(neighbor)
+    return -1
+
+
+def graph_dfs(adj: list[list[int]], start: int, target: int) -> bool:
+    """Whether *target* is reachable from *start* (iterative depth-first search)."""
+
+    def visit(node: int, seen: set[int] | None = None) -> bool:
+        seen = set() if seen is None else seen
+        if node == target:
+            return True
+        seen.add(node)
+        return any(
+            neighbor not in seen and visit(neighbor, seen) for neighbor in adj[node]
+        )
+
+    if not adj and start != target:
+        return False
+    return visit(start)

ads/problems_advanced.py

@@ -0,0 +1,203 @@
+"""Advanced Python tier: performance-optimized variants.
+
+Each function is behaviorally equivalent to its :mod:`ads.problems`
+counterpart but trades verbosity for lower constant factors and better
+space usage (rolling DP rows, in-place sorts, iterative graph walks).
+"""
+
+from __future__ import annotations
+
+from bisect import bisect_left
+from collections import deque
+
+
+def two_sum_advanced(nums: list[int], target: int) -> list[int]:
+    """Two-sum with a single pass and early exit (same contract)."""
+    seen: dict[int, int] = {}
+    for i, value in enumerate(nums):
+        other = target - value
+        if other in seen:
+            j = seen[other]
+            return [min(j, i), max(j, i)]
+        seen[value] = i
+    return [-1, -1]
+
+
+def binary_search_advanced(sorted_nums: list[int], target: int) -> int:
+    """Lower-bound binary search delegated to the C-accelerated bisect module."""
+    index = bisect_left(sorted_nums, target)
+    if index < len(sorted_nums) and sorted_nums[index] == target:
+        return index
+    return -1
+
+
+def _merge_into(
+    source: list[int], left: int, mid: int, right: int, buffer: list[int]
+) -> None:
+    buffer[left:right] = source[left:right]
+    i, j, k = left, mid, left
+    while i < mid and j < right:
+        if buffer[i] <= buffer[j]:
+            source[k] = buffer[i]
+            i += 1
+        else:
+            source[k] = buffer[j]
+            j += 1
+        k += 1
+    while i < mid:
+        source[k] = buffer[i]
+        i += 1
+        k += 1
+
+
+def merge_sort_advanced(nums: list[int]) -> list[int]:
+    """In-place merge sort over a private copy using a single aux buffer."""
+    values = list(nums)
+    buffer = [0] * len(values)
+
+    width = 1
+    while width < len(values):
+        left = 0
+        while left < len(values):
+            mid = min(left + width, len(values))
+            right = min(left + 2 * width, len(values))
+            if mid < right:
+                _merge_into(values, left, mid, right, buffer)
+            left += 2 * width
+        width *= 2
+    return values
+
+
+def quick_sort_advanced(nums: list[int]) -> list[int]:
+    """Iterative in-place quick sort with median-of-three pivot (Lomuto)."""
+    values = list(nums)
+    stack: list[tuple[int, int]] = [(0, len(values) - 1)]
+
+    def median_of_three(lo: int, hi: int) -> int:
+        mid = (lo + hi) // 2
+        a, b, c = values[lo], values[mid], values[hi]
+        if (a < b) != (a < c):
+            return lo
+        if (b < a) != (b < c):
+            return mid
+        return hi
+
+    while stack:
+        low, high = stack.pop()
+        while low < high:
+            pivot_index = median_of_three(low, high)
+            values[pivot_index], values[high] = values[high], values[pivot_index]
+            pivot = values[high]
+            i = low
+            for j in range(low, high):
+                if values[j] < pivot:
+                    values[i], values[j] = values[j], values[i]
+                    i += 1
+            values[i], values[high] = values[high], values[i]
+            if i - low < high - i:
+                stack.append((i + 1, high))
+                high = i - 1
+            else:
+                stack.append((low, i - 1))
+                low = i + 1
+    return values
+
+
+def max_subarray_advanced(nums: list[int]) -> int:
+    """Kadane with stream-friendly fold (same contract, no pre-scan)."""
+    best: int | None = None
+    running = 0
+    for value in nums:
+        running = max(value, running + value)
+        best = running if best is None else max(best, running)
+    return 0 if best is None else best
+
+
+def lcs_advanced(a: str, b: str) -> int:
+    """LCS with O(min(m, n)) space via two rolling rows."""
+    if len(a) < len(b):
+        a, b = b, a
+    previous = [0] * (len(b) + 1)
+    for i in range(1, len(a) + 1):
+        current = [0] * (len(b) + 1)
+        for j in range(1, len(b) + 1):
+            if a[i - 1] == b[j - 1]:
+                current[j] = previous[j - 1] + 1
+            else:
+                up, left = previous[j], current[j - 1]
+                current[j] = up if up >= left else left
+        previous = current
+    return previous[len(b)]
+
+
+def knapsack_01_advanced(capacity: int, weights: list[int], values: list[int]) -> int:
+    """0/1 knapsack with O(capacity) space via a single rolling row."""
+    row = [0] * (capacity + 1)
+    for weight, value in zip(weights, values, strict=False):
+        if weight > capacity:
+            continue
+        for cap in range(capacity, weight - 1, -1):
+            candidate = row[cap - weight] + value
+            if candidate > row[cap]:
+                row[cap] = candidate
+    return row[capacity]
+
+
+def edit_distance_advanced(a: str, b: str) -> int:
+    """Levenshtein distance with O(min(m, n)) space via two rolling rows."""
+    if len(a) < len(b):
+        a, b = b, a
+    previous = list(range(len(b) + 1))
+    for i in range(1, len(a) + 1):
+        current = [0] * (len(b) + 1)
+        current[0] = i
+        for j in range(1, len(b) + 1):
+            insert_cost = current[j - 1] + 1
+            delete_cost = previous[j] + 1
+            substitute = previous[j - 1] + (0 if a[i - 1] == b[j - 1] else 1)
+            current[j] = min(insert_cost, delete_cost, substitute)
+        previous = current
+    return previous[len(b)]
+
+
+def graph_bfs_advanced(adj: list[list[int]], start: int, target: int) -> int:
+    """BFS shortest path using a preallocated distance array and deque."""
+    if start == target:
+        return 0
+    if not adj or not (0 <= start < len(adj)):
+        return -1 if target != start else 0
+    distances = [-1] * len(adj)
+    distances[start] = 0
+    pending = deque([start])
+    while pending:
+        node = pending.popleft()
+        steps = distances[node] + 1
+        for neighbor in adj[node]:
+            if distances[neighbor] != -1:
+                continue
+            distances[neighbor] = steps
+            if neighbor == target:
+                return steps
+            pending.append(neighbor)
+    return -1
+
+
+def graph_dfs_advanced(adj: list[list[int]], start: int, target: int) -> bool:
+    """Iterative DFS with an explicit stack (avoids recursion limits)."""
+    if not adj:
+        return start == target
+    if not (0 <= start < len(adj)):
+        return False
+    visited = [False] * len(adj)
+    pending = [start]
+    while pending:
+        node = pending.pop()
+        if node == target:
+            return True
+        if visited[node]:
+            continue
+        visited[node] = True
+        for neighbor in adj[node]:
+            if not visited[neighbor]:
+                pending.append(neighbor)
+    return False