rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/drc/magic.py

@@ -0,0 +1,287 @@
+"""Magic DRC solver adapter (I14): batch DRC behind the ToolAdapter port.
+
+Protocol, verified against magic 8.3.685 + scmos tech 8.2.8: Tcl over
+stdin, `drc check` + `drc catchup` under an explicit box (`check`
+rechecks the box area; `count` needs the catchup), `drc count total`
+for the verdict, then `drc find N` + box readout per error area until
+"There aren't that many errors". Magic exits 0 even for unknown techs
+and broken cells, so the verdict always comes from parsed output,
+never from the exit code.
+"""
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ...interfaces.runparams import MAX_TIMEOUT_S, MIN_TIMEOUT_S
+from ..errors import AdapterError
+
+OPERATION = "run_drc"
+_TIMEOUT_S = 120
+_BOX_MARGIN = 5
+_DEFAULT_BOX = (-5, -5, 15, 10)
+
+_TOTAL_RE = re.compile(r"Total DRC errors found: (\d+)")
+_AREA_RE = re.compile(r"Error area #(\d+):\n([^\n]+)\n(-?\d+) (-?\d+) (-?\d+) (-?\d+)")
+
+
+def _budget_or_raise(job):
+    """Job solver budget: validated, or the adapter default.
+
+    Args:
+        job: Solver job, maybe with a `timeout_s`.
+
+    Returns:
+        Budget seconds for every `_run` call.
+
+    Raises:
+        AdapterError: invalid_command for a boolean,
+            non-number, or out-of-bounds budget.
+    """
+    timeout = job.get("timeout_s", _TIMEOUT_S)
+    if (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, (int, float))
+        or not MIN_TIMEOUT_S <= timeout <= MAX_TIMEOUT_S
+    ):
+        raise AdapterError(
+            "invalid_command", f"Bad timeout_s: {timeout!r}."
+        )
+    return timeout
+
+
+def _box_for(cell_file):
+    x0 = y0 = x1 = y1 = None
+    for line in Path(cell_file).read_text().splitlines():
+        parts = line.split()
+        if len(parts) == 5 and parts[0] == "rect":
+            try:
+                coords = tuple(int(v) for v in parts[1:])
+            except ValueError:
+                continue
+            if x0 is None:
+                x0, y0, x1, y1 = coords
+            else:
+                x0 = min(x0, coords[0])
+                y0 = min(y0, coords[1])
+                x1 = max(x1, coords[2])
+                y1 = max(y1, coords[3])
+    if x0 is None:
+        return _DEFAULT_BOX
+    m = _BOX_MARGIN
+    return (x0 - m, y0 - m, x1 + m, y1 + m)
+
+
+class MagicDrcAdapter(ToolAdapter):
+    """run_drc via Magic: batch DRC over .mag cells, lambda-unit boxes.
+
+    Serves the run_drc operation with deck.tool `magic` (the
+    operation default). Tcl over stdin against a loaded cell; the
+    result is {total, violations[]} with rule/message plus
+    lambda-unit bbox areas.
+
+    Job keys:
+        cell (required): Cell name loaded inside magic.
+        cell_file (required): Path to the .mag cell file.
+        tech: Magic tech name (default scmos).
+        deck: Optional mapping; deck.tool selects the solver
+            (magic here, klayout for the KLayout path).
+        workdir: Run directory (default ".").
+        timeout_s: Sim budget in seconds (default 120).
+
+    Args:
+        runner: Optional isolated runner; direct subprocess when None.
+
+    Caution: Magic exits 0 even for broken cells and unknown techs —
+        the verdict always comes from parsed output, never the exit
+        code. Timeout rides the job budget.
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation, tech, and tool name.
+
+        Args:
+            target: Target the capabilities are reported for
+                (accepted, unused — one tech per job).
+
+        Returns:
+            Capability mapping with operations, tech, and tool.
+        """
+        return {"operations": [OPERATION], "tech": "scmos", "tool": "magic"}
+
+    def preflight(self, job):
+        """Check operation, magic binary, tech probe, and cell file.
+
+        Args:
+            job: Solver job with operation run_drc plus cell,
+                cell_file, and tech inputs.
+
+        Returns:
+            Checked mapping with tech, cell, and cell_file.
+
+        Raises:
+            AdapterError: unsupported_operation for another
+                operation, missing_dependency for a missing magic
+                binary or unloadable tech, invalid_reference for a
+                missing cell file.
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Magic DRC handles {OPERATION}, got {job.get('operation')}.",
+            )
+        timeout = _budget_or_raise(job)
+        if shutil.which("magic") is None:
+            raise AdapterError("missing_dependency", "magic binary not found.")
+        tech = job.get("tech", "scmos")
+        probe = self._run(
+            tech, "quit\n", job.get("workdir", "."), timeout=timeout
+        )
+        if f'Using technology "{tech}"' not in probe.stdout:
+            raise AdapterError(
+                "missing_dependency", f"Cannot load magic tech: {tech}."
+            )
+        cell_file = job.get("cell_file")
+        if not cell_file or not Path(cell_file).is_file():
+            raise AdapterError(
+                "invalid_reference", f"Cell file not found: {cell_file}."
+            )
+        return {
+            "tech": tech,
+            "cell": job.get("cell"),
+            "cell_file": cell_file,
+            "timeout_s": timeout,
+        }
+
+    def execute(self, job):
+        """Run magic DRC: a count pass, then per-area detail.
+
+        Args:
+            job: Solver job with operation run_drc plus cell,
+                cell_file, and tech inputs.
+
+        Returns:
+            Native output with exit_code, combined stdout/stderr,
+                tech, and cell.
+
+        Raises:
+            AdapterError: missing_dependency when the tech fails
+                to load mid-run, runner_unavailable when magic
+                output carries no DRC total line, plus the
+                preflight codes (execute re-checks first).
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        box = _box_for(checked["cell_file"])
+        count_script = (
+            "load {cell}\nbox values {x0} {y0} {x1} {y1}\n"
+            "drc check\ndrc catchup\ndrc count total\nquit\n"
+        ).format(cell=checked["cell"], x0=box[0], y0=box[1], x1=box[2], y1=box[3])
+        first = self._run(
+            checked["tech"], count_script, workdir,
+            timeout=checked["timeout_s"],
+        )
+        if "Failed to load technology" in first.stdout:
+            raise AdapterError(
+                "missing_dependency", f"Cannot load magic tech: {checked['tech']}."
+            )
+        match = _TOTAL_RE.search(first.stdout)
+        if match is None:
+            raise AdapterError(
+                "runner_unavailable", "magic output has no DRC total line."
+            )
+        total = int(match.group(1))
+        # Error areas never outnumber error tiles, so total+1 finds always
+        # reach the "aren't that many" terminator.
+        finds = "".join(
+            f"drc find {n}\nputs [box values]\ndrc why\n"
+            for n in range(1, total + 2)
+        )
+        detail_script = (
+            "load {cell}\nbox values {x0} {y0} {x1} {y1}\n"
+            "drc check\ndrc catchup\n{finds}quit\n"
+        ).format(
+            cell=checked["cell"],
+            x0=box[0],
+            y0=box[1],
+            x1=box[2],
+            y1=box[3],
+            finds=finds,
+        )
+        if total:
+            second = self._run(
+                checked["tech"], detail_script, workdir,
+                timeout=checked["timeout_s"],
+            )
+        else:
+            second = None
+        return {
+            "exit_code": first.returncode,
+            "stdout": first.stdout + (second.stdout if second else ""),
+            "stderr": first.stderr + (second.stderr if second else ""),
+            "tech": checked["tech"],
+            "cell": checked["cell"],
+        }
+
+    def parse(self, native_output):
+        """Parse the DRC total plus per-area rule boxes.
+
+        Args:
+            native_output: Native output with magic stdout.
+
+        Returns:
+            {total, violations[]} with rule plus lambda-unit
+                bbox areas.
+
+        Raises:
+            AdapterError: runner_unavailable when the output has no
+                DRC total line.
+        """
+        stdout = native_output.get("stdout", "")
+        match = _TOTAL_RE.search(stdout)
+        if match is None:
+            raise AdapterError(
+                "runner_unavailable", "magic output has no DRC total line."
+            )
+        violations = [
+            {
+                "area": int(area),
+                "rule": rule,
+                "bbox": [int(x0), int(y0), int(x1), int(y1)],
+            }
+            for area, rule, x0, y0, x1, y1 in _AREA_RE.findall(stdout)
+        ]
+        return {"total": int(match.group(1)), "violations": violations}
+
+    def _run(self, tech, script, workdir, timeout=_TIMEOUT_S):
+        argv = ["magic", "-dnull", "-noconsole", "-T", tech]
+        if self._runner is not None:
+            try:
+                return self._runner.run(
+                    argv, workdir, timeout, (), input_text=script
+                )
+            except ExecutionError as exc:
+                raise AdapterError(exc.code, str(exc)) from exc
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}."
+            )
+        try:
+            return subprocess.run(
+                argv,
+                input=script,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=workdir,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", f"magic timed out after {timeout}s."
+            ) from exc

