mbg-spice-sim
Runs ngspice simulations for analog blocks in this repository and turns the raw output into readable data, using mbg.simulation (run_spice, raw_to_csv, parse_dat). Use when the user asks to simulate a
SKILL.md.ai/skills/mbg-spice-sim/SKILL.md
GitHubMBG SPICE Simulation
Preferred API: mbg.analysis.Testbench
run_spice is the transport. For anything beyond a raw deck use the analysis
layer, which builds a correct deck and parses the results:
from mbg.analysis import Testbench, fft
tb = Testbench(netlist, cell="ota_5t",
supplies={"vdd": 3.3, "vss": 0.0},
sources={"inp": 1.65, "inm": 1.65, "vb": 0.8},
probes=["out"])
tb.op() # operating point
tb.dc("inp", 0, 3.3, 0.01) # DC sweep
tb.ac(1, 1e9, points=50) # AC sweep -> .bandwidth_3db("out")
tb.tran("1n", "1u") # transient -> .peak_to_peak(), .cross()
tb.monte_carlo("op", runs=50) # mismatch spread -> .stats("out")
freq, mag = fft(result, "out")
Three traps it handles for you:
design.ngspicemust be included before the model library. The GF180 device subcircuits declare 24 formal parameters, and the statistical ones (par_vth,par_k,var_vth,p_sqrtarea, ...) are defined indesign.ngspice. Without it ngspice reports their missing defaults asSyntax error: letter [$],Mismatch: 24 formal but 15 actual params,Expression err: $and finallyFormula() error— one burst per device. All four messages are the same single root cause;$is ngspice's marker for "no default supplied", not a corrupt netlist.- Each analysis reads the file it wrote.
dc/ac/trandropdc.dat/ac.dat/tran.datinto one workdir, so picking "the first .dat" hands back a previous analysis's data. A transient that comes back with the output node missing is this bug, not a probe problem. - AC data is complex.
wrdatawrites(freq, re, im)triplets for AC and(x, y)pairs for dc/tran. Magnitude is stored under the probe name, with<name>.re/<name>.imalongside for phase. dc/ac/tranprobe every port by default, not just the stimulus — recording only the swept source omits the response.- An AC source needs an AC magnitude. Attaching it must match the source
line, not a single-token value: a source written
DC 1.2silently kept a magnitude of zero and returned an all-zero sweep.ac()now raises rather than returning that. - ngspice's exit code is unreliable — it commonly returns non-zero after a
.controlblock that succeeded. Results are judged by whether data appeared. - Monte Carlo needs the
statisticalcorner withsw_stat_mismatch=1. GF180 computesdelvto = mis_vth * sw_stat_mismatch, and thetypicalcorner leaves that switch at zero, so re-seeding alone returns the same number every run.monte_carlo()sets both.
Purpose
Run ngspice on a netlist and read the results back as usable numbers. This skill covers the pre-layout and post-layout simulation stages of the flow; it does not build layout and does not run physical verification.
When to Use
- The user asks to simulate a circuit, run a testbench, or check an operating point.
- The user asks for a measured quantity: DC gain, GBW, phase margin, delay, offset, power, or a temperature or corner sweep.
- The user wants a pre-layout versus post-layout comparison of the same block.
When Not to Use
- Generating GDS from SPICE. Use
mbg-spice-to-gds. - DRC, LVS or PEX. Use
mbg-ic-verify. - Reading previous results without re-running anything. Use
mbg-design-regression.
Required Inputs
- A complete ngspice netlist including its own analysis and control lines.
run_spiceexecutes exactly what it is given; it does not append.tran,.ac,.controlor.endfor you. - Model libraries referenced through
$PDK_ROOT, not an absolute personal path.
Preconditions
ngspiceis on PATH.PDK_ROOT,PDKandPDKPATHare set. Inside the IIC-OSIC-TOOLS container the project standard isPDK_ROOT=/foss/pdks,PDK=gf180mcuD. On a host install they point at the volare PDK root instead.- Use
mbg.simulation.pdk_path(subpath)to build PDK-relative paths rather than writing an absolute path into a netlist.
Workflow
Confirm the netlist carries its own analysis statements and a
.end.Run it:
from mbg.simulation import run_spice, raw_to_csv, parse_dat, pdk_path r = run_spice(netlist_text, workdir="sim_out", fmt="raw") # r = {"stdout", "stderr", "returncode", "raw_path", "dat_paths", "workdir"}workdir=Noneuses a temporary directory that is cleaned up, so pass an explicitworkdirwhenever the artifacts need to survive the call.fmtselects the output form:"raw"(binary),"dat"(wrdatatext), or"both".Check
returncodefirst, then readstderr— ngspice frequently reports a convergence or model-resolution problem while still exiting 0, so a zero return code alone is not evidence that the simulation is meaningful.Convert results for analysis:
csv_path = raw_to_csv(r["raw_path"]) # binary raw -> CSV columns = parse_dat(r["dat_paths"][0]) # wrdata text -> column dictReport measured numbers with the analysis that produced them. Do not infer a metric the netlist never asked for.
Outputs
- A working directory containing the ngspice input and its raw or
.datoutput. - CSV or parsed column data derived from those files.
- Measured values, each tied to the analysis that produced it.
Failure Modes
ngspice: command not found— the tool is not on PATH; this usually means the command is running on the host rather than inside the container.- Model or
.libnot found —PDK_ROOT/PDKPATHare unset or point at the wrong root. Rebuild the path withpdk_path()and re-check the environment. - Exit code 0 but empty or flat output — the netlist had no analysis statement, or
the analysis ran but every node sat at its initial condition. Read
stdout. - Timeout —
run_spicedefaults to 300 s. A long transient or corner sweep needs an explicit largertimeout; do not silently truncate the analysis to fit.
Reporting Rules
Never report a simulation as passing without the artifact that shows it. Use the
project status vocabulary — PASS, FAIL, PARTIAL, NOT RUN, NOT AVAILABLE —
and prefer NOT RUN over an unsupported claim.