1 files changed, 56 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..da5996c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# kisim — run KiCad schematics 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`,
+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)
+- `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.
+
+## Notes
+
+- `results/*.raw` and regenerated `results/*.cir` files are gitignored; they
+  are rebuilt by running the sims.
+- Initially developed for the ASPECT+ payload board sims (2026).