velxio/docs/wiki/circuit-emulation-performance.md

# Performance Analysis

Measurements on WSL2 / Ubuntu 22.04 / Node.js 22.22.2 / Intel i7-12700.

## Full suite

```
Test Files  14 passed (14)
Tests       47 passed (47)
Duration    ~5 s total (wall clock)
            ~8 s user+sys CPU time
```

Breakdown by file (rounded):

| Suite | Tests | Duration |
|---|---|---|
| `avr_blink.test.js` | 2 | 2.4 s |
| `spice_transient.test.js` | 2 | 630 ms |
| `spice_555_astable.test.js` | 1 | 610 ms |
| `spice_active.test.js` | 6 | 600 ms |
| `spice_digital.test.js` | 4 | 420 ms |
| `spice_avr_mixed.test.js` | 3 | 800 ms |
| `spice_passive.test.js` | 3 | 360 ms |
| `spice_ac.test.js` | 2 | 340 ms |
| `ngspice_smoke.test.js` | 1 | 370 ms |
| `diodes.test.js` | 7 | 15 ms |
| `passive.test.js` | 11 | 10 ms |
| `e2e_pot_pwm_led.test.js` | 1 | 90 ms |
| `e2e_thermistor.test.js` | 1 | 120 ms |
| `transient_rc.test.js` | 3 | 25 ms |

Observations:

- **`avr_blink.test.js` dominates** (2.4 s of 5 s total). This is because it runs 2 × 2 seconds of real AVR time at 16 MHz = 32 M cycles per test, executed by `avr8js` in JavaScript. Nothing to optimise — that's the entire point of the test.
- **Hand-rolled MNA tests are essentially free** (passive: 10 ms for 11 tests, diodes: 15 ms for 7). A single `solveDC()` takes < 1 ms.
- **ngspice tests are dominated by the 400 ms first-boot cost**, which is paid once per test process. Each subsequent `runSim()` is 5–500 ms.
- **`spice_transient.test.js` costs 630 ms** largely because the RLC ringing test runs 30 ms of transient at 10 µs step = 3000 points with an inductor requiring fine integration.

## Per-analysis benchmarks (ngspice)

One-off timings for common patterns. Boot cost of 400 ms amortized over all runs in a process.

| Analysis | Circuit | Points | Time |
|---|---|---|---|
| `.op` | 3 R + 1 V | 1 | 5–10 ms |
| `.op` | 1 D + 1 R + 1 V | 1 | 20–30 ms |
| `.op` | 1 BJT + 3 R + 1 V | 1 | 50–80 ms |
| `.op` | 1 MOSFET-L1 + 1 R + 1 V | 1 | 40–60 ms |
| `.tran 10u 3m` | RC filter | 300 | 100–150 ms |
| `.tran 10u 30m` | RLC ringing | 3000 | 450 ms |
| `.tran 0.1m 40m` | Bridge rectifier (4 diodes) | 400 | 280 ms |
| `.tran 0.5u 2m` | Relaxation oscillator | 4000 | 600 ms |
| `.ac dec 20 10 1Meg` | RC low-pass | 100 | 8–12 ms |
| `.ac dec 30 10 1Meg` | LC bandpass | 150 | 10–15 ms |

## Hand-rolled MNA benchmarks

For the trivially small circuits we target (< 20 nodes):

| Operation | Time |
|---|---|
| `solveDC()` — 4 linear components | < 0.5 ms |
| `solveDC()` — 4 diodes + 3 R (Newton, 6 iterations) | ~3 ms |
| `solveTransient` — RC, 600 steps | ~20 ms |
| `solveTransient` — 4-diode bridge rectifier, 400 steps | *not implemented (no inductor, and BJT/diode-heavy circuits not profiled)* |

At larger circuit sizes (50+ nodes), the dense Gaussian elimination becomes quadratic and eventually uncompetitive with ngspice's sparse solver. For Velxio's expected circuit sizes (≤ 30 nodes in typical hobby circuits), hand-rolled is competitive with ngspice on DC but loses on transient.

## Memory footprint

| Pipeline | On-disk (npm install) | Runtime heap |
|---|---|---|
| Hand-rolled MNA | ~0 (no extra deps) | trivial |
| `avr8js` shared harness | ~1.5 MB | a few MB for CPU + SRAM + listeners |
| `eecircuit-engine` | **39 MB** | ~15–20 MB when booted (WASM linear memory) |

