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

# Test Catalog — All 47 Tests

Every test in [`test/test_circuit/test/`](../../test/test_circuit/test/) enumerated: the circuit under test, what physics it validates, and the numerical expectation.

## Baseline — hand-rolled MNA solver (25 tests)

### `passive.test.js` — 11 tests

Tests the linear DC solver on textbook passives.

| # | Test | Circuit | Expected | Tolerance |
|---|---|---|---|---|
| 1 | Voltage divider | 9V → 1k + 2k | V(out) = 6.0 V | 3 decimals |
| 2 | Equal-R divider | 5V → 1k + 1k | V(b) = 2.5 V | 3 decimals |
| 3 | Ohm's law | 5V, 220Ω | I = 22.7 mA | 5 decimals |
| 4 | Three 3kΩ parallel | series with 1k | V(p) = 1.5 V | 3 decimals |
| 5 | Current source + R | 1 mA into 2.2kΩ | V = 2.2 V | 3 decimals |
| 6 | Pot wiper at 50% | 10k pot, 5V | V = 2.5 V | 2 decimals |
| 7 | Pot sweep 0→1 | 5 steps | monotonic increase | ≥ −10 mV slack |
| 8 | NTC resistance @ 25°C | β=3950 | R = 10 000 Ω | within 1 Ω |
| 9 | NTC temperature monotonicity | T ∈ {0, 25, 50} | R(0) > R(25) > R(50) | textbook ranges |
| 10 | NTC + 10k divider | T ∈ {0, 25, 50} | V_A0 matches expected per table | per-point tolerance |
| 11 | Switch open/closed | 5V → 1k → switch → GND | open: 4.9–5.0 V, closed: < 50 mV | |

### `transient_rc.test.js` — 3 tests

| # | Test | Circuit | Expected | Tolerance |
|---|---|---|---|---|
| 1 | RC charging @ τ | 10k, 100µF, 5V | V(τ) ≈ 3.16 V | ±5% |
| 2 | 5τ settling | 1k, 1µF, 3.3V | V(5τ) > 99% V | hard bound |
| 3 | Capacitor discharge | pre-charged 5V → 10k | V(τ) in [1.5, 2.2] V | manual bounds |

### `diodes.test.js` — 7 tests

| # | Test | Circuit | Expected |
|---|---|---|---|
| 1 | Forward diode + 1k + 5V | Shockley default | V_d ∈ [0.55, 0.75] V, I ∈ [4, 5] mA |
| 2 | Reverse diode | diode blocks | V_a < 10 mV |
| 3 | Red LED + 220Ω + 5V | | V_f ∈ [1.8, 2.3] V, I ∈ [10, 16] mA, brightness > 0.5 |
| 4 | Blue LED higher Vf than red | | V_blue > V_red, V_blue ∈ [2.8, 3.6] V |
| 5 | LED brightness with supply | V ∈ {2.0, 3.0, 5.0} | monotonic, dim at 2V, bright at 5V |
| 6 | BJT switch ON | V_b = 5V, R_b = 10k | V_CE < 0.8 V |
| 7 | BJT switch OFF | V_b = 0 | V_CE > 4.9 V |

### `avr_blink.test.js` — 2 tests

