rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/project/canvas/__init__.py

@@ -0,0 +1,55 @@
+"""Project canvas: editable design intent (`canvas.toml`).
+
+The canvas states what the design must achieve — clocks, power,
+analog specs, photonic targets, tool knobs — versioned,
+closure-hashed, and failing loudly on any rule violation. It
+builds on PDK data but never regurgitates it. The compiler
+(SDC/decks) is CANVAS-CST-COMPILE scope; this package is the
+foundation: schema tables, validation, closure, emission.
+"""
+
+from .schema import (
+    CANVAS_SCHEMA,
+    GENERIC_TOOL_KNOBS,
+    HDL_LANGUAGES,
+    KNOWN_METRICS,
+    KNOWN_UNITS,
+    OPERATORS,
+    REF_SCOPES,
+    TOOL_KNOBS,
+)
+from .validate import (
+    CANVAS_FILENAME,
+    CANVAS_VERSION,
+    LEGACY_FILENAME,
+    CanvasError,
+    canvas_closure,
+    dump_canvas_toml,
+    load_project_canvas,
+    validate_canvas,
+)
+from . import compile as compile_mod
+from . import integrate as integrate_mod
+from . import templates as templates_mod
+
+__all__ = [
+    "CANVAS_FILENAME",
+    "CANVAS_SCHEMA",
+    "CANVAS_VERSION",
+    "GENERIC_TOOL_KNOBS",
+    "HDL_LANGUAGES",
+    "KNOWN_METRICS",
+    "KNOWN_UNITS",
+    "LEGACY_FILENAME",
+    "OPERATORS",
+    "REF_SCOPES",
+    "TOOL_KNOBS",
+    "CanvasError",
+    "canvas_closure",
+    "compile_mod",
+    "dump_canvas_toml",
+    "integrate_mod",
+    "load_project_canvas",
+    "templates_mod",
+    "validate_canvas",
+]

rocket_engine/project/canvas/compile.py

@@ -0,0 +1,109 @@
+"""Canvas compiler: canvas to SDC, decks, fragments."""
+
+import math
+
+from .schema import KNOWN_METRICS
+from .validate import CanvasError
+
+
+def _targets(doc):
+    """Return the target list of a canvas mapping.
+
+    Args:
+        doc: Canvas mapping with a targets list.
+
+    Returns:
+        Target list (empty when absent).
+    """
+    targets = doc.get("targets") or []
+    return targets if isinstance(targets, list) else []
+
+
+def _limit_mhz(target):
+    """Convert one clock target limit to MHz.
+
+    Args:
+        target: Target mapping with a limit value/unit.
+
+    Returns:
+        Frequency in MHz.
+    """
+    limit = target.get("limit") or {}
+    value = float(limit.get("value", 0))
+    unit = limit.get("unit", "MHz")
+    scale = {"Hz": 1e-6, "kHz": 1e-3, "MHz": 1.0, "GHz": 1e3}
+    return value * scale.get(unit, 1.0)
+
+
+def compile_sdc(doc):
+    """Compile a digital canvas to SDC tool-native text.
+
+    Args:
+        doc: Validated canvas mapping with clock targets.
+
+    Returns:
+        SDC text with create_clock plus operating conditions.
+
+    Raises:
+        CanvasError: bad_target when no clock target exists.
+    """
+    clocks = [t for t in _targets(doc)
+              if t.get("metric") in ("clock.frequency", "filter.cutoff")]
+    if not clocks:
+        raise CanvasError("bad_target",
+                          "canvas.targets: no clock target for SDC.")
+    mhz = _limit_mhz(clocks[0])
+    if not math.isfinite(mhz) or mhz <= 0:
+        raise CanvasError("bad_limit",
+                          "canvas.targets: clock limit must be positive.")
+    period_ns = 1000.0 / mhz
+    lines = [f"create_clock -name clk -period {period_ns:.4f} "
+             "[get_ports clk]",
+             "set_clock_uncertainty 0.050 [get_clocks clk]",
+             "set_input_delay 0.200 -clock clk [all_inputs]",
+             "set_output_delay 0.200 -clock clk [all_outputs]"]
+    return "\n".join(lines) + "\n"
+
+
+def compile_spice_bounds(doc):
+    """Compile an analog canvas to run_spice measurement bounds.
+
+    Args:
+        doc: Validated canvas mapping with analog targets.
+
+    Returns:
+        Bounds mapping of metric to {min, max} floats.
+    """
+    bounds = {}
+    for target in _targets(doc):
+        metric = target.get("metric")
+        if metric in ("clock.frequency", "filter.cutoff"):
+            continue
+        operator = target.get("operator", "ge")
+        value = float((target.get("limit") or {}).get("value", 0))
+        entry = bounds.setdefault(metric, {})
+        if operator in ("ge", "gt", "eq"):
+            entry["min"] = value
+        if operator in ("le", "lt", "eq"):
+            entry["max"] = value
+    return bounds
+
+
+def compile_librelane(doc):
+    """Compile canvas librelane knobs to a config fragment.
+
+    Args:
+        doc: Canvas mapping with tools.librelane knobs.
+
+    Returns:
+        Fragment mapping with density, effort, corners.
+    """
+    knobs = (doc.get("tools") or {}).get("librelane") or {}
+    frag = {}
+    if knobs.get("density") is not None:
+        frag["density"] = float(knobs["density"])
+    if knobs.get("effort") is not None:
+        frag["effort"] = str(knobs["effort"])
+    if knobs.get("corners") is not None:
+        frag["corners"] = list(knobs["corners"])
+    return frag

