aklofas/kicad-happy/spice

SPICE Simulation Skill

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.

Related Skills

Handoff guidance: The kicad skill's analyze_schematic.py produces the analysis JSON with subcircuit detections in the flat findings[] array (filtered by detector field). This skill reads that JSON, generates SPICE testbenches for simulatable subcircuits, runs the detected simulator (ngspice/LTspice/Xyce), and produces a structured verification report. Always run the schematic analyzer first. During a design review, run simulation after the analyzer and before writing the final report — simulation results should appear as a verification section in the report. The emc skill reuses this skill's simulator backend for SPICE-enhanced PDN impedance and EMI filter insertion loss checks — when ngspice is available, the EMC skill's --spice-enhanced flag activates these checks automatically.

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.

Workflow

Step 1: Run the schematic analyzer

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

Step 2: Run SPICE simulations

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.

# 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

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

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

# 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

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.

Step 2c (optional): Monte Carlo tolerance analysis

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.

# 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

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.

Step 3: Interpret results and present to user

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

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).

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

Output Format

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

Interpreting Results

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