tcad-bodeplot/ARCHITECTURE.md

# Difference Equation Analyzer (DEA) - Architecture & Functionality

## Overview
DEA is a specialized tool for designing, visualizing, and validating discrete-time filters. It bridges the gap between theoretical filter design (floating-point) and hardware implementation (fixed-point/MCU).

## 🏗 System Architecture

### 1. Backend (Python 3.12 + FastAPI)
The backend is responsible for heavy mathematical computations and data processing.

- **API Entry (`dea_api.py`)**: Routes requests to appropriate modules and serves the Vue.js frontend from `static/`.
- **Computation Engine (`dea/`)**:
    - `filter_design.py`: Uses `scipy.signal` to calculate coefficients for various filter topologies.
    - `bode.py`: Computes magnitude and phase response. Supports comparing "Ideal" (float) vs "Fixed" (quantized) responses.
    - `csv_processing.py`: Processes time-domain CSV data. It applies the current filter to the signal and downsamples the result for efficient visualization.
    - `validation.py`: Protects against unstable filter designs and invalid inputs.

### 2. Frontend (Vue 3 + Vite + Tailwind)
A reactive "Single Page Application" (SPA) approach.

> ⚠️ **開發 vs 部署 (Development vs Production)**
> - **開發模式 (Development)**: 透過 `npm run dev` 啟動 Vite dev server (預設 `http://localhost:5173`)。前端原始碼修改後會自動熱更新 (HMR)，**不需要** 手動 build。API 請求透過 `vite.config.js` 的 proxy 設定轉發至後端。
> - **生產模式 (Production)**: 透過 `http://localhost:8000/ui/` 存取。FastAPI 直接 serve `static/build/` 裡的 production bundle。**修改 `src/` 原始碼後，必須執行 `npm run build` 才會生效**。忘記 build 會導致前端程式碼與後端不同步，所有新功能看起來都「沒有作用」。

- **Reactive Logic (`src/app-options.js`)**:
    - Manages the state of all coefficients.
    - Implements "Fine-tuning" sliders that allow real-time adjustment of poles/zeros.
    - Handles Fixed-Point conversion logic (Q-format shifting).
- **UI Components (`src/App.vue`)**:
    - **Control Sidebar**: Interactive inputs for all filter parameters.
    - **Visualization**: Dual-plot system using Plotly.js for Bode plots and Time-domain waveforms.
- **Hardware Bridge**: Uses the **Web Serial API** to send commands directly to connected MCUs (requires HTTPS).

## 🚀 Execution Flow
1. **Design**: User selects a filter type or enters coefficients manually.
2. **Quantize**: User adjusts Q-format bits to see how quantization affects the frequency response.
3. **Verify**: User uploads a CSV to see how the filter behaves with real-world signals.
4. **Deploy**: User clicks "Write to MCU" to send the coefficients to their hardware.

## 🛠 Tech Stack
- **Backend**: FastAPI, NumPy, SciPy, Pandas, Uvicorn.
- **Frontend**: Vue 3, Vite, Tailwind CSS, Plotly.js.
- **Security**: Restricted to LAN/Loopback; implemented security headers and HTTPS support.

---

## 💎 V2 Feature: Parallel Fixed-Point Simulation
本分支 (`dev-v2-integretimedomain`) 的核心任務是在時域分析中實作「雙路徑對照系統」：

### 1. 雙路徑模擬邏輯 (Dual-Path Logic)
- **理想路徑 (Float Path)**: 使用 64-bit 浮點數進行運算，作為效能基準。
- **硬體模擬路徑 (Integer Path)**: 
    - **輸入量化**: 將原始訊號依 $Q_{in}$ 轉為整數。
    - **整數運算**: 使用整數係數 ($Q_{coeff}$) 進行差分方程式計算。
    - **位移校準**: 運算過程中考慮累加器位元數，並依 $Q_{out}$ 進行最終縮放。
    - **效果**: 模擬真實 DSP 的捨入誤差 (Rounding Error) 與量化雜訊。

### 2. 資料流更新
- **API `/api/filter`**: 接收檔案 ID 與係數參數，返回兩組數列（Float / Fixed）。
- **UI 圖表**: 同時繪製兩條曲線，讓開發者直觀判斷量化是否導致不穩定 (Instability) 或顯著失真。

