soldermaskdocs

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.

OutputWhere it goes
The tracessim.json beside the version's board.json, drawn by the scope
The findingsThe board's gaps and notes
On the command lineThe 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:

  1. ngspice on PATH (brew install ngspice), run in batch mode.
  2. Failing that, the shared library KiCad ships, driven through ctypes. On macOS that is KiCad.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.

SettingEffect
soldermask setupPrints which form was found
SOLDERMASK_NGSPICEPoints at an ngspice program or library
SOLDERMASK_SIM=off, or --no-sim on the command lineSkips the stage. The board says it was switched off.
--sim-only on the command lineResolves 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 barSimulates the version on screen. Writes its sim.json beside it and makes no new version.
simulate on MCP check_designRuns 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.

KindIn the deck asTaken from
Resistor, capacitor, inductorR, C, LThe value, or the first value in the catalogue description when the design left it blank
LEDA 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
DiodeA generic silicon or Schottky diodeThe anode and cathode the resolver found (A, and K or C); silicon or Schottky from the description
TransistorA 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
SwitchA closed contact (0.1 Ω) when it is on two nets, noted as pressed
ConnectorNothing; its pins are nodes
CrystalNothing, with nothing to drive it. It is named in unmodelled.
Linear regulatorOne behavioural source, out = min(in − dropout, Vout), with 50 mΩ outputSee below
Buck or boost converterAn 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 comparatorEach unit as a tanh stage with gain 10⁴ and 100 Ω output, swinging to its railsSupply pins named V+/VCC and V−/VEE/GND
A charger, a power-bank chip, or a regulator making a negative railNothing, as below. Its pins are open.The catalogue's category or description
Anything elseNothing. Its pins are open, and it is named in unmodelled.

A regulator's output voltage comes from, in order:

  1. the part number (AMS1117-3.3, XC6206P332, HT7550, L7805 and so on);
  2. the catalogue's typed output voltage, for a part the catalogue types as fixed;
  3. the catalogue description;
  4. 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:

PinOutput
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_v that no modelled part drives gets a source. It ramps from 0 to that voltage in 100 µs.
  • Every power net with a declared current_a gets 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

FindingReported as
A rail a modelled part drives settles within 5% of its declared voltageA note, such as +3V3 settles at 3.285 V (declared 3.3 V)
That rail settles further offA gap
A 5 V part on a rail declared 3.3 VAn assumption, said before the run
An LED over 30 mAA gap
An LED under 50 µAA 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 pinA note that it is not simulated, not a gap
An LED under 1 mAA 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 restA gap naming the pin, its voltage and the rail
A TP4056, MCP7383x or LTC4054 whose PROG resistor sets a current past the part's ratingA gap
That current over the battery net's declared currentA note, since that figure is often the board's load
Parts with no modelOne 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.

ConditionWhat the deck getsFails when
plugEach 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
stepThe same run, then every declared load from 10% to full in 1 µsA rail dips under the minimum supply of a chip on it
enableRegulators honour an enable pin held by parts in the deckA regulated rail never comes up
batteryEach cell swept from full to empty, other inputs unplugged and not judgedA chip drops out before the cell is half discharged. Later is a note.
cornerResistors, 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
audioA 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.

On this page