rocket_engine/project/canvas/integrate.py

@@ -0,0 +1,48 @@
+"""Canvas integration: project, submit, and I28 run closure."""
+
+from pathlib import Path
+
+from .templates import generate
+from .validate import CANVAS_FILENAME, dump_canvas_toml, load_project_canvas
+
+
+def wizard_create(project_root, pdk_id):
+    """Create a project canvas through the creation wizard.
+
+    Args:
+        project_root: Project dir the canvas.toml lands in.
+        pdk_id: PDK id the template is generated for.
+
+    Returns:
+        Path to the written canvas.toml (validates clean).
+    """
+    root = Path(project_root)
+    root.mkdir(parents=True, exist_ok=True)
+    doc = generate(pdk_id)
+    (root / CANVAS_FILENAME).write_text(dump_canvas_toml(doc))
+    loaded = load_project_canvas(root)
+    return Path(loaded["path"])
+
+
+def canvas_run_closure(project_root):
+    """Load the canvas closure for one I28 run.
+
+    Args:
+        project_root: Project dir holding canvas.toml.
+
+    Returns:
+        Closure mapping pinning canvas plus refs.
+    """
+    return load_project_canvas(project_root)["closure"]
+
+
+def validate_submit_canvas(project_root):
+    """Validate the canvas on the submit path.
+
+    Args:
+        project_root: Project dir holding canvas.toml.
+
+    Returns:
+        Validated config mapping (raises CanvasError otherwise).
+    """
+    return load_project_canvas(project_root)["config"]

rocket_engine/project/canvas/schema.py

