spice

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SPICE Simulation Skill

SPICE仿真技能

Automatically generates and runs SPICE testbenches for circuit subcircuits detected by the

kicad

skill's schematic analyzer. Supports ngspice, LTspice, and Xyce (auto-detected). Validates calculated values (filter frequencies, divider ratios, opamp gains) against actual simulation results and produces a structured report.

This skill inverts the typical simulation workflow: instead of requiring users to create simulation sources and configure analysis (which ~2.5% of KiCad users do), it generates targeted testbenches automatically from the analyzer's subcircuit detections.

自动为

kicad

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

本技能颠覆了传统仿真工作流：无需用户创建仿真源和配置分析（仅约2.5%的KiCad用户会这么做），它会从分析器的子电路检测结果中自动生成针对性的测试平台。

Related Skills

Skill	Purpose
`kicad`	Schematic/PCB analysis — produces the analyzer JSON this skill consumes
`digikey`	Parametric specs for behavioral models, datasheet downloads
`mouser`	Parametric specs (secondary source), datasheet downloads
`lcsc`	Parametric specs (no auth needed), datasheet downloads
`element14`	Parametric specs (international), datasheet downloads
`emc`	EMC pre-compliance — uses this skill's simulator infrastructure for SPICE-enhanced PDN impedance and EMI filter analysis

技能	用途
`kicad`	原理图/PCB分析——生成本技能所需的分析器JSON文件
`digikey`	行为模型的参数规格、数据表下载
`mouser`	参数规格（次要来源）、数据表下载
`lcsc`	参数规格（无需认证）、数据表下载
`element14`	参数规格（国际来源）、数据表下载
`emc`	EMC预合规——使用本技能的仿真器基础设施进行SPICE增强型PDN阻抗和EMI滤波器分析

Requirements

要求

A SPICE simulator — one of the following (auto-detected, first available wins):
- ngspice —
```
sudo apt install ngspice
```
  (Linux) /
```
brew install ngspice
```
  (macOS) / ngspice.sourceforge.io (Windows). Most common choice.
- LTspice — free from analog.com/ltspice. Popular on Windows, works via wine on Linux.
- Xyce — from xyce.sandia.gov. Parallel SPICE for large circuits.
- Override with
```
--simulator ngspice|ltspice|xyce
```
  or
```
SPICE_SIMULATOR
```
  env var.
Python 3.10+ — stdlib only, no pip dependencies
Schematic analyzer JSON — from
```
analyze_schematic.py --output
```

