Models & resolution

To simulate a part, circsim needs a SPICE model for it. This page explains how a part on your board gets matched to a model, what the different "kinds" of model mean, and (just as importantly) what happens when no model fits.

If you just want to fix an unresolved part, jump to the Model Doctor guide. This page is the concept behind it.

How a part finds its model

circsim resolves every part through a tiered pipeline. The first tier that produces a confident match wins, and circsim records which tier it used so you can see how it decided.

1. Your Model Doctor overrides win over everything. If you've stubbed a part, imported a model for it, or hand-edited its pin map, that's final.
2. Schematic Sim.* fields: if a matching .kicad_sch gives a part explicit KiCad simulation fields, circsim uses them. This is the highest-fidelity automatic source. circsim only uses Sim.Device when it can write a complete SPICE card from it: a resistor, capacitor or inductor needs a value (from Sim.Params, or from the Value field when KiCad wrote c=""), and a voltage or current source needs a dc value. A diode, transistor or MOSFET needs a model name that a bare Sim.Device cannot supply, and a device type circsim does not handle (SPICE, NMOS, NPN, and so on) is skipped. In every such case circsim carries on to the next tiers with the Value field and the library, rather than emitting a card the simulator would reject or silently drop.
3. Primitive inference: a reference starting with R, C, or L plus a parseable value becomes a resistor, capacitor, or inductor directly. (Values like DNP, N/A, or TBD are treated as "not fitted" and stubbed open.) The value reader accepts the spellings real boards and BOM exports use: 10k, 4k7, 4,7k (decimal comma), 10 kΩ and 10 kOhm (spaces, omega or Ohm), 100nF, 100NF, 4.7µF and 4.7μF (micro sign or Greek mu, any case of u/n/p), 1e-9 (exponent form), and ratings after the value (100nF/50V). Case matters only for M: M is mega and m is milli, so 2m2 is 2.2 milli and 2M2 is 2.2 mega. A thousands-style comma such as 1,000 is ambiguous between a European decimal and a thousands separator, so it is not read at all.
4. The bundled model library: the main path. circsim matches the part against its built-in library of diodes, LEDs, transistors, op-amps, the 555, logic, regulators, and more.
5. Your imported .lib/.sub files: models you import through the Model Doctor are prepended to the library, so your model for a given part number beats the bundled one.
6. Automatic stubs: a microcontroller, module, addressable LED or USB-serial bridge that no model claimed is stubbed for you, by name, as a supply-load stub (amber, never green). A crystal becomes a documented open.
7. Nothing matched: anything still unmatched is flagged for you (red "no model").

Matching against the library

Within the bundled library, circsim tries three things in order and stops at the first that yields exactly one match:

• By manufacturer part number. The MPN (from a BOM row, a board property, or the value field) is normalized: uppercased, with package and reel suffixes stripped (-TR, DBV, reel codes) but guarded so it never eats real part-number digits: 2N3904 stays 2N3904. This is the most reliable match. A BOM MPN beats a board MPN property, which beats the value field. When the value field is standing in for a missing MPN, circsim refuses the match on a reference that is never a library device: a battery holder (BT1), test point (TP1), switch (SW1), connector (J1, P1) or passive (R, C, L) whose value happens to be 3V0, 5V1 or 555 is not a zener or a 555. Every other reference convention is accepted (Q1, T1, TR1, V1 for a transistor; D1, CR1, LD1 for a diode or LED; U1, IC1, A1, N1 for an IC), because boards name the same part many ways.
• By value pattern. Some parts are recognized by their value field (an LED color, NE555, 3.0V for a zener), with the same refusal of references that are never a library device.
• By refdes prefix + footprint. A last-resort fallback that needs a footprint pattern, and it says so when it fires. Many library entries deliberately skip this tier to avoid false positives. A generic "U-prefixed 14-pin chip" rule once misidentified a CD4011 as an op-amp, so parts like the LM339 and CD4011 match by part number only. Footprint patterns are anchored to the footprint name, so an LED footprint is never read as a diode. An LED whose value is not a recognized color (Yellow, Amber, LED 0805) on an LED_* footprint resolves to the generic LED, which uses the red model as a stand-in; a library-fallback warning on the part's resolution reminds you to set the value or MPN if the color matters. This warning alone does not put the part in the Model Doctor, so it is not shown on a card.