**Velxio production impact**: adding ngspice-WASM grows the browser bundle by 39 MB (the WASM is bundled inside the JS module). Unacceptable as a hard dependency for every page load; tolerable behind a lazy-loaded "⚡ Electrical simulation" feature flag. The user clicks to activate; the browser fetches, caches, and initializes; ~400 ms later they can simulate.

## Scalability projections

Rough extrapolation of ngspice to larger circuits (based on ngspice's sparse solver being `O(n^1.2)` ish for well-conditioned circuits):

| # nodes | Expected `.op` time | Expected `.tran` (1000 steps) |
|---|---|---|
| 10 | 5 ms | 100 ms |
| 30 | 15 ms | 300 ms |
| 100 | 60 ms | 1.5 s |
| 300 | 300 ms | 8 s |

In Velxio, the expected typical circuit has 10–30 components. Each component contributes 1–3 nodes (most are 2-terminal). So 20–90 nodes. We are firmly in the sub-second-per-simulation zone.

For the Velxio UI to feel responsive, one `solveDC()` should complete in < 100 ms. That is the budget for a real-time "update voltages overlay" flow.

## Co-simulation overhead

`AVRSpiceBridge.run(10, buildNetlist)` runs 10 slices. Per slice:

| Phase | Time |
|---|---|
| `avr.runCycles(16000)` (1 ms of AVR) | ~3 ms in JS |
| Build netlist string | < 1 ms |
| `runNetlist()` (ngspice `.tran 10u 1m`) | 40–100 ms |
| Inject ADC voltage | < 1 ms |
| Per-slice total | 45–105 ms |

For 1 simulated second of real AVR time: 1000 slices × ~70 ms = **~70 seconds wall-clock**. That's a 70× slowdown. Acceptable for test scenarios; **too slow for live interactive use** in Velxio.

### Mitigations for live use in Velxio

1. **Larger slices**: 10 ms instead of 1 ms → 7× fewer ngspice calls. OK if the analog network's time constants are > 10 ms.
2. **Don't solve the analog circuit unless pins changed**: debounce `onPinChange` 50 ms; only `runNetlist` when the user moves a knob or the AVR toggles a pin.
3. **DC-only mode by default**: `.op` is ~10× faster than `.tran`. Only escalate to `.tran` when the user asks for a waveform view.
4. **Cache netlists**: if the component graph hasn't changed, reuse the previous netlist and only change the source values. Avoids string manipulation overhead.
5. **Web Worker**: move ngspice to a worker so the main thread stays responsive while simulations run.

With all mitigations, target: **< 100 ms of added simulation latency** per UI interaction.

## Solver comparison on the same problem

Voltage divider, V=9 V, R1=1k, R2=2k, R3=3k (parallel with R2):

| Solver | Wall-clock | Notes |
|---|---|---|
| Hand-rolled MNA | 0.4 ms | dense matrix |
| ngspice (first call) | 410 ms | includes 400 ms boot |
| ngspice (warm) | 8 ms | singleton reused |

RC charging, 1 ms of transient at 10 µs step (100 points):

| Solver | Wall-clock | Notes |
|---|---|---|
| Hand-rolled MNA | 3 ms | backward Euler |
| ngspice | 20 ms | trapezoidal default |

LED @ 220 Ω, 5 V (non-linear, 5 Newton iters):

| Solver | Wall-clock | Notes |
|---|---|---|
| Hand-rolled MNA | 2 ms | pnjlim + damping |
| ngspice | 35 ms | model setup + solve |

## What's fast and what's slow (rule of thumb)

**Fast** (≤ 10 ms):
- Hand-rolled `.op` on < 20 linear components
- ngspice `.op` on linear circuit
- ngspice `.ac` on linear circuit

**Medium** (10–100 ms):
- ngspice `.op` on 1–3 non-linear devices
- ngspice `.tran` on < 500 time points, passive only

**Slow** (100 ms – 1 s):
- ngspice `.tran` with non-linear devices and > 1000 time points
- ngspice oscillator simulations (need many cycles)

**Always slow** (> 1 s):
- `avr8js.runCycles(N)` where N > 10 million — this is the MCU side, not the analog side

## Optimizing a netlist

1. **Widen timesteps**. `.tran 1m 100m` with no fast edges will be fast. Add fast rise/fall times → slow.
2. **Avoid false non-linearity**. A comparator modeled with a B-source using `u()` is fast. A comparator modeled with a real op-amp macro is slow.
3. **Prefer `.op` over `.tran`** whenever the analysis doesn't need time-domain information.
4. **Remove unused components**. An unused LED model with temperature params slows down every iteration.
5. **Set `.options abstol=1n reltol=1m`** if you don't need 10-ppm accuracy — default tolerances are tight.