If no simulator is installed, skip simulation gracefully and note it in the report. Do not treat a missing simulator as an error — it's an optional enhancement.

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
```
命令的输出

如果未安装仿真器，请优雅地跳过仿真并在报告中注明。不要将缺少仿真器视为错误——这是一项可选的增强功能。

Workflow

工作流

Step 1: Run the schematic analyzer

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

bash

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

bash

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

Step 2: Run SPICE simulations

步骤2：运行SPICE仿真

Pass

--analysis-dir analysis/

— the script auto-resolves

schematic.json

from the manifest's current run, writes

spice.json

into the same run folder, and parks intermediate

.cir

.raw

files at

<run>/spice_work/

by default.

bash

undefined

传入

--analysis-dir analysis/

参数——脚本会自动解析当前运行清单中的

schematic.json

文件，将

spice.json

写入同一运行文件夹，并默认将中间

.cir

.raw

文件存放在

<run>/spice_work/

目录下。

bash

undefined

Recommended: auto-resolve schematic + write spice.json into the current run

推荐方式：自动解析原理图 + 将spice.json写入当前运行目录

python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/

Explicit form — positional or --schematic path

显式形式——使用位置参数或--schematic指定路径

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)

保留仿真文件用于调试（默认：当设置--analysis-dir时为<run>/spice_work/，否则为临时目录）

python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --workdir ./spice_runs

Increase timeout for complex circuits (default: 5s per subcircuit)

为复杂电路增加超时时间（默认：每个子电路5秒）

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

undefined

python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --compact

undefined

Step 2b (optional): PCB parasitic-aware simulation

步骤2b（可选）：PCB寄生参数感知仿真

When both schematic and PCB exist, run parasitic-annotated simulation for more accurate results on analog circuits:

bash

undefined

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

bash

undefined

Analyze PCB with full trace segment detail

分析PCB并包含完整的走线段细节

python3 <kicad-skill-path>/scripts/analyze_pcb.py design.kicad_pcb --full --output pcb.json

Extract parasitic R/L/C from PCB geometry

从PCB几何结构中提取寄生R/L/C参数

python3 <skill-path>/scripts/extract_parasitics.py pcb.json --output parasitics.json

Run simulation with PCB parasitics injected into testbenches

运行仿真并将PCB寄生参数注入测试平台

python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --parasitics parasitics.json --output sim_report.json


With `--parasitics`, testbenches include trace resistance and via inductance between components. The report shows the parasitic impact — e.g., "48mΩ trace resistance shifts RC filter fc down 0.3%."

**When to use parasitic simulation:** Consider it when the design has high-impedance feedback networks (>100kΩ), LC filters or RF matching networks, long analog signal traces, or high-frequency circuits where trace inductance matters. For typical digital designs with low-impedance power regulation, the ideal simulation is sufficient.

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匹配网络、长模拟信号走线，或走线电感起作用的高频电路时，考虑使用该功能。对于具有低阻抗电源调节的典型数字设计，理想仿真已足够。

Step 2c (optional): Monte Carlo tolerance analysis

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

Run N simulations per subcircuit with randomized component values within tolerance bands. Reports statistical distributions and sensitivity analysis — which component contributes most to output variation.

bash

undefined

对每个子电路运行N次仿真，在容差范围内随机化元件值。报告会统计分布情况和灵敏度分析——即哪个元件对输出变化的贡献最大。

bash

undefined

Run 100 Monte Carlo trials per subcircuit

每个子电路运行100次蒙特卡洛试验

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)

设置随机种子以保证可复现性（默认：42）

python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --mc-seed 123


**Tolerance sourcing:** Tolerances are extracted from component value strings first (e.g., "680K 1%" → 1%, "22uF/6.3V/20%/X5R" → 20%). When not specified in the value string, defaults are used: resistors 5%, capacitors 10%, inductors 20%.

**Output:** Each simulation result gains a `tolerance_analysis` section with:
- **statistics**: mean, std, min, max, 3-sigma bounds, spread percentage for the primary output metric (fc, Vout, gain, etc.)
- **sensitivity**: per-component contribution percentage showing which component dominates variation (e.g., "C3 (10% tol) contributes 68% of fc variation, R5 (5% tol) contributes 32%")
- **components**: list of toleranceable components with their resolved tolerance values

**When to use Monte Carlo:** Use it for feedback networks (regulator output accuracy), precision voltage dividers, RC/LC filters near spec limits, and any circuit where tolerance stacking could push behavior outside acceptable bounds. For N=100 at ~5-50ms per simulation, expect ~0.5-5s per subcircuit.

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σ边界、分布百分比
- **sensitivity**：每个元件的贡献百分比，显示哪个元件主导了输出变化（例如：“C3（10%容差）贡献了68%的fc变化，R5（5%容差）贡献了32%”）
- **components**：带有解析后容差值的可容差元件列表

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

Step 3: Interpret results and present to user

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

Read the JSON report and incorporate findings into the design review. See the "Interpreting Results" and "Presenting to Users" sections below.

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

What Gets Simulated

可仿真的内容

The script selects subcircuits from the analyzer's

findings[]

array (grouped by detector type). Not every detection is simulatable — the script skips configurations that can't produce meaningful results (comparators, open-loop opamps, active oscillators).

Detector	Analysis	What's Measured	Model Fidelity	Trustworthiness
`rc_filters`	AC sweep	-3dB frequency, phase at fc	Exact (ideal passives)	High — mathematically exact
`lc_filters`	AC sweep	Resonant frequency, Q factor, bandwidth	Near-exact (ideal L/C + ESR)	High — small Q error from ESR
`voltage_dividers`	DC operating point	Output voltage, error %	Exact (ideal passives)	High — unloaded
`feedback_networks`	DC operating point	FB pin voltage, regulator Vout	Exact (ideal passives)	High — cross-refs power_regulators
`opamp_circuits`	AC sweep	Gain, -3dB bandwidth	Per-part or ideal	High with behavioral model, medium with ideal
`crystal_circuits`	AC impedance	Load capacitance validation	Approximate (generic BVD)	Medium
`transistor_circuits`	DC sweep	Threshold voltage, on-state current	Approximate (generic FET/BJT)	Medium
`current_sense`	DC operating point	Current at 50mV/100mV drop	Exact (ideal resistor)	High
`protection_devices`	DC sweep	Diode presence, clamping onset	Approximate (generic diode)	Low
`decoupling_analysis`	AC impedance	PDN impedance profile	Exact + ESR estimates	High for passives
`power_regulators`	DC operating point	Feedback divider Vout	Exact (ideal passives)	High
`rf_matching`	AC sweep	Matching network resonance	Exact (ideal L/C)	High
`bridge_circuits`	DC sweep	FET switching verification	Approximate (generic)	Medium
`snubber_circuits`	AC impedance	Snubber damping frequency	Exact (ideal R/C)	High
`rf_chains`	Gain budget	Per-stage gain/loss estimate	Heuristic	Low — role-based
`bms_systems`	DC operating point	Cell balance resistor validation	Exact	High
`inrush_analysis`	Transient	Inrush current profile	Approximate	Medium

脚本从分析器的

findings[]

数组中选择子电路（按检测器类型分组）。并非所有检测结果都可仿真——脚本会跳过无法产生有意义结果的配置（比较器、开环运算放大器、有源振荡器）。

检测器	分析类型	测量内容	模型保真度	可信度
`rc_filters`	AC扫描	-3dB频率、fc处的相位	精确（理想无源器件）	高——数学上完全精确
`lc_filters`	AC扫描	谐振频率、Q值、带宽	近乎精确（理想L/C + ESR）	高——ESR导致的Q值误差很小
`voltage_dividers`	DC工作点	输出电压、误差百分比	精确（理想无源器件）	高——无负载
`feedback_networks`	DC工作点	FB引脚电压、调节器输出电压	精确（理想无源器件）	高——与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工作点	反馈分压器输出电压	精确（理想无源器件）	高
`rf_matching`	AC扫描	匹配网络谐振	精确（理想L/C）	高
`bridge_circuits`	DC扫描	FET开关验证	近似（通用模型）	中等
`snubber_circuits`	AC阻抗	缓冲器阻尼频率	精确（理想R/C）	高
`rf_chains`	增益预算	每级增益/损耗估算	启发式	低——基于角色
`bms_systems`	DC工作点	电池平衡电阻验证	精确	高
`inrush_analysis`	瞬态分析	浪涌电流曲线	近似	中等

What is NOT simulated

不可仿真的内容

Comparators / open-loop opamps — no feedback network to validate, skipped
Active oscillators — self-contained modules, nothing to verify externally
Regulator control loop stability — requires full compensator model (behavioral models cover DC feedback only)
Level-shifter FETs — require modeling both FETs together, skipped
High-side power switches — source and drain both on power rails, need full load context
Fuses and varistors — require manufacturer-specific models
Anything without parsed component values — if
```
parse_value()
```
couldn't extract R/C/L values, the detection is skipped

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

Output Format

输出格式

json

{
  "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"
}

Status values and what they mean:

Status	Meaning	Action
pass	Simulation confirms the analyzer's detection within tolerance	Report as confirmed. No action needed.
warn	Simulation shows something worth noting — small deviation, model limitation, or edge case	Report with context. Often the "warn" reflects a real but minor issue (e.g., slight gain error from ideal opamp model).
fail	Simulation contradicts the analyzer — wrong frequency, large gain error, unexpected behavior	Investigate. Could be a real design issue, a topology misdetection by the analyzer, or a testbench generation bug. Check the `.cir` file and log.
skip	Could not simulate — missing data, unsupported configuration, simulator error	Note in report. Check the `note` field for the reason.

json

{
  "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（警告）	仿真显示值得注意的内容——微小偏差、模型限制或边缘情况	附带上下文报告。通常“警告”反映了真实但次要的问题（例如：理想运算放大器模型导致的轻微增益误差）。
fail（失败）	仿真结果与分析器结果矛盾——错误的频率、大增益误差、意外行为	调查原因。可能是真实的设计问题、分析器的拓扑误检测，或测试平台生成错误。检查 `.cir` 文件和日志。
skip（跳过）	无法仿真——缺少数据、不支持的配置、仿真器错误	在报告中注明。查看 `note` 字段了解原因。

Interpreting Results

解读结果

Passive circuits (RC filters, LC filters, voltage dividers)

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

These simulations use ideal component models, so the simulation is mathematically exact. Any significant deviation (>1%) from the analyzer's calculated value indicates a bug in either:

The analyzer's topology detection (e.g., it misidentified which net is input vs output)
The testbench generation (topology reconstruction error)
The analyzer's value parsing (component value parsed incorrectly)

In testing across real projects, passive simulations consistently show <0.3% error — essentially confirming the analyzer's math is correct. A "pass" here means the calculated cutoff frequency, resonant frequency, or divider ratio is accurate.

What these simulations do NOT tell you: Whether the real circuit behaves this way. The simulation uses ideal isolated subcircuits without loading from downstream stages, PCB parasitics, or temperature effects. A voltage divider that simulates perfectly at 1.65V may actually produce 1.62V when loaded by a high-impedance ADC input — but that loading effect is real circuit behavior, not an analyzer error.

这些仿真使用理想元件模型，因此仿真结果在数学上完全精确。与分析器计算值的任何显著偏差（>1%）表明以下任一环节存在错误：

分析器的拓扑检测（例如：错误识别了输入/输出网络）
测试平台生成（拓扑重建错误）
分析器的值解析（元件值解析错误）

在实际项目测试中，无源仿真的误差始终<0.3%——本质上确认了分析器的计算是正确的。“通过”意味着计算的截止频率、谐振频率或分压器比例是准确的。

这些仿真无法告知你的信息：实际电路是否会如此表现。仿真使用的是理想隔离子电路，未考虑下游级的负载、PCB寄生参数或温度影响。一个在仿真中完美输出1.65V的分压器，当连接高阻抗ADC输入时，实际可能输出1.62V——但这种负载效应是真实的电路行为，而非分析器错误。

Opamp circuits

运算放大器电路

For recognized parts (~100 common opamps in the lookup table), the skill uses a per-part behavioral model with the correct GBW, slew rate, input offset, and output swing. For unrecognized parts, it falls back to the ideal model (Aol=1e6, GBW=10MHz).

The

model_note

field in the report indicates which model was used:

```
"LM358 behavioral (lookup:LM358, GBW=1.0MHz)"
```
— per-part model, bandwidth results are accurate
```
"ideal opamp (Aol=1e6, GBW~10MHz)"
```
— fallback, bandwidth results are approximate

When the behavioral model is used, the simulation correctly captures bandwidth limitations. An LM358 at gain=-100 shows bandwidth of ~10 kHz (correct for 1 MHz GBW), while the ideal model would misleadingly report ~100 kHz.

For opamps with behavioral models, gain-bandwidth limitation warnings are informational — they flag where the part's GBW constrains the circuit. These are valuable design insights, not simulation errors.

对于已识别的器件（查找表中约100种常见运算放大器），本技能使用分型号行为模型，包含正确的GBW、压摆率、输入失调和输出摆幅。对于未识别的器件，会回退到理想模型（Aol=1e6，GBW=10MHz）。

报告中的

model_note

字段会指示使用的模型：

"LM358 behavioral (lookup:LM358, GBW=1.0MHz)"

——分型号模型，带宽结果准确

```
"ideal opamp (Aol=1e6, GBW~10MHz)"
```
——回退模型，带宽结果近似

当使用行为模型时，仿真会正确捕捉带宽限制。增益为-100的LM358带宽约为10kHz（符合1MHz GBW的特性），而理想模型会错误地报告约100kHz。

对于使用行为模型的运算放大器，增益带宽限制警告是信息性的——它们标记了器件GBW限制电路性能的位置。这些是有价值的设计见解，而非仿真错误。

Crystal circuits

晶体电路

Crystal simulations validate load capacitor selection — they check that the effective load capacitance is in a reasonable range for the crystal's specified CL. They use a generic Butterworth-Van Dyke equivalent circuit model with typical parameters, not the specific crystal's data. The primary value is catching missing or grossly wrong load capacitors, not precise frequency prediction.

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

When simulations fail or skip

当仿真失败或被跳过

Check the

note

field first. Common causes:

Note	Cause	Fix
"could not measure -3dB frequency"	AC sweep range doesn't include the -3dB point	Check if the filter fc is very low (<0.1 Hz) or very high (>100 MHz)
"AC measurement failed"	Testbench topology error — the circuit doesn't converge	Check `.cir` file for floating nodes or missing connections
"Testbench generation failed: KeyError"	Analyzer detection is missing expected fields	Check analyzer JSON — the detection may be incomplete
"ngspice/ltspice/xyce failed: ..."	Simulator error	Check `.log` file for error messages

When debugging, use

--workdir

to preserve simulation files. The

.cir

file is a standard SPICE netlist that can be run manually (

ngspice -b file.cir

, or opened in LTspice/Xyce). The

.log

file contains simulator stdout/stderr.

首先查看

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

文件包含仿真器的标准输出/错误信息。

Presenting Results to Users

向用户呈现结果

When incorporating simulation results into a design review report, follow this pattern:

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

For passing simulations (confidence builders)

通过的仿真（增强信心）

undefined

undefined

RC Filter R5/C3 (fc=15.9kHz lowpass) -- Confirmed

RC滤波器R5/C3（fc=15.9kHz低通）——已确认

Simulated fc=15.9kHz, <0.3% from calculated. Phase=-45 deg at fc as expected.


Keep passing results brief — they confirm what the analyzer already reported. Group them if there are many.

仿真fc=15.9kHz，与计算值偏差<0.3%。fc处相位为-45度，符合预期。


通过的结果保持简洁——它们确认了分析器已报告的内容。如果数量较多，可分组呈现。

For warnings (context required)

警告的结果（需要上下文）

undefined

undefined

Opamp U4A (inverting gain=-10)

运算放大器U4A（反相增益=-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.

undefined

1kHz时仿真增益=20.0dB，与预期的-10倍匹配。带宽98.8kHz （使用理想模型）。注意：LM358的GBW约为1MHz，因此实际带宽约为 100kHz——请确保信号频率低于85kHz，以保证增益误差<1dB。

undefined

For failures (investigation needed)

失败的结果（需要调查）

undefined

undefined

RC Filter R12/C8 -- MISMATCH

RC滤波器R12/C8——不匹配

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.

undefined

仿真fc=3.2kHz，与预期的15.9kHz偏差80%。这可能表明分析器错误识别了滤波器拓扑——R12可能用于其他用途（上拉电阻，而非串联滤波元件）。请手动验证原理图中R12/C8周围的电路。

undefined

For skips (note the gap)

跳过的结果（注明缺口）

undefined

undefined

Crystal Y1 (32.768kHz) -- Not simulated

晶体Y1（32.768kHz）——未仿真

Active oscillator module — no external load caps to validate.

undefined

有源振荡器模块——无需验证外部负载电容。

undefined

Summary line for the simulation section

仿真部分的总结行

undefined

undefined

Simulation Verification (4 pass, 1 warn, 0 fail, 1 skip)

仿真验证（4通过，1警告，0失败，1跳过）

Verified 5 subcircuits in 0.03s. All passive circuits confirmed. One opamp result requires interpretation (see U4A above).

undefined

在0.03秒内验证了5个子电路。所有无源电路均已确认。一个运算放大器结果需要解读（见上文U4A）。

undefined

Model Accuracy Reference

模型准确性参考

For detailed information about the behavioral models used, their accuracy envelopes, and known limitations, read

references/simulation-models.md

. Consult this reference when:

A user questions the accuracy of a simulation result
An opamp or crystal simulation shows unexpected behavior
You need to explain what "ideal model" means in concrete terms

如需了解所用行为模型的详细信息、准确性范围和已知限制，请阅读

references/simulation-models.md

。在以下情况下查阅本参考：

用户质疑仿真结果的准确性
运算放大器或晶体仿真显示意外行为
需要具体解释“理想模型”的含义

Script Reference

脚本参考

Script	Purpose
`scripts/simulate_subcircuits.py`	Main orchestrator — CLI entry point, reads JSON, generates testbenches, runs simulator, produces report
`scripts/spice_templates.py`	Testbench generators per detector type — one function per detector name
`scripts/spice_models.py`	Behavioral model definitions (ideal opamp, generic semiconductors), net sanitization, engineering notation formatting
`scripts/spice_results.py`	Simulation output parsing and per-type evaluation with pass/warn/fail/skip logic
`scripts/spice_simulator.py`	Simulator backends — ngspice, LTspice, Xyce auto-detection and batch execution
`scripts/spice_part_library.py`	Lookup table of electrical specs for ~100 common opamps, LDOs, comparators, voltage references, crystal drivers
`scripts/spice_model_generator.py`	Parameterized behavioral .subckt generation from specs dicts
`scripts/spice_model_cache.py`	Project-local model cache in `spice/models/` next to the schematic
`scripts/spice_spec_fetcher.py`	Queries distributor APIs (LCSC, DigiKey, element14, Mouser), structured datasheet extractions, and PDF regex for parametric specs
`scripts/extract_parasitics.py`	Compute trace R, via L, coupling C from PCB analysis JSON

脚本	用途
`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

