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

[hengliao1972]

Summary

This PR introduces PyCircuit V5, a major upgrade encompassing a new cycle-aware programming model, complete design/testbench migration, simulation performance improvements, and compiler optimizations.

1. PyCircuit V5 Cycle-Aware Grammar

• New V5 frontend (compiler/frontend/pycircuit/v5.py): CycleAwareCircuit, CycleAwareDomain, CycleAwareSignal, StateSignal
• domain.next() — advances the logical cycle index, clearly demarcating pipeline stages and sequential logic phases
• domain.state() — declares feedback registers (StateSignal) with .set() for next-cycle values and conditional when= writes
• cas() — wraps raw Wire into CycleAwareSignal at a specific cycle
• mux() — V5 conditional selection with automatic cycle balancing across branches
• compile_cycle_aware() — new compilation entry point supporting both JIT and eager modes
• CycleAwareTb — V5 testbench wrapper with .next() for cycle advancement (replaces at=N parameters)
• Documentation: docs/PyCircuit V5 Programming Tutorial.md, docs/PyCurcit V5_CYCLE_AWARE_API.md

2. All Designs Migrated to V5

• 35 designs under designs/ fully migrated to V5 cycle-aware syntax
• Replaced m.out() registers → domain.state(), if Wire else → mux(), @function helpers → plain functions
• JIT-dependent designs (e.g., m.new(), m.array(), m.state(spec)) kept in JIT mode with compile_cycle_aware() compatibility fixes
• New designs added: RegisterFile, BypassUnit, IssueQueue, digital_filter, fm16 NPU system, etc.

3. All Testbenches Migrated to V5

• 32 testbenches rewritten using CycleAwareTb with .next() cycle advancement
• Removed all at=N parameters from drive()/expect() calls
• Multi-cycle testbenches use explicit tb.next() between cycles for clear temporal structure
• All 32 TBs pass compilation verification

4. Simulation Speedup (docs/simulation.md)

• Compiled-code simulation model: RTL compiled to native C++ struct with eval()/tick()
• SIMD acceleration: Wire<N> bit-vector operations use __uint128_t and SIMD intrinsics
• Signal change propagation: pyc_change_detect.hpp tracks dirty signals to skip unchanged eval paths
• PGO (Profile-Guided Optimization): 2-pass build workflow with llvm-profdata for hot-path optimization
• RegisterFile benchmark: 100K cycles in ~27ms compiled simulation

5. Cycle-Balance DFF Optimization (docs/cycle_balance_improvement.md)

• Shared delay-chain interning: compiler reuses (value, clock, reset, delay_depth) delay chains across multiple fanout paths
• Redundant DFF elimination: pyc-eliminate-dead-state removes unused registers after cycle balancing
• Result: reduced gate count and area by avoiding per-fanout duplicate delay chains

Test Plan

• All 35 designs compile successfully (MLIR emission verified)
• All 32 testbenches compile successfully
• RegisterFile 100K-cycle simulation produces correct results
• Bypass unit stress test with SVA assertions passes
• IssueQueue multi-stream enqueue/issue drain test passes

Made with Cursor