gdsdiff 0.1.0__py3-none-any.whl

gdsdiff/acceptance_evidence.py

@@ -0,0 +1,530 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+from .api import CompareRunResult, compare_gds_files
+from .cache import load_or_build_cached_geometry
+from .config import CompareConfig
+from .native import discover_native_capabilities
+
+SCHEMA_VERSION = "gdsdiff-acceptance-evidence-v1"
+TOP_NAME_OVERRIDES = {
+    "medium": "medium_compare_top",
+    "equal_count": "equal_count_top",
+}
+
+
+@dataclass(frozen=True)
+class AcceptanceCorpusPair:
+    name: str
+    before: Path
+    after: Path
+    top: str | None = None
+
+
+def default_acceptance_corpus(repo_root: str | Path) -> tuple[AcceptanceCorpusPair, ...]:
+    repo_root = Path(repo_root)
+    test_root = repo_root / "references" / "testGDS"
+    if not test_root.exists():
+        return ()
+    pairs: list[AcceptanceCorpusPair] = []
+    for before in sorted(test_root.rglob("*_before.gds")):
+        stem = before.name[: -len("_before.gds")]
+        after = before.with_name(f"{stem}_after.gds")
+        if not after.exists():
+            continue
+        relative_parent = before.parent.relative_to(test_root)
+        name = stem if stem else before.parent.name
+        if name == before.parent.name or name.startswith(f"{before.parent.name}"):
+            pair_name = name
+        else:
+            pair_name = "_".join((*relative_parent.parts, stem))
+        top = TOP_NAME_OVERRIDES.get(pair_name) or TOP_NAME_OVERRIDES.get(stem) or TOP_NAME_OVERRIDES.get(before.parent.name)
+        pairs.append(AcceptanceCorpusPair(pair_name, before, after, top=top))
+    return tuple(pairs)
+
+
+def run_acceptance_evidence(
+    pairs: tuple[AcceptanceCorpusPair, ...],
+    output_dir: str | Path,
+    *,
+    min_speedup: float = 100.0,
+    tile_size: int = 256,
+    fast_backend: str = "cuda",
+    monitor_cpu: bool = False,
+    monitor_interval_s: float = 0.1,
+    force_geometry_prefilter: bool = False,
+    geometry_cache_dir: str | Path | None = None,
+    warm_geometry_cache: bool = False,
+    structural_guard: bool = False,
+    native_geometry_guard: bool = False,
+) -> dict[str, Any]:
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    started = datetime.now(timezone.utc).isoformat()
+    rows = []
+    for pair in pairs:
+        row = _run_pair(
+            pair,
+            output_dir,
+            min_speedup=min_speedup,
+            tile_size=tile_size,
+            fast_backend=fast_backend,
+            monitor_cpu=monitor_cpu,
+            monitor_interval_s=monitor_interval_s,
+            force_geometry_prefilter=force_geometry_prefilter,
+            geometry_cache_dir=geometry_cache_dir,
+            warm_geometry_cache=warm_geometry_cache,
+            structural_guard=structural_guard,
+            native_geometry_guard=native_geometry_guard,
+        )
+        rows.append(row)
+    result = {
+        "schema_version": SCHEMA_VERSION,
+        "started": started,
+        "min_speedup": min_speedup,
+        "tile_size": tile_size,
+        "fast_backend": fast_backend,
+        "monitor_cpu": monitor_cpu,
+        "monitor_interval_s": monitor_interval_s,
+        "force_geometry_prefilter": force_geometry_prefilter,
+        "geometry_cache_dir": str(geometry_cache_dir) if geometry_cache_dir is not None else None,
+        "warm_geometry_cache": warm_geometry_cache,
+        "structural_guard": structural_guard,
+        "native_geometry_guard_requested": native_geometry_guard,
+        "capabilities": discover_native_capabilities().to_json(),
+        "results": rows,
+        "all_pairs_pass_speed_status_gate": all(row["passes_speed_status_gate"] for row in rows),
+        "all_pairs_have_exact_polygon_evidence": all(row["exact_polygon_evidence_complete"] for row in rows),
+        "all_monitored_cpu_runs_populated_all_cores_ge_50pct": all(
+            row["cpu_windowed_all_cores_ge_50pct_seen"] for row in rows
+        )
+        if monitor_cpu
+        else None,
+        "notes": [
+            "fast_backend timing is status evidence, not polygon-level evidence, unless exact_polygon_evidence_source says otherwise.",
+            "exact_diff_markdown is generated by the full exact gdstk oracle and is the vertex-level evidence artifact.",
+        ],
+    }
+    validate_acceptance_evidence(result)
+    output_path = output_dir / "acceptance_evidence.json"
+    output_path.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return result | {"output_path": str(output_path)}
+
+
+def validate_acceptance_evidence(result: dict[str, Any]) -> None:
+    required = {
+        "schema_version",
+        "started",
+        "min_speedup",
+        "tile_size",
+        "fast_backend",
+        "capabilities",
+        "results",
+        "all_pairs_pass_speed_status_gate",
+        "all_pairs_have_exact_polygon_evidence",
+    }
+    missing = sorted(required - set(result))
+    if missing:
+        raise ValueError(f"acceptance evidence missing fields: {', '.join(missing)}")
+    if result["schema_version"] != SCHEMA_VERSION:
+        raise ValueError("unsupported acceptance evidence schema")
+    if not isinstance(result["results"], list):
+        raise ValueError("acceptance evidence results must be a list")
+    for row in result["results"]:
+        _validate_row(row)
+
+
+def _validate_row(row: dict[str, Any]) -> None:
+    required = {
+        "pair",
+        "before",
+        "after",
+        "cpu_windowed_wall_s",
+        "fast_wall_s",
+        "exact_wall_s",
+        "speedup_vs_cpu_windowed",
+        "cpu_windowed_status",
+        "fast_status",
+        "exact_status",
+        "fast_status_matches_exact",
+        "exact_polygon_evidence_complete",
+        "passes_speed_status_gate",
+        "exact_diff_markdown",
+        "exact_policy_sha256",
+    }
+    missing = sorted(required - set(row))
+    if missing:
+        raise ValueError(f"acceptance evidence row missing fields: {', '.join(missing)}")
+    for field in ("cpu_windowed_wall_s", "fast_wall_s", "exact_wall_s", "speedup_vs_cpu_windowed"):
+        if row[field] < 0:
+            raise ValueError(f"{field} must be nonnegative")
+
+
+def _run_pair(
+    pair: AcceptanceCorpusPair,
+    output_dir: Path,
+    *,
+    min_speedup: float,
+    tile_size: int,
+    fast_backend: str,
+    monitor_cpu: bool,
+    monitor_interval_s: float,
+    force_geometry_prefilter: bool,
+    geometry_cache_dir: str | Path | None,
+    warm_geometry_cache: bool,
+    structural_guard: bool,
+    native_geometry_guard: bool,
+) -> dict[str, Any]:
+    exact_markdown_path = output_dir / f"{pair.name}_exact_diff.md"
+    if monitor_cpu:
+        with _forced_multicore_thresholds(), _CpuMonitor(interval_s=monitor_interval_s) as monitor:
+            cpu_windowed, cpu_windowed_wall = _timed_compare(
+                CompareConfig(pair.before, pair.after, top=pair.top, backend="cpu", tile_size=tile_size),
+                exact=False,
+                command=("acceptance-evidence", pair.name, "cpu-windowed"),
+            )
+            cpu_monitor = monitor.summary()
+    else:
+        cpu_windowed, cpu_windowed_wall = _timed_compare(
+            CompareConfig(pair.before, pair.after, top=pair.top, backend="cpu", tile_size=tile_size),
+            exact=False,
+            command=("acceptance-evidence", pair.name, "cpu-windowed"),
+        )
+        cpu_monitor = {"available": False, "reason": "monitoring disabled"}
+    if fast_backend == "cpu":
+        verified, verified_wall = _timed_compare(
+            CompareConfig(pair.before, pair.after, top=pair.top, backend="cpu", tile_size=tile_size),
+            exact=True,
+            exact_diff_markdown_path=exact_markdown_path,
+            command=("acceptance-evidence", pair.name, "cpu-exact-smoke"),
+        )
+        fast_status = verified.status.value
+        fast_wall = verified_wall
+        exact_wall = verified_wall
+    else:
+        cache_warm_s = 0.0
+        if warm_geometry_cache and geometry_cache_dir is not None:
+            cache_warm_s = _warm_geometry_cache(pair, geometry_cache_dir, tile_size=tile_size, backend=fast_backend)
+        verified, verified_wall = _timed_compare(
+            CompareConfig(
+                pair.before,
+                pair.after,
+                top=pair.top,
+                backend=fast_backend,
+                tile_size=tile_size,
+                geometry_cache_dir=geometry_cache_dir,
+            ),
+            exact=False,
+            exact_diff_markdown_path=exact_markdown_path,
+            verify_exact_after_fast=True,
+            use_fast_shortcuts=not force_geometry_prefilter,
+            use_structural_guard=structural_guard,
+            use_native_geometry_guard=native_geometry_guard,
+            command=("acceptance-evidence", pair.name, f"{fast_backend}-fast-plus-exact"),
+        )
+        fast_status = str(verified.report.exact_fallback.get("fast_status", verified.status.value))
+        fast_wall = float(
+            verified.timings.get(
+                "fast_status_s",
+                verified.timings.get("geometry_status_s", verified.timings.get("total_s", verified_wall)),
+            )
+        )
+        exact_wall = float(verified.timings.get("exact_verification_s", verified_wall))
+    speedup = cpu_windowed_wall / fast_wall if fast_wall > 0 else float("inf")
+    exact_policy_sha = _policy_sha256(verified)
+    all_cores_ge_50_seen = _all_cores_ge_50_seen(cpu_monitor)
+    return {
+        "pair": pair.name,
+        "before": str(pair.before),
+        "after": str(pair.after),
+        "top": pair.top,
+        "cpu_windowed_wall_s": cpu_windowed_wall,
+        "fast_wall_s": fast_wall,
+        "exact_wall_s": exact_wall,
+        "verified_total_wall_s": verified_wall,
+        "speedup_vs_cpu_windowed": speedup,
+        "cpu_windowed_status": cpu_windowed.status.value,
+        "cpu_windowed_timings": dict(cpu_windowed.timings),
+        "cpu_windowed_cpu_monitor": cpu_monitor,
+        "cpu_windowed_all_cores_ge_50pct_seen": all_cores_ge_50_seen,
+        "fast_status": fast_status,
+        "exact_status": verified.status.value,
+        "cpu_windowed_exact_verification_complete": cpu_windowed.report.exact_verification_complete,
+        "fast_exact_verification_complete": verified.report.exact_verification_complete,
+        "exact_verification_complete": verified.report.exact_verification_complete,
+        "fast_status_matches_exact": fast_status == verified.status.value,
+        "cpu_windowed_status_matches_exact": cpu_windowed.status == verified.status,
+        "exact_polygon_evidence_complete": verified.report.exact_verification_complete,
+        "exact_polygon_evidence_source": "fast-comparator-run-with-full-gdstk-oracle",
+        "passes_speed_status_gate": speedup >= min_speedup and fast_status == verified.status.value and verified.report.exact_verification_complete,
+        "exact_diff_markdown": str(exact_markdown_path),
+        "exact_policy_sha256": exact_policy_sha,
+        "exact_diff_markdown_sha256": _file_sha256(exact_markdown_path),
+        "artifacts": {
+            "exact_diff_markdown": str(exact_markdown_path),
+        },
+        "verified_report_backend": verified.report.backend,
+        "verified_report_exact_fallback": verified.report.exact_fallback,
+        "verified_timings": dict(verified.timings),
+        "force_geometry_prefilter": force_geometry_prefilter,
+        "geometry_cache_dir": str(geometry_cache_dir) if geometry_cache_dir is not None else None,
+        "warm_geometry_cache": warm_geometry_cache,
+        "geometry_cache_warm_s": cache_warm_s if fast_backend != "cpu" else 0.0,
+        "structural_guard": structural_guard,
+        "native_geometry_guard_requested": native_geometry_guard,
+        "native_geometry_guard_used": bool(verified.report.backend.get("native_geometry_guard")),
+    }
+
+
+def _timed_compare(config: CompareConfig, **kwargs) -> tuple[CompareRunResult, float]:
+    start = perf_counter()
+    result = compare_gds_files(config, **kwargs)
+    return result, perf_counter() - start
+
+
+def _warm_geometry_cache(pair: AcceptanceCorpusPair, geometry_cache_dir: str | Path, *, tile_size: int, backend: str) -> float:
+    start = perf_counter()
+    for path in (pair.before, pair.after):
+        load_or_build_cached_geometry(
+            cache_dir=geometry_cache_dir,
+            path=path,
+            top_name=pair.top,
+            layers="all",
+            meters_per_dbu=None,
+            path_policy="gdstk",
+        )
+    compare_gds_files(
+        CompareConfig(
+            pair.before,
+            pair.after,
+            top=pair.top,
+            backend=backend,
+            tile_size=tile_size,
+            geometry_cache_dir=geometry_cache_dir,
+        ),
+        exact=False,
+        verify_exact_after_fast=False,
+        use_fast_shortcuts=False,
+        command=("acceptance-evidence", pair.name, "warm-geometry-cache"),
+    )
+    return perf_counter() - start
+
+
+class _CpuMonitor:
+    def __init__(self, *, interval_s: float = 0.1) -> None:
+        self._interval_s = max(interval_s, 0.01)
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._samples: list[tuple[float, ...]] = []
+        self._available = True
+        self._reason = ""
+
+    def __enter__(self) -> "_CpuMonitor":
+        try:
+            initial = _read_cpu_counters()
+        except OSError as exc:
+            self._available = False
+            self._reason = str(exc)
+            return self
+        if not initial:
+            self._available = False
+            self._reason = "no per-core CPU counters found"
+            return self
+        self._thread = threading.Thread(target=self._run, args=(initial,), daemon=True)
+        self._thread.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=max(self._interval_s * 4, 0.25))
+
+    def summary(self) -> dict[str, Any]:
+        if not self._available:
+            return {"available": False, "reason": self._reason}
+        if not self._samples:
+            return {"available": True, "sample_count": 0, "reason": "no completed CPU samples"}
+        logical_cpu_count = len(self._samples[0])
+        return {
+            "available": True,
+            "sample_count": len(self._samples),
+            "logical_cpu_count": logical_cpu_count,
+            "max_cores_ge_25pct": max(_count_at_least(sample, 25.0) for sample in self._samples),
+            "max_cores_ge_50pct": max(_count_at_least(sample, 50.0) for sample in self._samples),
+            "max_cores_ge_75pct": max(_count_at_least(sample, 75.0) for sample in self._samples),
+            "mean_cores_ge_50pct": sum(_count_at_least(sample, 50.0) for sample in self._samples) / len(self._samples),
+            "max_mean_busy_pct": max(sum(sample) / len(sample) for sample in self._samples),
+            "mean_busy_pct": sum(sum(sample) / len(sample) for sample in self._samples) / len(self._samples),
+            "max_core_busy_pct": max(max(sample) for sample in self._samples),
+            "interval_s": self._interval_s,
+        }
+
+    def _run(self, previous: list[tuple[int, int]]) -> None:
+        while not self._stop.wait(self._interval_s):
+            try:
+                current = _read_cpu_counters()
+            except OSError as exc:
+                self._available = False
+                self._reason = str(exc)
+                return
+            if len(current) != len(previous):
+                self._available = False
+                self._reason = "CPU counter count changed during monitoring"
+                return
+            sample = tuple(_busy_percent(old, new) for old, new in zip(previous, current))
+            self._samples.append(sample)
+            previous = current
+
+
+def _read_cpu_counters() -> list[tuple[int, int]]:
+    path = Path("/proc/stat")
+    rows: list[tuple[int, int]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            parts = line.split()
+            if not parts:
+                continue
+            name = parts[0]
+            if not name.startswith("cpu") or name == "cpu" or not name[3:].isdigit():
+                continue
+            values = [int(value) for value in parts[1:]]
+            idle = values[3] + (values[4] if len(values) > 4 else 0)
+            total = sum(values)
+            rows.append((total, idle))
+    return rows
+
+
+def _busy_percent(old: tuple[int, int], new: tuple[int, int]) -> float:
+    old_total, old_idle = old
+    new_total, new_idle = new
+    total_delta = new_total - old_total
+    if total_delta <= 0:
+        return 0.0
+    idle_delta = new_idle - old_idle
+    return max(0.0, min(100.0, 100.0 * (total_delta - idle_delta) / total_delta))
+
+
+def _count_at_least(sample: tuple[float, ...], threshold: float) -> int:
+    return sum(1 for value in sample if value >= threshold)
+
+
+def _all_cores_ge_50_seen(summary: dict[str, Any]) -> bool:
+    if not summary.get("available"):
+        return False
+    logical_cpu_count = summary.get("logical_cpu_count")
+    max_cores = summary.get("max_cores_ge_50pct")
+    return isinstance(logical_cpu_count, int) and isinstance(max_cores, int) and max_cores >= logical_cpu_count
+
+
+@contextmanager
+def _forced_multicore_thresholds():
+    names = (
+        "GDSDIFF_PARALLEL_MIN_POLYGONS",
+        "GDSDIFF_PARALLEL_EXTRACT_PAIR_MIN_BYTES",
+        "GDS_GPU_COMPARE_PARALLEL_MIN_POLYGONS",
+        "GDS_GPU_COMPARE_PARALLEL_EXTRACT_PAIR_MIN_BYTES",
+    )
+    previous = {name: os.environ.get(name) for name in names}
+    try:
+        for name in names:
+            os.environ[name] = "1"
+        yield
+    finally:
+        for name, value in previous.items():
+            if value is None:
+                os.environ.pop(name, None)
+            else:
+                os.environ[name] = value
+
+
+def _policy_sha256(result: CompareRunResult) -> str:
+    payload = json.dumps(result.policy_result.to_json(), sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run GDS comparator acceptance evidence over the reference corpus.")
+    parser.add_argument("--repo-root", type=Path, default=Path.cwd())
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--pair", action="append", metavar="NAME:BEFORE:AFTER[:TOP]")
+    parser.add_argument("--min-speedup", type=float, default=100.0)
+    parser.add_argument("--tile-size", type=int, default=256)
+    parser.add_argument("--fast-backend", default="cuda")
+    parser.add_argument("--monitor-cpu", action="store_true")
+    parser.add_argument("--monitor-interval-s", type=float, default=0.1)
+    parser.add_argument("--force-geometry-prefilter", action="store_true")
+    parser.add_argument("--geometry-cache-dir", type=Path)
+    parser.add_argument("--warm-geometry-cache", action="store_true")
+    parser.add_argument("--structural-guard", action="store_true")
+    parser.add_argument("--native-geometry-guard", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.min_speedup < 0:
+        parser.error("--min-speedup must be nonnegative")
+    if args.tile_size <= 0:
+        parser.error("--tile-size must be positive")
+    if args.monitor_interval_s <= 0:
+        parser.error("--monitor-interval-s must be positive")
+    pairs = _parse_pairs(args.pair) if args.pair else default_acceptance_corpus(args.repo_root)
+    if not pairs:
+        parser.error("no acceptance corpus pairs found")
+    result = run_acceptance_evidence(
+        pairs,
+        args.output_dir,
+        min_speedup=args.min_speedup,
+        tile_size=args.tile_size,
+        fast_backend=args.fast_backend,
+        monitor_cpu=args.monitor_cpu,
+        monitor_interval_s=args.monitor_interval_s,
+        force_geometry_prefilter=args.force_geometry_prefilter,
+        geometry_cache_dir=args.geometry_cache_dir,
+        warm_geometry_cache=args.warm_geometry_cache,
+        structural_guard=args.structural_guard,
+        native_geometry_guard=args.native_geometry_guard,
+    )
+    print(result["output_path"])
+    return 0 if result["all_pairs_pass_speed_status_gate"] else 1
+
+
+def _parse_pairs(values: list[str]) -> tuple[AcceptanceCorpusPair, ...]:
+    pairs: list[AcceptanceCorpusPair] = []
+    for value in values:
+        parts = value.split(":")
+        if len(parts) not in {3, 4}:
+            raise ValueError("--pair must have form NAME:BEFORE:AFTER[:TOP]")
+        pairs.append(
+            AcceptanceCorpusPair(
+                name=parts[0],
+                before=Path(parts[1]),
+                after=Path(parts[2]),
+                top=parts[3] if len(parts) == 4 and parts[3] else None,
+            )
+        )
+    return tuple(pairs)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())