Per-Part Behavioral Models

分型号行为模型

When the analyzer detects an opamp with a recognized MPN (e.g., LM358, TL072, MCP6002), the skill uses a per-part behavioral model instead of the generic ideal opamp. The model captures the actual GBW, slew rate, input offset, and output swing from the part's datasheet.

Model resolution cascade:

Project cache (
```
<project>/spice/models/
```
) — previously resolved models
v1.4 typed datasheet facts — via
```
lookup(mpn, cache_dir=<project>/datasheets/extracted)
```
from the
```
datasheets
```
skill. Returns
```
DatasheetFacts
```
with
```
opamp.gbw
```
,
```
opamp.slew_rate
```
, etc. as
```
SpecValue
```
instances with trust gating. Recommended source when present.
Distributor API specs — queries LCSC (no auth), DigiKey, element14, Mouser for real parametric data
v1.3 structured datasheet extraction — reads pre-extracted specs from
```
<project>/datasheets/extracted/
```
(legacy dict-shaped JSON, scored for quality). Dual-read compat path; still consulted when v1.4 cache misses.
Datasheet PDF regex extraction — reads from
```
<project>/datasheets/
```
, extracts via text pattern matching (last resort)
Built-in lookup table — ~100 common parts as offline fallback
Ideal model fallback — if the MPN isn't recognized by any source

