# kisim — run KiCad schematics or plain netlists in ngspice from Python

`kisim.py` is a single-file simulation framework with no project knowledge. It:

1. exports a `.kicad_sch` to a SPICE netlist with `kicad-cli` (or takes a plain
   ngspice netlist — `.cir`/`.spice`/`.net` — and uses it as-is),
2. edits the netlist (instance parameters, source waveforms, regex substitutions),
3. runs `ngspice -b`, and
4. hands the results back as numpy arrays addressed by the schematic's own net
   and device names — e.g. `r.v("+28V")`, `r.i("V1")`, `r.p("Q2")`, `r.at("i(v1)", 0.1)`.

It also carries test-case and worst-case helpers (`Case`, `run_cases`,
`corners`, `tol`, `Wave`, `stim`, `worst`) and caches runs keyed on the
generated netlist.

**The module docstring in `kisim.py` is the full API reference.**

## Environment

Everything runs in the `kicad_work` micromamba environment:

```sh
micromamba create -n kicad_work -f environment.yml
micromamba activate kicad_work
micromamba run -n kicad_work python my_sim.py
```

Required on the system (not in the env):

- `kicad-cli` — schematic → SPICE netlist export (KiCad ≥ 7; developed on 10.0.6).
  Only needed for `.kicad_sch` inputs.
- `ngspice` — the simulator (developed on ngspice-47)

## Usage

From a script in a project folder one level under this one:

```python
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from kisim import KiSim

sim = KiSim("my_sim.kicad_sch", tran="10u 400m")
r = sim.run()                       # -> results/run.cir + run.raw (cached)
print(r.v("+28V")[-1], r.i("V1").max())
r.plot(["+28V", "i(V1)", "Q2:power"])
```

`save=[...]`, `power=[...]` and `currents=` control what gets probed — worth
using for big vendor models, where thousands of internal nodes make huge, slow
raw files.

## Example

`examples/` is a small runnable demo — a 5 V step into an RC low-pass:

- `rc_lp.cir` — a plain ngspice netlist (1 kΩ, 100 nF)
- `rc_lp.py` — runs it; then sweeps R1/C1 tolerance corners of the step
  response (`corners` + `run_cases`), reading τ and the pole (f−3dB) off each
  transient; then cross-checks the transient results against the control
  model H(s) = 1/(1 + sRC) with `scipy.signal` — analytic step overlay, poles
  and a Bode plot

```sh
micromamba run -n kicad_work python examples/rc_lp.py
```

## Notes

- `results/` directories (sim output, plots) are gitignored; rebuilt by running
  the sims.
- Initially developed for the ASPECT+ payload board sims (2026).