芯谱（XinPu）— ngspice 鸿蒙 PC 适配版

本仓库是 ngspice（SPICE 电路仿真内核，v47）的 HarmonyOS PC（鸿蒙电脑，2in1）适配工程，不是原始项目。 上架名称格式（Harmony PC 开发者社区规范）：芯谱（based on ngspice）。 上游基准：ngspice 47 官方发布源码包 ngspice-47.tar.gz（SHA-256 894e649651f1838a14095e5a5439e7d3aa63e87ede14d283173fda4fcdef675f）。 仓库命名遵循社区规范 ohos_项目名称，本仓库名为 ohos_ngspice。

简介

芯谱把 ngspice 仿真内核交叉编译为 HarmonyOS ARM64 共享库，并在其上实现了一个原生 ArkUI 电路仿真工作台： 编辑 SPICE 网表、运行 OP / DC / TRAN / AC 分析、查看与测量波形、导出结果，全部在本地离线完成，不发起网络请求。

ngspice 本身是仿真内核与命令解释器，不带原理图绘制；本适配版不提供拖拽画原理图的功能，输入方式为 SPICE 网表文本。

当前状态（2026-10-14）

首个适配版本 0.1.0（对应上游 ngspice 47），已完成真机与模拟器验证：

• ✅ 内核：ngspice 47 交叉编译为 OHOS ARM64 libngspice.so，含三个本地补丁（见 patches/）
• ✅ 工作台：多标签网表编辑器、四类分析、波形分析、结果管理、参数扫描、工程管理、草稿恢复、文件关联
• ✅ 真机验收：签名 HAP 在 HUAWEI MateBook Pro（HarmonyOS 6.1 / API 24）安装运行，六组自动回归 NGSPICE_SUITE / NGSPICE_EDITOR / NGSPICE_FILES / NGSPICE_CONTROL / NGSPICE_RESULTS / NGSPICE_DRAFT 全部 passed=true
• ✅ 数值对照：分压 .op = 5.000000 V（理论 5 V）；RC .tran 1 ms = 0.632120397 V（理论 0.632120559 V）； RC .ac -3 dB 点 = 0.707127516（理论 0.707106781）
• ✅ 上架截图：docs/listing/screenshots/ 5 张 2130×1430 窗口化截图（说明见该目录 INDEX.md）

验证记录汇总见 docs/device-validation.md 与 docs/research-evidence/。

下载安装

本仓库当前处于开发阶段，暂无应用市场发布包。构建步骤：

# 0. 启用构建配置（仓库不含本机签名材料，首次克隆需要复制模板）
cp build-profile.example.json5 build-profile.json5

# 1. 交叉编译 ngspice 内核（首次会下载 ngspice-47.tar.gz 并校验 SHA-256）
bash scripts/build-native.sh

# 2. 构建 HAP（需 DevEco Studio；默认产出 unsigned HAP）
bash scripts/build-hap.sh

签名：本仓库不包含签名材料。需要安装到设备时，在 DevEco Studio 中打开 File > Project Structure > Signing Configs → 勾选 Automatically generate signature， IDE 会把签名配置写回 build-profile.json5（该文件已被 .gitignore 忽略）。随后可直接安装：

hdc install entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.von.ngspice

所需权限

不申请任何权限。 应用只使用系统文件选择器读写用户主动选择的网表 / 模型 / 结果文件， 工程与草稿保存在应用私有沙箱目录，无网络、无后台任务。

使用示例

1. 从桌面启动"芯谱"，左侧选择内置示例（分压、RC 瞬态、RC 频响、DC 扫描）或新建网表；
2. 在编辑器中修改网表，F5 运行，Esc 停止；
3. 在结果区查看波形：滚轮缩放、拖动平移、点击设置游标 A/B 读取 Δx / Δy， 可叠加最多 12 条信号、切换数据表视图、在 AC 分析下切换幅值 / dB / 相位；
4. 参数扫描：指定两端元件与起止 / 步长（支持 k / meg / m / u / n 等 SPICE 后缀），最多 20 点顺序运行；
5. 通过工具栏或快捷键导出 CSV、波形 PNG、仿真日志与 .ngresult.json，结果 JSON 可再次导入对比。

快捷键