The

model_note

field in the report indicates which model was used:

"LM358 behavioral (lookup:LM358, GBW=1.0MHz)"

"ideal opamp (Aol=1e6, GBW~10MHz)"

Models are cached project-locally in a

spice/

directory alongside the schematic files (same pattern as

datasheets/

). This keeps models co-located with the design and handles board revisions and subprojects naturally.

当分析器检测到已识别的MPN运算放大器（例如LM358、TL072、MCP6002）时，本技能会使用分型号行为模型而非通用理想运算放大器。模型会捕捉器件数据表中的实际GBW、压摆率、输入失调和输出摆幅。

模型解析优先级：

项目缓存（
```
<project>/spice/models/
```
）——已解析的模型
v1.4类型化数据表事实——通过
```
datasheets
```
技能的
```
lookup(mpn, cache_dir=<project>/datasheets/extracted)
```
获取。返回带有
```
opamp.gbw
```
、
```
opamp.slew_rate
```
等
```
SpecValue
```
实例的
```
DatasheetFacts
```
，包含可信度评估。存在时为推荐来源。
分销商API规格——查询LCSC（无需认证）、DigiKey、element14、Mouser获取真实参数数据
v1.3结构化数据表提取——读取
```
<project>/datasheets/extracted/
```
中的预提取规格（遗留字典格式JSON，带有质量评分）。兼容路径；当v1.4缓存未命中时仍会查询。
数据表PDF正则表达式提取——读取
```
<project>/datasheets/
```
中的文件，通过文本模式匹配提取（最后手段）
内置查找表——约100种常见器件作为离线回退
理想模型回退——如果MPN未被任何来源识别

