48 lines
3.6 KiB
Markdown
48 lines
3.6 KiB
Markdown
|
# DEVSIM Customization: `min_error` Implementation Walkthrough
|
|||
|
|
|
|||
|
|
這份文件總結了我們為了將 DEVSIM 核心的載子收斂底限參數 `min_error` 開放給 Python 介面所做的所有工作。我們成功在獨立的 `devsim-dev` 環境中完成了原始碼修改、重新編譯，並在本地端虛擬環境中完成了安裝與驗證。
|
|||
|
|
|
|||
|
|
## 1. C++ 原始碼修改 (Backend Changes)
|
|||
|
|
我們成功實作了 Plan B，也就是完全仿造 `variable_update` 參數的設計模式，將 `min_error` 拉出成為一個選項。
|
|||
|
|
|
|||
|
|
### 修改了以下三個核心檔案：
|
|||
|
|
1. **[EquationHolder.hh](file:///home/pchan/devsim2026/devsim-dev/devsim/src/Equation/EquationHolder.hh)**
|
|||
|
|
- 在類別定義中宣告了 `void SetMinError(double);` 的新介面。
|
|||
|
|
|
|||
|
|
2. **[EquationHolder.cc](file:///home/pchan/devsim2026/devsim-dev/devsim/src/Equation/EquationHolder.cc)**
|
|||
|
|
- 實作了該介面，使其在內部呼叫泛型（`double` 或 `float128`）的底層 `equation->setMinError(...)`，以確實改變運算引擎中的收斂底限判定。
|
|||
|
|
|
|||
|
|
3. **[EquationCommands.cc](file:///home/pchan/devsim2026/devsim-dev/devsim/src/commands/EquationCommands.cc)**
|
|||
|
|
- 修改了 `createEquationCmd` 函數，在參數解析清單中註冊了 `"min_error"` 選項。
|
|||
|
|
- 設定其預設值為 `"1.0e-10"` 以保持向後相容性。
|
|||
|
|
- 提取 Python 端傳入的值，並呼叫 `eh.SetMinError(min_error)`。
|
|||
|
|
|
|||
|
|
> [!NOTE]
|
|||
|
|
> 這些修改使得我們無需更動 `Equation.cc` 內硬編碼的 `defminError = 1.0e-10`，而是以優雅、可擴充的方式從 API 進行覆寫。
|
|||
|
|
|
|||
|
|
## 2. 環境與編譯挑戰解決 (Build Process)
|
|||
|
|
編譯過程中我們遇到了一些環境與依賴挑戰，均順利排除：
|
|||
|
|
|
|||
|
|
- **子模組拉取**：因為原 DEVSIM repo 使用了相對路徑的 Git Submodules，但在 GitLab 的 Fork 中無法對應到公開庫。我們改由直接從 GitHub 官方抓取 `umfpack_lgpl`、`symdiff`、`superlu` 與 `boostorg` 相關套件。
|
|||
|
|
- **SuperLU 標籤相容性**：一開始使用了 `master` 版本的 SuperLU，導致與 DEVSIM 2.0 期待的 API (`dgstrf` 缺少第 12 個引數 `GlobalLU_t *`) 不合。我們迅速將其降版至與 DEVSIM 2.0 完全相容的 **`v5.2.2`**。
|
|||
|
|
- **編譯器與 128 位元支援**：為了支援 `-DDEVSIM_EXTENDED_PRECISION=ON`，我們從 `clang` 切換為 `gcc`，並且在 CMake 參數中動態加入了 `QUADMATH_ARCHIVE=-lquadmath` 連結參數，成功讓 `math` 與 `devsim` 模組連結了 Linux 原生的 `libquadmath`。
|
|||
|
|
|
|||
|
|
## 3. 打包與驗證 (Packaging & Verification)
|
|||
|
|
1. **打包 Wheel**：
|
|||
|
|
- 修正了 DEVSIM 官方編譯腳本 `build_standalone_wheel.sh` 中未加上引號，導致複製有空白的檔名（`PROJECT GUIDE.md`）會失敗的 Bug。
|
|||
|
|
- 順利打包產出了 `devsim-2.10.0-cp39-abi3-linux_x86_64.whl`。
|
|||
|
|
|
|||
|
|
2. **安裝與執行測試**：
|
|||
|
|
- 透過 `pip install --force-reinstall` 將自製的 DEVSIM 安裝進 `/home/pchan/devsim2026/.venv/` 環境中。
|
|||
|
|
- 我們撰寫了一支簡單的 Python 測試腳本 `test_min_error.py` 來呼叫包含 `min_error=1.0e-5` 的新 API。
|
|||
|
|
|
|||
|
|
**測試結果：**
|
|||
|
|
```python
|
|||
|
|
devsim.equation(device="dev1", region="reg1", name="MyEq", variable_name="MyVar", variable_update="positive", min_error=1.0e-5)
|
|||
|
|
```
|
|||
|
|
執行後沒有出現任何參數錯誤或崩潰（Crash），順利印出 `Equation with min_error successfully created!`，代表 Python 端與 C++ 端已完美橋接。
|
|||
|
|
|
|||
|
|
> [!TIP]
|
|||
|
|
> 之後您可以開始在 `devsim_bjt_example-main` 中對載子連續性方程式進行測試了！
|
|||
|
|
> 當您確認目前修改完全符合需求後，我們就可以隨時將這份修改透過 `git push` 上傳至 GitLab 成為專屬的 `wisetop-custom` 版本！
|