feat: Add 'build' to development dependencies for improved package management

Author: miskibin

benchmark_results.csv

@@ -1,7 +1,21 @@
-timestamp,snapshot_name,snapshot_branch,snapshot_commit,snapshot_dirty,warmup_rounds,benchmark_rounds,benchmark_iterations,engine_depth,num_games,positions_count,lm_snapshot_median_ms,lm_snapshot_mean_ms,lm_snapshot_min_ms,lm_snapshot_max_ms,lm_snapshot_stdev_ms,lm_current_median_ms,lm_current_mean_ms,lm_current_min_ms,lm_current_max_ms,lm_current_stdev_ms,lm_change_pct,match_snapshot_wins,match_current_wins,match_draws,match_snapshot_avg_nodes,match_current_avg_nodes,match_snapshot_avg_time_ms,match_current_avg_time_ms,match_time_change_pct,match_snapshot_total_nodes,match_current_total_nodes,hw_platform,hw_platform_release,hw_architecture,hw_cpu_brand,hw_cpu_cores,hw_ram_gb,hw_python_version
-2025-12-31T14:18:54.255407,snapshot_20251231_132737,main,75919c5,True,5,10,10,2,20,73,7.65,7.798,6.86,9.502,0.734,3.778,3.948,3.412,5.677,0.714,-50.62,10,10,0,16.3,16.3,4.84,2.35,-51.4,16340,16340,Windows,11,AMD64,12th Gen Intel(R) Core(TM) i5-1245U,12,31.7,3.12.10
-2025-12-31T14:31:57.164421,snapshot_20251231_142534,main,a3f4c6b,False,5,10,10,2,20,73,4.062,4.175,3.355,6.345,0.879,3.876,4.132,3.364,6.804,0.998,-4.57,10,10,0,16.2,16.3,2.03,1.26,-38.11,20030,20220,Windows,11,AMD64,12th Gen Intel(R) Core(TM) i5-1245U,12,31.7,3.12.10
-2025-12-31T14:36:11.096632,snapshot_20251231_142534,main,a3f4c6b,False,5,10,10,3,40,73,3.469,3.975,3.149,7.303,1.241,3.356,3.548,3.151,4.244,0.395,-3.25,20,20,0,150.6,138.4,15.02,7.58,-49.56,241020,221420,Windows,11,AMD64,12th Gen Intel(R) Core(TM) i5-1245U,12,31.7,3.12.10
-2025-12-31T14:42:50.445557,snapshot_20251231_143808,main,86da27b,True,5,10,10,3,40,73,3.346,3.631,3.021,5.345,0.689,3.363,3.434,3.063,4.059,0.311,0.51,40,0,0,76.9,60.2,4.18,6.03,44.27,86180,68620,Windows,11,AMD64,12th Gen Intel(R) Core(TM) i5-1245U,12,31.7,3.12.10
-2025-12-31T14:46:11.570275,snapshot_20251231_143808,main,86da27b,True,5,10,10,3,40,73,4.608,5.273,3.567,9.344,1.851,4.318,4.648,3.785,6.264,0.915,-6.3,40,0,0,76.9,60.2,12.57,17.93,42.7,86180,68620,Windows,11,AMD64,12th Gen Intel(R) Core(TM) i5-1245U,12,31.7,3.12.10
-2025-12-31T14:51:37.432914,snapshot_20251231_143808,main,86da27b,True,5,10,10,3,40,73,3.77,3.822,3.11,4.487,0.488,3.516,3.737,3.139,5.368,0.653,-6.74,0,20,20,122.0,125.2,7.53,6.99,-7.28,392940,403240,Windows,11,AMD64,12th Gen Intel(R) Core(TM) i5-1245U,12,31.7,3.12.10
+name,fen
+Introduction,B:W28,31,32,34,35,36,37,38,39,40,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,11,12,13,15,16,17,18,19,20,23
+Symmetrical Variation,W:W24,27,29,32,34,37,38,39,40,41,42,43,44,47,48,49,50:B1,2,3,4,7,8,9,11,12,13,15,16,17,18,20,23,25
+Chefneux Opening,W:W28,31,32,33,34,35,36,37,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,13,14,15,16,17,18,19,20,23
+Chogoliev Opening,W:W31,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,12,13,14,15,16,18,19,20,22
+Schwarzman Manoeuvring Opening,W:W31,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,13,14,15,16,18,19,20,21
+Eagle Opening,W:W28,31,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,19,20,22
+Hedgehog Opening,W:W28,31,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,18,19,20,21
+Black Panther Opening,W:W28,31,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,17,18,19,20,21
+Russian Bear Opening,W:W28,31,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,25
+Cow Opening,W:W28,31,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,24
+Diamond Opening,B:W29,31,32,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
+Sijbrands Opening,W:W27,28,32,33,34,35,36,37,38,39,40,41,42,43  ,45,46,47,48,49,50:B1,2,3,4,5,6,8,9,10,11,12,13,14,15,16,17,18,19,23,24
+Fork Lock Opening,B:W29,31,32,33,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
+French Opening,B:W30,31,32,33,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
+Polish Opening,B:W27,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
+Edge Opening,B:W26,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
+Wild Horse Opening,B:W30,31,32,33,34,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50:B1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
+Keller Opening,B:W24,26,29,33,34,36,37,38,39,40,41,42,43,44,45,46,47,48,49:B2,3,4,5,6,7,8,9,11,12,13,14,15,17,18,20,21,22,23
+Woldouby,W:W25,27,28,30,32,33,34,35,37,38:B12,13,14,16,18,19,21,23,24,26
+2025-12-31T17:18:57.958257,snapshot_20251231_155231,main,fe593e9,True,5,10,10,4,64,32,73,3.148,3.228,2.934,3.666,0.27,3.025,3.103,2.862,3.698,0.248,-3.89,31,31,2,140.0,140.0,6.86,6.84,-0.29,174594,174594,Windows,11,AMD64,12th Gen Intel(R) Core(TM) i5-12400F,12,31.8,3.12.10