Uses the real `fixtures/blink.hex` (copied from Velxio's test fixtures).

| # | Test | What it validates |
|---|---|---|
| 1 | Toggles pin 13 | After 2 s of AVR time, observed ≥ 3 edge transitions on D13; both 0 and 1 states visible |
| 2 | Drives simulated LED | Pin-13 voltage fed into a `VoltageSource`, 220 Ω + red LED; LED brightness switches between < 1% and > 50% |

### `e2e_pot_pwm_led.test.js` — 1 test

Uses `potToPwmProgram()` (hand-assembled: reads A0, writes to OCR0A for PWM on D6).

Circuit: `+5V → pot (10k) → A0 / GND` plus `D6 → 220Ω → red LED → GND`.

Sweep wiper 0.0 → 0.25 → 0.50 → 0.75 → 1.00:

| Wiper | V_A0 | PWM duty | I_LED | Brightness |
|---|---|---|---|---|
| 0.00 | 0.000 V | 0.0 % | 0.00 mA | 0.000 |
| 0.25 | 1.250 V | 24.7 % | 0.00 mA | 0.000 |
| 0.50 | 2.500 V | 49.8 % | 3.26 mA | 0.163 |
| 0.75 | 3.750 V | 74.9 % | 8.77 mA | 0.439 |
| 1.00 | 5.000 V | 100.0 % | 14.38 mA | 0.719 |

Assertions: duty at 0% < 5%, duty at 100% > 90%, brightness monotonic, final > 0.5, initial < 0.05.

### `e2e_thermistor.test.js` — 1 test

Uses `adcReadProgram()` + NTC + pullup divider.

Circuit: `+5V → 10kΩ → A0 → NTC → GND`.

Per temperature T ∈ {0, 15, 25, 35, 50} °C:

| T_set | V_A0 | ADC raw | R_ntc (true) | R_meas (recovered) | T_meas |
|---|---|---|---|---|---|
| 0 °C | 3.854 V | 789 | 33 621 Ω | 33 718 Ω | −0.05 °C |
| 15 °C | 3.065 V | 627 | 15 837 Ω | 15 833 Ω | 15.01 °C |
| 25 °C | 2.500 V | 511 | 10 000 Ω | 9 980 Ω | 25.04 °C |
| 35 °C | 1.971 V | 403 | 6 506 Ω | 6 500 Ω | 35.02 °C |
| 50 °C | 1.320 V | 270 | 3 588 Ω | 3 586 Ω | 50.02 °C |

Assertion: `|T_meas − T_set| < 1 °C` at every point. Achieved: < 0.05 °C.

## ngspice — `spice_*.test.js` (22 tests)

### `ngspice_smoke.test.js` — 1 test

The minimal possible smoke test.

| # | Test | Netlist | Expected |
|---|---|---|---|
| 1 | Boot + voltage divider | `V 9 → R 1k → R 2k → GND, .op` | `V(out) = 6.0` |

### `spice_passive.test.js` — 3 tests

All run with `.op`:

| # | Circuit | Expected |
|---|---|---|
| 1 | 9V → 1k + 2k | V(out) = 6 V |
| 2 | Three 3kΩ parallel + 1k series from 3V | V(p) = 1.5 V |
| 3 | 1 mA current source into 2.2kΩ | V(a) = 2.2 V |

### `spice_transient.test.js` — 2 tests

| # | Test | `.tran` | Expected |
|---|---|---|---|
| 1 | RC charging | 10m 3 | V(τ) ≈ 3.16 V, V(5τ) > 90% |
| 2 | RLC underdamped oscillation | 10u 30m, R=1Ω, L=10mH, C=10µF | zero-crossings imply f ≈ 503 Hz, ±15 % |

### `spice_ac.test.js` — 2 tests

| # | Test | `.ac` | Expected |
|---|---|---|---|
| 1 | RC low-pass Bode | 20 ppd, 10 Hz – 1 MHz | f₋₃dB ∈ [900, 1100] Hz; low-freq gain ≈ 0 dB; −20 dB/decade rolloff; phase @ cutoff ≈ −45° |
| 2 | Parallel-tank RLC bandpass | 30 ppd, 10 Hz – 1 MHz | peak near 5033 Hz (±20%), passive so max gain ≈ 0 dB; 10×f₀ rejection > 15 dB below peak |

### `spice_active.test.js` — 6 tests

| # | Test | Analysis | Expected |
|---|---|---|---|
| 1 | Diode forward (1N4148 model) | `.op` | V_a ∈ [0.55, 0.80] V |
| 2 | Bridge rectifier (4 diodes + sine 6V/50Hz) | `.tran 0.1m 40m` | peak output 4.2–5.4 V, always positive |
| 3 | Common-emitter amp (2N2222, 12V, ~1kHz input, bypassed R_E) | `.tran 10u 6m` | voltage gain > 30 |
| 4 | N-MOS Level-1 switch, V_gate=5V | `.op` | V(drain) < 1.0 V |
| 5 | N-MOS Level-1 off, V_gate=0 | `.op` | V(drain) > 4.9 V |
| 6 | Op-amp inverting amp (E-source, R_in=1k, R_f=10k) | `.op` | V(out) ≈ −2.0 V |

### `spice_digital.test.js` — 4 tests

All gates implemented with B-sources using `u()` step function.

| # | Gate | Rows tested |
|---|---|---|
| 1 | AND | 4 (truth table) |
| 2 | NAND | 4 |
| 3 | XOR | 4 |
| 4 | AND → RC low-pass | `.tran 10u 20m` — verifies filter ripple < 1.5 V, raw AND swings 0–5 V, filtered mean in (0, 5) |

### `spice_555_astable.test.js` — 1 test

RC relaxation oscillator built from a Schmitt-switch (S-element with hysteresis).

- R = 10 kΩ, C = 10 nF
- `SMOD: Vt=2.5, Vh=0.833, Ron=100, Roff=1G`
- `.tran 0.5u 2m`

Expected: output toggles, ≥ 3 rising edges detected in the steady-state window; measured frequency between 500 Hz and 50 kHz (wide range because behavioral model differs from ideal 555 math).

Typical measured: ~7 kHz.

### `spice_avr_mixed.test.js` — 3 tests

The flagship mixed-signal demonstrator.

#### Test 1 — NTC → ngspice → ADC → sketch

For each T ∈ {0, 25, 50} °C:
1. ngspice `.op` solves `10k pullup + R_ntc(T)`
2. `avr.setAnalogVoltage(0, V(a0))`
3. `avr.runCycles(500_000)` runs `adcReadProgram()`
4. Read `ADCH/ADCL` registers directly → reconstruct 10-bit result

Expected results match textbook within ±5 LSB:

| T | V(a0) from ngspice | ADC raw from avr8js |
|---|---|---|
| 0 °C | 3.854 V | 789 |
| 25 °C | 2.500 V | 512 |
| 50 °C | 1.320 V | 270 |

#### Test 2 — Sketch → PWM → ngspice RC → filtered DC

For V_A0 ∈ {1.0, 2.5, 4.0} V:
1. Run `potToPwmProgram()` with the given analog voltage
2. Read PWM duty (must match `V_A0 / 5` ± 0.05)
3. Feed `duty × 5` as DC source into `R=10k, R_load=10MΩ` in ngspice
4. `.op` gives filtered DC output — should match duty × 5 within 0.1 V

Measured:

| V_A0 | duty | V_filt | expected |
|---|---|---|---|
| 1.0 V | 20.0 % | 0.999 V | 1.00 V |
| 2.5 V | 50.2 % | 2.507 V | 2.51 V |
| 4.0 V | 80.0 % | 3.996 V | 4.00 V |

#### Test 3 — Co-simulation loop (AVRSpiceBridge)

The bridge runs the AVR in 1 ms slices, re-solving ngspice between each. Pot wiper is moved mid-test.

- wiper = 0.25 → 5 slices run → expected ADC ≈ 256 (0.25 × 1023). Measured: **256**. Tolerance ±20 LSB.
- wiper moves to 0.75 → 5 more slices → expected ADC ≈ 767. Measured: **768**.

Demonstrates that ngspice + avr8js can be cleanly co-simulated quasi-statically.

## Pass/fail history

All 47 tests passed as of 2026-04-15. Running `npm test` from `test/test_circuit/` is the canonical verification. Expected wall-clock: ~5 seconds on an i7.

Full command output:

```
 ✓ test/ngspice_smoke.test.js        (1 test)  372ms
 ✓ test/spice_passive.test.js        (3 tests) 358ms
 ✓ test/spice_transient.test.js      (2 tests) 629ms
 ✓ test/spice_ac.test.js             (2 tests) 340ms
 ✓ test/spice_active.test.js         (6 tests) 600ms
 ✓ test/spice_digital.test.js        (4 tests) 420ms
 ✓ test/spice_555_astable.test.js    (1 test)  609ms
 ✓ test/spice_avr_mixed.test.js      (3 tests) 800ms
 ✓ test/passive.test.js             (11 tests)   8ms
 ✓ test/transient_rc.test.js         (3 tests)  22ms
 ✓ test/diodes.test.js               (7 tests)  15ms
 ✓ test/avr_blink.test.js            (2 tests) 2400ms
 ✓ test/e2e_pot_pwm_led.test.js      (1 test)   90ms
 ✓ test/e2e_thermistor.test.js       (1 test)  121ms

 Test Files  14 passed (14)
 Tests       47 passed (47)
 Duration    ~5 s
```