Frontend V3 refactor: layout migration, API cleanup, and regression updates

.github/workflows/ci.yml

@@ -74,33 +74,66 @@ jobs:
           set -euxo pipefail
           ninja -C build pyc-compile pyc-opt
 
-      - name: Regenerate checked-in outputs (examples + janus)
+      - name: Regenerate local outputs (examples + janus)
         run: |
           set -euxo pipefail
-          bash examples/update_generated.sh
-          bash janus/update_generated.sh
-          git diff --exit-code
+          bash designs/examples/update_generated.sh
+          bash designs/janus/update_generated.sh
+          test -f .pycircuit_out/examples/counter/counter.v
+          test -f .pycircuit_out/examples/calculator/calculator.v
+          test -f .pycircuit_out/examples/digital_clock/digital_clock.v
+          test -f .pycircuit_out/janus/janus_bcc_pyc/janus_bcc_pyc.v
+
+      - name: Ensure generated artifacts are not tracked
+        run: |
+          set -euxo pipefail
+          if git ls-files | grep -E '(^|/)generated/'; then
+            echo "error: generated artifacts are tracked in git" >&2
+            exit 1
+          fi
+
+      - name: Enforce no legacy frontend APIs
+        run: |
+          set -euxo pipefail
+          python3 flows/tools/check_no_legacy_api.py
 
       - name: Run Linx CPU C++ regression
         run: |
           set -euxo pipefail
-          bash tools/run_linx_cpu_pyc_cpp.sh
+          bash flows/tools/run_linx_cpu_pyc_cpp.sh
 
       - name: Run Janus C++ regressions
         run: |
           set -euxo pipefail
-          bash janus/tools/run_janus_bcc_pyc_cpp.sh
-          bash janus/tools/run_janus_bcc_ooo_pyc_cpp.sh
+          bash designs/janus/tools/run_janus_bcc_pyc_cpp.sh
+          bash designs/janus/tools/run_janus_bcc_ooo_pyc_cpp.sh
+
+      - name: Perf smoke (Linx + Janus)
+        run: |
+          set -euxo pipefail
+          python3 flows/tools/perf/run_perf_smoke.py \
+            --profile release \
+            --sim-mode cpp-only \
+            --logic-depth 32 \
+            --perf-repeats-linx 16 \
+            --perf-repeats-janus 16 \
+            --perf-max-cycles 4096 \
+            --output .pycircuit_out/perf/perf_smoke.json
+          python3 flows/tools/perf/check_perf_regression.py \
+            --current .pycircuit_out/perf/perf_smoke.json \
+            --baseline flows/tools/perf/baseline.json \
+            --time-regression-pct 30 \
+            --throughput-regression-pct 30
 
       - name: Run Verilog sims (open-source flow)
         run: |
           set -euxo pipefail
-          python3 tools/pyc_flow.py verilog-sim fastfwd_pyc +max_cycles=200 +max_pkts=400 +seed=1 +notrace +nolog
-          python3 tools/pyc_flow.py verilog-sim issue_queue_2picker +notrace +nolog
-          python3 tools/pyc_flow.py verilog-sim linx_cpu_pyc --tool verilator \
-            +memh=examples/linx_cpu/programs/test_or.memh +expected=0000ff00 +notrace +nolog
+          python3 flows/tools/pyc_flow.py verilog-sim fastfwd_pyc +max_cycles=200 +max_pkts=400 +seed=1 +notrace +nolog
+          python3 flows/tools/pyc_flow.py verilog-sim issue_queue_2picker +notrace +nolog
+          python3 flows/tools/pyc_flow.py verilog-sim linx_cpu_pyc --tool verilator \
+            +memh=designs/examples/linx_cpu/programs/test_or.memh +expected=0000ff00 +notrace +nolog
 
       - name: FastFwd cross-check (C++ vs Verilog)
         run: |
           set -euxo pipefail
-          python3 tools/pyc_flow.py fastfwd-crosscheck --tool iverilog --seed 1 --cycles 200 --packets 400
+          python3 flows/tools/pyc_flow.py fastfwd-crosscheck --tool iverilog --seed 1 --cycles 200 --packets 400

.gitignore

