rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/postlayout/results.py

@@ -0,0 +1,330 @@
+"""Postlayout v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``run_post_layout`` parse shape (``measurements[]`` with
+pre/post ``comparison[]`` rows, ``waveforms[]`` with scale plus
+samples, and ``sim_fail`` violations) onto typed v1 datasets,
+views, measurements, and findings. Pure function of the parsed
+output: no I/O, no tool calls, deterministic ids derived from the
+run id. Long waveforms are stride-downsampled to the inline cap;
+canonical units live on ``measurements[]``.
+"""
+
+TASK = "run_post_layout"
+
+_DIAG_CAP = 240
+_INLINE_CAP = 1024
+
+_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 _downsample(values):
+    """Stride-downsample one sample list to the inline cap.
+
+    Args:
+        values: Sample values in stored order.
+
+    Returns:
+        (samples, downsampled) pair with at most _INLINE_CAP
+            entries, stride-picked deterministically.
+    """
+    values = list(values)
+    if len(values) <= _INLINE_CAP:
+        return values, False
+    step = -(-len(values) // _INLINE_CAP)
+    return values[::step], True
+
+
+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 postlayout parse output to a v1 ResultBundle.
+
+    Measurement rows become a table dataset plus a bound table
+    view; comparison rows become a second table when present;
+    every waveform becomes a transient series dataset with an
+    explicit time axis plus a bound trace view; violations become
+    findings with capped messages.
+
+    Args:
+        parsed: v0 parse mapping with ``measurements[]``,
+            ``comparison[]``, ``waveforms[]``, 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 []
+    comparison_in = parsed.get("comparison") or []
+    waveforms_in = parsed.get("waveforms") 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": "measurements",
+        }
+    ]
+    if comparison_in:
+        cmp_id = f"{run_id}:dataset:comparison"
+        datasets.append(
+            {
+                "id": cmp_id,
+                "kind": "table",
+                "row_count": len(comparison_in),
+                "columns": [
+                    {
+                        "id": f"{cmp_id}:name",
+                        "name": "name",
+                        "dtype": "utf8",
+                        "unit": "1",
+                        "data": [row["name"] for row in comparison_in],
+                    },
+                    {
+                        "id": f"{cmp_id}:delta",
+                        "name": "delta",
+                        "dtype": "float64",
+                        "unit": "1",
+                        "data": [float(row["delta"]) for row in comparison_in],
+                    },
+                    {
+                        "id": f"{cmp_id}:status",
+                        "name": "status",
+                        "dtype": "utf8",
+                        "unit": "1",
+                        "data": [row["status"] for row in comparison_in],
+                    },
+                ],
+                "conditions": [],
+            }
+        )
+        views.append(
+            {
+                "id": f"{run_id}:view:comparison",
+                "kind": "table",
+                "dataset_id": cmp_id,
+                "name": "pre-post comparison",
+            }
+        )
+    for index, wave in enumerate(waveforms_in):
+        samples, _ = _downsample(wave.get("samples") or [])
+        scale, _ = _downsample(wave.get("scale") or [])
+        ds_id = f"{run_id}:dataset:waveform:{index}"
+        axis_id = f"{ds_id}:time"
+        sig_id = f"{ds_id}:signal"
+        datasets.append(
+            {
+                "id": ds_id,
+                "kind": "series",
+                "analysis": "tran",
+                "axes": [
+                    {
+                        "id": axis_id,
+                        "name": "time",
+                        "quantity": "time",
+                        "unit": "s",
+                        "kind": "continuous",
+                        "scale": "linear",
+                        "values": [float(v) for v in scale],
+                    }
+                ],
+                "signals": [
+                    {
+                        "id": sig_id,
+                        "name": wave.get("name", f"waveform_{index}"),
+                        "quantity": "voltage",
+                        "unit": "V",
+                        "values": {
+                            "storage": "inline",
+                            "dtype": "float64",
+                            "shape": [len(samples)],
+                            "data": [float(v) for v in samples],
+                        },
+                    }
+                ],
+                "conditions": [],
+            }
+        )
+        views.append(
+            {
+                "id": f"{run_id}:view:waveform:{index}",
+                "kind": "traces",
+                "dataset_id": ds_id,
+                "name": wave.get("name", f"waveform_{index}"),
+                "x_axis": axis_id,
+                "traces": [
+                    {"signal": sig_id, "transform": "identity",
+                     "axis": "left"}
+                ],
+            }
+        )
+    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/postlayout/translate.py