### 3. 高效能資料處理架構 (High-Performance Data Processing)
- **檔案快取與防呆**:
  - 支援高達 **300 MB** 的 CSV 檔案上傳。
  - 當檔案被選擇後，立即背景上傳至後端暫存區 (`temp_csv/`)，避免重複傳輸。
  - 嚴格限制時域運算最多處理 **1,200,000 筆** 資料點，保護伺服器不因 O(N) 的純 Python 整數運算而死當。
- **精準記憶體讀取**: 
  - 利用 Pandas 的 `usecols` 參數，僅載入使用者選定的單一訊號欄位，極大幅度降低記憶體佔用。
- **即時預覽 (Live Preview)**:
  - 透過前端的 Debounce 機制 (500ms)，當使用者點擊 +/- 按鈕微調 Q-format 參數或係數時，系統會自動使用快取的檔案呼叫 API 並重繪圖表，達成無縫且直覺的實驗體驗。

---

## 🛠 Firmware Implementation Guidelines (韌體實作指引)

在將此工具設計出來的濾波器係數移植到 C 語言或 MCU (如 RISC-V) 時，請務必遵守以下實作準則，以確保硬體行為與本系統的模擬結果 100% 一致：

### 1. 高精度狀態變數架構 (Extended Precision State Variables)
為了極小化截斷誤差 (Truncation Error)，硬體實作的迴圈請**不要**對前饋 (Feed-forward) 進行位移。
- **作法**：讓歷史陣列 `y_history[]` 保存前饋乘加後的高精度格式 ($Q_{in+b}$)。僅在計算回授 (Feedback) 的乘積後，才對回授項進行右移對齊，並在最終輸出給硬體腳位時做最後的右移。這等於讓 IIR 濾波器內部默默保留了額外的 $Q_b$ bits 小數精度。

### 2. 消除直流偏移 (DC Bias) 的 1-Clock Rounding 演算法秘技
傳統的右移 (`>>`) 會造成無條件捨去向下取整 (Floor)，這會引入永遠為負的平均誤差 ($-0.5$ LSB)，導致濾波器產生直流偏移。必須改用四捨五入 (Rounding)。
- **硬體現狀**：標準的 RISC-V 指令集 (RV32I / RV32IMAC) **沒有**硬體的 round off shift 指令 (其 `SRA` 指令是純 Floor)。除非晶片具備 DSP 擴充指令集 ('P' Extension)。
- **C 語言實作秘技**：絕對**不要**為了四捨五入去呼叫 C standard library 的 `round()`，這會啟動浮點數運算，吃掉上百個 Clock。請用純整數實作：
  ```c
  // 完美的 1-clock 整數四捨五入寫法 (Round to nearest):
  // 編譯器會將 (1 << (shift_bits - 1)) 編譯為常數，只會多消耗一個 ADD 指令。
  y_out = (acc + (1 << (shift_bits - 1))) >> shift_bits;
  ```
  這個技巧已實作於本工具前端的「Round (+0.5 補償)」選項中，開啟後可大幅提升信噪比與波形穩定性。

---

## ⚙️ Development Environment Notes (開發環境注意事項)

### 1. Vite Proxy 設定
`vite.config.js` 中的 proxy target **必須**使用 `http://`（而非 `https://`），因為 uvicorn 預設以 HTTP 模式啟動。若設定為 `https://`，Vite 會嘗試發送 TLS 握手封包到純 HTTP 的 uvicorn，導致所有 API 請求失敗 (502 Bad Gateway)，uvicorn 日誌會大量出現 `Invalid HTTP request received.` 警告。

```js
// ✅ 正確
proxy: { '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true } }

// ❌ 錯誤 — 會導致 API 全部失敗
proxy: { '/api': { target: 'https://127.0.0.1:8000', secure: false } }
```

### 2. Production Build 流程
若使用者透過 `http://localhost:8000/ui/` 存取系統（FastAPI serve 靜態檔），則前端程式碼修改後**必須**執行以下命令：
```bash
npm run build   # 將 src/ 編譯輸出至 static/build/
```
然後在瀏覽器中按 `Ctrl+Shift+R` (硬重新整理) 以清除快取載入最新版本。

### 3. 兩種存取方式對照表
| 項目 | Vite Dev Server | Production (FastAPI) |
|------|----------------|---------------------|
| URL  | `http://localhost:5173` | `http://localhost:8000/ui/` |
| 修改後生效 | 自動 (HMR) | 需 `npm run build` |
| 適用場景 | 開發 / 除錯 | 正式使用 / Demo |
| API 轉發 | 透過 Vite proxy | 直接打同一 port |