@@ -220,8 +220,10 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 
-# Verilog tool build outputs
-examples/generated/**/verilator/
-
-# Janus generated outputs (pyc-compile, verilator builds, benchmark artifacts)
+# pyCircuit generated outputs (local artifacts only; never checked in)
+.pycircuit_out/
+designs/**/generated/
+designs/examples/generated/**/verilator/
+designs/janus/generated/
+examples/generated/
 janus/generated/

CHANGELOG.md

@@ -6,3 +6,4 @@ This project is still in an early prototype stage; APIs and generated outputs ma
 
 - Add `pyc.concat` lowering for readable `{a, b, c}` packed concatenations in generated Verilog and C++.
 - Improve generated identifier readability and traceability (scope + file/line name mangling).
+- C++ emitter: add default-on hierarchical instance input-change cache to skip redundant submodule `eval()` calls; add `PYC_DISABLE_INSTANCE_EVAL_CACHE` override for A/B checks.

CMakeLists.txt

@@ -5,24 +5,25 @@ include(GNUInstallDirs)
 
 option(PYC_BUILD_MLIR_TOOLS "Build MLIR-based pyc tools" ON)
 option(PYC_BUILD_CPP_EXAMPLES "Build C++ simulation examples" ON)
-option(PYC_INSTALL_TEMPLATES "Install include/pyc template libraries" ON)
+option(PYC_INSTALL_TEMPLATES "Install runtime template libraries" ON)
 option(PYC_INSTALL_PYTHON "Install Python frontend sources (for binary packages)" ON)
 
 if(PYC_BUILD_MLIR_TOOLS)
-  add_subdirectory(pyc/mlir)
+  add_subdirectory(compiler/mlir)
 endif()
 
 if(PYC_BUILD_CPP_EXAMPLES)
-  add_subdirectory(examples/cpp)
+  add_subdirectory(designs/examples/cpp)
 endif()
 
 if(PYC_INSTALL_TEMPLATES)
