layout-canvas 0.1.0__py3-none-any.whl

layout_canvas/__init__.py

@@ -0,0 +1,14 @@
+"""Package initialization."""
+
+import gdsfactory as gf
+
+# Ensure gdsfactory has an active generic PDK default for block generators and compilation
+try:
+    gf.get_active_pdk()
+except Exception:
+    gf.gpdk.PDK.activate()
+
+from layout_canvas.blocks import base
+
+__version__ = "0.1.0"
+__all__ = ["base"]

layout_canvas/blocks/__init__.py

@@ -0,0 +1,25 @@
+"""Block package initialization."""
+
+from layout_canvas.blocks.base import (
+    Block,
+    all_blocks,
+    get,
+    on_pdk_registered,
+    register,
+    unregister,
+)
+
+# Importing the package activates the descriptor-driven ``gen_*``
+# generators: ``generic`` installs its PDK-registration hook on import and
+# replays every PDK already in the registry, so block availability is
+# load-order independent.
+from layout_canvas.blocks import generic  # noqa: F401
+
+__all__ = [
+    "Block",
+    "get",
+    "register",
+    "unregister",
+    "all_blocks",
+    "on_pdk_registered",
+]

layout_canvas/blocks/base.py

@@ -0,0 +1,184 @@
+"""Block registry.
+
+A *block* is a parametric layout generator plus its contract: parameter schema,
+port list, constraints it guarantees internally and a SPICE netlist emitter.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import gdsfactory as gf
+
+from layout_canvas.ir.model import BlockSpec, ParamSpec
+
+BuildFn = Callable[..., gf.Component]
+NetlistFn = Callable[..., str]
+
+
+@dataclass(frozen=True)
+class Block:
+    spec: BlockSpec
+    build: BuildFn
+    netlist: NetlistFn | None = None
+
+    @property
+    def name(self) -> str:
+        return self.spec.name
+
+    def defaults(self) -> dict[str, Any]:
+        return {p.name: p.default for p in self.spec.params}
+
+    def resolve_params(self, params: dict[str, Any]) -> dict[str, Any]:
+        """Merge user params with defaults, coerce types and range-check."""
+        specs = {p.name: p for p in self.spec.params}
+        unknown = set(params) - set(specs)
+        if unknown:
+            raise ValueError(f"{self.name}: unknown params {sorted(unknown)}")
+        out: dict[str, Any] = {}
+        for name, ps in specs.items():
+            out[name] = _coerce(ps, params.get(name, ps.default), self.name)
+        return out
+
+    def component(self, **params: Any) -> gf.Component:
+        resolved = self.resolve_params(params)
+        key = (self.name, tuple(sorted(resolved.items())))
+        cached = _COMPONENT_CACHE.get(key)
+        if cached is not None:
+            return cached
+        component = self.build(**resolved)
+        _COMPONENT_CACHE[key] = component
+        return component
+
+    def spice(self, **params: Any) -> str:
+        if self.netlist is None:
+            raise NotImplementedError(f"{self.name} has no netlist emitter")
+        return self.netlist(**self.resolve_params(params))
+
+
+def _coerce(ps: ParamSpec, value: Any, block: str) -> Any:
+    try:
+        if ps.type == "int":
+            if isinstance(value, float) and not value.is_integer():
+                raise ValueError
+            v: Any = int(value)
+        elif ps.type == "float":
+            v = float(value)
+        elif ps.type == "bool":
+            v = value if isinstance(value, bool) else str(value).lower() in ("1", "true", "yes")
+        else:
+            v = str(value)
+    except (TypeError, ValueError) as e:
+        raise ValueError(f"{block}.{ps.name}: expected {ps.type}, got {value!r}") from e
+    if ps.min is not None and v < ps.min:
+        raise ValueError(f"{block}.{ps.name}={v} below min {ps.min}")
+    if ps.max is not None and v > ps.max:
+        raise ValueError(f"{block}.{ps.name}={v} above max {ps.max}")
+    if ps.choices is not None and v not in ps.choices:
+        raise ValueError(f"{block}.{ps.name}={v!r} not in {ps.choices}")
+    return v
+
+
+_REGISTRY: dict[str, Block] = {}
+# gdsfactory stores cells in a process-wide KCLayout and rejects duplicate
+# cell names. Repeated compilation in an MCP session must therefore reuse the
+# immutable component for an identical block/parameter tuple.
+_COMPONENT_CACHE: dict[tuple[str, tuple[tuple[str, Any], ...]], gf.Component] = {}
+
+
+def register(spec: BlockSpec, netlist: NetlistFn | None = None) -> Callable[[BuildFn], BuildFn]:
+    def deco(fn: BuildFn) -> BuildFn:
+        _REGISTRY[spec.name] = Block(spec=spec, build=fn, netlist=netlist)
+        return fn
+
+    return deco
+
+
+def unregister(name: str) -> None:
+    """Drop a block and its cached components (generated-block removal)."""
+    _REGISTRY.pop(name, None)
+    for key in [k for k in _COMPONENT_CACHE if k[0] == name]:
+        _COMPONENT_CACHE.pop(key, None)
+
+
+def _sync_external_pdks() -> None:
+    """Re-scan the external-PDK env hooks when they changed.
+
+    External descriptors load lazily; their ``gen_*`` blocks register
+    through the ``on_pdk_registered`` hook during that scan, so a caller
+    that never touched ``get_pdk`` still sees them.
+    """
+    from layout_canvas.pdk.descriptor import _ensure_external
+
+    _ensure_external()
+
+
+def on_pdk_registered(
+    cb: Callable[[Any], None],
+    *,
+    on_removed: Callable[[str], None] | None = None,
+) -> None:
+    """Subscribe ``cb(pdk)`` to PDK registrations — present and future.
+
+    The external-PDK scan runs first, so ``cb`` sees every currently
+    registered PDK exactly once (import-order independent), then subscribes
+    for future ``register_pdk`` calls. ``on_removed`` (optional) fires with
+    a name when an external PDK leaves the registry on an env rescan.
+    """
+    from layout_canvas.pdk import all_pdks
+    from layout_canvas.pdk.descriptor import (
+        add_pdk_listener,
+        add_pdk_removed_listener,
+    )
+
+    existing = list(all_pdks().values())  # triggers the lazy external scan
+    add_pdk_listener(cb)
+    if on_removed is not None:
+        add_pdk_removed_listener(on_removed)
+    for pdk in existing:
+        cb(pdk)
+
+
+def get(name: str) -> Block:
+    _sync_external_pdks()
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        raise KeyError(f"unknown block {name!r}; known: {sorted(_REGISTRY)}") from None
+
+
+def describe_pdk_block_gap(pdk_name: str) -> str | None:
+    """Explain a missing block in terms of the PDK registry.
+
+    A JSON-loaded (descriptor-only) PDK has no parametric generators — the
+    honest answer names that boundary instead of a bare "unknown block".
+    Returns None when the PDK is unknown or already has blocks.
+    """
+    from layout_canvas.pdk import get_pdk
+
+    try:
+        get_pdk(pdk_name)
+    except KeyError:
+        return None
+    if any(b.spec.pdk == pdk_name for b in _REGISTRY.values()):
+        return None
+    return (
+        f"no blocks registered for pdk {pdk_name!r} — descriptor PDKs get "
+        "gen_diff_pair/gen_current_mirror/gen_guard_ring automatically when "
+        "extract.roles covers the contact stack; this one does not. Bring "
+        "cells in via import_gds or register_cell, or write a Python block "
+        "generator"
+    )
+
+
+def all_blocks() -> dict[str, Block]:
+    _sync_external_pdks()
+    return dict(_REGISTRY)
+
+
+def clear_component_cache() -> None:
+    """Release cached Python references without invalidating the global layout."""
+
+    _COMPONENT_CACHE.clear()

layout_canvas/blocks/cells.py

@@ -0,0 +1,70 @@
+"""Register a compiled Design as a reusable cell block.
+
+This is the consumption half of ``compiler/hierarchy.cell_abstract``: a
+design compiled once can be instantiated by a parent design as
+``block: "<alias>"`` after registration. The cell's PortSpec contract is
+derived from the child design's formal ports.
+
+The cell's netlist emitter flattens the child's full hierarchical netlist
+into the parent deck: every primitive subckt is inlined and the child's top
+``.subckt`` is retargeted to this block's name, so ``simulate_design`` can
+run real device-level simulation instead of refusing.
+"""
+
+from __future__ import annotations
+
+import gdsfactory as gf
+
+from layout_canvas.blocks import base
+from layout_canvas.compiler.compile import compile_design
+from layout_canvas.compiler.netlist import compile_netlist
+from layout_canvas.ir.model import BlockSpec, Design, PortSpec
+
+
+def _flattened_netlist(design: Design, alias: str, ports: list[PortSpec]) -> str:
+    """Inline ``design``'s complete netlist, renaming its top to ``alias``.
+
+    The emitted source keeps every primitive ``.subckt`` the child needs;
+    the parent's compiler then renames the alias-decl to the variant name.
+    """
+    lines = compile_netlist(design).strip().splitlines()
+    port_names = " ".join(p.name for p in ports)
+    for i, line in enumerate(lines):
+        tok = line.strip().split()
+        if len(tok) > 1 and tok[0].lower() == ".subckt" and tok[1] == design.name:
+            lines[i] = f".subckt {alias} {port_names}".rstrip()
+            for j in range(i + 1, len(lines)):
+                if lines[j].strip().lower().startswith(".ends"):
+                    lines[j] = f".ends {alias}"
+                    break
+            break
+    return "\n".join(lines)
+
+
+def register_design_cell(alias: str, design: Design) -> base.Block:
+    """Register ``design`` under ``alias`` so parent IR can instantiate it."""
+    ports = [
+        PortSpec(name=p.name, layer="met1", direction=p.direction) for p in design.ports
+    ]
+    spec = BlockSpec(
+        name=alias,
+        pdk=design.pdk,
+        level="L2",
+        summary=f"Compiled cell macro for design {design.name!r}",
+        params=[],
+        ports=ports,
+        constraints=["fixed internal layout; reuse via abstract pins"],
+        tags=["cell", "macro"],
+        version=design.ir_version,
+    )
+
+    def _build() -> gf.Component:
+        return compile_design(design)
+
+    block = base.Block(
+        spec=spec,
+        build=lambda **_: _build(),
+        netlist=lambda **_: _flattened_netlist(design, alias, ports),
+    )
+    base._REGISTRY[alias] = block
+    return block

layout_canvas/blocks/gds_cell.py

@@ -0,0 +1,222 @@
+"""Register an external GDS file (e.g. a Virtuoso stream-out) as a cell block.
+
+The layout side is closed: ``build`` re-imports the GDS verbatim through
+``gf.import_gds``. The port contract comes from pin labels — texts on the
+PDK's pin-label datatype (``PDK.pin_purpose``) — walked recursively through
+the cell hierarchy so labels buried in subcells still surface.
+
+Netlist is opt-in: pass ``spice_text`` carrying a ``.subckt <cell_name>``
+declaration whose pin count matches the discovered labels and the block
+gets a real transistor-level emitter (retargeted to the alias). Without it
+the block keeps ``netlist=None`` — the existing fail-closed path makes
+``simulate_design``/``simulate_auto`` refuse by name and LVS compares
+against a black-box, never a false pass.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import gdsfactory as gf
+
+from layout_canvas.blocks import base
+from layout_canvas.ir.model import BlockSpec, PortSpec
+from layout_canvas.pdk import get_pdk
+
+# Datatypes considered "drawing" when mapping a pin label's layer number
+# back to a conductor: sky130 uses 20, IHP uses 0. Vias/contacts share the
+# layer number and are excluded by name.
+_DRAWING_DATATYPES = (0, 20)
+_NON_DRAWING_NAMES = ("via", "con", "mcon", "licon", "tap")
+
+
+@dataclass(frozen=True)
+class _Pin:
+    name: str
+    layer_name: str
+    layer_tuple: tuple[int, int]
+    x: float
+    y: float
+
+
+def _drawing_layer_name(pdk_layers: dict[str, tuple[int, int]], layer_number: int) -> str | None:
+    """Resolve a pin-label layer number to its conductor layer name."""
+    candidates = [
+        name for name, (ln, dt) in pdk_layers.items()
+        if ln == layer_number and dt in _DRAWING_DATATYPES
+        and not any(k in name for k in _NON_DRAWING_NAMES)
+    ]
+    return sorted(candidates)[0] if candidates else None
+
+
+def _pin_labels(gds_path: Path, cell_name: str | None, pdk_name: str) -> tuple[str, list[_Pin]]:
+    """Read the GDS, pick the top cell, harvest pin-label texts (um)."""
+    import klayout.db as db
+
+    ly = db.Layout()
+    ly.read(str(gds_path))
+    tops = list(ly.top_cells())
+    if not tops:
+        raise ValueError(f"{gds_path}: GDS has no top cell")
+    if cell_name is None:
+        if len(tops) > 1:
+            names = sorted(c.name for c in tops)
+            raise ValueError(
+                f"{gds_path}: multiple top cells {names}; pass cell_name to pick one"
+            )
+        cell = tops[0]
+    else:
+        cell = ly.cell(cell_name)
+        if cell is None:
+            raise ValueError(
+                f"{gds_path}: cell {cell_name!r} not found; "
+                f"tops: {sorted(c.name for c in tops)}"
+            )
+
+    pdk = get_pdk(pdk_name)
+    pins: list[_Pin] = []
+    seen: set[str] = set()
+    for li in ly.layer_indexes():
+        info = ly.get_info(li)
+        if info.datatype != pdk.pin_purpose:
+            continue
+        layer_name = _drawing_layer_name(pdk.layers, info.layer)
+        if layer_name is None:
+            continue
+        it = db.RecursiveShapeIterator(ly, cell, li)
+        while not it.at_end():
+            sh = it.shape()
+            if sh.is_text():
+                text = sh.text_string.strip()
+                pt = it.trans() * sh.text_trans * db.Point(0, 0)
+                if text and text not in seen:
+                    seen.add(text)
+                    pins.append(_Pin(
+                        name=text,
+                        layer_name=layer_name,
+                        layer_tuple=(info.layer, pdk.layers[layer_name][1]),
+                        x=pt.x * ly.dbu,
+                        y=pt.y * ly.dbu,
+                    ))
+            it.next()
+    if not pins:
+        raise ValueError(
+            f"{gds_path} cell {cell.name!r}: no pin labels found on "
+            f"(layer/{pdk.pin_purpose}) for pdk {pdk_name!r}. "
+            "Export from Virtuoso with pin labels (e.g. on met*/pn layers)."
+        )
+    return cell.name, pins
+
+
+def _retarget_spice(spice_text: str, cell_name: str, alias: str, n_ports: int) -> str:
+    """Validate the supplied netlist and rename its top subckt to ``alias``."""
+    lines = spice_text.strip().splitlines()
+    decl = None
+    for i, line in enumerate(lines):
+        tok = line.strip().split()
+        if len(tok) > 1 and tok[0].lower() == ".subckt" and tok[1].lower() == cell_name.lower():
+            decl = i
+            subckt_pins = [t for t in tok[2:] if "=" not in t]
+            if len(subckt_pins) != n_ports:
+                raise ValueError(
+                    f"netlist .subckt {cell_name} declares {len(subckt_pins)} pins "
+                    f"but the GDS exposes {n_ports} pin labels"
+                )
+            lines[i] = f".subckt {alias} {' '.join(tok[2:])}".rstrip()
+            break
+    if decl is None:
+        raise ValueError(
+            f"spice_text has no '.subckt {cell_name}' declaration matching the GDS cell"
+        )
+    for j in range(decl + 1, len(lines)):
+        if lines[j].strip().lower().startswith(".ends"):
+            lines[j] = f".ends {alias}"
+            break
+    return "\n".join(lines)
+
+
+def register_gds_cell(
+    alias: str,
+    gds_path: str | Path,
+    pdk: str,
+    cell_name: str | None = None,
+    spice_text: str | None = None,
+) -> base.Block:
+    """Register a GDS file under ``alias`` so parent IR can instantiate it."""
+    path = Path(gds_path)
+    if not path.is_file():
+        raise ValueError(f"GDS not found: {path}")
+    resolved_cell, pins = _pin_labels(path, cell_name, pdk)
+
+    ports = [
+        PortSpec(name=p.name, layer=p.layer_name, direction="inout") for p in pins
+    ]
+    spec = BlockSpec(
+        name=alias,
+        pdk=pdk,
+        level="L2",
+        summary=f"External GDS cell {resolved_cell!r} imported from {path.name}",
+        params=[],
+        ports=ports,
+        constraints=["imported fixed layout"],
+        tags=["cell", "external", "gds"],
+    )
+
+    emitter = None
+    if spice_text is not None:
+        netlist_text = _retarget_spice(spice_text, resolved_cell, alias, len(ports))
+        emitter = lambda **_: netlist_text
+
+    pin_width = 0.2
+    try:
+        pin_width = float(get_pdk(pdk).rules.get("min_pin_width_um", 0.2))
+    except (KeyError, TypeError, ValueError):
+        pass
+
+    def _build() -> gf.Component:
+        comp = gf.import_gds(str(path), cellname=resolved_cell)
+        for p in pins:
+            comp.add_port(
+                name=p.name,
+                center=(p.x, p.y),
+                width=pin_width,
+                orientation=0,
+                layer=p.layer_tuple,
+            )
+        return comp
+
+    block = base.Block(spec=spec, build=lambda **_: _build(), netlist=emitter)
+    base._REGISTRY[alias] = block
+    _IMPORTED[alias] = (resolved_cell, pins, path, pdk)
+    return block
+
+
+_IMPORTED: dict[str, tuple[str, list[_Pin], Path, str]] = {}
+
+
+def import_summary(block: base.Block) -> dict:
+    """Payload shared by the web ``import_gds`` action and the MCP tool."""
+    cell_name, pins, path, pdk = _IMPORTED.get(
+        block.spec.name, (block.spec.name, [], Path(""), block.spec.pdk))
+    bb = block.component().bbox()
+    drc: dict[str, Any]
+    try:
+        from layout_canvas.tools.drc import run_drc
+
+        res = run_drc(str(path), tech=pdk, engine="pya")
+        drc = {"status": res.status, "violations": res.total_violations}
+    except Exception as exc:
+        drc = {"status": "unavailable", "violations": None, "error": str(exc)}
+    return {
+        "alias": block.spec.name,
+        "cell": cell_name,
+        "ports": [
+            {"name": p.name, "layer": p.layer_name,
+             "x": round(p.x, 4), "y": round(p.y, 4)}
+            for p in pins
+        ],
+        "bbox": [float(bb.left), float(bb.bottom), float(bb.right), float(bb.top)],
+        "drc": drc,
+    }