按键	操作	按键	操作
Ctrl+O	打开网表	Ctrl+Shift+E	导出 CSV
Ctrl+N	新建网表	Ctrl+Shift+P	导出波形 PNG
Ctrl+S	保存	Ctrl+Shift+J	导出结果 JSON
Ctrl+Shift+S	另存为	Ctrl+Shift+R	导入结果 JSON
Ctrl+Shift+M	导入模型	Ctrl+Shift+L	导出仿真日志
Ctrl+F / Ctrl+H	查找 / 替换全部	Ctrl+Z / Ctrl+Y	撤销 / 重做
F5	运行当前网表	Esc	停止当前仿真

接口说明

• ArkTS ↔ C++（Node-API，模块 libngspice_bridge.so，类型声明见 Index.d.ts）：
  • runExample(example: string): Promise<SimulationResult>：运行内置验证示例；
  • runNetlist(netlist: string, vector: string, timeoutMs?: number): Promise<SimulationResult>： 运行网表，timeoutMs 默认 30000，范围 1–600000；
  • requestStop(): boolean：协作停止，首次接受请求返回 true。
• 错误模型：Promise 拒绝返回 SimulationError { code, log, elapsedMs }，code 取值 CANCELLED / TIMEOUT / SIMULATION_FAILED。
• 结果格式：SimulationResult 含 signals（每个信号含 real / imaginary Float64Array）、 scale、pointCount、elapsedMs 与 log 等字段；持久化格式 .ngresult.json 由应用自行导入导出。
• 文件关联：.cir / text/plain 网表与 .ngresult.json（application/x-ngspice-result）， 支持从系统文件管理器双击打开。

约束与限制

• 设备形态：仅 2in1（鸿蒙 PC）；原生库仅构建 arm64-v8a，不涉手机 / 平板。
• SDK：编译 / 目标 SDK 26.0.0，最低兼容 HarmonyOS 6.0.0（API 20）。
• 分析类型：OP、DC、TRAN、AC；不支持噪声 / 失真 / 傅里叶等分析。
• 内核为精简构建：--disable-xspice --disable-cider --disable-osdi --disable-klu --disable-openmp， 不含 XSPICE 行为模型、CIDER、OSDI 与 KLU 求解器。
• 安全边界：拒绝 .control 命令块；网表上限 1 MiB，模型上限 4 MiB；结果预算 64 个信号 / 100 万采样点； 百万点波形按可见区分桶绘制。
• 仿真运行控制为协作停止：停止请求在求解器检查点生效，不保证任意电路的硬时间上限。
• 无原理图编辑器：输入为 SPICE 网表文本。

仓库结构

ohos-ngspice/
├── README.md / README.OpenSource / CHANGELOG.md / LICENSE
├── THIRD_PARTY_NOTICES.md          # 第三方组件与许可说明
├── build-profile.example.json5     # 构建配置模板（真实文件含签名材料，不入库）
├── AppScope/                       # 应用级配置（bundle com.von.ngspice，版本 0.1.0）
├── entry/                          # 鸿蒙工程（Stage 模型，2in1）
│   ├── src/main/ets/               # ArkUI 工作台（页面 + 服务：文件 / 工程 / 结果 / 草稿 / 设置）
│   ├── src/main/cpp/               # Node-API 桥接与 CMake（链接 libngspice.so）
│   └── src/main/resources/         # 资源、图标与 ngspice COPYING
├── patches/                        # 三个 ngspice 47 本地补丁
├── scripts/                        # 内核交叉编译、HAP 构建、图标生成
├── docs/                           # 构建复现、真机验证、运行控制、调研、上架截图
└── hvigor/                         # Hvigor 配置

贡献代码

• 上游项目：https://ngspice.sourceforge.io/（ngspice 本体问题请向上游反馈）
• 本适配版仓库：https://gitcode.com/OpenHarmonyPCDeveloper/ohos_ngspice
• 修改上游源码的部分以补丁形式保存在 patches/，补丁保持上游原始许可证条款； 新增文件采用相同许可证条款。提交前请确保 bash scripts/build-native.sh && bash scripts/build-hap.sh 可复现构建。

开源协议

• 本项目以 Modified BSD（BSD-3-Clause） 发布，见 LICENSE。
• ngspice 为混合许可项目：主体为 Modified BSD，src/frontend/numparam 等组件为 LGPL-2.1+， 完整清单、裁剪说明与上游 COPYING 原文见 THIRD_PARTY_NOTICES.md 与 entry/src/main/resources/rawfile/licenses/ngspice-COPYING.txt（上游 COPYING 随 HAP 分发）。
• 应用图标与"芯谱"品牌为原创设计（scripts/make_icon.py），不使用上游 ngspice 的 logo 或商标。
• 上游版权归 ngspice team 及各贡献者所有；本适配版新增代码版权归本仓库维护者所有。