Source code for squadds.layouts.client

"""Lazy Hugging Face access to SQuADDS layout artifacts."""

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from typing import Any

import pandas as pd
from huggingface_hub import hf_hub_download

from .manifest import DEFAULT_LAYOUT_REPOSITORY, parse_gds_polygons, parse_gds_summary, sha256_file


[docs] @dataclass(frozen=True) class LayoutReference: """A manifest-backed pointer to an immutable layout artifact.""" layout_id: str artifact_id: str gds_path: str component_name: str source_id: str | None = None design_id: str | None = None
[docs] @classmethod def from_record(cls, record: dict[str, Any]) -> LayoutReference: return cls( layout_id=record["layout_id"], artifact_id=record["artifact_id"], gds_path=record["gds_path"], component_name=record["component_name"], source_id=record.get("source_id"), design_id=record.get("design_id"), )
[docs] class LayoutClient: """Find, download, and inspect GDS files without eager bulk downloads.""" def __init__( self, repo_id: str = DEFAULT_LAYOUT_REPOSITORY, revision: str = "main", manifest_filename: str = "metadata/manifest.parquet", geometry_features_filename: str = "metadata/geometry-features-v1.parquet", manifest_path: str | Path | None = None, geometry_features_path: str | Path | None = None, artifact_root: str | Path | None = None, ): self.repo_id = repo_id self.revision = revision self.manifest_filename = manifest_filename self.geometry_features_filename = geometry_features_filename self.manifest_path = Path(manifest_path) if manifest_path else None self.geometry_features_path = Path(geometry_features_path) if geometry_features_path else None self.artifact_root = Path(artifact_root) if artifact_root else None self._manifest: pd.DataFrame | None = None self._geometry_features: pd.DataFrame | None = None
[docs] def manifest(self) -> pd.DataFrame: """Load the compact manifest only; raw GDS files remain remote.""" if self._manifest is None: path = self.manifest_path or Path( hf_hub_download( repo_id=self.repo_id, repo_type="dataset", filename=self.manifest_filename, revision=self.revision, ) ) self._manifest = pd.read_parquet(path) return self._manifest.copy()
[docs] def find( self, *, layout_id: str | None = None, design_id: str | None = None, source_id: str | None = None, ) -> LayoutReference: """Resolve exactly one artifact by its stable identity or provenance.""" supplied = {"layout_id": layout_id, "design_id": design_id, "source_id": source_id} filters = {key: value for key, value in supplied.items() if value is not None} if len(filters) != 1: raise ValueError("Provide exactly one of layout_id, design_id, or source_id.") key, value = next(iter(filters.items())) matches = self.manifest().loc[lambda frame: frame[key] == value] if len(matches) == 0: raise LookupError(f"No layout found for {key}={value!r}.") if len(matches) > 1: if key == "design_id" and matches["layout_id"].nunique() == 1: # Some historical simulation rows repeat an identical design. # They legitimately share one geometry identity, so return the # first deterministic manifest record rather than rejecting it. matches = matches.sort_values("gds_path").head(1) else: raise LookupError(f"Multiple layouts found for {key}={value!r}; use layout_id instead.") return LayoutReference.from_record(matches.iloc[0].to_dict())
[docs] def geometry_features(self, reference: LayoutReference) -> dict[str, Any]: """Return the versioned numerical geometry features for one layout.""" if self._geometry_features is None: path = self.geometry_features_path or Path( hf_hub_download( repo_id=self.repo_id, repo_type="dataset", filename=self.geometry_features_filename, revision=self.revision, ) ) self._geometry_features = pd.read_parquet(path) matches = self._geometry_features.loc[lambda frame: frame["layout_id"] == reference.layout_id] if len(matches) != 1: raise LookupError(f"No unique geometry feature record for {reference.layout_id!r}.") return matches.iloc[0].to_dict()
[docs] def download(self, reference: LayoutReference, verify_checksum: bool = True) -> Path: """Download one GDS artifact and verify its immutable content checksum.""" path = ( self.artifact_root / reference.gds_path if self.artifact_root else Path( hf_hub_download( repo_id=self.repo_id, repo_type="dataset", filename=reference.gds_path, revision=self.revision, ) ) ) if not path.is_file(): raise FileNotFoundError(f"Layout artifact is missing: {path}") if verify_checksum and sha256_file(path) != reference.artifact_id.removeprefix("sha256:"): raise ValueError(f"Checksum mismatch for {reference.gds_path}.") return path
[docs] def summary(self, reference: LayoutReference) -> dict[str, Any]: """Download and inspect a single GDS file using the optional GDS backend.""" return parse_gds_summary(self.download(reference))
[docs] def polygons( self, reference: LayoutReference, *, layer: int | None = None, datatype: int | None = None, ) -> list[dict[str, Any]]: """Download and return selected polygon vertices in micrometers.""" return parse_gds_polygons(self.download(reference), layer=layer, datatype=datatype)