feat: PyCircuit V5 — cycle-aware grammar, design migration, simulation speedup & cycle-balance optimization

.gitignore

@@ -3,9 +3,16 @@ __pycache__/
 *.py[codz]
 *$py.class
 
+# macOS
+.DS_Store
+
 # C extensions
 *.so
 *.dylib
+*.dSYM/
+
+# Generated PDFs (schematics, etc.)
+*.pdf
 
 # Distribution / packaging
 .Python

compiler/frontend/pycircuit/__init__.py

@@ -1,6 +1,5 @@
 from . import ct
 from . import hierarchical
-from . import lib
 from . import logic
 from . import spec
 from . import wiring
@@ -17,6 +16,23 @@
 from .hw import Bundle, Circuit, ClockDomain, Pop, Reg, Vec, Wire, cat, unsigned
 from .jit import JitError, compile
 from .literals import LiteralValue, S, U, s, u
+from .v5 import (
+    CycleAwareCircuit,
+    CycleAwareDomain,
+    CycleAwareSignal,
+    CycleAwareTb,
+    StateSignal,
+    cas,
+    compile_cycle_aware,
+    log,
+    mux,
+    pyc_CircuitLogger,
+    pyc_CircuitModule,
+    pyc_ClockDomain,
+    pyc_Signal,
+    signal,
+)
+from . import lib
 from .probe import ProbeBuilder, ProbeError, ProbeRef, ProbeView, TbProbeHandle, TbProbes
 from .tb import Tb, sva
 from .testbench import TestbenchProgram