@@ -0,0 +1,71 @@
+"""KLT to vendor translation for the postlayout path."""
+
+import re
+
+from ..errors import AdapterError
+
+_KLT_RE = re.compile(r"klt", re.IGNORECASE)
+_DEVICE_RE = re.compile(r"^([XMRCL]\S*)\s+(\S+)\s+(\S+)\s+(\S+)(.*)$",
+                        re.M)
+
+_VENDOR_MAP = {
+    "sky130_klt_nmos": "sky130_fd_pr__nfet_01v8",
+    "sky130_klt_pmos": "sky130_fd_pr__pfet_01v8",
+    "klt_nmos": "nfet_01v8",
+    "klt_pmos": "pfet_01v8",
+    "klt_res": "resistor",
+    "klt_cap": "capacitor",
+}
+
+
+def is_klt_netlist(text):
+    """Report whether a netlist carries klt generic devices.
+
+    Args:
+        text: Netlist text under check.
+
+    Returns:
+        True when klt markers appear, else False.
+    """
+    return bool(_KLT_RE.search(text or ""))
+
+
+def translate_klt_netlist(text, vendor="sky130"):
+    """Translate klt generic devices to vendor models.
+
+    Args:
+        text: Extracted netlist text with klt device classes.
+        vendor: Vendor family the models translate to.
+
+    Returns:
+        (translated, mapping) with the translated netlist plus the
+            device rename rows.
+
+    Raises:
+        AdapterError: unsupported_operation when a klt device has
+            no vendor mapping — loud refusal naming the gap, never
+            a silent sim_fail.
+    """
+    mapping = []
+    out_lines = []
+    for line in (text or "").splitlines():
+        mapped = line
+        lowered = line.lower()
+        if "klt" in lowered:
+            hit = None
+            for klt, vend in _VENDOR_MAP.items():
+                if klt in lowered:
+                    hit = (klt, vend)
+                    break
+            if hit is None:
+                raise AdapterError(
+                    "unsupported_operation",
+                    f"KLT device has no {vendor} vendor mapping: "
+                    f"{line.strip()[:160]} (POSTLAYOUT-REAL gap).",
+                )
+            klt, vend = hit
+            pattern = re.compile(re.escape(klt), re.IGNORECASE)
+            mapped = pattern.sub(vend, line)
+            mapping.append({"from": klt, "to": vend, "vendor": vendor})
+        out_lines.append(mapped)
+    return "\n".join(out_lines) + ("\n" if out_lines else ""), mapping

rocket_engine/adapters/profile.py

