rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/workflows/connectgraph_emit.py

@@ -0,0 +1,336 @@
+"""Raw-IR netlist emitters (CONNECT-GRAPH): SPICE, Verilog, VHDL.
+
+`to_raw_ir` resolves one language-neutral record from extracted
+structs — pins to canonical net names through `Connectivity.net_name`
+plus the 4-level format chain — and each printer only arranges raw
+lines and runs its small textual post-pass. Emitters never walk the
+graph: they accept raw-IR mappings only. Bus expansion and line
+joinery each live in exactly one shared helper.
+
+Format chain, first non-empty template wins:
+
+- instance_custom: instance `custom[language]`.
+- symbol_custom: symbol `custom[language]`.
+- instance_format: instance `format[language]`.
+- symbol_format: symbol `format[language]`.
+
+Templates substitute {name}, {symbol}, {cell}, {pins[PIN]},
+{pin_nets} (pin-order nets, space-joined), and {generics[KEY]}.
+Custom lines emit verbatim after substitution; format lines also run
+the language post-pass. An instance with no template at any level is
+skipped silently; a present-but-broken template raises loudly.
+"""
+
+import re
+
+from .connectgraph import ConnectGraphError
+
+RAW_IR_VERSION = 1
+
+LANGUAGES = ("spice", "verilog", "vhdl")
+
+FORMAT_LEVELS = (
+    "instance_custom",
+    "symbol_custom",
+    "instance_format",
+    "symbol_format",
+)
+
+_VHDL_DIRECTIONS = {"input": "in", "output": "out", "inout": "inout"}
+_BUS_RE = re.compile(r"^(?P<base>.+)\[(?P<bit>\d+)\]$")
+_SPICE_WIDTH = 80
+
+
+def resolve_format(instance, symbol, language):
+    """Resolve one instance template through the 4-level chain.
+
+    Args:
+        instance: Instance mapping with custom/format mappings.
+        symbol: Symbol mapping with custom/format mappings.
+        language: One of spice, verilog, vhdl.
+
+    Returns:
+        (level, template) with level from FORMAT_LEVELS, or
+        (None, None) when no level carries a template.
+    """
+    candidates = (
+        ("instance_custom", (instance.get("custom") or {}).get(language)),
+        ("symbol_custom", (symbol.get("custom") or {}).get(language)),
+        ("instance_format", (instance.get("format") or {}).get(language)),
+        ("symbol_format", (symbol.get("format") or {}).get(language)),
+    )
+    for level, template in candidates:
+        if template:
+            return (level, template)
+    return (None, None)
+
+
+def to_raw_ir(structs):
+    """Build the language-neutral raw IR from extracted structs.
+
+    Args:
+        structs: NetlistStructs from prepare_netlist_structs.
+
+    Returns:
+        Plain-data mapping (JSON-safe) with cell, nets, ports,
+        instances carrying per-language lines, and skipped names.
+
+    Raises:
+        ConnectGraphError: Broken template at a resolved level.
+    """
+    connectivity = structs.connectivity
+    nets = [{"id": net.id, "name": connectivity.net_name(net.id)} for net in connectivity.nets]
+    nets.sort(key=lambda n: n["name"])
+    instances = []
+    skipped = []
+    for resolved in structs.instances:
+        symbol = structs.symbols[resolved.symbol]
+        pin_nets = {
+            pin: connectivity.net_name(net_id) for pin, net_id in resolved.pins
+        }
+        namespace = {
+            "name": resolved.name,
+            "symbol": resolved.symbol,
+            "cell": structs.cell,
+            "pins": pin_nets,
+            "pin_nets": " ".join(
+                pin_nets[pin] for pin, _ in resolved.pins
+            ),
+            "generics": dict(resolved.generics),
+        }
+        lines = {}
+        resolutions = {}
+        view = {"custom": resolved.custom, "format": resolved.format}
+        for language in LANGUAGES:
+            level, template = resolve_format(view, symbol, language)
+            if level is None:
+                continue
+            try:
+                lines[language] = [template.format(**namespace)]
+            except (KeyError, IndexError, ValueError) as exc:
+                raise ConnectGraphError(
+                    f"Instance {resolved.name}: broken {language} template "
+                    f"at {level}: {exc}."
+                ) from exc
+            resolutions[language] = level
+        if not resolutions:
+            skipped.append(resolved.name)
+            continue
+        instances.append(
+            {
+                "name": resolved.name,
+                "symbol": resolved.symbol,
+                "pins": [
+                    {"pin": pin, "net": connectivity.net_name(net_id)}
+                    for pin, net_id in resolved.pins
+                ],
+                "generics": dict(resolved.generics),
+                "levels": resolutions,
+                "lines": lines,
+            }
+        )
+    instances.sort(key=lambda i: i["name"])
+    return {
+        "tool": "connectgraph",
+        "raw_ir_version": RAW_IR_VERSION,
+        "cell": structs.cell,
+        "nets": nets,
+        "ports": [dict(p) for p in structs.ports],
+        "instances": instances,
+        "skipped": sorted(skipped),
+    }
+
+
+def emit_netlists(raw_ir, languages=None):
+    """Emit netlists for the requested languages.
+
+    Args:
+        raw_ir: Raw-IR mapping from to_raw_ir.
+        languages: Subset of spice/verilog/vhdl; all when omitted.
+
+    Returns:
+        Mapping of language to netlist text.
+
+    Raises:
+        ConnectGraphError: Unknown language requested.
+    """
+    wanted = list(LANGUAGES) if languages is None else list(languages)
+    unknown = [language for language in wanted if language not in LANGUAGES]
+    if unknown:
+        raise ConnectGraphError(f"Unknown netlist language(s): {', '.join(unknown)}.")
+    printers = {"spice": emit_spice, "verilog": emit_verilog, "vhdl": emit_vhdl}
+    return {language: printers[language](raw_ir) for language in wanted}
+
+
+def emit_spice(raw_ir):
+    """Print the SPICE netlist: subckt frame plus raw instance lines.
+
+    Args:
+        raw_ir: Raw-IR mapping from to_raw_ir.
+
+    Returns:
+        Byte-stable SPICE netlist text ending in one newline.
+    """
+    _check_raw_ir(raw_ir)
+    ports = " ".join(p["name"] for p in raw_ir["ports"])
+    header = f".subckt {raw_ir['cell']}" + (f" {ports}" if ports else "")
+    body = []
+    for instance in raw_ir["instances"]:
+        for line in instance["lines"].get("spice", []):
+            if instance["levels"]["spice"] in ("instance_format", "symbol_format"):
+                body.extend(_wrap_continuation(line, _SPICE_WIDTH, "+"))
+            else:
+                body.append(line)
+    return _join_block(
+        f"* {raw_ir['cell']} - generated by connectgraph raw IR (do not edit)",
+        [header, *body, f".ends {raw_ir['cell']}"],
+    )
+
+
+def emit_verilog(raw_ir):
+    """Print the Verilog netlist: module frame plus raw instances.
+
+    Args:
+        raw_ir: Raw-IR mapping from to_raw_ir.
+
+    Returns:
+        Byte-stable Verilog netlist text ending in one newline.
+    """
+    _check_raw_ir(raw_ir)
+    decls = _verilog_port_decls(raw_ir["ports"])
+    header = f"module {raw_ir['cell']} ({', '.join(decls)});"
+    wires = _bus_declarations(
+        [n["name"] for n in raw_ir["nets"]],
+        {p["name"] for p in raw_ir["ports"]},
+        scalar="wire {name};",
+        vector="wire [{hi}:{lo}] {base};",
+    )
+    body = []
+    for instance in raw_ir["instances"]:
+        body.extend(instance["lines"].get("verilog", []))
+    return _join_block(
+        f"// {raw_ir['cell']} - generated by connectgraph raw IR (do not edit)",
+        [header, *wires, *body, "endmodule"],
+    )
+
+
+def emit_vhdl(raw_ir):
+    """Print the VHDL netlist: entity plus raw port-map instances.
+
+    Args:
+        raw_ir: Raw-IR mapping from to_raw_ir.
+
+    Returns:
+        Byte-stable VHDL netlist text ending in one newline.
+    """
+    _check_raw_ir(raw_ir)
+    ports = "; ".join(
+        f"{p['name']} : {_VHDL_DIRECTIONS[p['direction']]} std_logic"
+        for p in raw_ir["ports"]
+    )
+    signals = _bus_declarations(
+        [n["name"] for n in raw_ir["nets"]],
+        {p["name"] for p in raw_ir["ports"]},
+        scalar="signal {name} : std_logic;",
+        vector="signal {base} : std_logic_vector({hi} downto {lo});",
+    )
+    body = []
+    for instance in raw_ir["instances"]:
+        body.extend(instance["lines"].get("vhdl", []))
+    return _join_block(
+        f"-- {raw_ir['cell']} - generated by connectgraph raw IR (do not edit)",
+        [
+            "library ieee;",
+            "use ieee.std_logic_1164.all;",
+            f"entity {raw_ir['cell']} is",
+            f"port ({ports});" if ports else "port ();",
+            f"end entity {raw_ir['cell']};",
+            f"architecture raw of {raw_ir['cell']} is",
+            *signals,
+            "begin",
+            *body,
+            f"end architecture raw;",
+        ],
+    )
+
+
+def _check_raw_ir(raw_ir):
+    if (
+        not isinstance(raw_ir, dict)
+        or raw_ir.get("raw_ir_version") != RAW_IR_VERSION
+        or not isinstance(raw_ir.get("instances"), list)
+    ):
+        raise ConnectGraphError(
+            "Emitters accept raw-IR mappings from to_raw_ir only."
+        )
+
+
+def _join_block(comment, lines):
+    return comment + "\n" + "\n".join(lines) + "\n"
+
+
+def _wrap_continuation(line, width, marker):
+    """Wrap one line with continuation markers (the line joinery)."""
+    if len(line) <= width:
+        return [line]
+    words = line.split(" ")
+    chunks = [words[0]]
+    for word in words[1:]:
+        if len(chunks[-1]) + 1 + len(word) > width and chunks[-1]:
+            chunks.append(marker + word)
+        else:
+            chunks[-1] = chunks[-1] + " " + word if chunks[-1] else word
+    fixed = []
+    for chunk in chunks[1:]:
+        fixed.append(chunk if chunk.startswith(marker) else marker + chunk)
+    return [chunks[0], *fixed]
+
+
+def _bus_groups(names, ports):
+    """Expand bus-bit names into one declaration group each.
+
+    Scalars yield ("scalar", name); bits base[i] fold into one
+    ("vector", base, lo, hi). Groups fully covered by ports are
+    dropped — the port header already declares them.
+    """
+    bits = {}
+    scalars = set()
+    for name in names:
+        match = _BUS_RE.match(name)
+        if match:
+            bits.setdefault(match.group("base"), []).append(
+                (int(match.group("bit")), name)
+            )
+        else:
+            scalars.add(name)
+    groups = []
+    for base in sorted(set(bits) | scalars):
+        if base in scalars and base not in bits:
+            if base not in ports:
+                groups.append(("scalar", base))
+            continue
+        member_names = [name for _, name in bits.get(base, [])]
+        if member_names and all(name in ports for name in member_names):
+            continue
+        lo = min(bit for bit, _ in bits[base])
+        hi = max(bit for bit, _ in bits[base])
+        groups.append(("vector", base, lo, hi))
+    return groups
+
+
+def _bus_declarations(names, ports, scalar, vector):
+    """Declare nets once: scalars flat, bus bits as one vector."""
+    declarations = []
+    for group in _bus_groups(names, ports):
+        if group[0] == "scalar":
+            declarations.append(scalar.format(name=group[1]))
+        else:
+            declarations.append(
+                vector.format(base=group[1], hi=group[3], lo=group[2])
+            )
+    return declarations
+
+
+def _verilog_port_decls(ports):
+    kinds = {"input": "input", "output": "output", "inout": "inout"}
+    return [f"{kinds[p['direction']]} {p['name']}" for p in ports]