rocket_engine/adapters/drc/results.py

@@ -0,0 +1,184 @@
+"""Magic DRC v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``run_drc`` magic parse shape (``violations[]`` with
+rule, lambda-unit area, and bbox) onto a typed rule table, a
+bound view, and findings. Pure function of the parsed output: no
+I/O, no tool calls, deterministic ids derived from the run id.
+Magic reports no severity or message per box (see ESCAPE-HARDEN),
+so every box fails as an error finding naming its rule.
+"""
+
+TASK = "run_drc"
+
+_DIAG_CAP = 240
+
+
+def _cap(text):
+    """Cap one diagnostic string at the bundle prose limit.
+
+    Args:
+        text: Raw diagnostic text, possibly unbounded tool prose.
+
+    Returns:
+        The text unchanged when short, else truncated with an
+            ellipsis marker.
+    """
+    text = text if isinstance(text, str) else str(text)
+    if len(text) <= _DIAG_CAP:
+        return text
+    return text[: _DIAG_CAP - 3] + "..."
+
+
+def _bbox_text(bbox):
+    """Render one lambda-unit bbox as comma-joined coordinates.
+
+    Args:
+        bbox: Coordinate list from the v0 violation, if any.
+
+    Returns:
+        Comma-joined coordinate text, or an empty string when the
+            violation carries no bbox.
+    """
+    if not bbox:
+        return ""
+    return ",".join(str(c) for c in bbox)
+
+
+def _message(violation):
+    """Render one violation message from its rule, area, and bbox.
+
+    Args:
+        violation: v0 violation with rule, area, and bbox.
+
+    Returns:
+        Capped message naming the rule and its geometry.
+    """
+    rule = violation.get("rule", "drc")
+    area = violation.get("area")
+    bbox = _bbox_text(violation.get("bbox"))
+    text = f"{rule} at [{bbox}] area {area}"
+    return _cap(text)
+
+
+def _provenance(project_id, run_id, tools, provenance):
+    """Build ResultProvenance, defaulting to a placeholder closure.
+
+    Args:
+        project_id: Project the run belongs to.
+        run_id: Run the bundle describes.
+        tools: Tool ingredient mappings (id, version, digest?).
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Provenance mapping valid against the v1 schema.
+    """
+    if provenance is not None:
+        return provenance
+    ref = {"scope": "project", "id": project_id, "revision": "r1"}
+    return {
+        "snapshot": dict(ref),
+        "input_lock": dict(ref),
+        "closure_hash": "0" * 64,
+        "tools": [
+            {
+                "id": item["id"],
+                "version": item.get("version", ""),
+                "digest": item.get("digest", "0" * 64),
+            }
+            for item in tools
+        ],
+        "parents": [],
+    }
+
+
+def normalize(parsed, *, run_id, project_id="project", target=None,
+              tools=(), provenance=None):
+    """Normalize one magic DRC parse output to a v1 ResultBundle.
+
+    Rule boxes become a table dataset (rule, area, bbox) plus a
+    bound table view; every box also becomes an error finding
+    naming its rule.
+
+    Args:
+        parsed: v0 parse mapping with ``violations[]``.
+        run_id: Run the bundle describes (anchors all ids).
+        project_id: Project the run belongs to.
+        target: v1 target mapping; project kind by default.
+        tools: Tool ingredient mappings for provenance.
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Schema-valid ResultBundle mapping.
+    """
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:violations"
+    datasets = [
+        {
+            "id": table_id,
+            "kind": "table",
+            "row_count": len(violations),
+            "columns": [
+                {
+                    "id": f"{table_id}:rule",
+                    "name": "rule",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [v.get("rule", "") for v in violations],
+                },
+                {
+                    "id": f"{table_id}:area",
+                    "name": "area",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(v.get("area", 0)) for v in violations],
+                },
+                {
+                    "id": f"{table_id}:bbox",
+                    "name": "bbox",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [_bbox_text(v.get("bbox")) for v in violations],
+                },
+            ],
+            "conditions": [],
+        }
+    ]
+    views = [
+        {
+            "id": f"{run_id}:view:violations",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "drc violations",
+        }
+    ]
+    findings = [
+        {
+            "id": f"{run_id}:finding:{index}",
+            "severity": "error",
+            "code": v.get("rule", "drc") or "drc",
+            "message": _message(v),
+        }
+        for index, v in enumerate(violations)
+    ]
+    return {
+        "schema": "rocketeda/results/v1",
+        "ref": {"scope": "project", "id": run_id, "revision": "r1"},
+        "run_id": run_id,
+        "task": TASK,
+        "target": dict(target)
+        if target is not None
+        else {"project_id": project_id, "kind": "project"},
+        "state": "complete",
+        "freshness": "current",
+        "convergence": "not_applicable",
+        "provenance": _provenance(project_id, run_id, tools, provenance),
+        "datasets": datasets,
+        "views": views,
+        "measurements": [],
+        "findings": findings,
+        "artifacts": [],
+        "logs": [],
+        "gaps": [],
+    }