@@ -0,0 +1,220 @@
+"""PDK profile records: data-driven simulator resolution (PDK-PROFILE).
+
+Adapters read PDK profile records (data), never PDK special-cases
+(code): per-PDK simulator needs (model relpaths, corner names,
+spiceinit lines) live in profile data under docs/pdk/<lane>/,
+with a builtin copy here for contexts where the docs tree is not
+shipped. New PDKs arrive as profile entries, never adapter edits.
+
+Shape follows the PDK-PROFILE direction lock: {gdsfactory package
+pin, KLayout tech, decks, models}. The `sim` section carries what
+a SPICE adapter needs: `model_rel` (default deck relpath under
+the registered store entry), `corners` (valid corner names), and
+`spiceinit_extra` (PDK-only .spiceinit lines beyond the base).
+"""
+
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+from ..interfaces.paths import slugify
+from .errors import AdapterError
+
+PROFILE_SCHEMA = "rocketeda/pdk-profile/v0.1"
+
+_BASE_SPICEINIT = (
+    "set ngbehavior=hsa     ; HSPICE-ish compatibility for PDK model libs",
+    "set ng_nomodcheck      ; do not check model parameters",
+    "option noinit          ; do not dump operating point data into the log",
+    "option klu             ; KLU direct linear solver",
+)
+
+#: Builtin sim record, mirroring docs/pdk/sky130a/profile.yaml
+#: (the authority). Used only when the docs tree is not beside
+#: the package (installed wheels ship code, not docs/).
+_BUILTIN_SIM = {
+    "sky130a": {
+        "model_rel": "libs.tech/combined/sky130.lib.spice",
+        "corners": ["tt", "ss", "ff", "sf", "fs"],
+        "spiceinit_extra": [
+            "set skywaterpdk        ; skip some checks for faster lib loading",
+        ],
+    },
+}
+
+
+def _checkout_root():
+    """Engine checkout root, or None outside a source tree.
+
+    Returns:
+        Checkout root when this file sits inside one (a
+        pyproject marker beside src/), else None.
+    """
+    root = Path(__file__).resolve().parents[2]
+    if (root / "pyproject.toml").is_file():
+        return root
+    return None
+
+
+def lane_profile_path(pdk_id):
+    """Profile file for one PDK lane, when the docs tree is present.
+
+    Args:
+        pdk_id: Canonical PDK display id (either spelling resolves).
+
+    Returns:
+        Profile path, or None when the id is missing, when no
+        checkout docs tree is beside the package, or when the lane
+        file is absent.
+    """
+    if not pdk_id or not isinstance(pdk_id, str):
+        return None
+    root = _checkout_root()
+    if root is None:
+        return None
+    candidate = root / "docs" / "pdk" / slugify(pdk_id) / "profile.yaml"
+    if candidate.is_file():
+        return candidate
+    return None
+
+
+def load_profile_record(path):
+    """Load and validate one lane profile file.
+
+    Args:
+        path: Profile YAML path.
+
+    Returns:
+        Validated profile mapping.
+
+    Raises:
+        AdapterError: invalid_profile for an unreadable file or a
+            record failing schema validation.
+    """
+    try:
+        data = YAML(typ="safe").load(Path(path).read_text())
+    except OSError as exc:
+        raise AdapterError(
+            "invalid_profile", f"Cannot read PDK profile {path}: {exc}."
+        ) from exc
+    return validate_record(data, source=str(path))
+
+
+def validate_record(record, source="record"):
+    """Validate one profile mapping against the profile schema.
+
+    Args:
+        record: Profile mapping under check.
+        source: Where the record came from (for messages).
+
+    Returns:
+        The same mapping, validated.
+
+    Raises:
+        AdapterError: invalid_profile for a non-mapping record, a
+            wrong schema version, or a missing id.
+    """
+    if not isinstance(record, dict):
+        raise AdapterError(
+            "invalid_profile", f"PDK profile must be a mapping: {source}."
+        )
+    if record.get("schema") != PROFILE_SCHEMA:
+        raise AdapterError(
+            "invalid_profile",
+            f"PDK profile {source} must carry schema {PROFILE_SCHEMA}.",
+        )
+    if not record.get("id") or not isinstance(record.get("id"), str):
+        raise AdapterError(
+            "invalid_profile", f"PDK profile {source} misses id."
+        )
+    return record
+
+
+def sim_for(pdk_id, record=None):
+    """Sim record for one PDK: lane file first, builtin next.
+
+    Args:
+        pdk_id: Canonical PDK display id (either spelling resolves).
+        record: Optional already-loaded profile mapping, winning
+            over the lane file and the builtin.
+
+    Returns:
+        Sim mapping (model_rel, corners, spiceinit_extra), or None
+        when the PDK declares no sim profile.
+    """
+    if isinstance(record, dict):
+        sim = record.get("sim")
+        if isinstance(sim, dict):
+            return sim
+    if not pdk_id or not isinstance(pdk_id, str):
+        return None
+    path = lane_profile_path(pdk_id)
+    if path is not None:
+        try:
+            sim = load_profile_record(path).get("sim")
+        except AdapterError:
+            sim = None
+        if isinstance(sim, dict):
+            return sim
+    return _BUILTIN_SIM.get(slugify(pdk_id))
+
+
+def default_model_rel(pdk_id, record=None):
+    """Default store model relpath for one PDK, if profiled.
+
+    Args:
+        pdk_id: Canonical PDK display id (either spelling resolves).
+        record: Optional already-loaded profile mapping.
+
+    Returns:
+        Default model relpath, or None when the PDK declares no
+        sim profile (callers fail loudly, never guess a relpath).
+    """
+    sim = sim_for(pdk_id, record=record)
+    if not isinstance(sim, dict):
+        return None
+    rel = sim.get("model_rel")
+    return rel if isinstance(rel, str) and rel else None
+
+
+def base_spiceinit():
+    """PDK-neutral .spiceinit lines every SPICE run stages.
+
+    Returns:
+        Base .spiceinit lines (no PDK-only flags; those ride the
+        profile `spiceinit_extra`).
+    """
+    return list(_BASE_SPICEINIT)
+
+
+def spiceinit_for(pdk_id, record=None):
+    """Full .spiceinit lines for one PDK: base plus profile extras.
+
+    Args:
+        pdk_id: Canonical PDK display id (either spelling resolves).
+        record: Optional already-loaded profile mapping.
+
+    Returns:
+        .spiceinit lines; base only when the PDK declares no sim
+        profile.
+    """
+    lines = base_spiceinit()
+    sim = sim_for(pdk_id, record=record)
+    if isinstance(sim, dict):
+        for line in sim.get("spiceinit_extra") or []:
+            if isinstance(line, str) and line and line not in lines:
+                lines.append(line)
+    return lines
+
+
+def render_spiceinit(lines):
+    """Render .spiceinit text from staged lines.
+
+    Args:
+        lines: .spiceinit lines (base plus profile extras).
+
+    Returns:
+        .spiceinit file text with a profile-driven header.
+    """
+    head = "* rocket_engine ngspice init (profile-driven: see docs/pdk/)."
+    return head + "\n" + "\n".join(lines) + "\n"

