rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/elmer/__init__.py

@@ -0,0 +1,163 @@
+"""Elmer FEM adapter: run_thermal behind the ToolAdapter port."""
+
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_thermal"
+_TOOL = "ElmerSolver"
+_DUMP = "savescalars.json"
+_TIMEOUT_S = 600
+_NS_RE = re.compile(r"^(NS|SS) \(ITER=", re.M)
+
+
+class ElmerAdapter(ToolAdapter):
+    """run_thermal via Elmer: SaveScalars dump parsed to verdict.
+
+    Serves the run_thermal operation with tool `elmer`. Channel
+    priority is SaveScalars JSON first, CSV next, VTU fields as
+    artifacts, deterministic NS/SS stdout last. No solver Python
+    API exists, so execution stays subprocess.
+
+    Job keys:
+        sif (required): Elmer case.sif path.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 600).
+
+    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": "elmer",
+                "dump": _DUMP}
+
+    def preflight(self, job):
+        """Check operation, sif, and ElmerSolver presence.
+
+        Args:
+            job: Solver job with operation run_thermal plus sif.
+
+        Returns:
+            Checked mapping with sif, binary, and timeout.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_reference
+                for a missing sif, missing_dependency when
+                ElmerSolver is absent (BLOCKED-needs-host).
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Elmer handles {OPERATION}, got {job.get('operation')}.")
+        sif = job.get("sif")
+        if not sif or not Path(sif).is_file():
+            raise AdapterError(
+                "invalid_reference", f"Case sif not found: {sif}.")
+        binary = shutil.which(_TOOL)
+        if binary is None:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: ElmerSolver not on PATH "
+                "(CSC PPA route).")
+        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 = {"sif": str(sif), "binary": binary,
+                   "timeout_s": timeout}
+        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 ElmerSolver on the sif under a timeout.
+
+        Args:
+            job: Solver job with operation run_thermal plus sif.
+
+        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}.")
+        try:
+            proc = subprocess.run(
+                [checked["binary"], checked["sif"]], capture_output=True,
+                text=True, timeout=checked["timeout_s"], cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "Elmer run timed out.") from exc
+        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 SaveScalars dump, else NS/SS lines, else fail.
+
+        Args:
+            native_output: Native output with the dump mapping.
+
+        Returns:
+            {total, violations[], measurements[], source}.
+
+        Raises:
+            AdapterError: runner_unavailable with no dump and no
+                iteration lines.
+        """
+        dump = native_output.get("dump")
+        if isinstance(dump, dict):
+            if dump.get("converged") is False or not dump.get("scalars"):
+                return {"total": 1, "violations": [{
+                    "rule": "fem_converge", "severity": "error",
+                    "message": "Elmer solve did not converge."}],
+                    "measurements": [], "source": "dump",
+                    "dump_file": native_output.get("dump_file", _DUMP)}
+            measurements = []
+            for name, value in (dump.get("scalars") or {}).items():
+                try:
+                    measurements.append({"name": name, "value": float(value),
+                                         "unit": "SI"})
+                except (TypeError, ValueError):
+                    continue
+            return {"total": 0, "violations": [], "measurements": measurements,
+                    "source": "dump",
+                    "dump_file": native_output.get("dump_file", _DUMP)}
+        text = (native_output.get("stdout") or "")
+        if _NS_RE.search(text):
+            return {"total": 0, "violations": [],
+                    "measurements": [{"name": "iterations", "value": 1.0,
+                                      "unit": "count"}],
+                    "source": "stdio_fallback"}
+        raise AdapterError(
+            "runner_unavailable", "Elmer output has no SaveScalars verdict.")

rocket_engine/adapters/envelope.py

@@ -0,0 +1,120 @@
+"""Shared marker-delimited envelope extraction for solver drivers.
+
+Solver stdout is untrusted: warnings, banners, and progress lines may
+surround the one JSON envelope the driver prints. Drivers frame the
+envelope with ``ROCKETEDA_ENVELOPE_BEGIN``/``ROCKETEDA_ENVELOPE_END``
+markers (one marker per line, JSON between); this helper extracts the
+framed document and tolerates any chatter outside it. Legacy clean
+stdout (exactly one JSON document, no markers) still parses, and
+unmarked chatter falls back to a best-effort envelope scan so old
+drivers degrade gracefully. Chatter is never fatal: the native stdout
+(with warnings) stays intact for the Engine run log, which stores it
+verbatim (see ``Engine._run_operation``); only the envelope is parsed.
+"""
+
+import json
+
+from .errors import AdapterError
+
+ENVELOPE_BEGIN = "ROCKETEDA_ENVELOPE_BEGIN"
+ENVELOPE_END = "ROCKETEDA_ENVELOPE_END"
+
+
+def emit_envelope(payload):
+    """Emit one marker-delimited envelope document.
+
+    Args:
+        payload: Envelope mapping with an ``ok`` boolean.
+
+    Returns:
+        Marker-framed envelope text (begin line, JSON line, end line).
+    """
+    return "\n".join(
+        [ENVELOPE_BEGIN, json.dumps(payload), ENVELOPE_END]
+    ) + "\n"
+
+
+def _scan(text):
+    """Last envelope-shaped JSON object in text, or None when absent."""
+    decoder = json.JSONDecoder()
+    found = None
+    start = 0
+    while True:
+        index = text.find("{", start)
+        if index == -1:
+            return found
+        try:
+            data, _ = decoder.raw_decode(text[index:])
+        except ValueError:
+            start = index + 1
+            continue
+        if isinstance(data, dict) and isinstance(data.get("ok"), bool):
+            found = data
+        start = index + 1
+
+
+def extract_envelope(stdout, *, tool):
+    """Extract one driver envelope from possibly chattered stdout.
+
+    Markers first, then the legacy whole-stdout document, then a
+    best-effort envelope scan for unmarked chatter. The native stdout
+    is never mutated: warnings stay in it for the Engine run log.
+
+    Args:
+        stdout: Driver stdout text (bytes are decoded as UTF-8).
+        tool: Driver label for the no-envelope message (sax,
+            circulax, views, meow).
+
+    Returns:
+        Envelope mapping with an ``ok`` boolean.
+
+    Raises:
+        AdapterError: runner_unavailable when no JSON envelope is
+            found or the framed document is not an envelope.
+    """
+    if isinstance(stdout, (bytes, bytearray)):
+        text = bytes(stdout).decode("utf-8", errors="replace")
+    elif isinstance(stdout, str):
+        text = stdout
+    elif stdout is None:
+        text = ""
+    else:
+        raise AdapterError(
+            "runner_unavailable",
+            f"{tool} driver printed no JSON envelope.",
+        )
+    message = f"{tool} driver printed no JSON envelope."
+    begin = text.rfind(ENVELOPE_BEGIN)
+    if begin != -1:
+        end = text.find(ENVELOPE_END, begin + len(ENVELOPE_BEGIN))
+        if end == -1:
+            raise AdapterError("runner_unavailable", message)
+        candidate = text[begin + len(ENVELOPE_BEGIN):end].strip()
+        try:
+            data = json.loads(candidate)
+        except (TypeError, ValueError):
+            data = _scan(candidate)
+            if data is None:
+                raise AdapterError(
+                    "runner_unavailable", message
+                ) from None
+            return data
+        if not isinstance(data, dict) or not isinstance(
+            data.get("ok"), bool
+        ):
+            raise AdapterError("runner_unavailable", message)
+        return data
+    try:
+        data = json.loads(text)
+    except (TypeError, ValueError):
+        pass
+    else:
+        if not isinstance(data, dict) or not isinstance(
+            data.get("ok"), bool
+        ):
+            raise AdapterError("runner_unavailable", message)
+        return data
+    found = _scan(text)
+    if found is None:
+        raise AdapterError("runner_unavailable", message)
+    return found

rocket_engine/adapters/equivalence/__init__.py

@@ -0,0 +1,156 @@
+"""Equivalence adapter: run_formal with the eqy provider."""
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_formal"
+_TOOL = "eqy"
+_DONE_RE = re.compile(r"DONE \((PASS|FAIL|UNKNOWN|ERROR), rc=(\d+)\)")
+
+
+class EqyAdapter(ToolAdapter):
+    """run_formal via eqy: verdict file plus DONE plus partitions.
+
+    Serves the run_formal operation with tool `eqy`. Gating is the
+    V1 verdict filename (PASS/FAIL/UNKNOWN/ERROR), confirmed by the
+    DONE line; per-partition S1 status rows plus partition JSON
+    carry the table. Never imports eqy.py (exit-unsafe).
+
+    Job keys:
+        config (required): Eqy .eqy config path.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 600).
+
+    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}
+
+    def preflight(self, job):
+        """Check operation, config, and eqy presence.
+
+        Args:
+            job: Solver job with operation run_formal plus config.
+
+        Returns:
+            Checked mapping with config, binary, and timeout.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_reference
+                for a missing config, missing_dependency when eqy
+                is absent (BLOCKED-needs-host).
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Eqy handles {OPERATION}, got {job.get('operation')}.")
+        config = job.get("config")
+        if not config or not Path(config).is_file():
+            raise AdapterError(
+                "invalid_reference", f"Eqy config not found: {config}.")
+        binary = shutil.which(_TOOL)
+        if binary is None:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: eqy not on PATH (oss-cad-suite).")
+        timeout = job.get("timeout_s", 600)
+        if (not isinstance(timeout, (int, float))
+                or isinstance(timeout, bool) or not timeout > 0):
+            raise AdapterError("invalid_command", f"Bad timeout: {timeout!r}.")
+        checked = {"config": str(config), "binary": binary,
+                   "timeout_s": timeout}
+        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 eqy on the config under a timeout.
+
+        Args:
+            job: Solver job with operation run_formal plus config.
+
+        Returns:
+            Native output with exit_code, stdout/stderr, verdict
+                file, and partitions.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        try:
+            proc = subprocess.run(
+                [checked["binary"], checked["config"]], capture_output=True,
+                text=True, timeout=checked["timeout_s"], cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "Eqy run timed out.") from exc
+        verdict = None
+        for name in ("PASS", "FAIL", "UNKNOWN", "ERROR"):
+            if (Path(workdir) / name).is_file():
+                verdict = name
+                break
+        return {"exit_code": proc.returncode, "stdout": proc.stdout,
+                "stderr": proc.stderr, "verdict_file": verdict,
+                "partitions": []}
+
+    def parse(self, native_output):
+        """Parse the V1 verdict file plus DONE line.
+
+        Args:
+            native_output: Native output with verdict file/stdout.
+
+        Returns:
+            {total, violations[], verdict, source}.
+
+        Raises:
+            AdapterError: runner_unavailable with no verdict file
+                and no DONE line.
+        """
+        verdict = native_output.get("verdict_file")
+        match = _DONE_RE.search(native_output.get("stdout") or "")
+        if match is not None:
+            verdict = verdict or match.group(1)
+        if verdict not in ("PASS", "FAIL", "UNKNOWN", "ERROR"):
+            raise AdapterError(
+                "runner_unavailable", "Eqy output has no verdict.")
+        partitions = native_output.get("partitions") or []
+        failed = [p for p in partitions
+                  if str(p.get("status", "")).split()[0:1] == ["FAIL"]
+                  or p.get("status") == "FAIL"]
+        if verdict == "PASS" and not failed:
+            return {"total": 0, "violations": [], "verdict": verdict,
+                    "partitions": partitions, "source": "verdict_file"}
+        violations = [{
+            "rule": "equivalence_fail", "severity": "error",
+            "message": f"Eqy verdict {verdict}."}]
+        for part in failed:
+            violations.append({"rule": "equivalence_partition",
+                               "severity": "error",
+                               "message": f"Partition {part.get('name')}"
+                                          " failed."})
+        return {"total": len(violations), "violations": violations,
+                "verdict": verdict, "partitions": partitions,
+                "source": "verdict_file"}

rocket_engine/adapters/errors.py

@@ -0,0 +1,181 @@
+"""Error type for adapter violations. Carries a stable machine code.
+
+The v0->v1 code table lives here too: every v0 engine code maps to
+its v1 catalog code (or None where v1 has no counterpart) plus the
+HTTP status the transports serve. Statuses for mapped codes follow
+contracts/v1/catalog/errors.json exactly (RULING-02: v1 wins); the
+parity test pins that. Emitted payloads keep the v0 code — fidelity
+to what the engine raised — while the status comes from this table.
+"""
+
+
+class AdapterError(Exception):
+    """Adapter violation with a stable machine code.
+
+    Args:
+        code: Stable machine-readable error code.
+        message: Human-readable detail.
+        fields: Itemized fields, when the error names any.
+    """
+
+    def __init__(self, code, message, fields=None):
+        super().__init__(message)
+        self.code = code
+        self.fields = fields or []
+
+
+#: v0 code -> (v1 catalog code or None, HTTP status). None marks a
+#: v0-only row: no v1 counterpart exists, so the v0 code is served
+#: with the tabled status. Unknown codes default to 400 with the
+#: v0 code kept — stable engine codes are client-caused; uncoded
+#: crashes are 500s handled separately, never through this table.
+_CODE_TABLE = {
+    # Approvals: run-state conflicts.
+    "approval_denied": ("invalid_run_state", 409),
+    "approval_expired": ("invalid_run_state", 409),
+    "approval_forbidden": ("invalid_run_state", 409),
+    "approval_invalid": ("invalid_run_state", 409),
+    "approval_pending": ("invalid_run_state", 409),
+    # Conflicts.
+    "request_conflict": ("request_conflict", 409),
+    "unmet_dependency": (None, 409),
+    "resync_required": ("read_set_incomplete", 409),
+    "revision_conflict": ("revision_conflict", 409),
+    "console_busy": ("request_conflict", 409),
+    "coalesced_run_lost": ("request_conflict", 409),
+    # Duplicates.
+    "component_exists": ("duplicate_configuration", 422),
+    "project_exists": ("duplicate_configuration", 422),
+    # Capabilities and runtime.
+    "missing_dependency": ("capability_unavailable", 422),
+    "isolation_unavailable": ("runtime_unavailable", 503),
+    "runner_unavailable": ("runtime_unavailable", 503),
+    # Malformed input.
+    "invalid_address": ("invalid_request", 400),
+    "invalid_arguments": ("invalid_request", 400),
+    "invalid_cell": ("invalid_request", 400),
+    "invalid_command": ("invalid_request", 400),
+    "invalid_component": ("invalid_request", 400),
+    "invalid_data": ("invalid_request", 400),
+    "invalid_document": ("invalid_request", 400),
+    "invalid_entity": ("invalid_request", 400),
+    "invalid_kind": ("invalid_request", 400),
+    "invalid_ledger": ("invalid_request", 400),
+    "invalid_path": ("invalid_request", 400),
+    "invalid_policy": ("invalid_request", 400),
+    "invalid_predicate": ("invalid_request", 400),
+    "invalid_project": ("invalid_request", 400),
+    "invalid_reference": ("invalid_request", 400),
+    "invalid_run_param": ("invalid_request", 400),
+    "invalid_run_request": ("invalid_request", 400),
+    "invalid_schema": ("invalid_request", 400),
+    "invalid_yaml": ("invalid_request", 400),
+    "unknown_run_param": ("invalid_request", 400),
+    "type_mismatch": ("invalid_request", 400),
+    "empty_cell": ("invalid_request", 400),
+    "empty_entry": ("invalid_request", 400),
+    "empty_policy": ("invalid_request", 400),
+    "future_format": ("invalid_request", 400),
+    "gitignore_mismatch": ("invalid_request", 400),
+    "batch_unreadable": ("invalid_request", 400),
+    "cell_unreadable": ("invalid_request", 400),
+    "path_escape": ("invalid_request", 400),
+    # Unknown ids.
+    "not_found": ("not_found", 404),
+    "missing_entry": ("not_found", 404),
+    "missing_policy": ("not_found", 404),
+    "unknown_cell": ("not_found", 404),
+    "unknown_component": ("not_found", 404),
+    "unknown_document": ("not_found", 404),
+    "unknown_entity": ("not_found", 404),
+    "unknown_request": ("not_found", 404),
+    "unknown_revision": ("not_found", 404),
+    "unknown_run": ("not_found", 404),
+    "unknown_topic": ("not_found", 404),
+    # Unsupported (semantic, not malformed).
+    "unsupported_operation": ("unknown_task", 422),
+    "unsupported_version": ("unknown_task", 422),
+    # v0-only rows: no v1 counterpart; status is the contract.
+    "cross_project_denied": (None, 403),
+    "cross_origin_denied": (None, 403),
+    "backfill_readonly": (None, 403),
+    "pool_full": (None, 429),
+    "server_busy": (None, 503),
+    "body_too_large": (None, 413),
+    "unsupported_media_type": (None, 415),
+    "method_not_allowed": (None, 405),
+    "credential_revoked": (None, 500),
+    "credential_unknown": (None, 500),
+    "non_loopback_bind_denied": (None, 500),
+    "internal_error": ("internal_error", 500),
+}
+
+#: v0 code -> v1 catalog code (None where v1 has no counterpart).
+V0_TO_V1 = {code: v1 for code, (v1, _) in _CODE_TABLE.items()}
+
+#: Codes that ask the client to back off (served with Retry-After).
+_RETRYABLE = frozenset({"pool_full", "server_busy"})
+
+
+def status_for_code(code):
+    """HTTP status for one v0 error code.
+
+    Args:
+        code: Stable v0 error code.
+
+    Returns:
+        Tabled status, or 400 for an unlisted code (the code is
+        still emitted — the table has a gap, not the engine).
+    """
+    return _CODE_TABLE.get(code, (None, 400))[1]
+
+
+def v1_for_code(code):
+    """v1 catalog code for one v0 error code, if one exists.
+
+    Args:
+        code: Stable v0 error code.
+
+    Returns:
+        v1 code, or None where v1 has no counterpart.
+    """
+    return _CODE_TABLE.get(code, (None, 400))[0]
+
+
+def retry_after_for(code, seconds):
+    """Retry-After value for one v0 code, when the client must wait.
+
+    Args:
+        code: Stable v0 error code.
+        seconds: Backoff the transport advertises.
+
+    Returns:
+        Seconds as a string for pool_full/server_busy, else None.
+    """
+    if code in _RETRYABLE:
+        return str(seconds)
+    return None
+
+
+def error_payload(exc):
+    """Wire payload for one failure: code + message + fields.
+
+    Coded engine errors serialize untouched (fields only when the
+    error names any); uncoded crashes become a generic internal
+    error — raw exception text never crosses the wire.
+
+    Args:
+        exc: Raised failure.
+
+    Returns:
+        Mapping with code and message, plus fields when present.
+    """
+    code = getattr(exc, "code", None)
+    if code is None:
+        return {"code": "internal_error",
+                "message": "Internal engine error."}
+    payload = {"code": code, "message": str(exc) or code}
+    fields = getattr(exc, "fields", None)
+    if fields:
+        payload["fields"] = list(fields)
+    return payload

rocket_engine/adapters/extract_magic/README.md

@@ -0,0 +1,15 @@
+# adapters/extract_magic — Magic extraction solver
+
+Batch extraction behind the `ToolAdapter` port: preflight refuses
+missing binaries, unloadable techs, and missing cells; execute runs
+magic headless (`-dnull -noconsole`) over `extract all` + `ext2spice
+lvs`; parse reads back the `<cell>.ext`/`<cell>.spice` pair into
+`{device_count, devices[]}` with class + w/l per FET.
+
+Verified against magic 8.3.685 + sky130A tech 1.0.588 on
+`sky130_fd_sc_hd__inv_2` from the registered PDK (4 FETs, exact
+w/l). Magic exits 0 even on failure, so the verdict comes from
+parsed output, never the exit code.
+
+Status: EXTRACT-SKY130 GREEN. See `docs/probe-extract-lvs.md`.
+Status: EXTRACT-GDS GREEN. See `docs/probe-extract-gds.md`.