Simulation

Embedr can simulate a circuit described in a .zen file with ngspice: check a filter's cutoff, an LED's current, a divider's output or a regulator's ripple before layout, and keep that check in the project to run again after every change.

How it works

1. A .zen file declares a Simulation(name, setup) block. The setup adds sources and an ngspice .control section with the analyses, measurements and plots you want.
2. You ask the agent to simulate it. The row reads SPICE simulation ("Running ngspice simulation").
3. Embedr turns the file's parts into a SPICE netlist, runs ngspice, and returns the ngspice output with a pass or fail result.
4. Plots and tables the control section writes are saved in your project, next to the .zen file.

You can ask the agent to write the simulation for you:

Add a simulation for the RC filter in pcb/bench/rc_filter.zen: AC sweep from 1 Hz to 1 MHz,
measure the -3 dB point, fail if it is outside 1.4–1.8 kHz, and plot the response to output/.

Simulate pcb/bench/led_driver.zen and tell me the LED current at 3.3 V and 5 V.

What can be simulated

Every part in the simulated file needs a SPICE model:

• The standard generic parts carry their own: resistors, capacitors, inductors, ferrite beads, LEDs, crystals and net ties.
• A KiCad symbol with simulation properties (Sim.Library, Sim.Name, Sim.Device, Sim.Pins) supplies one.
• For anything else, point the component at a model file in your project, for example models/part.lib.

A part without a model stops the run with "Components missing a SpiceModel". Give it a model, mark it do-not-populate, or simulate a smaller file that leaves it out. A separate bench file next to your board is the usual way to simulate one section of a design.

Only files with a Simulation(...) block simulate. The agent simulates the main board file unless you name another file.

Example

pcb/bench/rc_filter.zen:

Resistor = Module("@stdlib/generics/Resistor.zen")
Capacitor = Module("@stdlib/generics/Capacitor.zen")

VIN = Net()
VOUT = Net()
GND = Ground()

Resistor(name="R1", value="10kohm", P1=VIN, P2=VOUT)
Capacitor(name="C1", value="10nF", P1=VOUT, P2=GND)

Simulation(
    name="rc_lowpass",
    setup=f"""
V1 {VIN} {GND} DC 0 AC 1
.control
  ac dec 100 1 1Meg
  meas ac f3db when vdb({VOUT})=-3
  if f3db < 1400 or f3db > 1800
    echo "FAIL: cutoff $&f3db Hz"
    quit 1
  end
  echo "PASS: cutoff $&f3db Hz"
  set hcopydevtype = svg
  hardcopy output/rc_response.svg vdb({VOUT}) title "RC response"
.endc
""",
)

• Nets are referenced with {...} inside the setup text, so {VOUT} becomes the real net name.
• Analyses: op (operating point), dc (sweep), ac (frequency response) and tran (transient).
• meas extracts a number; echo prints it to the output.
• quit 1 inside an if turns a measurement into a pass/fail check: the run is reported as failed.
• hardcopy writes an SVG plot, relative to the .zen file's folder. Keep outputs in a small folder such as output/.
• Write values ngspice understands, such as 2meg rather than 2M (in SPICE, M means milli).

After a run, the project looks like this:

pcb/
  bench/
    rc_filter.zen
    output/
      rc_response.svg

What you get

• Pass or fail. "Simulation passed" or "Simulation failed" for the file. A run fails when ngspice reports an error or a quit 1 check triggers.
• The ngspice output. Every echo and measurement, which the agent reads back to you.
• Files. Plots (SVG or PNG) and tables (CSV or TXT) the control section created or changed, listed under "Outputs written by the control block". Open them from the file tree.
• Plots for the agent. On desktop the agent looks at up to six plots as images, so it can comment on curves as well as numbers.

A passing simulation covers the circuit as modelled: ideal sources, no parasitics and no layout effects. It is not a layout or manufacturing check.

Local ngspice or the cloud

On desktop, Settings → Local tools → Where tools run → SPICE simulation has two options:

• Local when available (default): use ngspice on this computer when it is installed, otherwise the cloud.
• Always cloud: always simulate in the cloud.

Install ngspice to simulate locally:

System	Install
macOS	brew install ngspice
Linux	sudo apt install ngspice
Windows	Download ngspice from ngspice.sourceforge.io and set the NGSPICE environment variable to ngspice.exe

Embedr finds ngspice on your PATH or in the usual install locations (/opt/homebrew/bin, /usr/local/bin, /usr/bin, C:\Program Files\ngspice\bin, C:\Spice64\bin).

Cloud simulation needs you to be signed in. Your pcb/ source is sent along with any SPICE model files under pcb/ (.lib, .sub, .cir, .mod, .spice, .inc, .txt), and the plots and tables come back into your project in the same place a local run would write them.

In the browser

In Embedr in the browser, simulations always run in the cloud. Plots are shown to you with the result and saved in the project. The agent reads the numbers from the ngspice output rather than from the plots, so ask for meas and echo lines for anything you want judged.

Plan Mode

The agent does not run simulations in Plan Mode. Switch back to agent mode to simulate.

Troubleshooting

Message	What to do
"… has no Simulation() setup; add one with a SPICE stimulus and .control block."	Add a Simulation(...) block to that file, or name the file that has one.
"Components missing a SpiceModel"	Give the part a model, mark it do-not-populate, or simulate a bench file without it.
"The SPICE simulation failed; see the ngspice output."	Read the output: a FAIL line from your checks, or an ngspice error such as an unknown net or bad value.
"The SPICE simulation timed out …"	ngspice is stopped after 5 seconds. Shorten transient runs (for example tran 10n 10u), reduce sweep points, and avoid loops.
"ngspice is not installed (…) and the simulation worker needs a signed-in session."	Install ngspice, or sign in to simulate in the cloud.
"Simulations are set to run in the cloud (Settings → Local tools), and the simulation worker needs a signed-in session."	Sign in, or switch SPICE simulation to Local when available.
"SPICE simulation is unavailable in this run"	The cloud simulator could not be reached for this run. Try again later, or run it in the desktop app with ngspice installed.
"An initialized project pcb workspace is required."	Ask the agent to initialize the PCB workspace first. See Schematics and PCB.
"filePath must be an existing .zen file inside the project pcb workspace."	Point at a .zen file under pcb/.