virtual-pe-machine

虛擬處理元件機 — 脈動陣列模擬器 (آلة عنصر المعالجة الافتراضية — محاكي المصفوفة الانقباضية)

Virtual Processing Element Machine — C++17 simulation of a Q4.4 fixed-point systolic array processing element for RTL cross-validation and formal-model testing.

Authors: Ahmad Ali Parr, Jessica L. Williams (SNAPKITTYWEST)

---

Architecture

         ┌─────────────────────────────────────┐
         │       Processing Element (PE)        │
         │                                      │
  A_in ──┤  S1: Capture ──► S2: Multiply ──► S3: Accumulate  ├── C_out (↓)
         │       │                                    │       │
         │       └──────────── A_out (→) ────────────┘       │
         └─────────────────────────────────────┘

Property	Value	值 (القيمة)
Pipeline stages	3 (Capture → Multiply → Accumulate)	3 級管線 (3 مراحل)
Latency	2 clock cycles (valid_in → valid_out)	2 週期延遲 (دورتان تأخير)
Arithmetic	Q4.4 fixed-point (8-bit signed, range [−8, 7.9375])	Q4.4 定點 (نقطة ثابتة Q4.4)
Accumulator	16-bit with saturation to INT16_MIN / INT16_MAX	16 位元飽和累加器 (مُراكم 16 بت بإشباع)
Data flow	A rightward, C downward (systolic)	A 向右、C 向下 (A يمينًا، C للأسفل)
Clock	Synchronous rising-edge	同步上升緣 (حافة صاعدة متزامنة)

---

Files

File	Lines	Description	描述 (الوصف)
virtual_pe_machine.hpp	~500	Q44Fixed · Accumulator · 3-stage Pipeline · ProcessingElement · SystolicArray · PEVerifier	核心庫 (المكتبة الأساسية)
virtual_pe_test.cpp	~600	5 examples + 4-test verification suite + RTL cross-validation spec	測試套件 (مجموعة الاختبارات)

---

Build and Run

g++ -std=c++17 -O2 virtual_pe_test.cpp -o virtual_pe_test
./virtual_pe_test
# Tests passed: 4/4  ✓ All tests PASSED

Requirements: C++17 compiler (GCC ≥ 7 / Clang ≥ 5 / MSVC ≥ 19.14). No external dependencies.

---

Verification Tests

#	Test	Assertion	驗證 (التحقق)
1	Fixed-Point Arithmetic	2.0 × 3.5 = 7.0 (raw product = 1792)	定點乘法正確性 (صحة ضرب النقطة الثابتة)
2	Saturation Logic	INT16_MAX + 1000 saturates to INT16_MAX	飽和邏輯 (منطق الإشباع)
3	Pipeline Latency	valid_out asserted exactly 2 cycles after valid_in	管線延遲 = 2 (تأخير خط الأنابيب = 2)
4	MAC Numerical Correctness	2.0 × 3.0 = 1536 (Q8.8 accumulator)	MAC 數值正確性 (الصحة العددية لـ MAC)

---

RTL Cross-Validation Protocol

To validate against processing_element.sv:

1. Run identical input sequences to both RTL (ModelSim / VCS) and this simulator
2. Compare valid_out and C_out every cycle
3. Expect bit-accurate match on all outputs

---

Core Types

struct Q44Fixed {
    int8_t raw;                    // Q4.4: 4 integer, 4 fractional bits
    static Q44Fixed from_float(float v);
    int16_t multiply(Q44Fixed o);  // returns Q8.8 product
};

struct Accumulator {
    int16_t value = 0;
    void accumulate(int16_t product);  // saturating add
    void clear();
};

struct ProcessingElement {
    void clock_tick(Q44Fixed A_in, Q44Fixed C_in, bool valid_in, bool clear);
    Q44Fixed A_out();     // rightward propagation
    int16_t  C_out();     // downward accumulator
    bool     valid_out(); // pipeline-delayed valid
};

---

License

This project is released under a trilicense model. You may choose any one of the following:

License	SPDX	Link
Boost Software License 1.0	BSL-1.1	LICENSE-BSL
GNU Affero General Public License v3	AGPL-3.0	LICENSE-AGPL
Mozilla Public License 2.0	MPL-2.0	LICENSE-MPL

Unauthorized cloud SaaS redistribution without source disclosure is prohibited under all three licenses.

---

SnapKitty West / SNAPKITTYWEST — Evidence or Silence — 2026