spice

SPICE 仿真技能

自动为 kicad 技能的原理图分析器检测到的电路子电路生成并运行 SPICE 测试平台。支持 ngspice、LTspice 和 Xyce（自动检测）。将计算值（滤波器频率、分压比、运算放大器增益）与实际仿真结果进行验证，并生成结构化报告。

此技能颠覆了常规的仿真工作流：无需用户创建仿真源并配置分析（KiCad 用户中只有约 2.5% 会这样做），而是根据分析器检测到的子电路自动生成有针对性的测试平台。

相关技能

技能	用途
kicad	原理图/PCB 分析——生成此技能所用的分析器 JSON
digikey	行为模型的参数规格、数据手册下载
mouser	参数规格（备用来源）、数据手册下载
lcsc	参数规格（无需身份验证）、数据手册下载
element14	参数规格（国际）、数据手册下载
emc	EMC 预兼容性——使用此技能的仿真器基础设施进行 SPICE 增强型 PDN 阻抗和 EMI 滤波器分析

交接指南： kicad 技能的 analyze_schematic.py 会在扁平的 findings[] 数组中生成包含子电路检测结果的分析 JSON（按 detector 字段筛选）。此技能读取该 JSON，为可仿真的子电路生成 SPICE 测试平台，运行检测到的仿真器（ngspice/LTspice/Xyce），并生成结构化验证报告。请始终先运行原理图分析器。在设计审查期间，请在分析器之后、撰写最终报告之前运行仿真——仿真结果应作为验证部分出现在报告中。emc 技能会复用此技能的仿真器后端，进行 SPICE 增强型 PDN 阻抗和 EMI 滤波器插入损耗检查；ngspice 可用时，EMC 技能的 --spice-enhanced 标志会自动启用这些检查。

要求

• SPICE 仿真器——以下选项之一（自动检测，优先使用第一个可用项）：
  • ngspice——sudo apt install ngspice（Linux）/ brew install ngspice（macOS）/ ngspice.sourceforge.io（Windows）。最常用的选择。
  • LTspice——可从 analog.com/ltspice 免费获取。在 Windows 上很受欢迎，也可通过 wine 在 Linux 上运行。
  • Xyce——来自 xyce.sandia.gov。适用于大型电路的并行 SPICE。
  • 可通过 --simulator ngspice|ltspice|xyce 或 SPICE_SIMULATOR 环境变量覆盖。
• Python 3.10+——仅使用标准库，无需 pip 依赖
• 原理图分析器 JSON——来自 analyze_schematic.py --output

如果未安装仿真器，请跳过仿真并在报告中注明。缺少仿真器不应视为错误——它只是可选增强功能。

工作流

第 1 步：运行原理图分析器

python3 <kicad-skill-path>/scripts/analyze_schematic.py design.kicad_sch --analysis-dir analysis/

第 2 步：运行 SPICE 仿真

传入 --analysis-dir analysis/——脚本会从清单的当前运行中自动解析 schematic.json，将 spice.json 写入同一运行文件夹，并默认将中间 .cir / .raw 文件放入 <run>/spice_work/。

# Recommended: auto-resolve schematic + write spice.json into the current run
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/

# Explicit form — positional or --schematic path
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --output sim_report.json

# Simulate specific types only
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --types rc_filters,voltage_dividers

# Keep simulation files for debugging (default: <run>/spice_work/ when --analysis-dir is set, else a temp dir)
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --workdir ./spice_runs

# Increase timeout for complex circuits (default: 5s per subcircuit)
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --timeout 10

# Omit file paths from output (cleaner for reports)
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --compact

第 2b 步（可选）：考虑 PCB 寄生参数的仿真

如果原理图和 PCB 均存在，可运行带寄生参数标注的仿真，以获得更准确的模拟电路结果：

# Analyze PCB with full trace segment detail
python3 <kicad-skill-path>/scripts/analyze_pcb.py design.kicad_pcb --full --output pcb.json

# Extract parasitic R/L/C from PCB geometry
python3 <skill-path>/scripts/extract_parasitics.py pcb.json --output parasitics.json

