| name | qspice-convergence-debugging |
| description | Diagnose and fix QSpice simulations that fail to converge, stop early, or produce no usable waveform. Use when a run errors, the log shows "no convergence", "timestep too small", singular-matrix, or gmin-stepping failures, or when V(out) is missing/flat after a simulation. |
| license | MIT |
| metadata | {"author":"qspice-mcp","version":"1.0"} |
QSpice: Convergence Debugging
A structured workflow for simulations that fail to converge, abort early, or
yield empty/flat results. Convergence failures are about the numerics and the
circuit, not the MCP server.
When to use
run_simulation returns an error or the result has no/short waveform.read_log shows: no convergence, timestep too small, singular matrix,
gmin stepping failed, iteration limit, or analysis stopped before the
requested stop time.- A signal that should be active is flat or missing in
list_signals.
When NOT to use
connected=false / missing QSPICE_EXE → setup/config problem, not numerics.- Backend-unavailable errors → call
describe_server_capabilities first.
Workflow
- Read the evidence.
read_log — identify the exact failure phrase and the
time/node where it stopped. Don't guess before reading the log.
- Localize.
inspect_schematic + list_components — find the stage near the
failing node (switching node, feedback, high-impedance net, nonlinear device).
- Form one hypothesis from the table below and change one thing.
- Re-run
run_simulation, then read_log again. Iterate; change one factor
at a time so you know what helped.
Common causes → fixes
| Log symptom | Likely cause | Fix |
|---|
singular matrix, floating node | No DC path to ground; dangling net | Add a path to GND (large R to ground), fix unconnected pins; verify with list_components |
timestep too small | Stiff switching, ideal edges, no parasitics | Add small series R / snubber; soften driver edges; relax reltol slightly |
no convergence at t=0 | Hard DC operating point | Add .ic initial conditions; enable gmin/source stepping; add soft-start to sources |
| Stops mid-transient | Discontinuity / ideal switch chatter | Add hysteresis or RC snubber across the switch; add device parasitics |
Nonlinear/behavioral (B) blowup | Aggressive expression, divide-by-zero | Clamp/limit the B expression; add series resistance |
Applying fixes via tools
- Component value/parasitic:
set_component_value or
set_component_parameters (e.g. add a series R, snubber C).
- Add a part (snubber, bleeder to GND):
add_component + add_wire
(+ add_junction / add_net_label as needed).
- Simulator directives (
.options reltol=..., .ic ..., .options gmin=...):
add a SPICE directive. If editing the schematic's directives is not exposed for
your case, simulate the derived netlist: generate_netlist, append the
.options/.ic line, then run_simulation on that .net/.cir.
Useful directive starting points
.options reltol=0.005 ; loosen from default 0.001 if borderline
.options gmin=1e-10 ; help DC operating point
.options method=gear ; more stable integration for stiff circuits
.ic V(out)=0 V(sw)=0 ; seed a known operating point
Loosen tolerances only modestly — over-loosening trades accuracy for convergence.
Verify the fix
After it runs to completion: read_log (clean exit, reached stop time) →
list_signals → measure_waveform on the target node to confirm the result is
physically sane (e.g. a buck V(out) near its expected regulation point), not
just "it ran."
Conventions
- Read the log before changing anything; change one factor per iteration.
- Prefer adding real parasitics (series R, snubbers) over brute-force tolerance
loosening — it's both more convergent and more physical.
- Re-confirm correctness with
measure_waveform, not just a non-error exit.
