Simulation
The simulation switches the board's rails on in ngspice and reads what every net settles to. It runs after the parts are resolved and before anything is placed.
It is the dynamic version of the ERC's Ohm's-law rules. The ERC works
out what a resistor should pass from the declared rail. spice.simulate(netlist)
puts every part it has a model for into a deck and runs it.
| Output | Where it goes |
|---|---|
| The traces | sim.json beside the version's board.json, drawn by the scope |
| The findings | The board's gaps and notes |
| On the command line | The sim section |
Report only
The pass rule (repair.passes()) does not read the simulation. The models
are generic stand-ins, not the parts, and a verdict that moved on them would
fail boards for the model's sake. What it gives you is a sentence beside the
result: +3V3 settles at 3.285 V (declared 3.3 V); D1 1.42 mA.
The engine
The engine is ngspice, which KiCad also simulates with. It is found in one of two forms:
ngspiceonPATH(brew install ngspice), run in batch mode.- Failing that, the shared library KiCad ships, driven through
ctypes. On macOS that isKiCad.app/Contents/Frameworks/libngspice.0.dylib; on Linux,libngspice.so.0.
It runs in a child process with a ten-second timeout. A deck ngspice cannot solve can crash the process, and a failed simulation must cost a note, never the build.
| Setting | Effect |
|---|---|
soldermask setup | Prints which form was found |
SOLDERMASK_NGSPICE | Points at an ngspice program or library |
SOLDERMASK_SIM=off, or --no-sim on the command line | Skips the stage. The board says it was switched off. |
--sim-only on the command line | Resolves and simulates, and nothing else. Writes sim.json to --out and saves no version. |
| Simulate on the workbench's Sim box, or in the command bar | Simulates the version on screen. Writes its sim.json beside it and makes no new version. |
simulate on MCP check_design | Runs the stage on the checked design and returns sim. It is off by default. |
With no engine, the board gets the note not simulated: ngspice not found and
no sim.json. The scope then says there is no simulation rather than drawing a
flat line.
What is in the deck
Ground is node 0. Two ground nets become one node, and the assumptions say so. Every other net is a node.
| Kind | In the deck as | Taken from |
|---|---|---|
| Resistor, capacitor, inductor | R, C, L | The value, or the first value in the catalogue description when the design left it blank |
| LED | A diode whose forward voltage at 20 mA is its colour's (electrical.LED_VF) | The anode and cathode the resolver found, or pin 1 as the anode |
| Diode | A generic silicon or Schottky diode | The anode and cathode the resolver found (A, and K or C); silicon or Schottky from the description |
| Transistor | A generic NPN or PNP (β 150), or NMOS or PMOS (threshold 1.8 V) | Pins named B/C/E or G/D/S; polarity from the description |
| Switch | A closed contact (0.1 Ω) when it is on two nets, noted as pressed | |
| Connector | Nothing; its pins are nodes | |
| Crystal | Nothing, with nothing to drive it. It is named in unmodelled. | |
| Linear regulator | One behavioural source, out = min(in − dropout, Vout), with 50 mΩ output | See below |
| Buck or boost converter | An ideal converter with no ripple, driving the rail it regulates. A buck is the linear source with 0.3 V dropout. A boost gives Vout once its input passes 0.8 V. | A buck whose output pin is its switch node drives the rail past its inductor; a boost drives the rail past its diode. That inductor and diode are drawn as the converter. |
| Op-amp or comparator | Each unit as a tanh stage with gain 10⁴ and 100 Ω output, swinging to its rails | Supply pins named V+/VCC and V−/VEE/GND |
| A charger, a power-bank chip, or a regulator making a negative rail | Nothing, as below. Its pins are open. | The catalogue's category or description |
| Anything else | Nothing. Its pins are open, and it is named in unmodelled. |
A regulator's output voltage comes from, in order:
- the part number (
AMS1117-3.3,XC6206P332,HT7550,L7805and so on); - the catalogue's typed output voltage, for a part the catalogue types as fixed;
- the catalogue description;
- the rail's declared voltage.
The assumptions say which. The dropout comes from the description, such as
1.1V@(800mA). Without one it is 1.2 V for a 1117, 1.7 V for a 78Lxx,
2 V for a 78xx, and 0.3 V otherwise.
An adjustable part sets its output from its pins instead:
| Pin | Output |
|---|---|
| ADJ (an LM317) | 1.25 V above the ADJ pin, with the design's divider in the deck |
| FB, VFB, VSNS or VSENSE (a converter) | The reference times (1 + top / bottom) of the divider on the pin. The reference is the part's datasheet record's feedback voltage, else the lowest output the catalogue gives it. |
A feedback pin with no divider on it, or no reference in the catalogue, falls back to the list above.
A comparator is simulated like an op-amp, with a note that its open-collector output needs the pull-up the design gives it.
A part on fewer than two nets is not in the circuit. It is not counted as unmodelled, because the resolver has already reported its dropped connections.
Stimulus
- Every power net with a declared
voltage_vthat no modelled part drives gets a source. It ramps from 0 to that voltage in 100 µs. - Every power net with a declared
current_agets a load of V/I to ground. - A rail that a modelled regulator drives gets no source. It is the rail being checked. A rail past a regulator's inductor counts as driven.
- A power net that declares no voltage gets nothing, and the assumptions say so.
The simulation is refused when the design has no ground net, no rail with a declared voltage, or no part with a model. A note gives the reason. A circuit with nothing switched on settles at zero everywhere, and that is not a result.
Duration
The run lasts five time constants of the slowest RC in view, bounded to 1-10
ms. Each capacitor is paired with the parallel resistance on its net. The trace
is resampled onto 2,001 even points. .option rshunt=1e9 gives every open pin
a path to ground, so an unmodelled part's node does not stall the solver.
What it reports
| Finding | Reported as |
|---|---|
| A rail a modelled part drives settles within 5% of its declared voltage | A note, such as +3V3 settles at 3.285 V (declared 3.3 V) |
| That rail settles further off | A gap |
| A 5 V part on a rail declared 3.3 V | An assumption, said before the run |
| An LED over 30 mA | A gap |
| An LED under 50 µA | A gap: conducts nothing … check its polarity and what its anode is on |
| An LED under 50 µA with an unmodelled part on its path, such as a GPIO pin | A note that it is not simulated, not a gap |
| An LED under 1 mA | A note: dim for an indicator |
| A chip's logic pin over the highest rail the chip is fed from, by more than 0.5 V, at rest | A gap naming the pin, its voltage and the rail |
| A TP4056, MCP7383x or LTC4054 whose PROG resistor sets a current past the part's rating | A gap |
| That current over the battery net's declared current | A note, since that figure is often the board's load |
| Parts with no model | One gap naming them. Their pins are open, so the traces show the rails without them. |
sim.json also carries:
- the assumptions: where each regulator's numbers came from, which switches were closed, and which power nets got no source;
- the deck itself, as
deck, so you can run it through ngspice by hand.
Pins at rest. The pin check reads DC operating points, not the transient. A slow RC on an enable pin has then finished charging. Each switch is solved both pressed and released, so a reset button does not hide a pull-up. A chip's power and logic pins come from its datasheet record where there is one, else from the pin names.
tools/sim_survey.py runs the stage over every saved version, read only.
tools/sim_bench.py injects faults into saved designs and counts what the
simulator and the design check catch. On 144 designs the simulator was not
tuned on, it caught 96 of 119 injected faults of the kinds it checks (81%). It
raised a false finding on 3 of the 144 designs as built. The
changelog has the run.
Conditions
soldermask/conditions.py puts the same deck through what a bench puts a board
through. Every condition comes from the design's own declarations. It is report
only, and nothing in it reaches the verdict.
Every build runs the audio condition when the board has an audio jack or a
speaker. A corner above 20 Hz comes back as the design check's audio-corner
warning. tools/sim_conditions.py runs all six conditions over saved designs.
| Condition | What the deck gets | Fails when |
|---|---|---|
plug | Each input switched on through its lead: USB 0.3 Ω and 0.7 µH, a terminal or jack 0.1 Ω and 1 µH, a cell its chemistry's resistance. A pin header is a host board's rail, with no lead. Capacitors carry ESR. | A rail rings past a capacitor's rated voltage or a pin's absolute maximum |
step | The same run, then every declared load from 10% to full in 1 µs | A rail dips under the minimum supply of a chip on it |
enable | Regulators honour an enable pin held by parts in the deck | A regulated rail never comes up |
battery | Each cell swept from full to empty, other inputs unplugged and not judged | A chip drops out before the cell is half discharged. Later is a note. |
corner | Resistors, rails and each LED's forward voltage at the ends of their ranges. An LED a chip drives is lit through that pin. An LED with no known forward voltage is not judged. | An LED is under 1 mA at the low corner, or over 30 mA at the high |
audio | A sweep from a chip through a series capacitor into its load: a jack 32 Ω, a speaker 8 Ω, a line input 10 kΩ. An RJ45, Ethernet, DC, barrel or power jack is not an audio jack. | The -3 dB corner is above 20 Hz |
Some rails sit behind a fuse, a ferrite bead, a diode, an inductor or a small resistor. Those rails are fed through that part and get no source of their own. A MOSFET counts only when passives hold its gate on, as in reverse-polarity protection. A fuse or bead is its catalogue resistance. A TVS or zener breaks down at its catalogue voltage.
The limits come from the component library's verified rows first. Then come the catalogue's supply range and a capacitor's rated voltage. A chip with none of these has no limit, and the condition does not guess one.
What it does not do
- No layout effects. There is no layout yet. Copper resistance, plane inductance and coupling between tracks are not in a deck built from a netlist.
- No MCU, radio or sensor behaviour. Those parts are
unmodelled. Their rails are still traced and still carry the current the design declared for them. - No temperature, and no switching ripple on a converter. Track heating is judged after routing, in Copper too narrow for its current.
- No regulator current limit. A regulator's input draws nothing, so an input rail shows only the load declared on it.
- No 555, charger IC or logic. The model library grows part by part, and every part not in it is named.