If two entries match at the same tier, circsim does not guess. It marks the part ambiguous and asks you to pin it down with an MPN. Silence beats a coin-flip.

The kinds of model

Not all models are equal, and circsim is explicit about which kind each part gets, because it changes how much you should trust the result.

Primitive-level models

Diodes, LEDs, bipolar transistors, and discrete MOSFETs are modeled as ngspice primitives: real .model cards whose parameters (saturation current, forward voltage, transistor gain, MOSFET turn-on thresholds) are derived from the part's datasheet operating points using SPICE's standard device equations (the fitting script is in the repository, and CI rejects any card that reproduces a known third-party library card). These are as good as SPICE gets at the hobbyist level. (The exact equation sets have names: Gummel-Poon for bipolar transistors, VDMOS for power MOSFETs, which you'll see in the model library reference; you don't need them to use the models.)

Behavioral macromodels

Op-amps, comparators, the NE555, linear regulators, the TL431 reference, and a few power-management ICs are behavioral subcircuits. They reproduce the part's terminal behavior (gain, bandwidth, slew rate, saturation voltages, current limit) without simulating the internal transistors. A behavioral op-amp will clip at the right rail, slew at the right rate, and leave a rail promptly when its input reverses, and its supply pins carry its load current (as do the 555's, a regulator's, and a logic gate's), but its high-frequency and thermal quirks are approximate. It's good enough to catch design mistakes, but it isn't a substitute for the real chip. See fidelity.

Some behavioral models are deliberately simplified operating-point stubs: a battery-protection IC modeled in its normal (non-tripped) state, a switching LED driver modeled as its DC-average current sink. circsim documents exactly what each one does and doesn't capture.

Digital logic