@@ -0,0 +1,241 @@
+"""Canvas registry tables: metrics, tool knobs, UI schema descriptor.
+
+Every table here is evidence-backed: metric names and units come
+from the shipped demo canvases (`waveform-generator/canvas.toml`,
+`photonic_matmul/canvas.toml`) and the fuel constraint checks the
+COMPILE slice migrates 1:1 (`rocket_fuel/examples/*/`). Adding a
+metric or knob is a table edit here plus a test — never a silent
+accept.
+"""
+
+#: Metric name -> (dimension, allowed units). Flat fuel names ride
+#: alongside dotted canvas names so the migration probe reads 1:1.
+KNOWN_METRICS = {
+    "clock.frequency": ("frequency", ("Hz", "kHz", "MHz", "GHz")),
+    "filter.cutoff": ("frequency", ("Hz", "kHz", "MHz", "GHz")),
+    "ugbw_mhz": ("frequency", ("Hz", "kHz", "MHz", "GHz")),
+    "supply.voltage": ("voltage", ("V", "mV")),
+    "supply.current": ("current", ("A", "mA", "uA")),
+    "power.dissipation": ("power", ("W", "mW", "uW")),
+    "dc_gain_db": ("gain", ("dB",)),
+    "gain.dc": ("gain", ("dB",)),
+    "phase_margin_deg": ("phase", ("deg",)),
+    "phase.margin": ("phase", ("deg",)),
+    "dac.resolution": ("resolution", ("bit",)),
+    "dac.dnl": ("mismatch", ("LSB",)),
+    "dac.inl": ("mismatch", ("LSB",)),
+    "sim.temperature": ("temperature", ("C", "K")),
+    "drc.violations": ("count", ("count",)),
+    "drc_violations": ("count", ("count",)),
+}
+
+#: Every unit any metric or quantity accepts (union for quantity
+#: checks on spice knobs such as abstol/vntol/temperature).
+KNOWN_UNITS = sorted(
+    {unit for _, units in KNOWN_METRICS.values() for unit in units}
+    | {"Ohm", "kOhm", "F", "pF", "fF", "s", "ms", "us", "ns", "ps"}
+)
+
+#: Comparison operators a target may state.
+OPERATORS = ("lt", "le", "eq", "ge", "gt")
+
+#: Authored HDL dialects, one per canvas (frozen contract enum).
+HDL_LANGUAGES = ("verilog", "systemverilog", "vhdl", "amaranth")
+
+#: Reference scopes (frozen contract PinnedRef/WorkingRef).
+REF_SCOPES = ("project", "library", "pdk", "package", "engine")
+
+#: Tool name -> knob name -> knob spec. Spec kinds: ref (a Pinned
+#: or Working Ref), text (delegated file path or inline text),
+#: hash (pinned sha256), number (plain float with optional
+#: bounds), enum, string_list, boolean, quantity (value + unit).
+TOOL_KNOBS = {
+    "librelane": {
+        "profile": {"kind": "ref"},
+        "configuration": {"kind": "text"},
+        "sha256": {"kind": "hash"},
+        "density": {"kind": "number", "min_exclusive": 0, "max": 1},
+        "effort": {"kind": "enum", "values": ("low", "standard", "high")},
+        "corners": {"kind": "string_list"},
+    },
+    "ngspice": {
+        "profile": {"kind": "ref"},
+        "configuration": {"kind": "text"},
+        "sha256": {"kind": "hash"},
+        "temperature": {"kind": "quantity", "units": ("C", "K")},
+        "reltol": {"kind": "number", "min_exclusive": 0},
+        "abstol": {"kind": "quantity"},
+        "vntol": {"kind": "quantity"},
+        "method": {"kind": "enum", "values": ("trap", "gear")},
+        "max_order": {"kind": "integer", "min": 1, "max": 6},
+    },
+    "xyce": {
+        "profile": {"kind": "ref"},
+        "configuration": {"kind": "text"},
+        "sha256": {"kind": "hash"},
+        "temperature": {"kind": "quantity", "units": ("C", "K")},
+        "reltol": {"kind": "number", "min_exclusive": 0},
+        "abstol": {"kind": "quantity"},
+        "vntol": {"kind": "quantity"},
+        "method": {"kind": "enum", "values": ("trap", "gear")},
+        "max_order": {"kind": "integer", "min": 1, "max": 6},
+    },
+    "yosys": {
+        "profile": {"kind": "ref"},
+        "configuration": {"kind": "text"},
+        "sha256": {"kind": "hash"},
+        "flatten": {"kind": "boolean"},
+        "optimization": {
+            "kind": "enum", "values": ("area", "delay", "balanced")
+        },
+    },
+    "openroad": {
+        "profile": {"kind": "ref"},
+        "configuration": {"kind": "text"},
+        "sha256": {"kind": "hash"},
+        "density": {"kind": "number", "min_exclusive": 0, "max": 1},
+        "effort": {"kind": "enum", "values": ("low", "standard", "high")},
+    },
+}
+
+#: Knobs any unlisted tool accepts (the generic ToolSetting: a
+#: profile plus an optional delegated configuration).
+GENERIC_TOOL_KNOBS = ("profile", "configuration", "sha256")
+
+_CANVAS_VERSION = "rocketeda/canvas/v1"
+
+
+def ui_schema():
+    """Describe every canvas section for rendering and editing.
+
+    The UI renders and edits every section from this descriptor
+    alone — no section, metric, or knob exists that is not
+    listed here.
+
+    Returns:
+        Descriptor with the canvas version and one entry per
+            section (name, description, fields or item shape).
+    """
+    metric_field = {
+        "name": "metric",
+        "type": "enum",
+        "required": True,
+        "values": sorted(KNOWN_METRICS),
+    }
+    sections = [
+        {
+            "name": "schema",
+            "description": "Canvas version pin.",
+            "fields": [
+                {
+                    "name": "schema",
+                    "type": "const",
+                    "required": True,
+                    "values": [_CANVAS_VERSION],
+                }
+            ],
+        },
+        {
+            "name": "hdl",
+            "description": "One authored HDL dialect per canvas; "
+            "omit the section when there is no authored digital "
+            "content (photonic-only).",
+            "fields": [
+                {
+                    "name": "language",
+                    "type": "enum",
+                    "required": True,
+                    "values": list(HDL_LANGUAGES),
+                },
+                {
+                    "name": "top",
+                    "type": "string",
+                    "required": False,
+                },
+            ],
+        },
+        {
+            "name": "technology",
+            "description": "Sealed technology reference (PDK pin).",
+            "fields": [
+                {"name": "scope", "type": "enum", "required": True,
+                 "values": list(REF_SCOPES)},
+                {"name": "id", "type": "string", "required": True},
+                {"name": "revision", "type": "string", "required": True},
+            ],
+        },
+        {
+            "name": "pdks",
+            "description": "Pinned PDK references the intent builds on.",
+            "item": {
+                "type": "ref",
+                "fields": [
+                    {"name": "scope", "type": "enum",
+                     "required": True, "values": list(REF_SCOPES)},
+                    {"name": "id", "type": "string", "required": True},
+                    {"name": "revision", "type": "string",
+                     "required": True},
+                ],
+            },
+        },
+        {
+            "name": "targets",
+            "description": "Design targets: one metric, one "
+            "operator, one limit with units.",
+            "item": {
+                "type": "target",
+                "fields": [
+                    metric_field,
+                    {
+                        "name": "operator",
+                        "type": "enum",
+                        "required": True,
+                        "values": list(OPERATORS),
+                    },
+                    {
+                        "name": "limit",
+                        "type": "quantity",
+                        "required": True,
+                    },
+                    {
+                        "name": "required",
+                        "type": "boolean",
+                        "required": False,
+                    },
+                ],
+            },
+        },
+        {
+            "name": "tools",
+            "description": "Per-tool knobs: inline values or one "
+            "delegated configuration file, never both.",
+            "tools": {
+                name: {
+                    "knobs": sorted(spec),
+                    "spec": {
+                        knob: dict(details)
+                        for knob, details in spec.items()
+                    },
+                }
+                for name, spec in TOOL_KNOBS.items()
+            },
+        },
+        {
+            "name": "references",
+            "description": "Project-relative content refs hashed "
+            "into the run closure.",
+            "item": {
+                "type": "reference",
+                "fields": [
+                    {"name": "path", "type": "string",
+                     "required": True},
+                    {"name": "sha256", "type": "hash",
+                     "required": False},
+                ],
+            },
+        },
+    ]
+    return {"canvas": _CANVAS_VERSION, "sections": sections}
+
+
+CANVAS_SCHEMA = ui_schema()