# Run simulation with PCB parasitics injected into testbenches
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --parasitics parasitics.json --output sim_report.json

使用 --parasitics 后，测试平台会包含元件之间的走线电阻和过孔电感。报告会显示寄生参数的影响，例如：“48mΩ 的走线电阻使 RC 滤波器的 fc 降低了 0.3%。”

何时使用寄生参数仿真： 如果设计包含高阻抗反馈网络（>100kΩ）、LC 滤波器或 RF 匹配网络、较长的模拟信号走线，或走线电感会产生影响的高频电路，请考虑使用此仿真。对于采用低阻抗电源稳压的典型数字设计，理想仿真已足够。

步骤 2c（可选）：蒙特卡洛容差分析

对每个子电路运行 N 次仿真，在容差范围内随机化元件值。生成统计分布和敏感度分析，显示哪些元件对输出变化的贡献最大。

# Run 100 Monte Carlo trials per subcircuit
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --output sim_report.json

# Use uniform distribution (conservative worst-case envelope) instead of Gaussian
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --mc-distribution uniform

# Set random seed for reproducibility (default: 42)
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --mc-seed 123

容差来源： 首先从元件值字符串中提取容差（例如，“680K 1%” → 1%，“22uF/6.3V/20%/X5R” → 20%）。如果值字符串中未指定容差，则使用默认值：电阻 5%、电容 10%、电感 20%。

输出： 每个仿真结果都会新增一个 tolerance_analysis 部分，其中包含：

• statistics：主要输出指标（fc、Vout、增益等）的均值、标准差、最小值、最大值、3-sigma 范围和离散百分比
• sensitivity：各元件的贡献百分比，显示哪个元件对变化影响最大（例如，“C3（容差 10%）对 fc 变化的贡献为 68%，R5（容差 5%）的贡献为 32%”）
• components：包含已解析容差值的可容差元件列表

何时使用蒙特卡洛： 可用于反馈网络（稳压器输出精度）、精密分压器、接近规格限制的 RC/LC 滤波器，以及任何容差叠加可能导致电路行为超出可接受范围的场景。对于 N=100 且每次仿真约需 5-50ms 的情况，预计每个子电路耗时约 0.5-5s。

步骤 3：解读结果并呈现给用户

阅读 JSON 报告，并将分析结果纳入设计评审。请参阅下文的“解读结果”和“向用户呈现”部分。

仿真内容

该脚本会从分析器的 findings[] 数组中选择子电路（按检测器类型分组）。并非每种检测结果都可仿真——对于无法生成有意义仿真结果的配置（比较器、开环运算放大器、有源振荡器），脚本会跳过。

检测器	分析	测量内容	模型保真度	可信度
rc_filters	AC 扫频	-3dB 频率、fc 处的相位	精确（理想无源元件）	高——数学上精确
lc_filters	AC 扫频	谐振频率、Q 值、带宽	接近精确（理想 L/C + ESR）	高——ESR 会造成轻微 Q 值误差
voltage_dividers	DC 工作点	输出电压、误差百分比	精确（理想无源元件）	高——未加载
feedback_networks	DC 工作点	FB 引脚电压、稳压器 Vout	精确（理想无源元件）	高——引用 power_regulators
opamp_circuits	AC 扫频	增益、-3dB 带宽	按具体型号或理想模型	使用行为模型时较高，使用理想模型时中等
crystal_circuits	AC 阻抗	负载电容验证	近似（通用 BVD）	中
transistor_circuits	DC 扫描	阈值电压、导通电流	近似（通用 FET/BJT）	中
current_sense	DC 工作点	压降为 50mV/100mV 时的电流	精确（理想电阻）	高
protection_devices	DC 扫描	二极管存在性、钳位起始点	近似（通用二极管）	低
decoupling_analysis	AC 阻抗	PDN 阻抗曲线	精确 + ESR 估算	对无源元件而言较高
power_regulators	DC 工作点	反馈分压器 Vout	精确（理想无源元件）	高
rf_matching	AC 扫频	匹配网络谐振	精确（理想 L/C）	高
bridge_circuits	DC 扫描	FET 开关验证	近似（通用模型）	中
snubber_circuits	AC 阻抗	缓冲器阻尼频率	精确（理想 R/C）	高
rf_chains	增益预算	各级增益/损耗估算	启发式	低——基于角色
bms_systems	DC 工作点	电芯均衡电阻验证	精确	高
inrush_analysis	瞬态分析	浪涌电流曲线	近似	中