The 74HC and CD4000 logic families use behavioral digital models (built on ngspice's XSPICE extension, which lets a real logic gate live inside an analog simulation). The gate does the right truth table with datasheet-typical thresholds, and the plain gates carry datasheet-typical delays (the fidelity page says which timing is gated and which is not). Schmitt-trigger parts (the 74HC14, CD40106) carry true hysteresis, so an RC astable (an oscillator made from just a resistor, a capacitor, and one gate) built around one actually oscillates.

Every gate output has a finite drive: roughly 40 ohm and 25 mA for 74HC at 5 V, roughly 400 ohm and 3 mA for CD4000 at 5 V (both scale with the rail). A logic pin wired straight to an LED, a relay coil, or a heavy load therefore sags toward the load instead of holding the rail. The active-low clear, preset, and master-reset pins of the 74HC74, 74HC164, and 74HC595 behave as active-low, so tying them high leaves the register free to clock.

Stubs and interactive pins

Some parts can't be modeled, and circsim represents them honestly rather than faking it.

• Open stub: the part's pins are left electrically open. Right for a part that isn't fitted, or one you want to remove from the simulation.
• Short stub: the pins are tied together. Useful for modeling a jumper, a fitted zero-ohm, or a closed switch.
• Supply-load stub (automatic): the default for a recognized microcontroller, module, addressable LED or USB-serial bridge. See below.
• Interactive pins: the model for microcontrollers and other complex digital ICs. There's no SPICE model and the firmware does not run. Instead, each pin becomes a control you drive by hand: set it high, low, or high-impedance, or watch its voltage. This lets you answer "if GPIO5 goes high, does the LED turn on?" without pretending to simulate the chip. Drive the pins from the Interactive Pins panel.
• Documented open: a known part that circsim deliberately doesn't model because there's no meaningful SPICE analog (a USB-PD negotiation controller, say). It shows as grey "open by design," not red "unresolved," and carries a note explaining why.

Connectors get special treatment: a bare-board connector is electrically open (power arrives through your bench instruments, not the connector), so J/P parts resolve to a clean open stub with an "ok" status rather than nagging you.

Supply-load stubs

circsim recognizes the common controllers by name, from the MPN property (or the BOM MPN), the value field, or the footprint name: ESP32 and ESP8266 modules, STM32 (F1, F4, and the C0/F0/G0/L0/L4 low-power series), ATmega and ATtiny (and Arduino Nano/Uno/Pro Mini modules), RP2040 (and the Pico module), nRF52, SAMD21, CH32V003 and MSP430, plus WS2812B / NeoPixel LEDs and the CH340 USB-serial bridge. Each becomes a supply-load stub: a two-terminal load from the part's supply pad to its ground pad that draws the family's datasheet supply current once the rail is above the part's minimum operating voltage, and does nothing else. The rail sags and loads like the real board, so the regulator, the supply's series resistance and the copper see the current; the part's logic and pins are not simulated.

• The supply and ground pads come from the attached schematic's power-input pin names when there is one, then from a datasheet pinout where the stub has one (CH340, WS2812B), then from the names of the nets on the part's pads (+3V3, VCC, GND).
• The part is stubbed (amber), never ok, and its card in the Model Doctor says what it was modeled as, the current, and the pads it chose.
• If the family is recognized but no datasheet figure is bundled for it (an STM32 of another series, a PIC, an LPC), or its supply pads cannot be identified, the part becomes interactive pins with no supply current, and the warning says why. circsim does not invent a load.
• A library match made only from the part's refdes and package (an IC in a generic SOIC-8) does not count: an ATtiny85 or CH32V003 on an 8-pin package, or an ATtiny84 on a SOIC-14, is stubbed rather than given an unrelated model or left ambiguous. Names that merely share a prefix with a controller family (the MAX3232 and MAX3221 RS-232 transceivers, nRF24L01 radios) are not treated as controllers.
• A library match by MPN or value, or a model you imported, always wins over a stub, and so does your own Model Doctor choice. Choosing Interactive pins in the Model Doctor replaces the supply load with the pin panel, and the part then draws nothing.
• The currents are one working figure per family (an ESP32 at 100 mA is its Wi-Fi receive current, an ATmega at 10 mA is 16 MHz at 5 V), not the part's worst case. A lit WS2812B draws up to 60 mA; the stub is its 1 mA idle current, so add the lit load as a bench current load if it matters. See the model library for every figure and its source.

What you see, and what to do

Each part shows a status in the Parts panel and, if it needs attention, in the Model Doctor:

Status	Dot	Meaning
OK	green	Modeled, or intentionally open (connector)
Open by design	grey	A documented part with no meaningful model
Stubbed (shown as "placeholder" in the Model Doctor)	amber	You stubbed it open/short/interactive, or an automatic rule modeled it as a supply-load stub
No model	red	Nothing matched, needs your attention

A diode or LED on a JLCPCB / EasyEDA footprint, with no schematic to name its pins, has a green dot (it has a model), but its footprint name cannot say which pad is the anode: circsim simulates it with KiCad's default and names it in the sim log with a pinmap-unverified: polarity warning when the board opens. See the diode-polarity trap.

A red "no model" part contributes nothing to the simulation and appears in the fidelity banner. The Model Doctor is where you fix it: import a .lib, get one from an LLM and validate it against ngspice, stub it, or set an interactive-pin panel. Imported and LLM-written models are treated as code: circsim refuses any model carrying a control block or a file include.

Related

• Model library reference: the full list of built-in parts.
• Pin-map precedence: how circsim decides which pad is which terminal (and the JLC/EasyEDA diode-polarity story).
• Fix an unresolved part: the hands-on workflow.