rocket_engine/project/canvas/templates.py

@@ -0,0 +1,46 @@
+"""Per-PDK canvas templates plus the creation generator."""
+
+_SUPPORTED = ("sky130A", "sky130GF", "gf180", "ihp", "asap7", "lxt",
+              "cspdk", "ubc", "vtt")
+
+
+def supported_pdks():
+    """List PDK ids with a shipped canvas template.
+
+    Returns:
+        Sorted PDK ids the generator accepts.
+    """
+    return sorted(_SUPPORTED)
+
+
+def generate(pdk_id):
+    """Generate a filled canvas document for one PDK.
+
+    Args:
+        pdk_id: PDK id the template is generated for.
+
+    Returns:
+        Canvas mapping that validates clean via validate_canvas.
+
+    Raises:
+        ValueError: For an unsupported PDK id.
+    """
+    if pdk_id not in _SUPPORTED:
+        raise ValueError(f"Unsupported PDK for canvas template: {pdk_id!r}.")
+    return {
+        "schema": "rocketeda/canvas/v1",
+        "pdks": [{"scope": "pdk", "id": "sky130A"
+                  if pdk_id in ("sky130A", "sky130GF") else pdk_id,
+                  "revision": "pinned-rev"}],
+        "targets": [
+            {"metric": "clock.frequency", "operator": "ge",
+             "limit": {"value": 100, "unit": "MHz"}},
+            {"metric": "drc.violations", "operator": "le",
+             "limit": {"value": 0, "unit": "count"}},
+        ],
+        "tools": {"yosys": {"flatten": True},
+                  "ngspice": {"reltol": 0.001},
+                  "librelane": {"density": 0.6, "effort": "standard",
+                                "corners": ["tt"]}},
+        "hdl": {"language": "verilog", "top": "top"},
+    }