# Spice

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-aklofas-kicad-happy-spice`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aklofas](https://agentstack.voostack.com/s/aklofas)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aklofas](https://github.com/aklofas)
- **Source:** https://github.com/aklofas/kicad-happy/tree/main/skills/spice
- **Website:** https://github.com/aklofas/kicad-happy

## Install

```sh
agentstack add skill-aklofas-kicad-happy-spice
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

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

**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.8+** — 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

```bash
python3 /scripts/analyze_schematic.py design.kicad_sch --output analysis.json
```

### Step 2: Run SPICE simulations

```bash
# Simulate all supported subcircuit types
python3 /scripts/simulate_subcircuits.py analysis.json --output sim_report.json

# Simulate specific types only
python3 /scripts/simulate_subcircuits.py analysis.json --types rc_filters,voltage_dividers

# Keep simulation files for debugging (default: temp dir, cleaned up)
python3 /scripts/simulate_subcircuits.py analysis.json --workdir ./spice_runs

# Increase timeout for complex circuits (default: 5s per subcircuit)
python3 /scripts/simulate_subcircuits.py analysis.json --timeout 10

# Omit file paths from output (cleaner for reports)
python3 /scripts/simulate_subcircuits.py analysis.json --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:

```bash
# Analyze PCB with full trace segment detail
python3 /scripts/analyze_pcb.py design.kicad_pcb --full --output pcb.json

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

# Run simulation with PCB parasitics injected into testbenches
python3 /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.

```bash
# Run 100 Monte Carlo trials per subcircuit
python3 /scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --output sim_report.json

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

# Set random seed for reproducibility (default: 42)
python3 /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).

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

### 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

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

## Interpreting Results

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

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

## Presenting Results to Users

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

### For passing simulations (confidence builders)

```
### RC Filter R5/C3 (fc=15.9kHz lowpass) -- Confirmed
Simulated fc=15.9kHz, /spice/models/`) — previously resolved models
2. **Distributor API specs** — queries LCSC (no auth), DigiKey, element14, Mouser for real parametric data
3. **Structured datasheet extraction** — reads pre-extracted specs from `/datasheets/extracted/` (cached JSON with SPICE-relevant parameters, scored for quality)
4. **Datasheet PDF regex extraction** — reads from `/datasheets/`, extracts via text pattern matching (last resort)
5. **Built-in lookup table** — ~100 common parts as offline fallback
6. **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)"` vs `"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.

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aklofas](https://github.com/aklofas)
- **Source:** [aklofas/kicad-happy](https://github.com/aklofas/kicad-happy)
- **License:** MIT
- **Homepage:** https://github.com/aklofas/kicad-happy

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aklofas-kicad-happy-spice
- Seller: https://agentstack.voostack.com/s/aklofas
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.