rocket_engine/adapters/sax/README.md

@@ -0,0 +1,23 @@
+# adapters/sax — SAX photonic sim solver
+
+`run_optical` behind the `ToolAdapter` port: preflight refuses the
+wrong operation, bad timeouts, missing/extra sources, unparseable
+specs, and unresolvable interpreters; execute stages the sim driver
+plus a job JSON into the workdir and runs
+`python sax_driver.py sax_job.json`; parse normalizes the JSON
+envelope into `{total, violations[], measurements[], spectra[],
+sax_version}` with file/line locations where meaningful.
+
+Verified against sax 0.18.2 on MZI/ring fixtures
+(`tests/adapters/fixtures/sax/`). The balanced MZI reproduces its
+documented transmission exactly (cross 1.0, bar 0.0); the mistuned
+MZI misses its target with an engine-computed margin; a malformed
+circuit synthesizes an error violation naming the offender with
+file + line rather than going clean. A sax-less interpreter
+raises `missing_dependency`, never a fake verdict.
+
+Tool resolution is the engine interpreter (sax arrives via the pip
+`photonic` group) plus an explicit job `tool_dir` holding an
+alternate python; where the tools live is B10 scope. Registered in
+the Engine as `run_optical` → `sax` per F8, so `deck.tool: sax`
+selects it and a missing hint falls back to it as the default.