docs/source/benchmarking.rst

@@ -63,6 +63,55 @@ Results
 
 Benchmark results are automatically appended to ``benchmark_results.csv`` in the project root.
 
+Optimization Workflow
+---------------------
+
+Recommended workflow for improving engine performance:
+
+1. **Profile**
+   
+   Run profiling to identify bottlenecks:
+
+   .. code-block:: bash
+
+      # For general engine profiling
+      python tools/profile_engine_detailed.py
+
+      # For legal moves generation specifically
+      python tools/profile_legal_moves.py
+
+2. **Improve**
+
+   Make code changes to address identified bottlenecks.
+
+3. **Verify Profile**
+
+   Run the profiling script again to verify local improvements.
+
+4. **Test**
+
+   Ensure no regressions in functionality:
+
+   .. code-block:: bash
+
+      pytest .
+
+5. **Benchmark**
+
+   Compare against the baseline snapshot to verify performance gains:
+
+   .. code-block:: bash
+
+      python tools/compare_versions.py
+
+6. **Snapshot**
+
+   If satisfied with the results, create a new snapshot to serve as the next baseline:
+
+   .. code-block:: bash
+
+      python tools/create_snapshot.py
+
 Profiling
 ---------
 

pyproject.toml

@@ -49,6 +49,7 @@ dev = [
     "pytest",
     "mypy",
     "sphinx",
+    "build",
     "rich",
     "pytest-benchmark",
 ]

tools/compare_versions.py

@@ -13,7 +13,6 @@
 import subprocess
 import sys
 import tempfile
-import venv
 from datetime import datetime
 from pathlib import Path
 
@@ -26,18 +25,32 @@
 WARMUP_ROUNDS = 5
 BENCHMARK_ROUNDS = 10
 BENCHMARK_ITERATIONS = 10  # Number of times to run the legal moves benchmark
-ENGINE_DEPTH = 3
-NUM_GAMES = 40
+ENGINE_DEPTH = 4
 
 # === Paths ===
 PROJECT_ROOT = Path(__file__).parent.parent
 POSITIONS_FILE = PROJECT_ROOT / "test" / "games" / "standard" / "random_positions.json"
+OPENINGS_FILE = PROJECT_ROOT / "tools" / "openings.csv"
 WORKERS_DIR = PROJECT_ROOT / "tools" / "workers"
 RESULTS_CSV = PROJECT_ROOT / "benchmark_results.csv"
 
 console = Console()
 
 