rocket_engine/workflows/gates.py

@@ -0,0 +1,144 @@
+"""Target+canvas gating over a flow plan (WIRE-DECLARED-OPS MC-25).
+
+`plan_checks_report` plans a flow against backends only; this
+module scopes that plan to a v1 target and canvas without
+changing readiness. Every stage names its deck tools (joined
+through the stages DECKS table), the canvas tool settings for
+those tools, and the project-top metric budgets it must
+satisfy — cost (settings) and evidence travel with the plan.
+Constraints naming a `target` stay plan-level (`scoped_targets`)
+for the run to scope; only project-top budgets gate stages.
+"""
+
+from .stages import DECKS
+
+
+def _target_or_raise(target):
+    """Clean one v1 target to its kind plus project scope.
+
+    Args:
+        target: Target mapping with a non-empty kind.
+
+    Returns:
+        Cleaned target with kind plus project_id/cell when given.
+
+    Raises:
+        ValueError: Non-mapping target or a missing kind.
+    """
+    if not isinstance(target, dict) or not isinstance(
+        target.get("kind"), str
+    ) or not target["kind"]:
+        raise ValueError(f"Plan target needs a kind: {target!r}.")
+    clean = {"kind": target["kind"]}
+    for key in ("project_id", "cell"):
+        if target.get(key) is not None:
+            clean[key] = target[key]
+    return clean
+
+
+def _canvas_or_raise(canvas):
+    """Clean one canvas to metric budgets plus tool settings.
+
+    Args:
+        canvas: Canvas mapping with optional `targets`
+            (MetricConstraint list) and `tools` (tool settings);
+            None means an empty canvas.
+
+    Returns:
+        (budgets, scoped, tools): project-top budget mappings,
+            target-scoped (metric, target) pairs, and the tool
+            settings mapping.
+
+    Raises:
+        ValueError: Non-mapping canvas, a non-list targets, or
+            a non-mapping tools.
+    """
+    if canvas is None:
+        return [], [], {}
+    if not isinstance(canvas, dict):
+        raise ValueError(f"Plan canvas must be a mapping: {canvas!r}.")
+    targets = canvas.get("targets", [])
+    tools = canvas.get("tools", {})
+    if not isinstance(targets, list) or any(
+        not isinstance(item, dict) or not item.get("metric")
+        for item in targets
+    ):
+        raise ValueError(f"Plan canvas targets malformed: {targets!r}.")
+    if not isinstance(tools, dict):
+        raise ValueError(f"Plan canvas tools malformed: {tools!r}.")
+    budgets = [
+        {"metric": item["metric"], "operator": item.get("operator"),
+         "limit": item.get("limit")}
+        for item in targets
+        if item.get("target") is None
+    ]
+    scoped = [
+        {"metric": item["metric"], "target": item["target"]}
+        for item in targets
+        if item.get("target") is not None
+    ]
+    return budgets, scoped, dict(tools)
+
+
+def _stage_tools(stage):
+    """Sorted deck-tool names serving one stage's entrypoints.
+
+    Args:
+        stage: Planned stage with entrypoints.
+
+    Returns:
+        Sorted tool names from the DECKS table (scripted and
+            uncovered entrypoints contribute none).
+    """
+    tools = set()
+    for entrypoint in stage.get("entrypoints", []):
+        for cite in DECKS.get(entrypoint, []):
+            tools.add(cite["tool"])
+    return sorted(tools)
+
+
+def gate_plan_for_target(plan, target, canvas=None):
+    """Scope one flow plan to a target and canvas.
+
+    Readiness is untouched — the gate only joins cost and
+    evidence: per-stage deck tools, the canvas tool settings for
+    those tools, and the project-top metric budgets every stage
+    must satisfy.
+
+    Args:
+        plan: Flow plan mapping with flow plus stages (as from
+            plan_checks_report).
+        target: v1 target the plan serves (kind required).
+        canvas: Canvas mapping with targets/tools; None means an
+            empty canvas.
+
+    Returns:
+        Plan mapping plus target, canvas_metrics, canvas_tools,
+            scoped_targets, and per-stage target_kind, tools,
+            canvas_tools, and budgets.
+
+    Raises:
+        ValueError: Bad target or canvas shape.
+    """
+    clean_target = _target_or_raise(target)
+    budgets, scoped, tools = _canvas_or_raise(canvas)
+    stages = []
+    for stage in plan.get("stages", []):
+        stage_tools = _stage_tools(stage)
+        stages.append({
+            **stage,
+            "target_kind": clean_target["kind"],
+            "tools": stage_tools,
+            "canvas_tools": {tool: tools[tool] for tool in stage_tools
+                             if tool in tools},
+            "budgets": [dict(budget) for budget in budgets],
+        })
+    return {
+        **plan,
+        "target": clean_target,
+        "canvas_metrics": [b["metric"] for b in budgets]
+        + [s["metric"] for s in scoped],
+        "canvas_tools": sorted(tools),
+        "scoped_targets": scoped,
+        "stages": stages,
+    }

