gdsdiff 0.1.0__py3-none-any.whl

gdsdiff/config.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from typing import Iterable, Literal
+
+from .semantics import Backend, DifferenceDirection, EvidenceEngine, FailurePolicy, PathPolicy
+
+LayerSelector = Literal["all"] | tuple["LayerSpec", ...]
+
+
+def _decimal_or_none(value) -> Decimal | None:
+    if value is None:
+        return None
+    if isinstance(value, Decimal):
+        result = value
+    else:
+        try:
+            result = Decimal(str(value))
+        except (InvalidOperation, ValueError) as exc:
+            raise ValueError(f"invalid decimal value: {value!r}") from exc
+    if not result.is_finite() or result <= 0:
+        raise ValueError(f"decimal value must be finite and positive: {value!r}")
+    return result
+
+
+@dataclass(frozen=True, order=True)
+class LayerSpec:
+    layer: int
+    datatype: int = 0
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.layer, int) or not isinstance(self.datatype, int):
+            raise TypeError("layer and datatype must be integers")
+        if self.layer < 0 or self.datatype < 0:
+            raise ValueError("layer and datatype must be nonnegative")
+
+    @classmethod
+    def parse(cls, value: str | tuple[int, int] | "LayerSpec") -> "LayerSpec":
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, tuple):
+            if len(value) != 2:
+                raise ValueError("layer tuple must be (layer, datatype)")
+            return cls(int(value[0]), int(value[1]))
+        parts = str(value).strip().split(":")
+        if len(parts) != 2 or not parts[0] or not parts[1]:
+            raise ValueError(f"layer spec must have form L:D, got {value!r}")
+        return cls(int(parts[0]), int(parts[1]))
+
+    def to_json(self) -> dict[str, int]:
+        return {"layer": self.layer, "datatype": self.datatype}
+
+
+def parse_layer_selector(value: str | LayerSpec | Iterable[str | tuple[int, int] | LayerSpec]) -> LayerSelector:
+    if value == "all":
+        return "all"
+    if isinstance(value, str):
+        parts = [part.strip() for part in value.split(",") if part.strip()]
+        if not parts:
+            raise ValueError("layer selector cannot be empty")
+        layers = tuple(sorted({LayerSpec.parse(part) for part in parts}))
+    elif isinstance(value, LayerSpec):
+        layers = (value,)
+    else:
+        layers = tuple(sorted({LayerSpec.parse(part) for part in value}))
+    if not layers:
+        raise ValueError("layer selector cannot be empty")
+    return layers
+
+
+@dataclass(frozen=True)
+class GridSpec:
+    meters_per_dbu: Decimal | str | float | None = None
+    source_old_precision_m: Decimal | str | float | None = None
+    source_new_precision_m: Decimal | str | float | None = None
+    selection_mode: str = "auto"
+    rounding_mode: str = "nearest-ties-away-from-zero"
+    max_coordinate: int | None = None
+    max_snap_error_dbu: Decimal | str | float | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "meters_per_dbu", _decimal_or_none(self.meters_per_dbu))
+        object.__setattr__(self, "source_old_precision_m", _decimal_or_none(self.source_old_precision_m))
+        object.__setattr__(self, "source_new_precision_m", _decimal_or_none(self.source_new_precision_m))
+        object.__setattr__(self, "max_snap_error_dbu", _decimal_or_none(self.max_snap_error_dbu))
+        if self.rounding_mode != "nearest-ties-away-from-zero":
+            raise ValueError("unsupported rounding mode")
+        if self.max_coordinate is not None and self.max_coordinate <= 0:
+            raise ValueError("max_coordinate must be positive when set")
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "meters_per_dbu": str(self.meters_per_dbu) if self.meters_per_dbu is not None else None,
+            "source_old_precision_m": str(self.source_old_precision_m)
+            if self.source_old_precision_m is not None
+            else None,
+            "source_new_precision_m": str(self.source_new_precision_m)
+            if self.source_new_precision_m is not None
+            else None,
+            "selection_mode": self.selection_mode,
+            "rounding_mode": self.rounding_mode,
+            "max_coordinate": self.max_coordinate,
+            "max_snap_error_dbu": str(self.max_snap_error_dbu) if self.max_snap_error_dbu is not None else None,
+        }
+
+
+@dataclass(frozen=True)
+class AllowedRegion:
+    layers: tuple[LayerSpec, ...]
+    direction: DifferenceDirection | str = DifferenceDirection.BOTH
+    bbox: tuple[int, int, int, int] | None = None
+    whole_layer: bool = False
+    halo_dbu: int = 0
+    label: str = ""
+    reason: str = ""
+
+    def __post_init__(self) -> None:
+        layers = tuple(sorted({LayerSpec.parse(layer) for layer in self.layers}))
+        if not layers:
+            raise ValueError("allowed region must list at least one layer")
+        object.__setattr__(self, "layers", layers)
+        object.__setattr__(self, "direction", DifferenceDirection.coerce(self.direction))
+        if self.halo_dbu < 0:
+            raise ValueError("allowed region halo_dbu must be nonnegative")
+        if self.whole_layer:
+            if self.bbox is not None:
+                raise ValueError("whole-layer allowed region cannot also set bbox")
+        elif self.bbox is None:
+            raise ValueError("allowed region requires bbox unless whole_layer is true")
+        else:
+            x0, y0, x1, y1 = self.bbox
+            if x0 >= x1 or y0 >= y1:
+                raise ValueError("allowed region bbox must satisfy x0 < x1 and y0 < y1")
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "layers": [layer.to_json() for layer in self.layers],
+            "direction": self.direction.value,
+            "bbox": list(self.bbox) if self.bbox is not None else None,
+            "whole_layer": self.whole_layer,
+            "halo_dbu": self.halo_dbu,
+            "label": self.label,
+            "reason": self.reason,
+        }
+
+
+def parse_allowed_region(value: str) -> AllowedRegion:
+    """Parse ``L:D,DIRECTION,X0,Y0,X1,Y1[,HALO]`` into an allowance."""
+
+    parts = [part.strip() for part in value.split(",")]
+    if len(parts) not in {6, 7}:
+        raise ValueError("allowed region must have form L:D,DIRECTION,X0,Y0,X1,Y1[,HALO]")
+    layer = LayerSpec.parse(parts[0])
+    direction = DifferenceDirection.coerce(parts[1])
+    x0, y0, x1, y1 = (int(part) for part in parts[2:6])
+    halo = int(parts[6]) if len(parts) == 7 else 0
+    return AllowedRegion(
+        layers=(layer,),
+        direction=direction,
+        bbox=(x0, y0, x1, y1),
+        halo_dbu=halo,
+    )
+
+
+def parse_allowed_whole_layer(value: str) -> AllowedRegion:
+    """Parse ``L:D,DIRECTION`` into a whole-layer allowance."""
+
+    parts = [part.strip() for part in value.split(",")]
+    if len(parts) != 2:
+        raise ValueError("whole-layer allowance must have form L:D,DIRECTION")
+    return AllowedRegion(
+        layers=(LayerSpec.parse(parts[0]),),
+        direction=DifferenceDirection.coerce(parts[1]),
+        whole_layer=True,
+    )
+
+
+@dataclass(frozen=True)
+class CompareConfig:
+    old_path: Path | str
+    new_path: Path | str
+    top: str | None = None
+    old_top: str | None = None
+    new_top: str | None = None
+    require_top_name_match: bool = False
+    layers: str | LayerSpec | Iterable[str | tuple[int, int] | LayerSpec] = "all"
+    dbu: Decimal | str | float | None = None
+    precision: Decimal | str | float | None = None
+    path_policy: PathPolicy | str = PathPolicy.GDSTK
+    backend: Backend | str = Backend.AUTO
+    evidence_engine: EvidenceEngine | str = EvidenceEngine.AUTO
+    tile_size: int = 1024
+    allowed_regions: tuple[AllowedRegion, ...] = field(default_factory=tuple)
+    allow_empty_selected_layer: bool = False
+    strict: bool = True
+    require_gpu: bool = False
+    failure_policy: FailurePolicy | str = FailurePolicy.FAIL_ON_UNEXPECTED
+    memory_budget_bytes: int | None = None
+    geometry_cache_dir: Path | str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "old_path", Path(self.old_path))
+        object.__setattr__(self, "new_path", Path(self.new_path))
+        if self.geometry_cache_dir is not None:
+            object.__setattr__(self, "geometry_cache_dir", Path(self.geometry_cache_dir))
+        if self.top and (self.old_top or self.new_top):
+            raise ValueError("top cannot be combined with old_top or new_top")
+        if bool(self.old_top) != bool(self.new_top):
+            raise ValueError("old_top and new_top must be supplied together")
+        layers = parse_layer_selector(self.layers)
+        object.__setattr__(self, "layers", layers)
+        dbu = _decimal_or_none(self.dbu)
+        precision = _decimal_or_none(self.precision)
+        if dbu is not None and precision is not None and dbu != precision:
+            raise ValueError("explicit dbu and precision must match in MVP semantics")
+        object.__setattr__(self, "dbu", dbu)
+        object.__setattr__(self, "precision", precision)
+        object.__setattr__(self, "path_policy", PathPolicy.coerce(self.path_policy))
+        backend = Backend.coerce(self.backend)
+        if self.require_gpu and backend == Backend.CPU:
+            raise ValueError("require_gpu cannot be used with backend='cpu'")
+        object.__setattr__(self, "backend", backend)
+        object.__setattr__(self, "evidence_engine", EvidenceEngine.coerce(self.evidence_engine))
+        object.__setattr__(self, "failure_policy", FailurePolicy.coerce(self.failure_policy))
+        if self.tile_size <= 0:
+            raise ValueError("tile_size must be positive")
+        if self.memory_budget_bytes is not None and self.memory_budget_bytes <= 0:
+            raise ValueError("memory_budget_bytes must be positive when set")
+        object.__setattr__(self, "allowed_regions", tuple(self.allowed_regions))
+
+    def to_json_dict(self) -> dict[str, object]:
+        data = {
+            "old_path": str(self.old_path),
+            "new_path": str(self.new_path),
+            "top": self.top,
+            "old_top": self.old_top,
+            "new_top": self.new_top,
+            "require_top_name_match": self.require_top_name_match,
+            "layers": "all" if self.layers == "all" else [layer.to_json() for layer in self.layers],
+            "dbu": str(self.dbu) if self.dbu is not None else None,
+            "precision": str(self.precision) if self.precision is not None else None,
+            "path_policy": self.path_policy.value,
+            "backend": self.backend.value,
+            "evidence_engine": self.evidence_engine.value,
+            "tile_size": self.tile_size,
+            "allowed_regions": [region.to_json() for region in self.allowed_regions],
+            "allow_empty_selected_layer": self.allow_empty_selected_layer,
+            "strict": self.strict,
+            "require_gpu": self.require_gpu,
+            "failure_policy": self.failure_policy.value,
+            "memory_budget_bytes": self.memory_budget_bytes,
+        }
+        if self.geometry_cache_dir is not None:
+            data["geometry_cache_dir"] = str(self.geometry_cache_dir)
+        return data