未模拟的内容

• 比较器 / 开环运放 — 没有可供验证的反馈网络，因此跳过
• 有源振荡器 — 独立模块，无需外部验证
• 稳压器控制环路稳定性 — 需要完整的补偿器模型（行为模型仅覆盖直流反馈）
• 电平转换 FET — 需要同时对两个 FET 建模，因此跳过
• 高侧电源开关 — 源极和漏极都连接到电源轨，需要完整的负载上下文
• 保险丝和压敏电阻 — 需要制造商特定的模型
• 任何未能解析出元件值的对象 — 如果 parse_value() 无法提取 R/C/L 值，就会跳过检测

输出格式

{
  "summary": {"total": 5, "pass": 3, "warn": 1, "fail": 0, "skip": 1},
  "simulation_results": [
    {
      "subcircuit_type": "rc_filter",
      "components": ["R5", "C3"],
      "filter_type": "low-pass",
      "status": "pass",
      "expected": {"fc_hz": 15915, "type": "low-pass"},
      "simulated": {"fc_hz": 15878, "phase_at_fc_deg": -0.78},
      "delta": {"fc_error_pct": 0.23},
      "cir_file": "/tmp/spice_sim_xxx/rc-filter_R5_C3.cir",
      "log_file": "/tmp/spice_sim_xxx/rc-filter_R5_C3.log",
      "elapsed_s": 0.004
    }
  ],
  "workdir": "/tmp/spice_sim_xxx",
  "total_elapsed_s": 0.032,
  "simulator": "ngspice"
}

状态值及其含义：

状态	含义	操作
pass	仿真确认分析器的检测结果在容差范围内	报告为已确认。无需采取任何操作。
warn	仿真显示有值得注意的情况——轻微偏差、模型限制或边缘情况	附带上下文进行报告。通常，“warn”反映的是确实存在但轻微的问题（例如，理想运放模型导致的轻微增益误差）。
fail	仿真结果与分析器相矛盾——频率错误、增益误差较大或行为异常	进行调查。可能是实际设计问题、分析器误判拓扑，或测试平台生成错误。检查 .cir 文件和日志。
skip	无法进行仿真——数据缺失、配置不受支持或仿真器出错	在报告中注明。查看 note 字段了解原因。

解读结果

无源电路（RC 滤波器、LC 滤波器、分压器）

这些仿真使用理想元件模型，因此仿真在数学上是精确的。与分析器计算值相比，任何显著偏差（>1%）都表明以下方面存在错误：

• 分析器的拓扑检测（例如，误判了哪个网络是输入端、哪个是输出端）
• 测试平台生成（拓扑重建错误）
• 分析器的数值解析（元件值解析错误）

在实际项目测试中，无源电路仿真始终显示 <0.3% 的误差，基本证实分析器的计算是正确的。此处的“pass”意味着计算出的截止频率、谐振频率或分压比准确无误。

这些仿真无法告知的内容： 实际电路是否会有这样的表现。仿真使用理想的独立子电路，不考虑下游级的负载、PCB 寄生效应或温度影响。仿真结果为 1.65V 的分压器，在连接高阻抗 ADC 输入后，实际可能只有 1.62V——但这种负载效应属于实际电路行为，并非分析器错误。

运放电路

对于可识别的器件（查找表中约有 100 种常见运放），该技能会使用针对具体器件的行为模型，其 GBW、压摆率、输入失调和输出摆幅均准确。对于无法识别的器件，则回退到理想模型（Aol=1e6，GBW=10MHz）。

报告中的 model_note 字段会指明所用模型：

