Circuit simulator — /tools/circuit-sim/ on embeddedera.com¶
Owner request 2026-11-11: our own browser circuit simulator, built by us (not a copy). Lives in the
embeddedera-site repo (Astro, vanilla TS, workers already used by the impedance tool). EN + ES.
Decisions¶
- 2026-11-11 Owner: option A — our own solver (modified nodal analysis, textbook method) in TypeScript, running in a Web Worker. Option B (ngspice compiled to WebAssembly, "accurate check" / vendor .lib models) comes later. Rule 1 reason for building: live interactive animation is the product; ngspice is batch-only. Falstad CircuitJS is GPL — never read or copy its code (clean room).
- 2026-11-11 Owner: both modes — Live (real-time animation) and Run & plot, same engine.
Modes¶
- Live: solver steps in real time; moving current dots, wires coloured by voltage, click switches, drag pot/source sliders, meters update, LEDs glow, scope traces scroll. Speed slider (slow-motion for RC).
- Run & plot: transient to a stop time, DC sweep (e.g. diode I-V, transistor curves), AC sweep (Bode gain/phase). Probe any node/part, plot, export CSV.
Parts catalogue (tiers = phase they land in)¶
| Group | Parts | Phase |
|---|---|---|
| Sources | ground, DC voltage, DC current, battery (V + internal R), rail label | 1 |
| Sources | AC sine, function generator (square/pulse/triangle/sawtooth) | 2 |
| Sources | controlled sources VCVS/VCCS/CCVS/CCCS | 6 |
| Passives | resistor, potentiometer, lamp | 1 |
| Passives | capacitor, electrolytic (polarity warning), inductor | 2 |
| Passives | transformer (coupled inductors), fuse, thermistor, LDR, crystal | 6 |
| Switches | SPST, SPDT, push button (momentary) | 1 |
| Switches | DPDT, relay (coil + contacts) | 6 |
| Diodes | diode, LED (colours, glows), | 1 |
| Diodes | Zener, Schottky, bridge rectifier | 3 |
| Transistors | NPN, PNP (Ebers-Moll), N/P MOSFET (level-1 square law) | 3 |
| Transistors | JFET, SCR/triac | later |
| ICs | op-amp (ideal + real: rails, slew, GBW), comparator | 4 |
| ICs | 555 timer, linear regulator / LDO (behavioural) | 4 |
| ICs | logic gates / mixed digital | later |
| Instruments | voltmeter, ammeter, ohmmeter, probe | 1 |
| Instruments | oscilloscope (2–4 ch) | 2 |
| Outputs | buzzer/speaker (Web Audio), DC motor, 7-segment | 6 |
Architecture¶
src/lib/sim/pure TS engine, no deps: sparse matrix + LU, Newton–Raphson with damping and gmin / source stepping, backward Euler → trapezoidal with adaptive step, small-signal AC with complex numbers.- Each part = one module:
stamp(matrix, state)+nonlinear?+draw()+props. Adding a part never touches the engine. - Circuit = JSON netlist; saved in the URL for share links; export SPICE netlist (KiCad users).
- Editor: SVG grid canvas, place/drag/wire/rotate/undo, property panel. Phone = view and tweak only.
- Look: site
schematic.css(voltage-coloured wires already approved on /tools/voltage-divider).
Test oracle¶
Every part ships with golden circuits whose results must match ngspice (≤0.1 % DC, ≤1 % transient/AC).
ngspice is not installed on the server (no sudo apt); phase 0 picks: ngspice WASM npm package run in
Node, or a ngspice Docker image. Oracle runs in local tests, not in the browser.
Phases (each ends: oracle tests pass + live sandbox preview checked)¶
- Spike (~2 days): engine core, R/V/I, DC operating point, oracle harness. Stop gate: if Newton convergence is shaky, re-plan before the editor.
- Editor + Live mode, DC: phase-1 parts above. Already useful (LED resistor, divider, switches).
- Time: C, L, AC/function sources, scope, Run & plot transient. First public release (RC/RL).
- Semis: Zener/Schottky/bridge, BJT, MOSFET; DC sweep plots (I-V curves).
- ICs: op-amp, comparator, 555, regulator.
- AC sweep / Bode.
- Extras from the table; example-circuit pages (SEO); "Open in simulator" from existing calculators. Later: option B (ngspice WASM) as "accurate check" + vendor models.
Risks¶
Nonlinear convergence (transistors, diodes in loops); stiff transients; editor UX on touch; scope creep — the table is the scope, new parts go in a phase, not into the current one.
Open¶
- Build in progress (2026-11-11): branch
circuit-sim(worktree ~/embeddedera-site-sim, contract types.ts/catalog.ts/netlist.ts/units.ts + tests). Helpers: engine = Codex (worktree ~/embeddedera-site-sim-engine, codex-worker, attended single job — SOP-025 forbids the full-access launcher for parallel unattended writes), editor+page = Sonnet (~/embeddedera-site-sim-editor), io/report/examples = Sonnet (~/embeddedera-site-sim-io). Next: merge all three into circuit-sim, swap stubs, unlisted preview viagh workflow run deploy.yml --ref circuit-sim. Never merge to main without owner.
Log¶
- 2026-11-11 Plan written; owner chose option A, Live + Run & plot.
- 2026-11-11 Owner: go — build an unlisted preview with helpers (sub-sessions/Codex), brand match, import/export, saved circuits and a report. Scope of first preview: all 27 catalogue parts, Live + transient/DC/AC plots, .json import/export, share link, SPICE export, PNG/SVG, CSV, printable report (Save as PDF), My circuits (localStorage), 12 examples.