rocket_engine/adapters/drc/results_kl.py

@@ -0,0 +1,188 @@
+"""KLayout DRC v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``run_drc`` klayout parse shape (``violations[]`` with
+rule, message, and optional metric ``bbox_um``) onto a typed rule
+table, a bound view, and findings. Pure function of the parsed
+output: no I/O, no tool calls, deterministic ids derived from
+the run id. Deck mode carries messages; synthetic mode carries
+only rule plus bbox, so a missing message falls back to the rule
+and its geometry (see ESCAPE-HARDEN).
+"""
+
+TASK = "run_drc"
+
+_DIAG_CAP = 240
+
+
+def _cap(text):
+    """Cap one diagnostic string at the bundle prose limit.
+
+    Args:
+        text: Raw diagnostic text, possibly unbounded tool prose.
+
+    Returns:
+        The text unchanged when short, else truncated with an
+            ellipsis marker.
+    """
+    text = text if isinstance(text, str) else str(text)
+    if len(text) <= _DIAG_CAP:
+        return text
+    return text[: _DIAG_CAP - 3] + "..."
+
+
+def _bbox_text(bbox_um):
+    """Render one metric bbox as comma-joined coordinates.
+
+    Args:
+        bbox_um: Metric coordinate list, if any.
+
+    Returns:
+        Comma-joined coordinate text, or an empty string when the
+            violation carries no geometry.
+    """
+    if not bbox_um:
+        return ""
+    return ",".join(str(c) for c in bbox_um)
+
+
+def _message(violation):
+    """Render one violation message, falling back to rule geometry.
+
+    Args:
+        violation: v0 violation with rule, message, and bbox_um.
+
+    Returns:
+        Capped message text naming the rule.
+    """
+    message = violation.get("message")
+    if message:
+        return _cap(message)
+    rule = violation.get("rule", "drc")
+    bbox = _bbox_text(violation.get("bbox_um"))
+    return _cap(f"{rule} at [{bbox}] um")
+
+
+def _provenance(project_id, run_id, tools, provenance):
+    """Build ResultProvenance, defaulting to a placeholder closure.
+
+    Args:
+        project_id: Project the run belongs to.
+        run_id: Run the bundle describes.
+        tools: Tool ingredient mappings (id, version, digest?).
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Provenance mapping valid against the v1 schema.
+    """
+    if provenance is not None:
+        return provenance
+    ref = {"scope": "project", "id": project_id, "revision": "r1"}
+    return {
+        "snapshot": dict(ref),
+        "input_lock": dict(ref),
+        "closure_hash": "0" * 64,
+        "tools": [
+            {
+                "id": item["id"],
+                "version": item.get("version", ""),
+                "digest": item.get("digest", "0" * 64),
+            }
+            for item in tools
+        ],
+        "parents": [],
+    }
+
+
+def normalize(parsed, *, run_id, project_id="project", target=None,
+              tools=(), provenance=None):
+    """Normalize one klayout DRC parse output to a v1 ResultBundle.
+
+    Violations become a table dataset (rule, message, bbox) plus
+    a bound table view; every violation also becomes an error
+    finding with a capped message.
+
+    Args:
+        parsed: v0 parse mapping with ``violations[]``.
+        run_id: Run the bundle describes (anchors all ids).
+        project_id: Project the run belongs to.
+        target: v1 target mapping; project kind by default.
+        tools: Tool ingredient mappings for provenance.
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Schema-valid ResultBundle mapping.
+    """
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:violations"
+    datasets = [
+        {
+            "id": table_id,
+            "kind": "table",
+            "row_count": len(violations),
+            "columns": [
+                {
+                    "id": f"{table_id}:rule",
+                    "name": "rule",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [v.get("rule", "") for v in violations],
+                },
+                {
+                    "id": f"{table_id}:message",
+                    "name": "message",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [_message(v) for v in violations],
+                },
+                {
+                    "id": f"{table_id}:bbox",
+                    "name": "bbox",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [
+                        _bbox_text(v.get("bbox_um")) for v in violations
+                    ],
+                },
+            ],
+            "conditions": [],
+        }
+    ]
+    views = [
+        {
+            "id": f"{run_id}:view:violations",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "drc violations",
+        }
+    ]
+    findings = [
+        {
+            "id": f"{run_id}:finding:{index}",
+            "severity": "error",
+            "code": v.get("rule", "drc") or "drc",
+            "message": _message(v),
+        }
+        for index, v in enumerate(violations)
+    ]
+    return {
+        "schema": "rocketeda/results/v1",
+        "ref": {"scope": "project", "id": run_id, "revision": "r1"},
+        "run_id": run_id,
+        "task": TASK,
+        "target": dict(target)
+        if target is not None
+        else {"project_id": project_id, "kind": "project"},
+        "state": "complete",
+        "freshness": "current",
+        "convergence": "not_applicable",
+        "provenance": _provenance(project_id, run_id, tools, provenance),
+        "datasets": datasets,
+        "views": views,
+        "measurements": [],
+        "findings": findings,
+        "artifacts": [],
+        "logs": [],
+        "gaps": [],
+    }