报告中的

model_note

字段会指示使用的模型：

"LM358 behavioral (lookup:LM358, GBW=1.0MHz)"

"ideal opamp (Aol=1e6, GBW~10MHz)"

。

模型会缓存在项目本地的

spice/

datasheets/

模式相同）。这使模型与设计共存，并自然处理电路板版本和子项目。

Known Limitations

已知限制

Voltage dividers are simulated unloaded. The analyzer's ratio is R_bot/(R_top+R_bot) without loading. Adding a load resistor would make the simulation more "real" but would create false "errors" relative to the analyzer's calculated value. The purpose is to validate the calculation, not model the full circuit.
LC filter Q factor uses estimated inductor ESR. A default Q=100 is assumed for the inductor. Real inductor Q varies from 10 (power inductors) to 300+ (RF inductors). The resonant frequency is accurate regardless of Q.
Opamp supply rails are inferred from net names. May default to +/-5V if the power nets aren't labeled with voltage. Single-supply designs are detected when only VCC is found (VEE defaults to 0V).
Per-part models cover ~100 common parts. Uncommon opamps/LDOs fall back to ideal models. The lookup table can be extended by adding entries to
```
spice_part_library.py
```
.
High-gain opamp circuits with realistic GBW may show lower-than-expected gain at the 1 kHz measurement point when bandwidth is limited. This is physically correct behavior (the model correctly captures the GBW limitation) but may need lower-frequency measurement for accurate gain comparison.
Net names from the analyzer may be
__unnamed_N
. These are KiCad internal net names for unlabeled wires. They work correctly in simulation but make
```
.cir
```
files less readable.

