README.md

[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](https://opensource.org/licenses/BSL-1.0)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-purple.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-orange.svg)](https://www.mozilla.org/en-US/MPL/2.0/)
[![C++17](https://img.shields.io/badge/C%2B%2B-17-00599C.svg)](https://en.cppreference.com/w/cpp/17)
[![Tests](https://img.shields.io/badge/Tests-4%2F4%20Passed-brightgreen.svg)](#verification-tests)
[![Evidence or Silence](https://img.shields.io/badge/Protocol-Evidence%20or%20Silence-black.svg)](#)

# 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

```bash
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

```cpp
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](https://opensource.org/licenses/BSL-1.0) |
| GNU Affero General Public License v3 | AGPL-3.0 | [LICENSE-AGPL](https://www.gnu.org/licenses/agpl-3.0) |
| Mozilla Public License 2.0 | MPL-2.0 | [LICENSE-MPL](https://www.mozilla.org/en-US/MPL/2.0/) |

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

---

SnapKitty West / SNAPKITTYWEST — Evidence or Silence — 2026