From abe94972619bcd48fa928ccefdff9a814971a5a5 Mon Sep 17 00:00:00 2001
From: Vaino Kauppila <vaino@vke.fi>
Date: Sun, 11 Oct 2026 15:21:53 +0300
Subject: examples: runnable RC low-pass demo on a plain netlist (no KiCad)

rc_lp.cir + rc_lp.py: 5 V step into 1k + 100n, prints V(out) at one
time constant and writes a plot. README updated for netlist support;
results/ output dir ignored.
---
 .gitignore         |  3 ++-
 README.md          | 23 ++++++++++++++++++-----
 examples/rc_lp.cir |  5 +++++
 examples/rc_lp.py  | 25 +++++++++++++++++++++++++
 4 files changed, 50 insertions(+), 6 deletions(-)
 create mode 100644 examples/rc_lp.cir
 create mode 100644 examples/rc_lp.py

diff --git a/.gitignore b/.gitignore
index f1619f6..45d0a97 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
-# ngspice output — regenerate by running the sims
+# simulation output — regenerate by running the sims
+results/
 *.raw
 *.raw.tmp
 
diff --git a/README.md b/README.md
index da5996c..b44856e 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,9 @@
-# kisim — run KiCad schematics in ngspice from Python
+# 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`,
+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
@@ -26,7 +27,8 @@ 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)
+- `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
@@ -49,8 +51,19 @@ r.plot(["+28V", "i(V1)", "Q2:power"])
 using for big vendor models, where thousands of internal nodes make huge, slow
 raw files.
 
+## Example
+
+`examples/` is a small runnable demo:
+
+- `rc_lp.cir` — a plain ngspice netlist: 5 V step into 1 kΩ + 100 nF
+- `rc_lp.py` — runs it with kisim and plots V(in)/V(out)
+
+```sh
+micromamba run -n kicad_work python examples/rc_lp.py
+```
+
 ## Notes
 
-- `results/*.raw` and regenerated `results/*.cir` files are gitignored; they
-  are rebuilt by running the sims.
+- `results/` directories (sim output, plots) are gitignored; rebuilt by running
+  the sims.
 - Initially developed for the ASPECT+ payload board sims (2026).
diff --git a/examples/rc_lp.cir b/examples/rc_lp.cir
new file mode 100644
index 0000000..58d1f57
--- /dev/null
+++ b/examples/rc_lp.cir
@@ -0,0 +1,5 @@
+* RC low-pass: 5 V step into 1 kohm + 100 nF
+V1 vin 0 PWL(0 0 1n 5)
+R1 vin vout 1k
+C1 vout 0 100n
+.end
diff --git a/examples/rc_lp.py b/examples/rc_lp.py
new file mode 100644
index 0000000..0a79b60
--- /dev/null
+++ b/examples/rc_lp.py
@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""Example: run a plain ngspice netlist with kisim -- no KiCad involved.
+
+    micromamba run -n kicad_work python examples/rc_lp.py
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import numpy as np
+
+from kisim import KiSim
+
+sim = KiSim("rc_lp.cir", tran="1u 2m")   # .cir input: used as-is, no kicad-cli
+r = sim.run()                            # -> results/run.cir + run.raw (cached)
+
+tau = 1e3 * 100e-9                       # R1 * C1
+vout = r.v("vout")
+print(f"5 V step into 1 kohm + 100 nF: tau = {tau * 1e6:.0f} us")
+print(f"V(vout) at 1 tau: {np.interp(tau, r.t, vout):.3f} V   (1 - 1/e of 5 V)")
+print(f"V(vout) settled:  {vout[-1]:.3f} V")
+
+r.plot(["vin", "vout"], title="RC low-pass: 5 V step", file=sim.workdir / "rc_lp.png")
+print("plot:", sim.workdir / "rc_lp.png")
-- 
cgit v1.3