分压器仿真为无负载状态。分析器的比例为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的高增益运算放大器电路，当带宽受限时，在1kHz测量点可能显示低于预期的增益。这是物理上的正确行为（模型正确捕捉了GBW限制），但可能需要更低频率的测量以获得准确的增益比较。
分析器的网络名称可能为
__unnamed_N
。这些是KiCad内部的未命名导线网络名称。它们在仿真中可正常工作，但会使
```
.cir
```
文件可读性降低。

spice

Original

Translation

SPICE Simulation Skill

SPICE仿真技能

Related Skills

相关技能

Requirements

要求

Workflow

工作流

Step 1: Run the schematic analyzer

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

Step 2: Run SPICE simulations

步骤2：运行SPICE仿真

Recommended: auto-resolve schematic + write spice.json into the current run

推荐方式：自动解析原理图 + 将spice.json写入当前运行目录

Explicit form — positional or --schematic path

显式形式——使用位置参数或--schematic指定路径

Simulate specific types only

仅仿真特定类型的子电路

Keep simulation files for debugging (default: <run>/spice_work/ when --analysis-dir is set, else a temp dir)

保留仿真文件用于调试（默认：当设置--analysis-dir时为<run>/spice_work/，否则为临时目录）

Increase timeout for complex circuits (default: 5s per subcircuit)