+def load_openings() -> list[dict]:
+    """Load openings from CSV file."""
+    openings = []
+    with open(OPENINGS_FILE, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            openings.append({
+                "name": row["name"],
+                "moves": row["moves"],
+                "fen": row["fen"] if row["fen"].strip() else None,
+            })
+    return openings
+
+
 def get_hardware_info() -> dict:
     """Collect hardware and system information."""
     info = {
@@ -81,6 +94,8 @@ def append_results_to_csv(
     lm2_medians: list,
     match_stats: dict,
     positions_count: int,
+    num_games: int,
+    num_openings: int,
 ):
     """Append benchmark results to CSV file."""
     from statistics import median, mean, stdev
@@ -111,7 +126,8 @@ def append_results_to_csv(
         "benchmark_rounds": BENCHMARK_ROUNDS,
         "benchmark_iterations": BENCHMARK_ITERATIONS,
         "engine_depth": ENGINE_DEPTH,
-        "num_games": NUM_GAMES,
+        "num_games": num_games,
+        "num_openings": num_openings,
         "positions_count": positions_count,
 
         # Legal moves - snapshot
@@ -165,23 +181,18 @@ def append_results_to_csv(
 
 def create_venv(path: Path) -> Path:
     """Create virtualenv and return python executable path."""
-    venv.create(path, with_pip=True, clear=True)
+    subprocess.run(["uv", "venv", str(path)], check=True, capture_output=True)
     if sys.platform == "win32":
         python = path / "Scripts" / "python.exe"
     else:
         python = path / "bin" / "python"
-    subprocess.run(
-        [str(python), "-m", "pip", "install", "--upgrade", "pip", "-q"],
-        check=True,
-        capture_output=True,
-    )
     return python
 
 
 def install_package(python: Path, source: Path):
     """Install py-draughts from wheel or source."""
     subprocess.run(
-        [str(python), "-m", "pip", "install", str(source), "-q"],
+        ["uv", "pip", "install", "--python", str(python), str(source), "-q"],
         check=True,
         capture_output=True,
     )
@@ -265,8 +276,11 @@ def get_engine_move(python: Path, fen: str | None, depth: int) -> dict:
     return json.loads(result.stdout)
 
 
-def play_match(python1: Path, python2: Path, num_games: int, depth: int) -> dict:
-    """Play engine vs engine match using persistent workers."""
+def play_match(python1: Path, python2: Path, openings: list[dict], depth: int) -> dict:
+    """Play engine vs engine match using persistent workers.
+    
+    Each opening is played twice: once with v1 as white, once with v2 as white.
+    """
     stats = {
         "v1_wins": 0,
         "v2_wins": 0,
@@ -279,62 +293,80 @@ def play_match(python1: Path, python2: Path, num_games: int, depth: int) -> dict
         "v2_moves": 0,
     }
 
+    num_games = len(openings) * 2  # Each opening played twice (swap colors)
+    game_num = 0
+
     # Start persistent workers (avoids ~500ms startup per move!)
     with EngineWorker(python1) as worker1, EngineWorker(python2) as worker2:
         with console.status("[bold green]Playing match...") as status:
-            for game_num in range(num_games):
-                status.update(f"[bold green]Game {game_num + 1}/{num_games}...")
-
-                # Alternate who plays white
-                if game_num % 2 == 0:
-                    white_worker, black_worker = worker1, worker2
-                    white_ver = "v1"
-                else:
-                    white_worker, black_worker = worker2, worker1
-                    white_ver = "v2"
-
-                fen = None
-                move_count = 0
-                result = {}
-
-                while move_count < 200:
-                    is_white_turn = move_count % 2 == 0
-                    current_worker = white_worker if is_white_turn else black_worker
-                    current_ver = white_ver if is_white_turn else ("v2" if white_ver == "v1" else "v1")
-
-                    result = current_worker.get_move(fen, depth)
-
-                    if result.get("error") or result.get("game_over") or not result.get("move"):
-                        break
-
-                    # Track stats
-                    if current_ver == "v1":
-                        stats["v1_nodes"] += result.get("nodes", 0)
-                        stats["v1_time_ms"] += result.get("time_ms", 0)
-                        stats["v1_moves"] += 1
+            for opening in openings:
+                opening_name = opening["name"]
+                opening_fen = opening["fen"]
+                
+                # Play each opening twice: v1 as white, then v2 as white
+                for swap in range(2):
+                    game_num += 1
+                    color_info = "snapshot=W" if swap == 0 else "current=W"
+                    status.update(f"[bold green]Game {game_num}/{num_games}: {opening_name} ({color_info})...")
+
+                    # Determine who plays white
+                    if swap == 0:
+                        white_worker, black_worker = worker1, worker2
+                        white_ver = "v1"
+                    else:
+                        white_worker, black_worker = worker2, worker1
+                        white_ver = "v2"
+
+                    # Start from opening position
+                    fen = opening_fen
+                    move_count = 0
+                    result = {}
+                    
+                    # Determine whose turn it is from FEN
+                    # FEN starts with 'W:' or 'B:' to indicate turn
+                    if fen and fen.startswith("B:"):
+                        is_white_turn = False
+                    else:
+                        is_white_turn = True  # Default to white's turn
+
+                    while move_count < 200:
+                        current_worker = white_worker if is_white_turn else black_worker
+                        current_ver = white_ver if is_white_turn else ("v2" if white_ver == "v1" else "v1")
+
+                        result = current_worker.get_move(fen, depth)
+
+                        if result.get("error") or result.get("game_over") or not result.get("move"):
+                            break
+
+                        # Track stats
+                        if current_ver == "v1":
+                            stats["v1_nodes"] += result.get("nodes", 0)
+                            stats["v1_time_ms"] += result.get("time_ms", 0)
+                            stats["v1_moves"] += 1
+                        else:
+                            stats["v2_nodes"] += result.get("nodes", 0)
+                            stats["v2_time_ms"] += result.get("time_ms", 0)
+                            stats["v2_moves"] += 1
+
+                        fen = result["fen"]
+                        move_count += 1
+                        is_white_turn = not is_white_turn
+
+                    # Determine winner
+                    game_result = result.get("result", "1/2-1/2")
+                    if game_result == "1-0":
+                        winner = white_ver
+                    elif game_result == "0-1":
+                        winner = "v2" if white_ver == "v1" else "v1"
                     else:
-                        stats["v2_nodes"] += result.get("nodes", 0)
-                        stats["v2_time_ms"] += result.get("time_ms", 0)
-                        stats["v2_moves"] += 1
-
-                    fen = result["fen"]
-                    move_count += 1
-
-                # Determine winner
-                game_result = result.get("result", "1/2-1/2")
-                if game_result == "1-0":
-                    winner = white_ver
-                elif game_result == "0-1":
-                    winner = "v2" if white_ver == "v1" else "v1"
-                else:
-                    winner = "draw"
-
-                if winner == "v1":
-                    stats["v1_wins"] += 1
-                elif winner == "v2":
-                    stats["v2_wins"] += 1
-                else:
-                    stats["draws"] += 1
+                        winner = "draw"
+
+                    if winner == "v1":
+                        stats["v1_wins"] += 1
+                    elif winner == "v2":
+                        stats["v2_wins"] += 1
+                    else:
+                        stats["draws"] += 1
 
     return stats
 
@@ -485,21 +517,25 @@ def main():
         console.print()
         console.print(lm_table)
 
+        # Load openings
+        openings = load_openings()
+        num_games = len(openings) * 2  # Each opening played as both colors
+
         # Engine match
-        console.print(f"\n[bold]Engine match ({NUM_GAMES} games, depth={ENGINE_DEPTH})...[/]")
-        match = play_match(py1, py2, NUM_GAMES, ENGINE_DEPTH)
+        console.print(f"\n[bold]Engine match ({num_games} games from {len(openings)} openings, depth={ENGINE_DEPTH})...[/]")
+        match = play_match(py1, py2, openings, ENGINE_DEPTH)
 
         # Calculate averages
         v1_avg_nodes = match["v1_nodes"] / match["v1_moves"] if match["v1_moves"] else 0
         v2_avg_nodes = match["v2_nodes"] / match["v2_moves"] if match["v2_moves"] else 0
         v1_avg_time = match["v1_time_ms"] / match["v1_moves"] if match["v1_moves"] else 0
         v2_avg_time = match["v2_time_ms"] / match["v2_moves"] if match["v2_moves"] else 0
 
-        v1_pct = (match["v1_wins"] / NUM_GAMES) * 100
-        v2_pct = (match["v2_wins"] / NUM_GAMES) * 100
-        draw_pct = (match["draws"] / NUM_GAMES) * 100
+        v1_pct = (match["v1_wins"] / num_games) * 100
+        v2_pct = (match["v2_wins"] / num_games) * 100
+        draw_pct = (match["draws"] / num_games) * 100
 
-        match_table = Table(title=f"Match Results ({NUM_GAMES} games)", box=box.ROUNDED)
+        match_table = Table(title=f"Match Results ({num_games} games from {len(openings)} openings)", box=box.ROUNDED)
         match_table.add_column("Metric", style="cyan")
         match_table.add_column("Snapshot", justify="right")
         match_table.add_column("Current", justify="right")
@@ -545,7 +581,7 @@ def main():
         else:
             console.print("[yellow]⚠ Performance regression detected[/]")
 
-        if match["draws"] == NUM_GAMES:
+        if match["draws"] == num_games:
             console.print("[dim]Note: 100% draws expected with identical code (deterministic engine)[/]")
 
         # Append results to CSV
@@ -556,6 +592,8 @@ def main():
             lm2_medians=lm2_medians,
             match_stats=match,
             positions_count=lm1_results[0]["positions_count"],
+            num_games=num_games,
+            num_openings=len(openings),
         )