gdsdiff/cuda_setup.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import subprocess
+import sys
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Sequence
+
+from .native import nvcc_architecture_flags, resolve_nvcc_path
+from .native_cache import native_cache_dir
+
+
+class CudaPreparationError(RuntimeError):
+    """Raised when the optional CUDA backend cannot be prepared and verified."""
+
+
+@dataclass(frozen=True)
+class CudaToolchainReport:
+    available: bool
+    platform: str
+    machine: str
+    nvcc_path: str | None
+    nvcc_version: str | None
+    host_compiler: str | None
+    driver_version: str | None
+    devices: tuple[str, ...]
+    architectures: tuple[str, ...]
+    compile_flags: tuple[str, ...]
+    cache_path: str
+    reason: str | None = None
+
+    def to_json(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class CudaPreparationReport:
+    ready: bool
+    built: bool
+    reused: bool
+    verified: bool
+    library_path: str
+    toolchain: CudaToolchainReport
+
+    def to_json(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def inspect_cuda_toolchain() -> CudaToolchainReport:
+    """Inspect CUDA without importing, compiling, or loading the backend."""
+
+    nvcc = resolve_nvcc_path()
+    version = _command_output((nvcc, "--version")) if nvcc else None
+    smi = _command_output(
+        (
+            "nvidia-smi",
+            "--query-gpu=name,compute_cap,driver_version",
+            "--format=csv,noheader,nounits",
+        )
+    )
+    devices = tuple(line.strip() for line in (smi or "").splitlines() if line.strip())
+    driver = None
+    if devices:
+        parts = [part.strip() for part in devices[0].split(",")]
+        driver = parts[-1] if len(parts) >= 3 else None
+    architectures = tuple(
+        part.strip() for part in os.environ.get("GDSDIFF_CUDA_ARCHITECTURES", "").replace(";", ",").split(",") if part.strip()
+    )
+    available = nvcc is not None and bool(devices)
+    reason = None
+    if nvcc is None:
+        reason = "nvcc was not found in PATH, CUDA_HOME, /usr/local/cuda, or /opt/cuda"
+    elif not devices:
+        reason = "no NVIDIA GPU/driver was visible through nvidia-smi"
+    return CudaToolchainReport(
+        available=available,
+        platform=platform.system(),
+        machine=platform.machine(),
+        nvcc_path=nvcc,
+        nvcc_version=version,
+        host_compiler=_which("g++"),
+        driver_version=driver,
+        devices=devices,
+        architectures=architectures,
+        compile_flags=nvcc_architecture_flags(),
+        cache_path=str(native_cache_dir()),
+        reason=reason,
+    )
+
+
+def prepare_cuda() -> CudaPreparationReport:
+    """Build the CUDA backend in the user cache and run a device smoke test."""
+
+    try:
+        toolchain = inspect_cuda_toolchain()
+    except (OSError, ValueError) as exc:
+        raise CudaPreparationError(str(exc)) from exc
+    if not toolchain.available:
+        raise CudaPreparationError(toolchain.reason or "CUDA toolchain is unavailable")
+    try:
+        from .backends.cuda_ctypes import compare_files_cuda, prepared_cuda_library_path
+
+        library = prepared_cuda_library_path()
+        existed = library.is_file()
+        with tempfile.TemporaryDirectory(prefix="gdsdiff-cuda-smoke-") as directory:
+            left = Path(directory) / "left.bin"
+            right = Path(directory) / "right.bin"
+            left.write_bytes(b"gdsdiff-cuda-smoke")
+            right.write_bytes(b"gdsdiff-cuda-smoke")
+            result = compare_files_cuda(left, right)
+            if not result.same:
+                raise CudaPreparationError("CUDA smoke comparison returned a mismatch")
+    except CudaPreparationError:
+        raise
+    except Exception as exc:
+        raise CudaPreparationError(str(exc)) from exc
+    if not library.is_file():
+        raise CudaPreparationError("CUDA preparation did not publish the expected native library")
+    built = not existed
+    return CudaPreparationReport(
+        ready=True,
+        built=built,
+        reused=not built,
+        verified=True,
+        library_path=str(library),
+        toolchain=toolchain,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="gdsdiff-prepare-cuda", description="Build and verify the optional gdsdiff CUDA backend.")
+    parser.add_argument("--json", action="store_true", help="Emit a machine-readable report.")
+    args = parser.parse_args(argv)
+    try:
+        report = prepare_cuda()
+    except CudaPreparationError as exc:
+        if args.json:
+            print(json.dumps({"ready": False, "error": str(exc)}, indent=2, sort_keys=True))
+        else:
+            print(f"gdsdiff-prepare-cuda: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(report.to_json(), indent=2, sort_keys=True))
+    else:
+        action = "built" if report.built else "reused"
+        print(f"CUDA backend ready ({action}): {report.library_path}")
+    return 0
+
+
+def _command_output(command: tuple[str | None, ...]) -> str | None:
+    if not command or command[0] is None:
+        return None
+    try:
+        completed = subprocess.run(command, check=False, capture_output=True, text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    output = (completed.stdout or completed.stderr).strip()
+    return output if completed.returncode == 0 and output else None
+
+
+def _which(command: str) -> str | None:
+    import shutil
+
+    return shutil.which(command)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gdsdiff/design_history.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+
+from .exact_oracle import format_twice_area
+from .policy import PolicyClassificationResult
+
+
+@dataclass(frozen=True)
+class DesignHistoryEntry:
+    title: str
+    policy_result: PolicyClassificationResult
+    diff_gds_path: str | Path | None = None
+    tests_run: tuple[str, ...] = field(default_factory=tuple)
+    notes: tuple[str, ...] = field(default_factory=tuple)
+    entry_date: date | None = None
+
+    def render_markdown(self) -> str:
+        entry_date = self.entry_date or date.today()
+        lines = [
+            f"### {entry_date.isoformat()} - {self.title}",
+            "",
+            f"- Status: {self.policy_result.status.value}.",
+            f"- Expected diff area dbu^2: {format_twice_area(self.policy_result.expected_twice_area)}.",
+            f"- Unexpected diff area dbu^2: {format_twice_area(self.policy_result.unexpected_twice_area)}.",
+        ]
+        if self.diff_gds_path is not None:
+            lines.append(f"- Diff GDS: `{self.diff_gds_path}`.")
+        if self.tests_run:
+            lines.append("- Tests run:")
+            lines.extend(f"  - `{test}`" for test in self.tests_run)
+        if self.notes:
+            lines.append("- Notes:")
+            lines.extend(f"  - {note}" for note in self.notes)
+        lines.append("- Layer summary:")
+        for layer in self.policy_result.layers:
+            lines.append(
+                "  - "
+                f"{layer.layer.layer}:{layer.layer.datatype} expected="
+                f"{format_twice_area(layer.expected_twice_area)} unexpected="
+                f"{format_twice_area(layer.unexpected_twice_area)} components="
+                f"{len(layer.components)}"
+            )
+        return "\n".join(lines) + "\n"
+
+
+def render_design_history_entry(
+    title: str,
+    policy_result: PolicyClassificationResult,
+    *,
+    diff_gds_path: str | Path | None = None,
+    tests_run: tuple[str, ...] = (),
+    notes: tuple[str, ...] = (),
+    entry_date: date | None = None,
+) -> str:
+    return DesignHistoryEntry(
+        title=title,
+        policy_result=policy_result,
+        diff_gds_path=diff_gds_path,
+        tests_run=tests_run,
+        notes=notes,
+        entry_date=entry_date,
+    ).render_markdown()

gdsdiff/diagnostics.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import json
+import platform
+import sys
+from typing import Any, Sequence
+
+from .native import discover_native_capabilities
+from .native_cache import ENV_NATIVE_CACHE_DIR, LEGACY_ENV_NATIVE_CACHE_DIR, native_cache_dir
+
+
+def backend_diagnostics() -> dict[str, Any]:
+    """Return CPU-safe runtime and optional-backend diagnostics."""
+
+    return {
+        "python": {
+            "implementation": platform.python_implementation(),
+            "version": platform.python_version(),
+        },
+        "platform": {
+            "system": platform.system(),
+            "machine": platform.machine(),
+        },
+        "native_cache": {
+            "path": str(native_cache_dir()),
+            "environment": ENV_NATIVE_CACHE_DIR,
+            "legacy_environment": LEGACY_ENV_NATIVE_CACHE_DIR,
+        },
+        "capabilities": discover_native_capabilities().to_json(),
+    }
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    if argv:
+        print("gdsdiff-diagnostics does not accept arguments", file=sys.stderr)
+        return 2
+    print(json.dumps(backend_diagnostics(), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gdsdiff/diff_gds.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import gdstk
+
+from .policy import ClassifiedComponent, PolicyClassificationResult
+
+
+@dataclass(frozen=True)
+class DiffGdsWriteResult:
+    path: Path
+    component_count: int
+    category_cells: tuple[str, ...]
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "path": str(self.path),
+            "component_count": self.component_count,
+            "category_cells": list(self.category_cells),
+        }
+
+
+def write_diff_gds(
+    policy_result: PolicyClassificationResult,
+    path: str | Path,
+    *,
+    unit: float = 1e-6,
+    precision: float = 1e-9,
+    top_cell_name: str = "GDS_GPU_COMPARE_DIFF",
+) -> DiffGdsWriteResult:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lib = gdstk.Library(unit=unit, precision=precision)
+    top = lib.new_cell(top_cell_name)
+    cells: dict[str, gdstk.Cell] = {}
+    component_count = 0
+    for component in _iter_components(policy_result):
+        cell_name = _category_cell_name(component)
+        cell = cells.get(cell_name)
+        if cell is None:
+            cell = lib.new_cell(cell_name)
+            cells[cell_name] = cell
+            top.add(gdstk.Reference(cell))
+        cell.add(
+            gdstk.Polygon(
+                component.points,
+                layer=component.layer.layer,
+                datatype=component.layer.datatype,
+            )
+        )
+        component_count += 1
+    lib.write_gds(path)
+    return DiffGdsWriteResult(path=path, component_count=component_count, category_cells=tuple(sorted(cells)))
+
+
+def _iter_components(policy_result: PolicyClassificationResult) -> tuple[ClassifiedComponent, ...]:
+    components = []
+    for layer in policy_result.layers:
+        components.extend(layer.components)
+    return tuple(sorted(components, key=lambda component: (component.classification, component.direction.value, component.layer, component.bbox)))
+
+
+def _category_cell_name(component: ClassifiedComponent) -> str:
+    return f"{component.classification}_{component.direction.value}".upper().replace("-", "_")