为复杂电路增加超时时间（默认：每个子电路5秒）

Omit file paths from output (cleaner for reports)

在输出中省略文件路径（让报告更简洁）

Step 2b (optional): PCB parasitic-aware simulation

步骤2b（可选）：PCB寄生参数感知仿真

Analyze PCB with full trace segment detail

分析PCB并包含完整的走线段细节

Extract parasitic R/L/C from PCB geometry

从PCB几何结构中提取寄生R/L/C参数

Run simulation with PCB parasitics injected into testbenches

运行仿真并将PCB寄生参数注入测试平台

Step 2c (optional): Monte Carlo tolerance analysis

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

Run 100 Monte Carlo trials per subcircuit

每个子电路运行100次蒙特卡洛试验

Use uniform distribution (conservative worst-case envelope) instead of Gaussian

使用均匀分布（保守的最坏情况范围）而非高斯分布

Set random seed for reproducibility (default: 42)

设置随机种子以保证可复现性（默认：42）

Step 3: Interpret results and present to user

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

What Gets Simulated

可仿真的内容

What is NOT simulated

不可仿真的内容

Output Format

输出格式

Interpreting Results

解读结果

Passive circuits (RC filters, LC filters, voltage dividers)

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

Opamp circuits

运算放大器电路

Crystal circuits

晶体电路

When simulations fail or skip

当仿真失败或被跳过

Presenting Results to Users

向用户呈现结果

For passing simulations (confidence builders)

通过的仿真（增强信心）

RC Filter R5/C3 (fc=15.9kHz lowpass) -- Confirmed

RC滤波器R5/C3（fc=15.9kHz低通）——已确认

For warnings (context required)

警告的结果（需要上下文）

Opamp U4A (inverting gain=-10)

运算放大器U4A（反相增益=-10）

For failures (investigation needed)

失败的结果（需要调查）

RC Filter R12/C8 -- MISMATCH

RC滤波器R12/C8——不匹配

For skips (note the gap)

跳过的结果（注明缺口）

Crystal Y1 (32.768kHz) -- Not simulated

晶体Y1（32.768kHz）——未仿真

Summary line for the simulation section