@@ -25,6 +41,19 @@
 probe = _probe_decorator
 
 __all__ = [
+    "CycleAwareCircuit",
+    "CycleAwareDomain",
+    "CycleAwareSignal",
+    "CycleAwareTb",
+    "cas",
+    "compile_cycle_aware",
+    "log",
+    "mux",
+    "pyc_CircuitLogger",
+    "pyc_CircuitModule",
+    "pyc_ClockDomain",
+    "pyc_Signal",
+    "signal",
     "Connector",
     "ConnectorBundle",
     "ConnectorStruct",

compiler/frontend/pycircuit/hw.py

@@ -746,6 +746,13 @@ def scope(self, name: str) -> Iterator[None]:
     def domain(self, name: str) -> ClockDomain:
         return ClockDomain(clk=self.clock(f"{name}_clk"), rst=self.reset(f"{name}_rst"))
 
+    def create_domain(self, name: str, *, frequency_desc: str = "", reset_active_high: bool = False) -> Any:
+        """V5 cycle-aware domain (next/prev/push/pop); see `pycircuit.v5.CycleAwareDomain`."""
+        from .v5 import CycleAwareDomain
+
+        _ = (frequency_desc, reset_active_high)
+        return CycleAwareDomain(self, str(name))
+
     def input(self, name: str, *, width: int, signed: bool = False) -> Wire:  # type: ignore[override]
         """Declare a module input port and return it as a `Wire`."""
         return Wire(self, super().input(name, width=width), signed=bool(signed))

compiler/frontend/pycircuit/jit_cache.py

@@ -272,15 +272,24 @@ def get_function_meta(fn: Any, *, fn_name: str | None = None) -> FunctionMeta:
     if cached is not None and (fn_name is None or cached.fdef.name == fn_name):
         return cached
 
-    lines, start_line = inspect.getsourcelines(fn)
-    source = textwrap.dedent("".join(lines))
-    tree = ast.parse(source)
+    synthetic = getattr(fn, "__pycircuit_jit_source__", None)
+    if isinstance(synthetic, str) and synthetic.strip():
+        source = textwrap.dedent(synthetic).strip() + "\n"
+        start_line = int(getattr(fn, "__pycircuit_jit_start_line__", 1) or 1)
+        tree = ast.parse(source)
+    else:
+        lines, start_line = inspect.getsourcelines(fn)
+        source = textwrap.dedent("".join(lines))
+        tree = ast.parse(source)
     name = fn_name if fn_name is not None else getattr(fn, "__name__", None)
     if not isinstance(name, str) or not name:
         raise RuntimeError(f"failed to infer function name for {fn!r}")
     fdef = _find_function_def(tree, name)
 
-    source_file = inspect.getsourcefile(fn) or inspect.getfile(fn)
+    if isinstance(synthetic, str) and synthetic.strip():
+        source_file = getattr(fn, "__pycircuit_jit_source_file__", None) or "<pycircuit_v5>"
+    else:
+        source_file = inspect.getsourcefile(fn) or inspect.getfile(fn)
     source_stem = None
     try:
         if source_file:

compiler/frontend/pycircuit/lib/cache.py

@@ -1,22 +1,17 @@
 from __future__ import annotations
 
-from ..connectors import Connector, ConnectorBundle
-from ..design import module
-from ..dsl import Signal
-from ..hw import Circuit
-from ..literals import u
+from pycircuit.hw import Circuit, ClockDomain, Wire
+from pycircuit.literals import u
 
 
-@module(structural=True)
 def Cache(
     m: Circuit,
-    clk: Connector,
-    rst: Connector,
-    req_valid: Connector,
-    req_addr: Connector,
-    req_write: Connector,
-    req_wdata: Connector,
-    req_wmask: Connector,
+    cd: ClockDomain,
+    req_valid: Wire,
+    req_addr: Wire,
+    req_write: Wire,
+    req_wdata: Wire,
+    req_wmask: Wire,
     *,
     ways: int = 4,
     sets: int = 64,
@@ -26,7 +21,7 @@ def Cache(
     write_back: bool = True,
     write_allocate: bool = True,
     replacement: str = "plru",
-) -> ConnectorBundle:
+):
     """Structural cache baseline.
 
     Default policy contract:
@@ -39,31 +34,27 @@ def Cache(
     """
 
     _ = (line_bytes, write_back, write_allocate, replacement)
-    clk_v = clk.read() if isinstance(clk, Connector) else clk
-    rst_v = rst.read() if isinstance(rst, Connector) else rst
-
-    req_valid_v = req_valid.read() if isinstance(req_valid, Connector) else req_valid
-    req_addr_v = req_addr.read() if isinstance(req_addr, Connector) else req_addr
-    req_write_v = req_write.read() if isinstance(req_write, Connector) else req_write
-    req_wdata_v = req_wdata.read() if isinstance(req_wdata, Connector) else req_wdata
-    req_wmask_v = req_wmask.read() if isinstance(req_wmask, Connector) else req_wmask
-    req_valid_w = m.wire(req_valid_v) if isinstance(req_valid_v, Signal) else req_valid_v
-    req_addr_w = m.wire(req_addr_v) if isinstance(req_addr_v, Signal) else req_addr_v
-    req_write_w = m.wire(req_write_v) if isinstance(req_write_v, Signal) else req_write_v
-    req_wdata_w = m.wire(req_wdata_v) if isinstance(req_wdata_v, Signal) else req_wdata_v
-    _req_wmask_w = m.wire(req_wmask_v) if isinstance(req_wmask_v, Signal) else req_wmask_v
+    clk_v = cd.clk
+    rst_v = cd.rst
+
+    req_valid_w = req_valid
+    req_addr_w = req_addr
+    req_write_w = req_write
+    req_wdata_w = req_wdata
+    _req_wmask_w = req_wmask
+    _ = _req_wmask_w
     ways_i = max(1, int(ways))
     sets_i = max(1, int(sets))
     set_bits = max(1, (sets_i - 1).bit_length())
     tag_bits = max(1, int(addr_width) - set_bits)
     plru_bits = max(1, ways_i - 1)
     way_idx_bits = max(1, (ways_i - 1).bit_length())
 
-    tags = [m.out(f"cache_tag_{i}", clk=clk_v, rst=rst_v, width=tag_bits, init=0) for i in range(ways_i)]
-    valids = [m.out(f"cache_valid_{i}", clk=clk_v, rst=rst_v, width=1, init=0) for i in range(ways_i)]
-    dirty = [m.out(f"cache_dirty_{i}", clk=clk_v, rst=rst_v, width=1, init=0) for i in range(ways_i)]
-    data = [m.out(f"cache_data_{i}", clk=clk_v, rst=rst_v, width=int(data_width), init=0) for i in range(ways_i)]
-    plru = m.out("cache_plru", clk=clk_v, rst=rst_v, width=plru_bits, init=0)
+    tags = [m.out(f"cache_tag_{i}", domain=cd, width=tag_bits, init=0) for i in range(ways_i)]
+    valids = [m.out(f"cache_valid_{i}", domain=cd, width=1, init=0) for i in range(ways_i)]
+    dirty = [m.out(f"cache_dirty_{i}", domain=cd, width=1, init=0) for i in range(ways_i)]
+    data = [m.out(f"cache_data_{i}", domain=cd, width=int(data_width), init=0) for i in range(ways_i)]
+    plru = m.out("cache_plru", domain=cd, width=plru_bits, init=0)
 
     req_tag = req_addr_w[set_bits : set_bits + tag_bits]
 
@@ -73,8 +64,8 @@ def Cache(
 
     for i in range(ways_i):
         way_hit = valids[i].out() & (tags[i].out() == req_tag)
-        hit_data = data[i].out() if way_hit else hit_data
-        hit_way = i if way_hit else hit_way
+        hit_data = way_hit._select_internal(data[i].out(), hit_data)
+        hit_way = way_hit._select_internal(u(way_idx_bits, i), hit_way)
         hit = hit | way_hit
 
     victim_way = plru.out()[0:way_idx_bits]
@@ -101,7 +92,7 @@ def Cache(
     resp_valid = req_valid_w
     resp_ready = req_valid_w
     resp_hit = hit
-    resp_data = hit_data if hit else u(int(data_width), 0)
+    resp_data = hit._select_internal(hit_data, u(int(data_width), 0))
     miss = req_valid_w & (~hit)
 
     return m.bundle_connector(

compiler/frontend/pycircuit/lib/mem2port.py

@@ -1,50 +1,44 @@
 from __future__ import annotations
 
-from ..connectors import Connector, ConnectorBundle, ConnectorError
-from ..design import module
-from ..dsl import Signal
-from ..hw import Circuit
+from pycircuit.dsl import Signal
+from pycircuit.hw import Circuit, ClockDomain, Wire
+
+
+class Mem2PortError(ValueError):
+    pass
 
 
-@module(structural=True)
 def Mem2Port(
     m: Circuit,
-    clk: Connector,
-    rst: Connector,
-    ren0: Connector,
-    raddr0: Connector,
-    ren1: Connector,
-    raddr1: Connector,
-    wvalid: Connector,
-    waddr: Connector,
-    wdata: Connector,
-    wstrb: Connector,
+    cd: ClockDomain,
+    ren0: Wire,
+    raddr0: Wire,
+    ren1: Wire,
+    raddr1: Wire,
+    wvalid: Wire,
+    waddr: Wire,
+    wdata: Wire,
+    wstrb: Wire,
     *,
     depth: int,
-) -> ConnectorBundle:
-    clk_v = clk.read() if isinstance(clk, Connector) else clk
-    rst_v = rst.read() if isinstance(rst, Connector) else rst
+):
+    clk_v = cd.clk
+    rst_v = cd.rst
     if not isinstance(clk_v, Signal) or clk_v.ty != "!pyc.clock":
-        raise ConnectorError("Mem2Port.clk must be !pyc.clock")
+        raise Mem2PortError("Mem2Port domain clk must be !pyc.clock")
     if not isinstance(rst_v, Signal) or rst_v.ty != "!pyc.reset":
-        raise ConnectorError("Mem2Port.rst must be !pyc.reset")
-
-    def wire_of(v):
-        vv = v.read() if isinstance(v, Connector) else v
-        if isinstance(vv, Signal):
-            return m.wire(vv)
-        return vv
+        raise Mem2PortError("Mem2Port domain rst must be !pyc.reset")
 
-    ren0_w = wire_of(ren0)
-    ren1_w = wire_of(ren1)
-    wvalid_w = wire_of(wvalid)
-    raddr0_w = wire_of(raddr0)
-    raddr1_w = wire_of(raddr1)
-    waddr_w = wire_of(waddr)
-    wdata_w = wire_of(wdata)
-    wstrb_w = wire_of(wstrb)
+    ren0_w = ren0
+    ren1_w = ren1
+    wvalid_w = wvalid
+    raddr0_w = raddr0
+    raddr1_w = raddr1
+    waddr_w = waddr
+    wdata_w = wdata
+    wstrb_w = wstrb
     if ren0_w.ty != "i1" or ren1_w.ty != "i1" or wvalid_w.ty != "i1":
-        raise ConnectorError("Mem2Port ren0/ren1/wvalid must be i1")
+        raise Mem2PortError("Mem2Port ren0/ren1/wvalid must be i1")
 
     rdata0, rdata1 = m.sync_mem_dp(
         clk_v,

compiler/frontend/pycircuit/lib/picker.py

@@ -1,26 +1,18 @@
 from __future__ import annotations
 
-from ..connectors import Connector, ConnectorBundle, ConnectorError
-from ..design import module
-from ..dsl import Signal
-from ..hw import Circuit
-from ..literals import u
+from pycircuit.hw import Circuit, Wire
+from pycircuit.literals import u
 
 
-@module(structural=True)
 def Picker(
     m: Circuit,
-    req: Connector,
+    req: Wire,
     *,
     width: int | None = None,
-) -> ConnectorBundle:
-    req_v = req.read() if isinstance(req, Connector) else req
-    if isinstance(req_v, Signal):
-        req_w = m.wire(req_v)
-    else:
-        req_w = req_v
+):
+    req_w = req
     if not hasattr(req_w, "ty") or not str(req_w.ty).startswith("i"):
-        raise ConnectorError("Picker.req must be an integer wire connector")
+        raise ValueError("Picker.req must be an integer wire")
     w = int(width) if width is not None else int(req_w.width)
     if w <= 0:
         raise ValueError("Picker width must be > 0")
@@ -32,8 +24,8 @@ def Picker(
 
     for i in range(w):
         take = req_w[i] & ~found
-        grant = u(w, 1 << i) if take else grant
-        index = u(idx_w, i) if take else index
+        grant = take._select_internal(u(w, 1 << i), grant)
+        index = take._select_internal(u(idx_w, i), index)
         found = found | req_w[i]
 
     return m.bundle_connector(