rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/cosim/results.py

@@ -0,0 +1,214 @@
+"""Cosim v1 normalizer: v0 joint parse output to a ResultBundle.
+
+Maps the ``run_cosim`` joint parse shape (``measurements[]``
+with the SNDR gate plus ones-density bounds, and violations for
+bitless analog halves or failing digital benches) onto a typed
+measurement table, bound views, measurements, and findings. Pure
+function of the parsed output: no I/O, no tool calls,
+deterministic ids derived from the run id. PASS measurements keep
+value, target, margin, and status.
+"""
+
+TASK = "run_cosim"
+
+_DIAG_CAP = 240
+
+_SEVERITY = {"error": "error", "warning": "warning"}
+
+
+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 _quantity(value, unit):
+    """Build one v1 Quantity, mapping unitless to dimensionless.
+
+    Args:
+        value: Numeric value.
+        unit: Unit string, possibly empty for unitless measures.
+
+    Returns:
+        Quantity mapping with an explicit unit.
+    """
+    return {"value": float(value), "unit": unit if unit else "1"}
+
+
+def _limit(item):
+    """Pick the binding target bound for one measurement.
+
+    Args:
+        item: v0 measurement with a ``target`` min/max mapping.
+
+    Returns:
+        The bound closest to the measured value, or None when the
+            target is empty.
+    """
+    target = item.get("target") or {}
+    scored = []
+    if target.get("min") is not None:
+        scored.append((float(item["value"]) - float(target["min"]),
+                        float(target["min"])))
+    if target.get("max") is not None:
+        scored.append((float(target["max"]) - float(item["value"]),
+                        float(target["max"])))
+    if not scored:
+        return None
+    return min(scored)[1]
+
+
+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 cosim joint parse output to a v1 ResultBundle.
+
+    Joint measurement rows become a table dataset plus a bound
+    table view; violations (bitless halves, failed benches)
+    become findings with capped messages.
+
+    Args:
+        parsed: v0 parse mapping with ``measurements[]`` and
+            ``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.
+    """
+    measurements_in = parsed.get("measurements") or []
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:measurements"
+    datasets = [
+        {
+            "id": table_id,
+            "kind": "table",
+            "row_count": len(measurements_in),
+            "columns": [
+                {
+                    "id": f"{table_id}:name",
+                    "name": "name",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [item["name"] for item in measurements_in],
+                },
+                {
+                    "id": f"{table_id}:value",
+                    "name": "value",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(item["value"]) for item in measurements_in],
+                },
+                {
+                    "id": f"{table_id}:margin",
+                    "name": "margin",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(item["margin"]) for item in measurements_in],
+                },
+                {
+                    "id": f"{table_id}:status",
+                    "name": "status",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [item["status"] for item in measurements_in],
+                },
+            ],
+            "conditions": [],
+        }
+    ]
+    views = [
+        {
+            "id": f"{run_id}:view:measurements",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "joint measurements",
+        }
+    ]
+    measurements = []
+    for item in measurements_in:
+        entry = {
+            "name": item["name"],
+            "value": _quantity(item["value"], item.get("unit", "")),
+            "margin": _quantity(item["margin"], item.get("unit", "")),
+            "status": "PASS" if item["status"] == "pass" else "FAIL",
+        }
+        bound = _limit(item)
+        if bound is not None:
+            entry["limit"] = _quantity(bound, item.get("unit", ""))
+        measurements.append(entry)
+    findings = [
+        {
+            "id": f"{run_id}:finding:{index}",
+            "severity": _SEVERITY.get(v.get("severity"), "info"),
+            "code": v.get("rule", "sim_fail"),
+            "message": _cap(v.get("message", "")),
+        }
+        for index, v in enumerate(violations)
+    ]
+    converged = not any(v.get("rule") == "sim_fail" for v in 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": "converged" if converged else "not_converged",
+        "provenance": _provenance(project_id, run_id, tools, provenance),
+        "datasets": datasets,
+        "views": views,
+        "measurements": measurements,
+        "findings": findings,
+        "artifacts": [],
+        "logs": [],
+        "gaps": [],
+    }

rocket_engine/adapters/devsim/__init__.py

@@ -0,0 +1,171 @@
+"""Devsim TCAD adapter: run_tcad behind the ToolAdapter port."""
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_tcad"
+_TOOL = "devsim"
+_DUMP = "devsim_dump.json"
+_TIMEOUT_S = 300
+
+
+class DevsimAdapter(ToolAdapter):
+    """run_tcad via devsim: driver dump parsed to measurements.
+
+    Serves the run_tcad operation with tool `devsim`. The driver
+    script calls get_contact_current/get_*_model_values plus
+    solve(info=True) and dumps JSON; the adapter parses the dump
+    file, never stdout scraping.
+
+    Job keys:
+        script (required): Driver python script path.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 300).
+        python: Driver python binary (default sys python).
+
+    Args:
+        runner: Optional isolated runner; direct subprocess when None.
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation and tool.
+
+        Args:
+            target: Target the capabilities are reported for.
+
+        Returns:
+            Capability mapping with operations and tool.
+        """
+        return {"operations": [OPERATION], "tool": _TOOL,
+                "dump": _DUMP}
+
+    def preflight(self, job):
+        """Check operation, script, and devsim importability.
+
+        Args:
+            job: Solver job with operation run_tcad plus script.
+
+        Returns:
+            Checked mapping with script, timeout, and python.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_reference
+                for a missing script, missing_dependency with
+                BLOCKED-needs-host when devsim is not importable.
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Devsim handles {OPERATION}, got {job.get('operation')}.",
+            )
+        script = job.get("script")
+        if not script or not Path(script).is_file():
+            raise AdapterError(
+                "invalid_reference", f"Driver script not found: {script}.")
+        try:
+            __import__(_TOOL)
+        except ImportError as exc:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: devsim not importable "
+                "(need devsim==2.11.2 in the engine venv).",
+            ) from exc
+        timeout = job.get("timeout_s", _TIMEOUT_S)
+        if (not isinstance(timeout, (int, float))
+                or isinstance(timeout, bool) or not timeout > 0):
+            raise AdapterError("invalid_command", f"Bad timeout: {timeout!r}.")
+        checked = {"script": str(script), "timeout_s": timeout,
+                   "python": job.get("python") or "python3"}
+        if self._runner is not None:
+            try:
+                self._runner.preflight()
+            except ExecutionError as exc:
+                raise AdapterError(exc.code, str(exc)) from exc
+        return checked
+
+    def execute(self, job):
+        """Run the driver script under a timeout.
+
+        Args:
+            job: Solver job with operation run_tcad plus script.
+
+        Returns:
+            Native output with exit_code, stdout/stderr, dump, file.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        proc = self._run([checked["python"], checked["script"]],
+                         workdir, checked["timeout_s"])
+        dump_path = Path(workdir) / _DUMP
+        dump = None
+        if dump_path.is_file():
+            try:
+                dump = json.loads(dump_path.read_text())
+            except ValueError:
+                dump = None
+        return {"exit_code": proc.returncode, "stdout": proc.stdout,
+                "stderr": proc.stderr, "dump": dump,
+                "dump_file": _DUMP}
+
+    def parse(self, native_output):
+        """Parse the driver JSON dump to verdict plus measurements.
+
+        Args:
+            native_output: Native output with the dump mapping.
+
+        Returns:
+            {total, violations[], measurements[], source} with the
+                dump file as source.
+
+        Raises:
+            AdapterError: runner_unavailable when no dump is present.
+        """
+        dump = native_output.get("dump")
+        if not isinstance(dump, dict):
+            raise AdapterError(
+                "runner_unavailable", "Devsim run left no dump JSON.")
+        solve = dump.get("solve") or {}
+        violations = []
+        if solve.get("converged") is False or not dump.get("currents"):
+            violations.append({"rule": "tcad_converge",
+                               "severity": "error",
+                               "message": "Devsim solve did not converge."})
+        measurements = []
+        for name, value in (dump.get("currents") or {}).items():
+            try:
+                measurements.append({"name": f"current.{name}",
+                                     "value": float(value), "unit": "A"})
+            except (TypeError, ValueError):
+                continue
+        pots = dump.get("potentials") or []
+        if pots:
+            measurements.append({"name": "potential.count",
+                                 "value": float(len(pots)), "unit": "count"})
+        return {"total": len(violations), "violations": violations,
+                "measurements": measurements, "source": "dump",
+                "dump_file": native_output.get("dump_file", _DUMP)}
+
+    def _run(self, argv, workdir, timeout_s):
+        if self._runner is not None:
+            try:
+                return self._runner.run(argv, workdir, timeout_s)
+            except ExecutionError as exc:
+                raise AdapterError(exc.code, str(exc)) from exc
+        try:
+            return subprocess.run(argv, capture_output=True, text=True,
+                                  timeout=timeout_s, cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "Devsim run timed out.") from exc

rocket_engine/adapters/digital_flow/README.md

@@ -0,0 +1,9 @@
+# LibreLane digital-flow adapter
+
+LibrelaneFlowAdapter serves run_digital_flow with the librelane deck tool. It stages project RTL and flow configuration, runs the Classic flow under a timeout, and parses stage output into findings, measurements, and artifact references for the D11–D27 gates.
+
+The adapter requires the pinned LibreLane 3.0.17 distribution and a compatible PDK root. Tool resolution uses PATH or the job tool_dir; version mismatch refuses. When supplied, BwrapRunner confines the flow with tool and PDK roots read-only and the work directory writable.
+
+Hermetic qualification covers synthetic run trees, parse outcomes, timeouts, and failure gates. The live SERV RTL-to-GDS proof is currently blocked because this environment lacks the pinned distribution and PDK root. Adapter registration is not a claim that the full flow has passed live qualification.
+
+See the [DIGITAL-FLOW report](../../../docs/work/DIGITAL-FLOW/report.md) and [provision plan](../../../docs/provision-plan.md).