• "LM358 behavioral (lookup:LM358, GBW=1.0MHz)" — 针对具体器件的模型，带宽结果准确
• "ideal opamp (Aol=1e6, GBW~10MHz)" — 回退模型，带宽结果为近似值

使用行为模型时，仿真能够正确反映带宽限制。LM358 在增益=-100 时的带宽约为 10 kHz（符合 1 MHz GBW 的情况），而理想模型会产生误导性结果，报告约 100 kHz。

对于具有行为模型的运放，增益带宽限制警告仅供参考——它指出了该器件的 GBW 会限制电路性能的情况。这些是有价值的设计洞见，并非仿真错误。

晶体电路

晶体仿真用于验证负载电容的选型——检查有效负载电容是否处于适合晶体指定 CL 的合理范围内。它们使用参数取典型值的通用 Butterworth-Van Dyke 等效电路模型，而非特定晶体的数据。其主要价值在于发现负载电容缺失或数值明显错误的情况，而非精确预测频率。

仿真失败或跳过时

请先检查 note 字段。常见原因如下：

备注	原因	修复方法
"could not measure -3dB frequency"	AC 扫频范围未包含 -3dB 点	检查滤波器 fc 是否过低（<0.1 Hz）或过高（>100 MHz）
"AC measurement failed"	测试平台拓扑错误——电路不收敛	检查 .cir 文件是否存在浮空节点或缺失连接
"Testbench generation failed: KeyError"	分析器检测缺少预期字段	检查分析器 JSON——检测结果可能不完整
"ngspice/ltspice/xyce failed: ..."	仿真器错误	检查 .log 文件中的错误消息

调试时，使用 --workdir 保留仿真文件。.cir 文件是标准 SPICE 网表，可手动运行（ngspice -b file.cir，或在 LTspice/Xyce 中打开）。.log 文件包含仿真器的 stdout/stderr。

向用户展示结果

将仿真结果纳入设计评审报告时，请遵循以下模式：

对于通过的仿真（增强可信度）

### RC Filter R5/C3 (fc=15.9kHz lowpass) -- Confirmed
Simulated fc=15.9kHz, <0.3% from calculated. Phase=-45 deg at fc as expected.

对通过的结果简要说明即可——它们只是确认分析器已报告的内容。如果结果较多，可将其分组。

对于警告（需要说明背景）

### Opamp U4A (inverting gain=-10)
Simulated gain=20.0dB at 1kHz, matching expected -10x. Bandwidth 98.8kHz
(ideal model). Note: LM358 GBW is ~1MHz, so actual bandwidth would be
~100kHz — verify signal frequency stays below 85kHz for <1dB gain error.

对于失败（需要调查）

### RC Filter R12/C8 -- MISMATCH
Simulated fc=3.2kHz vs expected 15.9kHz (80% deviation). This likely indicates
the analyzer misidentified the filter topology — R12 may be serving a different
purpose (pull-up, not series filter element). Manually verify the circuit
around R12/C8 in the schematic.

对于跳过的情况（说明缺失项）

### Crystal Y1 (32.768kHz) -- Not simulated
Active oscillator module — no external load caps to validate.

仿真章节的总结语

## Simulation Verification (4 pass, 1 warn, 0 fail, 1 skip)
Verified 5 subcircuits in 0.03s. All passive circuits confirmed.
One opamp result requires interpretation (see U4A above).

模型准确度参考

有关所用行为模型、其准确度范围和已知限制的详细信息，请阅读 references/simulation-models.md。遇到以下情况时，请查阅此参考资料：

• 用户质疑仿真结果的准确性
• 运放或晶体仿真表现异常
• 需要用具体内容解释“理想模型”的含义

脚本参考

