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 補償)」選項中，開啟後可大幅提升信噪比與波形穩定性。

---

## ⚙️ Deployment & Development Notes (部署與開發環境注意事項)

為了支援 **Web Serial API** 直接與外部 MCU 通訊，本專案在生產與正式使用中**全面採用 HTTPS 加密傳輸**。這對於開發代理（Proxy）與存取路徑有以下影響：

### 1. Vite Proxy 與 SSL 協定對齊
當 Uvicorn 以 **HTTPS** 模式啟動時（綁定 `key.pem` 與 `cert.pem`），Vite Dev Server 的 `/api` 代理目標**必須對齊為 `https://`**，並加上 `secure: false` 以允許自簽憑證：

```js
// ✅ 正確 (HTTPS 模式下)
proxy: {
  '/api': {
    target: 'https://127.0.0.1:8000',
    changeOrigin: true,
    secure: false
  }
}
```

### 2. 生產部署流程（純使用者使用）
如果您是**純使用者**，或者需要進行系統正式展示，**完全不需要啟動 Vite Dev Server (5173)**！
您只需要在修改前端後進行一次編譯，然後使用 FastAPI 單獨運行 8000 連接埠即可：

```bash
# 1. 前端編譯 (只需在修改 src/ 代碼後執行一次，若無修改則免)
npm run build   # 將 Vue 代碼打包至 static/build/

# 2. 啟動後端 HTTPS 服務 (同時提供 API 與網頁 UI)
.venv/bin/uvicorn dea_api:app --host 0.0.0.0 --port 8000 --ssl-keyfile certs/key.pem --ssl-certfile certs/cert.pem
```
或直接利用 systemd 後台服務啟動（開機自動拉起）：
```bash
sudo systemctl restart dea.service
```

### 3. 開發模式 vs 生產模式對照表
| 項目 | 開發模式 (Vite Dev Server) | 生產模式 (FastAPI Static Serve) |
|------|----------------|---------------------|
| **運行連接埠** | `http://localhost:5173` | `https://localhost:8000/ui/` |
| **後端通訊** | 透過 Vite Proxy 轉發至 8000 (HTTPS) | 同一 Port 直接連線，極致穩定且高效 |
| **修改後生效** | 自動熱更新 (HMR)，不需手動 build | 必須執行 `npm run build`，並在瀏覽器進行硬重新整理 |
| **主要用途** | 適合前端網頁排版、UI 除錯開發 | **正式使用、Demo 展示、MCU Web Serial 通訊** |
| **是否需 5173**| **是** | **否，完全不需啟用！** |