Optimize late no-warm reroutes

scripts/record_pre_pair_frontier_trace.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter
+from dataclasses import asdict
+from datetime import datetime
+from pathlib import Path
+
+from inire.tests.example_scenarios import TRACE_PERFORMANCE_SCENARIO_RUNS, TRACE_SCENARIO_RUNS
+
+
+def _trace_registry(include_performance_only: bool) -> tuple[tuple[str, object], ...]:
+    if include_performance_only:
+        return TRACE_SCENARIO_RUNS + TRACE_PERFORMANCE_SCENARIO_RUNS
+    return TRACE_SCENARIO_RUNS
+
+
+def _selected_runs(
+    selected_scenarios: tuple[str, ...] | None,
+    *,
+    include_performance_only: bool,
+) -> tuple[tuple[str, object], ...]:
+    if selected_scenarios is None:
+        perf_registry = dict(TRACE_PERFORMANCE_SCENARIO_RUNS)
+        return (
+            (
+                "example_07_large_scale_routing_no_warm_start",
+                perf_registry["example_07_large_scale_routing_no_warm_start"],
+            ),
+            (
+                "example_07_large_scale_routing_no_warm_start_seed43",
+                perf_registry["example_07_large_scale_routing_no_warm_start_seed43"],
+            ),
+        )
+
+    registry = dict(TRACE_SCENARIO_RUNS + TRACE_PERFORMANCE_SCENARIO_RUNS)
+    allowed_standard = dict(_trace_registry(include_performance_only))
+    runs = []
+    for name in selected_scenarios:
+        if name in allowed_standard:
+            runs.append((name, allowed_standard[name]))
+            continue
+        if name in registry:
+            runs.append((name, registry[name]))
+            continue
+        valid = ", ".join(sorted(registry))
+        raise SystemExit(f"Unknown pre-pair frontier-trace scenario: {name}. Valid scenarios: {valid}")
+    return tuple(runs)
+
+
+def _build_payload(
+    selected_scenarios: tuple[str, ...] | None,
+    *,
+    include_performance_only: bool,
+) -> dict[str, object]:
+    scenarios = []
+    for name, run in _selected_runs(selected_scenarios, include_performance_only=include_performance_only):
+        result = run()
+        scenarios.append(
+            {
+                "name": name,
+                "summary": {
+                    "total_results": len(result.results_by_net),
+                    "valid_results": sum(1 for entry in result.results_by_net.values() if entry.is_valid),
+                    "reached_targets": sum(1 for entry in result.results_by_net.values() if entry.reached_target),
+                },
+                "metrics": asdict(result.metrics),
+                "pre_pair_frontier_trace": None
+                if result.pre_pair_frontier_trace is None
+                else asdict(result.pre_pair_frontier_trace),
+            }
+        )
+    return {
+        "generated_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "generator": "scripts/record_pre_pair_frontier_trace.py",
+        "scenarios": scenarios,
+    }
+
+
+def _render_markdown(payload: dict[str, object]) -> str:
+    lines = [
+        "# Pre-Pair Frontier Trace",
+        "",
+        f"Generated at {payload['generated_at']} by `{payload['generator']}`.",
+        "",
+    ]
+
+    for scenario in payload["scenarios"]:
+        lines.extend(
+            [
+                f"## {scenario['name']}",
+                "",
+                f"Results: {scenario['summary']['valid_results']} valid / "
+                f"{scenario['summary']['reached_targets']} reached / "
+                f"{scenario['summary']['total_results']} total.",
+                "",
+            ]
+        )
+        trace = scenario["pre_pair_frontier_trace"]
+        if trace is None:
+            lines.extend(["No pre-pair frontier trace captured.", ""])
+            continue
+
+        lines.extend(
+            [
+                f"Captured iteration: `{trace['iteration']}`",
+                "",
+                f"Conflict edges: `{trace['conflict_edges']}`",
+                "",
+                "| Net | Nodes | Checks | Closed-Set | Cost | Hard Collision | Guidance Seed | Frontier Samples |",
+                "| :-- | --: | --: | --: | --: | --: | :--: | --: |",
+            ]
+        )
+        reason_counts: Counter[str] = Counter()
+        for net_trace in trace["nets"]:
+            frontier = net_trace["frontier"]
+            lines.append(
+                "| "
+                f"{net_trace['net_id']} | "
+                f"{net_trace['nodes_expanded']} | "
+                f"{net_trace['congestion_check_calls']} | "
+                f"{net_trace['pruned_closed_set']} | "
+                f"{net_trace['pruned_cost']} | "
+                f"{net_trace['pruned_hard_collision']} | "
+                f"{'yes' if net_trace['guidance_seed_present'] else 'no'} | "
+                f"{len(frontier['samples'])} |"
+            )
+            reason_counts["closed_set"] += frontier["pruned_closed_set"]
+            reason_counts["hard_collision"] += frontier["pruned_hard_collision"]
+            reason_counts["self_collision"] += frontier["pruned_self_collision"]
+            reason_counts["cost"] += frontier["pruned_cost"]
+
+        lines.extend(["", "Frontier prune totals by reason:", ""])
+        if reason_counts:
+            for reason, count in reason_counts.most_common():
+                lines.append(f"- `{reason}`: {count}")
+        else:
+            lines.append("- None")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Record pre-pair frontier-trace artifacts for selected trace scenarios.")
+    parser.add_argument(
+        "--scenario",
+        action="append",
+        dest="scenarios",
+        default=[],
+        help="Optional trace scenario name to include. May be passed more than once.",
+    )
+    parser.add_argument(
+        "--include-performance-only",
+        action="store_true",
+        help="Include performance-only trace scenarios when selecting from the standard registry.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=None,
+        help="Directory to write pre_pair_frontier_trace.json and .md into. Defaults to <repo>/docs.",
+    )
+    args = parser.parse_args()
+
+    repo_root = Path(__file__).resolve().parents[1]
+    output_dir = repo_root / "docs" if args.output_dir is None else args.output_dir.resolve()
+    output_dir.mkdir(exist_ok=True)
+
+    selected = tuple(args.scenarios) if args.scenarios else None
+    payload = _build_payload(selected, include_performance_only=args.include_performance_only)
+    json_path = output_dir / "pre_pair_frontier_trace.json"
+    markdown_path = output_dir / "pre_pair_frontier_trace.md"
+
+    json_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+    markdown_path.write_text(_render_markdown(payload) + "\n")
+
+    if json_path.is_relative_to(repo_root):
+        print(f"Wrote {json_path.relative_to(repo_root)}")
+    else:
+        print(f"Wrote {json_path}")
+    if markdown_path.is_relative_to(repo_root):
+        print(f"Wrote {markdown_path.relative_to(repo_root)}")
+    else:
+        print(f"Wrote {markdown_path}")
+
+
+if __name__ == "__main__":
+    main()