rocket_engine/workflows/photonic_wire.py

@@ -0,0 +1,76 @@
+"""PHOTONIC-WIRE lane: register the proven photonic solvers on an Engine.
+
+Circulax (time-domain transient circuit sim) serves run_optical
+behind deck.tool `circulax` as the second tool — sax stays first,
+so the default never moves. Meow (EME mode/field solving with
+two-resolution convergence evidence) serves run_em behind
+deck.tool `meow` as the only tool. FDTD/FEM stay out: proposed,
+not proven, so no other deck tool is registered here.
+
+This helper is the executable form of the composition.py wiring
+patch (see docs/work/PHOTONIC-WIRE/report.md): it performs the
+same solver registrations the patch bakes into Engine.__init__,
+plus the same SOLVER_DEPS detection rows the patch adds to
+interfaces/setup.py, so dispatch and capabilities reporting are
+provable on an unpatched tree. Post-patch it is an idempotent
+re-registration of identical keys.
+
+Generalization law: the adapters consume project specs (circuit
+YAML in, transient out; device YAML in, S-params plus
+convergence out). The RC/EME smokes qualify the installs; this
+lane generalizes them and never hardcodes their values.
+"""
+
+from ..interfaces.setup import SOLVER_DEPS
+
+PHOTONIC_TOOLS = {"run_optical": "circulax", "run_em": "meow"}
+
+# Detection rows mirroring the setup.py patch: each cites the
+# solver's own import probe, the way the sax row cites sax. Deeper
+# pip-transitive deps stay out — a solver present but broken fails
+# loud at run time, never as a misreported capability.
+PHOTONIC_DEPS = {
+    ("run_optical", "circulax"): {"python": ["circulax"]},
+    ("run_em", "meow"): {"python": ["meow"]},
+}
+
+
+def wire_photonics(engine, *, runner=None):
+    """Register the circulax and meow solvers on an Engine.
+
+    Circulax joins run_optical after sax (the default is the
+    first registered, so sax keeps it); meow opens run_em.
+    Detection rows land in SOLVER_DEPS only where the static
+    table has none, so an integrator-patched tree keeps its own
+    rows and capabilities reporting never raises unknown_solver
+    for a wired lane.
+
+    Args:
+        engine: Engine to wire (composition root with
+            register_solver).
+        runner: Optional isolated runner handed to both
+            adapters; direct subprocess when None.
+
+    Returns:
+        Mapping of operation to deck-tool key registered
+        ({"run_optical": "circulax", "run_em": "meow"}).
+
+    Raises:
+        ModuleNotFoundError: If the same-ticket adapter modules
+            (adapters.circulax.adapter, adapters.meow.adapter)
+            are not importable — the lane is missing, never
+            faked.
+
+    Caution: Mutates the shared SOLVER_DEPS map (additive rows
+        only, never overwrites) and the engine's solver registry
+        — call once per Engine; repeats re-register identically.
+    """
+    from ..adapters.circulax.adapter import CirculaxAdapter
+    from ..adapters.meow.adapter import MeowAdapter
+
+    for key, spec in PHOTONIC_DEPS.items():
+        SOLVER_DEPS.setdefault(key, dict(spec))
+    engine.register_solver("run_optical", CirculaxAdapter(runner=runner),
+                           tool="circulax")
+    engine.register_solver("run_em", MeowAdapter(runner=runner), tool="meow")
+    return dict(PHOTONIC_TOOLS)