-  install(DIRECTORY include/pyc DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
+  install(DIRECTORY runtime/cpp DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
+  install(DIRECTORY runtime/verilog DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
 endif()
 
 if(PYC_INSTALL_PYTHON)
   install(
-    DIRECTORY python/pycircuit
+    DIRECTORY compiler/frontend/pycircuit
     DESTINATION "${CMAKE_INSTALL_DATADIR}/pycircuit/python"
     PATTERN "__pycache__" EXCLUDE
     PATTERN "*.pyc" EXCLUDE

Makefile

@@ -6,7 +6,7 @@ help:
 	@echo "Targets:"
 	@echo "  configure  Configure CMake (needs LLVM_DIR/MLIR_DIR)"
 	@echo "  tools      Build pyc-compile + pyc-opt"
-	@echo "  regen      Regenerate checked-in outputs (examples/ + janus/)"
+	@echo "  regen      Regenerate local outputs under ./.pycircuit_out"
 	@echo "  test       Run C++ regressions (linx_cpu + janus)"
 	@echo "  install    Install into dist/pycircuit/"
 	@echo "  package    Build a TGZ via CPack"
@@ -27,14 +27,14 @@ tools: configure
 	ninja -C "$(BUILD_DIR)" pyc-compile pyc-opt
 
 regen: tools
-	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash examples/update_generated.sh
-	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash janus/update_generated.sh
+	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash designs/examples/update_generated.sh
+	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash designs/janus/update_generated.sh
 
 test: tools
-	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash tools/run_linx_cpu_pyc_cpp.sh
-	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash tools/run_fastfwd_pyc_cpp.sh
-	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash janus/tools/run_janus_bcc_pyc_cpp.sh
-	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash janus/tools/run_janus_bcc_ooo_pyc_cpp.sh
+	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash flows/tools/run_linx_cpu_pyc_cpp.sh
+	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash flows/tools/run_fastfwd_pyc_cpp.sh
+	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash designs/janus/tools/run_janus_bcc_pyc_cpp.sh
+	PYC_COMPILE="$(BUILD_DIR)/bin/pyc-compile" bash designs/janus/tools/run_janus_bcc_ooo_pyc_cpp.sh
 
 install: tools
 	cmake --install "$(BUILD_DIR)" --prefix dist/pycircuit

boards/zybo_z7_20/README.md

@@ -6,7 +6,7 @@ pyCircuit-generated `Counter` RTL to blink the Zybo Z7-20 user LEDs.
 ## What it builds
 
 - Top: `boards/zybo_z7_20/rtl/zybo_counter_top.sv`
-- Generated design: `examples/generated/counter/counter.v`
+- Generated design: `designs/examples/generated/counter/counter.v`
 - Constraints: `boards/zybo_z7_20/constraints/zybo_z7_20_minimal.xdc`
 - Vivado script: `boards/zybo_z7_20/vivado/build_zybo_counter.tcl`
 
@@ -43,7 +43,7 @@ This repo also includes a Zybo top that instantiates the pyCircuit-generated
 - Top: `boards/zybo_z7_20/rtl/zybo_linx_cpu_top.sv`
 - Constraints: `boards/zybo_z7_20/constraints/zybo_z7_20_linx_cpu.xdc`
 - Vivado script: `boards/zybo_z7_20/vivado/build_zybo_linx_cpu.tcl`
-- Windows helper: `tools/windows/zybo_z7_20_linx_cpu_flow.ps1`
+- Windows helper: `flows/tools/windows/zybo_z7_20_linx_cpu_flow.ps1`
 
 Build/program:
 
@@ -63,7 +63,7 @@ use the PS/PL platform wrappers (in-order + OOO):
 - Vivado scripts:
   - `boards/zybo_z7_20/vivado/build_zybo_linx_platform_inorder.tcl`
   - `boards/zybo_z7_20/vivado/build_zybo_linx_platform_ooo.tcl`
-- Windows helper: `tools/windows/zybo_z7_20_linx_platform_flow.ps1`
+- Windows helper: `flows/tools/windows/zybo_z7_20_linx_platform_flow.ps1`
 
 Build/program:
 

boards/zybo_z7_20/ps/linx_monitor/src/main.c

@@ -106,7 +106,7 @@ static void memh_feed_byte(uint64_t addr, uint8_t byte, uint64_t *base, uint64_t
 }
 
 static void load_memh_stream(void) {
-  // Parses the same format produced by janus/tools/ihex_to_memh.py:
+  // Parses the same format produced by designs/janus/flows/tools/ihex_to_memh.py:
   //   @<addr>
   //   <byte>
   //   <byte>

boards/zybo_z7_20/tests/fpga_manifest_inorder.json

@@ -3,14 +3,14 @@
   "boot_pc": "0x0000000000010000",
   "boot_sp": "0x000000000003ff00",
   "tests": [
-    { "name": "test_or", "memh": "examples/linx_cpu/programs/test_or.memh", "expected_exit": 0 },
-    { "name": "test_csel_fixed", "memh": "examples/linx_cpu/programs/test_csel_fixed.memh", "expected_exit": 0 },
-    { "name": "test_branch2", "memh": "examples/linx_cpu/programs/test_branch2.memh", "expected_exit": 0 },
-    { "name": "test_call_simple", "memh": "examples/linx_cpu/programs/test_call_simple.memh", "expected_exit": 0 },
-    { "name": "test_jump", "memh": "examples/linx_cpu/programs/test_jump.memh", "expected_exit": 0 },
-    { "name": "test_pcrel", "memh": "examples/linx_cpu/programs/test_pcrel.memh", "expected_exit": 0 },
+    { "name": "test_or", "memh": "designs/examples/linx_cpu/programs/test_or.memh", "expected_exit": 0 },
+    { "name": "test_csel_fixed", "memh": "designs/examples/linx_cpu/programs/test_csel_fixed.memh", "expected_exit": 0 },
+    { "name": "test_branch2", "memh": "designs/examples/linx_cpu/programs/test_branch2.memh", "expected_exit": 0 },
+    { "name": "test_call_simple", "memh": "designs/examples/linx_cpu/programs/test_call_simple.memh", "expected_exit": 0 },
+    { "name": "test_jump", "memh": "designs/examples/linx_cpu/programs/test_jump.memh", "expected_exit": 0 },
+    { "name": "test_pcrel", "memh": "designs/examples/linx_cpu/programs/test_pcrel.memh", "expected_exit": 0 },
 
-    { "name": "coremark_lite", "memh": "janus/generated/benchmarks/coremark_lite.memh", "expected_exit": 0 },
-    { "name": "dhrystone_lite", "memh": "janus/generated/benchmarks/dhrystone_lite.memh", "expected_exit": 0 }
+    { "name": "coremark_lite", "memh": "designs/janus/generated/benchmarks/coremark_lite.memh", "expected_exit": 0 },
+    { "name": "dhrystone_lite", "memh": "designs/janus/generated/benchmarks/dhrystone_lite.memh", "expected_exit": 0 }
   ]
 }

boards/zybo_z7_20/tests/fpga_manifest_ooo.json

@@ -3,15 +3,15 @@
   "boot_pc": "0x0000000000010000",
   "boot_sp": "0x000000000003ff00",
   "tests": [
-    { "name": "test_or", "memh": "janus/programs/test_or.memh", "expected_exit": 0 },
-    { "name": "test_csel_fixed", "memh": "janus/programs/test_csel_fixed.memh", "expected_exit": 0 },
-    { "name": "test_store100_llvm", "memh": "janus/programs/test_store100_llvm.memh", "expected_exit": 0 },
-    { "name": "test_branch2", "memh": "janus/programs/test_branch2.memh", "boot_pc": "0x000000000001000a", "expected_exit": 0 },
-    { "name": "test_call_simple", "memh": "janus/programs/test_call_simple.memh", "boot_pc": "0x000000000001001c", "expected_exit": 0 },
-    { "name": "test_jump", "memh": "janus/programs/test_jump.memh", "expected_exit": 0 },
-    { "name": "test_pcrel", "memh": "janus/programs/test_pcrel.memh", "expected_exit": 0 },
+    { "name": "test_or", "memh": "designs/janus/programs/test_or.memh", "expected_exit": 0 },
+    { "name": "test_csel_fixed", "memh": "designs/janus/programs/test_csel_fixed.memh", "expected_exit": 0 },
+    { "name": "test_store100_llvm", "memh": "designs/janus/programs/test_store100_llvm.memh", "expected_exit": 0 },
+    { "name": "test_branch2", "memh": "designs/janus/programs/test_branch2.memh", "boot_pc": "0x000000000001000a", "expected_exit": 0 },
+    { "name": "test_call_simple", "memh": "designs/janus/programs/test_call_simple.memh", "boot_pc": "0x000000000001001c", "expected_exit": 0 },
+    { "name": "test_jump", "memh": "designs/janus/programs/test_jump.memh", "expected_exit": 0 },
+    { "name": "test_pcrel", "memh": "designs/janus/programs/test_pcrel.memh", "expected_exit": 0 },
 
-    { "name": "coremark_lite", "memh": "janus/generated/benchmarks/coremark_lite.memh", "expected_exit": 0 },
-    { "name": "dhrystone_lite", "memh": "janus/generated/benchmarks/dhrystone_lite.memh", "expected_exit": 0 }
+    { "name": "coremark_lite", "memh": "designs/janus/generated/benchmarks/coremark_lite.memh", "expected_exit": 0 },
+    { "name": "dhrystone_lite", "memh": "designs/janus/generated/benchmarks/dhrystone_lite.memh", "expected_exit": 0 }
   ]
 }

compiler/frontend/pycircuit/__init__.py

@@ -0,0 +1,32 @@
+from .component import component
+from .design import module
+from .hw import Bundle, Circuit, ClockDomain, Pop, Queue, Reg, Vec, Wire, cat, unsigned
+from .jit import JitError, compile, compile_design, jit_inline
+from .literals import LiteralValue, S, U, s, u
+from .tb import Tb, sva
+
+__all__ = [
+    "Bundle",
+    "Circuit",
+    "ClockDomain",
+    "JitError",
+    "LiteralValue",
+    "Pop",
+    "Queue",
+    "Reg",
+    "S",
+    "Tb",
+    "U",
+    "Vec",
+    "Wire",
+    "cat",
+    "compile",
+    "compile_design",
+    "component",
+    "jit_inline",
+    "module",
+    "s",
+    "sva",
+    "u",
+    "unsigned",
+]