脚本	用途
scripts/simulate_subcircuits.py	主协调脚本——CLI 入口点，读取 JSON、生成测试平台、运行仿真器并生成报告
scripts/spice_templates.py	按检测器类型生成测试平台——每种检测器名称对应一个函数
scripts/spice_models.py	行为模型定义（理想运放、通用半导体）、网络名称清理、工程计数法格式化
scripts/spice_results.py	仿真输出解析和按类型评估，包含通过/警告/失败/跳过逻辑
scripts/spice_simulator.py	仿真器后端——自动检测并批量运行 ngspice、LTspice、Xyce
scripts/spice_part_library.py	常见约 100 种运放、LDO、比较器、电压基准和晶体驱动器的电气规格查找表
scripts/spice_model_generator.py	根据规格字典生成参数化行为 .subckt
scripts/spice_model_cache.py	与原理图位于同一目录 spice/models/ 中的项目本地模型缓存
scripts/spice_spec_fetcher.py	查询分销商 API（LCSC、DigiKey、element14、Mouser），并从结构化数据手册提取内容及通过 PDF 正则表达式获取参数规格
scripts/extract_parasitics.py	根据 PCB 分析 JSON 计算走线 R、过孔 L、耦合 C

每个器件的行为模型

当分析器检测到具有已识别 MPN 的运放（例如 LM358、TL072、MCP6002）时，该技能会使用每个器件的行为模型，而非通用理想运放模型。该模型根据器件数据手册，涵盖实际的增益带宽积（GBW）、压摆率、输入失调和输出摆幅。

模型解析顺序：

1. 项目缓存（<project>/spice/models/）——之前解析的模型
2. v1.4 类型化数据手册事实——通过 lookup(mpn, cache_dir=<project>/datasheets/extracted) 从 datasheets 技能获取。返回的 DatasheetFacts 中，opamp.gbw、opamp.slew_rate 等字段均为带可信度门控的 SpecValue 实例。有此来源时推荐使用。
3. 分销商 API 规格——查询 LCSC（无需认证）、DigiKey、element14、Mouser 获取真实参数数据
4. v1.3 结构化数据手册提取——读取 <project>/datasheets/extracted/ 中预提取的规格（旧版字典结构 JSON，经过质量评分）。兼容双重读取的路径；v1.4 缓存未命中时仍会查询。
5. 数据手册 PDF 正则提取——读取 <project>/datasheets/ 中的文件，通过文本模式匹配提取（最后手段）
6. 内置查询表——约 100 种常见器件，作为离线回退方案
7. 理想模型回退——如果任何来源都无法识别该 MPN

报告中的 model_note 字段会指出使用了哪种模型："LM358 behavioral (lookup:LM358, GBW=1.0MHz)" 与 "ideal opamp (Aol=1e6, GBW~10MHz)"。

模型会缓存在项目本地的 spice/ 目录中，与原理图文件放在一起（与 datasheets/ 采用相同方式）。这样模型便与设计共置，并能自然适配电路板修订和子项目。

已知限制

• 电压分压器按无负载状态仿真。 分析器的比率为 R_bot/(R_top+R_bot)，不考虑负载。增加负载电阻会让仿真更加“真实”，但相较于分析器计算出的值会造成虚假的“错误”。仿真的目的是验证计算，而非对整个电路建模。
• LC 滤波器的 Q 值采用估算的电感 ESR。 假设电感的默认 Q 值为 100。实际电感的 Q 值从 10（功率电感）到 300 以上（RF 电感）不等。无论 Q 值如何，谐振频率都准确。
• 运放电源轨根据网络名称推断。 如果电源网络未标注电压，默认值可能为 +/-5V。若只检测到 VCC，则判定为单电源设计（VEE 默认为 0V）。
• 每个器件的模型涵盖约 100 种常见器件。 不常见的运放/LDO 会回退到理想模型。可通过向 spice_part_library.py 添加条目扩展查询表。
• 具有真实 GBW 的高增益运放电路在带宽受限时，可能在 1 kHz 测量点显示低于预期的增益。这是符合物理规律的行为（模型正确反映了 GBW 限制），但为了准确比较增益，可能需要降低测量频率。
• 分析器生成的网络名称可能为 __unnamed_N。 这是 KiCad 为未标注导线生成的内部网络名称。它们在仿真中可以正常工作，但会降低 .cir 文件的可读性。