wobbl 0.1.0__py3-none-any.whl

wobbl/__init__.py

@@ -0,0 +1,16 @@
+"""Wobbl: simulate anything before you build it.
+
+Wobbl turns a CAD file and a plain question ("will this motor mount crack under
+200 N?") into a verified engineering answer: it meshes the part, applies loads
+and materials, runs a real solver (CalculiX, ngspice), checks its own work and
+reports the number, a confidence level, the assumptions and a suggested fix.
+
+The package is layered the same way the work flows:
+
+    domain (what you ask)  ->  solver adapter (who computes it)
+        ->  verification (can we trust it)  ->  report (what you see)
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

wobbl/__main__.py

@@ -0,0 +1,4 @@
+from .cli.main import main
+
+if __name__ == "__main__":
+    main()

wobbl/ask.py

@@ -0,0 +1,177 @@
+"""Read a plain English question into a study, and say exactly what was assumed.
+
+"will this motor mount crack under 200 N?" is not enough to simulate; the
+loaded face, the direction and the supports are missing. Wobbl fills the gaps
+with the most common reading (bolted through the holes, load on the face
+farthest from them, pushing down) and prints every guess together with the
+exact command that would override it. Agents should pass structured flags.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .geometry.faces import PartFeatures
+from .materials import LIBRARY, get_material
+from .structural.spec import Fixture, Load, StructuralStudy, parse_fixture, parse_load
+from .units import parse_quantity
+
+_FORCE = re.compile(r"(\d+(?:\.\d+)?)\s*(kn|n|newtons?|lbf|lbs?|pounds?|kgf|kg|kips?)\b", re.I)
+_PRESS = re.compile(r"(\d+(?:\.\d+)?)\s*(mpa|kpa|psi|bar|pa)\b", re.I)
+_GRAV = re.compile(r"(\d+(?:\.\d+)?)\s*g'?s?\b(?!\w)", re.I)
+_SF = re.compile(r"safety factor (?:of |above |at least |>=? ?)?(\d+(?:\.\d+)?)", re.I)
+
+
+@dataclass
+class Reading:
+    domain: str = "strength"
+    guesses: list[str] = field(default_factory=list)
+    load: str | None = None
+    fixture: str | None = None
+    material: str | None = None
+    target_sf: float | None = None
+
+
+def detect_domain(question: str, path: str = "") -> str:
+    q = question.lower()
+    if path.lower().endswith((".cir", ".sp", ".spice", ".net")) or re.search(
+            r"\b(led|resistor|ripple|mosfet|regulator|buck|capacitor|circuit|volts?|amps?)\b", q):
+        return "circuit"
+    if re.search(r"\b(overheat|heat|hot|temperature|thermal|cool|watts?|\d+\s*w\b|celsius|°c)\b", q):
+        return "thermal"
+    return "strength"
+
+
+def find_material(question: str) -> str | None:
+    q = question.lower()
+    names = []
+    for m in LIBRARY.values():
+        for n in (m.key, *m.aliases, m.name.lower()):
+            if len(n) >= 3 and re.search(r"(?<![\w-])" + re.escape(n) + r"(?![\w-])", q):
+                names.append((len(n), m.key))
+    if names:
+        return max(names)[1]
+    if re.search(r"\b(3d[- ]?print|printed|fdm)\b", q):
+        return "pla"
+    if re.search(r"\bsteel\b", q):
+        return "mild-steel"
+    if re.search(r"\balumin", q):
+        return "6061-t6"
+    return None
+
+
+def _direction(q: str) -> str | None:
+    for words, d in ((r"\b(down|downward|downwards|pushing down|presses down|press down|weight|sits on|on top)\b",
+                      "down"), (r"\b(up|upward|upwards|lift|lifting|pull up)\b", "up"),
+                     (r"\b(sideways|side load|lateral)\b", "+x")):
+        if re.search(words, q):
+            return d
+    return None
+
+
+def read_question(question: str, features: PartFeatures, study: StructuralStudy) -> Reading:
+    """Fill the parts of ``study`` the user did not give explicitly, from the question and the geometry."""
+    r = Reading()
+    q = question.lower()
+    if study.material in (None, "", "auto"):
+        mat = find_material(q)
+        if mat is None:
+            mat = "6061-t6"
+            r.guesses.append("material not mentioned: assumed aluminum 6061-T6 (override with --material)")
+        r.material = mat
+        study.material = mat
+    m = _SF.search(q)
+    if m and study.target_sf is None:
+        study.target_sf = float(m.group(1))
+    if not study.fixtures:
+        fx = _guess_fixture(q, features)
+        r.guesses.append(f"supports not given: {fx[1]} (override with --fix)")
+        study.fixtures.append(parse_fixture(fx[0]))
+    if not study.loads:
+        ld = _guess_load(q, features, study)
+        if ld is None:
+            raise ValueError("the question has no load I can read. Say it like '200 N', '45 lbf', '3 g' or "
+                             "'0.2 MPa', or pass --load '200 N down @ top'")
+        r.guesses.append(f"load placement: {ld[1]} (override with --load)")
+        study.loads.append(parse_load(ld[0]))
+    return r
+
+
+def _guess_fixture(q: str, f: PartFeatures) -> tuple[str, str]:
+    holes = f.holes()
+    if re.search(r"\b(bolt|bolted|screw|screwed|mounted through|mounting holes?)\b", q) and holes:
+        d = _common_hole(holes)
+        return f"bolt holes d={d:.4g}", f"bolted through the {d:.3g} mm holes"
+    m = re.search(r"\b(fixed|clamped|glued|welded|bolted|mounted|held)\s+(?:at|on|to)\s+(?:the\s+)?"
+                  r"(top|bottom|left|right|front|back|base)\b", q)
+    if m:
+        side = {"base": "bottom"}.get(m.group(2), m.group(2))
+        return f"fixed {side}", f"the {side} face is held still"
+    if holes:
+        d = _common_hole(holes)
+        return f"bolt holes d={d:.4g}", f"bolted through the {d:.3g} mm holes (the most common hole size)"
+    return "fixed bottom", "the bottom face is held still"
+
+
+def _common_hole(holes) -> float:
+    """The most common hole size; ties go to the size whose holes sit lowest, since parts usually bolt down."""
+    ds = np.round(np.array([2 * h.radius for h in holes]), 2)
+    vals, counts = np.unique(ds, return_counts=True)
+    best = vals[counts == counts.max()]
+    if len(best) == 1:
+        return float(best[0])
+    low = {v: min(h.axis_point[2] for h, d in zip(holes, ds) if d == v) for v in best}
+    return float(min(best, key=lambda v: low[v]))
+
+
+def _guess_load(q: str, f: PartFeatures, study: StructuralStudy) -> tuple[str, str] | None:
+    direction = _direction(q) or "down"
+    m = _FORCE.search(q)
+    gm = _GRAV.search(q)
+    pm = _PRESS.search(q)
+    if pm:
+        return f"{pm.group(1)} {pm.group(2)} @ top", f"pressure on the top face"
+    if gm and not m:
+        return f"{gm.group(1)} g {direction}", f"{gm.group(1)} g of acceleration, {direction}"
+    if not m:
+        return None
+    unit = m.group(2).lower()
+    nice = {"n": "N", "newton": "N", "newtons": "N", "kn": "kN", "kg": "kgf", "kgs": "kgf", "kgf": "kgf",
+            "lb": "lbf", "lbs": "lbf", "lbf": "lbf", "pound": "lbf", "pounds": "lbf", "kip": "kip", "kips": "kip"}
+    mag = f"{m.group(1)} {nice.get(unit, unit)}"
+    sel, why = _far_face(f, study)
+    if re.search(r"\b(on|at) (the )?top\b", q):
+        sel, why = "top", "the top face"
+    elif re.search(r"\b(tip|end|free end)\b", q):
+        sel, why = _far_face(f, study)
+    return f"{mag} {direction} @ {sel}", f"{mag} pushing {direction} on {why}"
+
+
+def _far_face(f: PartFeatures, study: StructuralStudy) -> tuple[str, str]:
+    """The flat face farthest from the supports: the free end of a cantilevered part."""
+    flats = [x for x in f.faces.values() if x.kind == "plane" and x.area > 0.01 * sum(y.area for y in f.faces.values())]
+    if not flats:
+        return "top", "the top face"
+    sup = []
+    for fx in study.fixtures:
+        if "hole" in fx.faces:
+            sup += [np.asarray(h.axis_point) for h in f.holes()]
+    if not sup:
+        lo = np.asarray(f.bbox[0])
+        sup = [lo]
+    c = np.mean(sup, axis=0)
+    best = max(flats, key=lambda x: float(np.linalg.norm(np.asarray(x.centroid) - c)))
+    return f"face {best.id}", f"face {best.id}, the flat face farthest from the supports"
+
+
+def gravity_in_question(q: str) -> bool:
+    return bool(re.search(r"\b(own weight|self weight|gravity|drop)\b", q.lower()))
+
+
+def force_text(value: str) -> float:
+    return parse_quantity(value, "force").value
+
+
+__all__ = ["read_question", "detect_domain", "find_material", "Reading", "get_material", "Fixture", "Load"]

wobbl/circuits/__init__.py

@@ -0,0 +1 @@
+"""Circuit checks with ngspice."""

wobbl/circuits/run.py

@@ -0,0 +1,270 @@
+"""Run a circuit check with ngspice and verify it: textbook comparison, time step convergence, power balance."""
+from __future__ import annotations
+
+import math
+import re
+import time
+from pathlib import Path
+
+import numpy as np
+
+from ..outcome_generic import GenericOutcome
+from ..solvers import base as solvers
+from ..units import fmt
+from ..verify.checks import Check, confidence
+from .templates import TEMPLATES, Template, e24_above
+
+
+def _ngspice():
+    a = solvers.for_domain("circuit")
+    a.require()
+    return a
+
+
+def simulate(t: Template, work: Path, step_factor: float = 1.0) -> dict[str, np.ndarray]:
+    net = t.netlist.rstrip()
+    if net.lower().endswith(".end"):
+        net = net[:-4].rstrip()
+    if t.analysis == "tran":
+        step, stop = t.tran
+        s = step * step_factor
+        net += f"\n.tran {s:.6e} {stop:.6e} 0 {s:.6e} uic\n"
+    data, log, secs = _ngspice().run(net + "\n.end\n", work, t.vectors, f"{t.name}_{step_factor:g}")
+    return data
+
+
+def _interp_at(x, y, x0):
+    return float(np.interp(x0, x, y))
+
+
+def run_circuit(template: str, params: dict, out_dir: str | Path, question: str = "") -> GenericOutcome:
+    from ..report.render import line_plot
+
+    t0 = time.time()
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    if template not in TEMPLATES:
+        raise ValueError(f"unknown circuit template '{template}' (use {', '.join(TEMPLATES)}) or pass a netlist")
+    tpl = TEMPLATES[template](params)
+    work = out / "work"
+    data = simulate(tpl, work)
+    checks: list[Check] = []
+    extra = []
+    fixes = []
+    imgs = {}
+    p = tpl.params
+    sp = _ngspice()
+    solver = f"ngspice {sp.version()}"
+    if template == "led":
+        i = -float(data["i(v1)"][-1])
+        va = float(data["v(a)"][-1])
+        vs, r = p["supply"], p["resistor"]
+        exact = tpl.expect["i_led"]
+        err = abs(i - exact) / max(exact, 1e-12)
+        checks.append(Check("hand calculation", "pass" if err < 0.01 else "warn",
+                            f"diode equation solved by hand gives {fmt(exact * 1000)} mA, ngspice {fmt(i * 1000)} mA "
+                            f"({100 * err:.2g}% apart); the quick estimate (Vs - Vf)/R is "
+                            f"{fmt(tpl.expect['i_simple'] * 1000)} mA", {"exact_A": exact}))
+        p_src, p_r, p_led = vs * i, i * i * r, va * i
+        bal = abs(p_src - p_r - p_led) / max(p_src, 1e-12)
+        checks.append(Check("power balance", "pass" if bal < 0.005 else "warn",
+                            f"supply gives {fmt(p_src * 1000)} mW = resistor {fmt(p_r * 1000)} mW + LED "
+                            f"{fmt(p_led * 1000)} mW ({100 * bal:.2g}% apart)"))
+        imax, rating = p["imax"], p["rating"]
+        if vs <= p["vf"] * 0.9:
+            verdict, head = "fails", f"The {fmt(vs)} V supply is below the LED's {fmt(p['vf'])} V forward voltage: " \
+                                     "it will barely glow."
+        elif i > imax:
+            verdict = "fails"
+            head = (f"The LED fries: {fmt(i * 1000)} mA through it, above its {fmt(imax * 1000)} mA rating "
+                    f"({i / imax:.2g}x).")
+        elif i > 0.8 * imax or p_r > 0.6 * rating:
+            verdict = "warm"
+            head = (f"{fmt(i * 1000)} mA through the LED ({100 * i / imax:.0f}% of its rating); resistor dissipates "
+                    f"{fmt(p_r * 1000)} mW of its {fmt(rating * 1000)} mW rating. Works, little margin.")
+        else:
+            verdict = "ok"
+            head = (f"Safe: {fmt(i * 1000)} mA through the LED ({100 * i / imax:.0f}% of its {fmt(imax * 1000)} mA "
+                    f"rating); the resistor runs at {fmt(p_r * 1000)} mW.")
+        checks.append(Check("operating limits", "info",
+                            f"LED {fmt(i * 1000)} mA of {fmt(imax * 1000)} mA; resistor {fmt(p_r * 1000)} mW of "
+                            f"{fmt(rating * 1000)} mW"))
+        target = 0.020 if imax <= 0.05 else 0.7 * imax
+        if verdict != "ok" or i < 0.3 * imax:
+            rn = e24_above((vs - p["vf"]) / target) if vs > p["vf"] else None
+            if rn:
+                pr = (vs - p["vf"]) ** 2 / rn
+                fixes.append({"kind": "resistor", "title": f"Use a {fmt(rn)} ohm resistor",
+                              "summary": f"Gives about {fmt((vs - p['vf']) / rn * 1000)} mA; it dissipates "
+                                         f"{fmt(pr * 1000)} mW, so a {'0.25' if pr < 0.12 else '0.5' if pr < 0.25 else '1'}"
+                                         f" W part is enough.", "auto": False})
+        metrics = [("LED current", f"{fmt(i * 1000)} mA"), ("rating", f"{fmt(imax * 1000)} mA"),
+                   ("resistor power", f"{fmt(p_r * 1000)} mW"), ("LED power", f"{fmt(p_led * 1000)} mW")]
+        values = {"i_led_A": i, "v_led_V": va, "p_resistor_W": p_r}
+        assumptions = [f"{p['led']} LED modeled with the diode equation: {fmt(p['vf'])} V at "
+                       f"{'20 mA' if imax <= 0.05 else '350 mA'}, ideality {p['n']:.2g}, series resistance 1.5 ohm.",
+                       f"Resistor {fmt(r)} ohm exact, rated {fmt(rating)} W.", "Room temperature, steady DC."]
+    elif template == "rc":
+        tt, v = data["time"], data["v(out)"]
+        vt = _interp_at(tt, v, p["tau"])
+        exp_v = tpl.expect["v_at_tau"]
+        err = abs(vt - exp_v) / exp_v
+        checks.append(Check("hand calculation", "pass" if err < 0.005 else "warn",
+                            f"V(t = RC) is {fmt(vt)} V; theory says 63.2% of {fmt(p['v'])} V = {fmt(exp_v)} V "
+                            f"({100 * err:.2g}% apart)"))
+        d2 = simulate(tpl, work, 0.5)
+        v2 = _interp_at(d2["time"], d2["v(out)"], p["tau"])
+        checks.append(_step_check(vt, v2, "V(t = RC)"))
+        reach = tt[np.argmax(v >= 0.99 * p["v"])] if (v >= 0.99 * p["v"]).any() else float("nan")
+        verdict, head = "ok", (f"Time constant {fmt(p['tau'] * 1000)} ms: the output reaches 63% in "
+                               f"{fmt(p['tau'] * 1000)} ms and 99% in {fmt(reach * 1000)} ms.")
+        metrics = [("time constant", f"{fmt(p['tau'] * 1000)} ms"), ("V at RC", f"{fmt(vt)} V"),
+                   ("99% after", f"{fmt(reach * 1000)} ms")]
+        values = {"v_at_tau": vt, "t99_s": float(reach)}
+        assumptions = ["Ideal resistor and capacitor, step input at t = 0."]
+        imgs["waveform"] = line_plot(out / "images" / "waveform.png", tt * 1000, {"v(out)": v}, "ms", "V")
+    elif template == "buck":
+        tt, vo, il = data["time"], data["v(out)"], data["i(l1)"]
+        period = 1 / p["frequency"]
+        tw = tt[-1] - 20 * period
+        m = tt >= tw
+        rip_v = float(vo[m].max() - vo[m].min())
+        rip_i = float(il[m].max() - il[m].min())
+        vavg = float(np.mean(vo[m]))
+        m2 = (tt >= tw - 20 * period) & (tt < tw)
+        drift = abs(vavg - float(np.mean(vo[m2]))) / max(vavg, 1e-12)
+        ev, ei = tpl.expect["ripple_v"], tpl.expect["ripple_i"]
+        errv = abs(rip_v - ev) / ev
+        checks.append(Check("hand calculation", "pass" if errv < 0.15 else "warn",
+                            f"ideal waveform math (triangular inductor ripple dI = {fmt(ei)} A through C and ESR) gives "
+                            f"{fmt(ev * 1000)} mV; ngspice {fmt(rip_v * 1000)} mV and {fmt(rip_i)} A "
+                            f"({100 * errv:.0f}% apart; the math ignores switch and diode drops)"))
+        checks.append(Check("steady state", "pass" if drift < 0.005 else "warn",
+                            f"average output moved {100 * drift:.2g}% between the last two 20 cycle windows"))
+        d2 = simulate(tpl, work, 0.5)
+        m_2 = d2["time"] >= d2["time"][-1] - 20 * period
+        rip2 = float(d2["v(out)"][m_2].max() - d2["v(out)"][m_2].min())
+        checks.append(_step_check(rip_v, rip2, "output ripple"))
+        if not tpl.expect["ccm"]:
+            checks.append(Check("operating mode", "warn", "inductor current reaches zero each cycle "
+                                                          "(discontinuous mode); ripple formulas do not apply"))
+        spec = float(p.get("max_ripple", 0.01 * p["vout"]))
+        spec = spec if spec > 0 else 0.01 * p["vout"]
+        verdict = "ok" if rip_v <= spec else "fails"
+        head = (f"Output ripple {fmt(rip_v * 1000)} mV peak to peak on {fmt(vavg)} V "
+                f"({'within' if verdict == 'ok' else 'over'} the {fmt(spec * 1000)} mV limit); inductor ripple "
+                f"{fmt(rip_i)} A, peak {fmt(float(il[m].max()))} A.")
+        if verdict != "ok":
+            cnew = rip_i / (8 * p["frequency"] * max(spec * 0.8 - rip_i * p["esr"], 1e-6))
+            fixes.append({"kind": "capacitor", "title": f"Raise output capacitance to about {fmt(cnew * 1e6)} uF",
+                          "summary": "Ripple falls with 1/(8 f C) until ESR dominates; use low ESR ceramics.",
+                          "auto": False})
+        metrics = [("ripple", f"{fmt(rip_v * 1000)} mV"), ("output", f"{fmt(vavg)} V"),
+                   ("inductor ripple", f"{fmt(rip_i)} A"), ("duty", f"{100 * p['duty']:.1f}%")]
+        values = {"ripple_V": rip_v, "ripple_A": rip_i, "vout_avg": vavg, "il_peak": float(il[m].max())}
+        assumptions = [f"Open loop at the steady state duty cycle {100 * p['duty']:.1f}%; real controllers add "
+                       "their own ripple and transients.", f"Switch on resistance {fmt(p.get('rds', 0.05))} ohm, "
+                       "Schottky catch diode.", f"Capacitor ESR {fmt(p['esr'] * 1000)} mohm, no ESL."]
+        zoom = tt >= tt[-1] - 3 * period
+        imgs["waveform"] = line_plot(out / "images" / "waveform.png", (tt[zoom] - tt[zoom][0]) * 1e6,
+                                     {"v(out)": vo[zoom]}, "us", "V")
+    elif template == "mosfet":
+        tt, vd, idr = data["time"], data["v(d)"], data["i(vs)"]
+        f = p["frequency"]
+        tw = tt[-1] - (10 / f if f > 0 else tt[-1] / 2)
+        m = tt >= tw
+        pc_sim = float(np.mean(vd[m] * idr[m]))
+        i_rms = float(np.sqrt(np.mean(idr[m] ** 2)))
+        rds25 = p["rds_on"]
+        pc_hand = i_rms ** 2 * rds25
+        err = abs(pc_sim - pc_hand) / max(pc_hand, 1e-12)
+        checks.append(Check("hand calculation", "pass" if err < 0.02 else "warn",
+                            f"conduction loss I_rms^2 R = {fmt(pc_hand)} W; ngspice average of V x I = {fmt(pc_sim)} W "
+                            f"({100 * err:.2g}% apart)"))
+        trf = float(p.get("switching_time", 40e-9))
+        psw = 0.5 * p["vbus"] * p["current"] * trf * f * 2 if f > 0 else 0.0
+        ta = float(p.get("ambient", 25))
+        theta = float(p.get("theta_ja", 62))
+        tjmax = float(p.get("tj_max", 150))
+        tc = float(p.get("rds_tempco", 0.006))
+        tj = ta
+        for _ in range(50):
+            ptot = pc_sim * (1 + tc * (tj - 25)) + psw
+            tj_new = ta + ptot * theta
+            if abs(tj_new - tj) < 1e-3:
+                break
+            tj = tj_new if tj_new < 1000 else 1000
+        runaway = tj >= 999
+        checks.append(Check("thermal loop", "fail" if runaway else "pass",
+                            "on resistance rises with temperature faster than the heat can leave: thermal runaway"
+                            if runaway else f"junction settles at {fmt(tj)} C after the on resistance warms up "
+                                            f"({fmt(rds25 * (1 + tc * (tj - 25)) * 1000)} mohm hot)"))
+        verdict = "ok" if tj <= tjmax - 25 else ("warm" if tj <= tjmax else "hot")
+        head = (f"Junction reaches about {fmt(tj)} C ({fmt(ptot)} W: {fmt(ptot - psw)} W conduction, {fmt(psw)} W "
+                f"switching) with {fmt(theta)} C/W to {fmt(ta)} C air; limit {fmt(tjmax)} C.")
+        if verdict != "ok":
+            th_need = (tjmax - 25 - ta) / max(ptot, 1e-9)
+            fixes.append({"kind": "heatsink", "title": f"Get the junction to air resistance under {fmt(th_need)} C/W",
+                          "summary": "Add copper area or a heatsink; for TO-220, a clip on sink of about "
+                                     f"{fmt(max(th_need - 2, 1))} C/W plus pad is typical.", "auto": False})
+            fixes.append({"kind": "part", "title": f"Pick a part with under {fmt(rds25 * (tjmax - 25 - ta) / max(tj - ta, 1e-9) * 1000)} mohm",
+                          "summary": "Conduction loss scales with on resistance.", "auto": False})
+        metrics = [("junction", f"{fmt(tj)} C"), ("limit", f"{fmt(tjmax)} C"), ("loss", f"{fmt(ptot)} W"),
+                   ("theta JA", f"{fmt(theta)} C/W")]
+        values = {"tj_C": tj, "p_total_W": ptot, "p_cond_W": ptot - psw, "p_sw_W": psw}
+        assumptions = [f"On resistance {fmt(rds25 * 1000)} mohm at 25 C rising {tc * 100:g}% per C.",
+                       f"Switching loss from {fmt(trf * 1e9)} ns edges: 0.5 V I (tr + tf) f.",
+                       f"Junction to air {fmt(theta)} C/W (datasheet, no heatsink unless included)."]
+    out_o = GenericOutcome("circuit", template, question, verdict, head, metrics, "high", [], checks, assumptions,
+                           {**values, "params": {k: (v if isinstance(v, (int, float, str, bool)) else str(v))
+                                                 for k, v in p.items()},
+                            "_figures": [["waveform", "Simulated waveform"]]}, imgs, fixes, solver=solver,
+                           t_total=time.time() - t0)
+    out_o.confidence, out_o.confidence_reasons = confidence(checks, extra)
+    (out / "netlist.cir").write_text(tpl.netlist)
+    return out_o.write(out)
+
+
+def _step_check(a: float, b: float, label: str) -> Check:
+    d = abs(a - b) / max(abs(b), 1e-15)
+    st = "pass" if d < 0.01 else ("warn" if d < 0.05 else "fail")
+    return Check("time step convergence", st, f"{label} {fmt(a)} with the normal step, {fmt(b)} with half the step "
+                                              f"({100 * d:.2g}% apart)")
+
+
+def run_netlist(path: str, probes: list[str], out_dir: str | Path, question: str = "") -> GenericOutcome:
+    """Any user netlist: run it, report the probed vectors, and recheck with half the time step."""
+    from ..report.render import line_plot
+
+    t0 = time.time()
+    out = Path(out_dir)
+    text = Path(path).read_text()
+    if not probes:
+        raise ValueError("say which signals to read, for example --probe 'v(out)' --probe 'i(V1)'")
+    body = re.sub(r"(?ims)^\.control.*?^\.endc\s*$", "", text)
+    tran = re.search(r"(?im)^\.tran\s+(\S+)\s+(\S+)(.*)$", body)
+    tpl = Template(Path(path).stem, body, probes, {}, "dc")
+    data = _ngspice().run(body, out / "work", probes, "run")[0]
+    checks = []
+    if tran:
+        from ..units import parse_spice_value
+        step = parse_spice_value(tran.group(1))
+        half = body[:tran.start()] + f".tran {step / 2:.6e} {tran.group(2)}{tran.group(3)}" + body[tran.end():]
+        d2 = _ngspice().run(half, out / "work", probes, "half")[0]
+        for pr in probes:
+            a, b = float(np.max(np.abs(data[pr]))), float(np.max(np.abs(d2[pr])))
+            checks.append(_step_check(a, b, f"peak |{pr}|"))
+    vals = {pr: {"min": float(np.min(data[pr])), "max": float(np.max(data[pr])), "mean": float(np.mean(data[pr])),
+                 "final": float(data[pr][-1])} for pr in probes}
+    xkey = "time" if "time" in data else next(iter(data))
+    imgs = {"waveform": line_plot(out / "images" / "waveform.png", data[xkey], {pr: data[pr] for pr in probes},
+                                  xkey, "value")}
+    lvl, reasons = confidence(checks)
+    head = "; ".join(f"{pr}: min {fmt(v['min'])}, max {fmt(v['max'])}, final {fmt(v['final'])}" for pr, v in
+                     vals.items())
+    o = GenericOutcome("circuit", path, question, "ok", head, [(pr, fmt(v["final"])) for pr, v in vals.items()][:4],
+                       lvl, reasons, checks, ["Simulated as written; models come from the netlist."],
+                       {"probes": vals, "_figures": [["waveform", "Simulated signals"]]}, imgs,
+                       solver=f"ngspice {_ngspice().version()}", t_total=time.time() - t0)
+    _ = tpl, math
+    return o.write(out)

wobbl/circuits/templates.py

@@ -0,0 +1,184 @@
+"""Ready made circuit checks: LED current, RC timing, buck regulator ripple, MOSFET heating.
+
+Each template writes a SPICE netlist, runs ngspice, and also computes the
+textbook answer so the two can be compared. Values use plain SI units.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from ..units import parse_spice_value, parse_quantity
+
+VT = 8.617333e-5 * 300.15  # thermal voltage at 27 C as ngspice computes it, V
+
+# 5 mm through hole LEDs: forward voltage at 20 mA, continuous current rating
+LEDS = {
+    "red": (2.0, 0.030), "orange": (2.05, 0.030), "yellow": (2.1, 0.030), "green": (3.1, 0.030),
+    "blue": (3.2, 0.030), "white": (3.2, 0.030), "uv": (3.4, 0.030), "ir": (1.3, 0.050),
+    "power-white": (3.0, 0.350), "power-red": (2.2, 0.350),
+}
+E24 = [1.0, 1.1, 1.2, 1.3, 1.5, 1.6, 1.8, 2.0, 2.2, 2.4, 2.7, 3.0, 3.3, 3.6, 3.9, 4.3, 4.7, 5.1, 5.6, 6.2, 6.8, 7.5,
+       8.2, 9.1]
+
+
+def e24_above(x: float) -> float:
+    if x <= 0:
+        return 1.0
+    dec = 10 ** math.floor(math.log10(x))
+    for m in E24 + [10.0]:
+        if m * dec >= x * 0.999:
+            return m * dec
+    return 10 * dec
+
+
+def val(params: dict, key: str, default=None, kind: str | None = None) -> float:
+    v = params.get(key, default)
+    if v is None:
+        raise ValueError(f"missing parameter '{key}'")
+    if isinstance(v, (int, float)):
+        return float(v)
+    s = str(v).strip()
+    if kind:
+        try:
+            return parse_quantity(s, kind).value
+        except Exception:  # noqa: BLE001
+            pass
+    return parse_spice_value(s)
+
+
+@dataclass
+class Template:
+    name: str
+    netlist: str
+    vectors: list[str]
+    params: dict
+    analysis: str = "dc"           # dc or tran
+    tran: tuple[float, float] | None = None   # (step, stop)
+    expect: dict = field(default_factory=dict)  # closed form numbers
+
+
+def led(p: dict) -> Template:
+    vs = val(p, "supply", "5", "voltage")
+    r = val(p, "resistor", "150", "resistance")
+    color = str(p.get("led", "red")).lower()
+    vf, imax = LEDS.get(color, LEDS["red"])
+    vf = val(p, "vf", vf, "voltage")
+    imax = val(p, "imax", imax, "current")
+    n, rs = max(2.0, vf / 1.2), 1.5  # keeps IS above the ~1e-28 floor ngspice applies
+    i_ref = 0.020 if imax < 0.2 else 0.350
+    isat = i_ref / math.exp((vf - i_ref * rs) / (n * VT))
+    net = f"""* LED with series resistor
+V1 vin 0 DC {vs}
+R1 vin a {r}
+D1 a 0 LEDX
+.model LEDX D(IS={isat:.6e} N={n} RS={rs})
+.dc V1 {vs} {vs} 1
+.end
+"""
+    # textbook: solve Vs = I R + I Rs + n Vt ln(I/Is + 1) by Newton
+    i = max((vs - vf) / r, 1e-9)
+    for _ in range(100):
+        f = i * (r + rs) + n * VT * math.log(i / isat + 1) - vs
+        df = (r + rs) + n * VT / (i + isat)
+        i_new = max(i - f / df, 1e-15)
+        if abs(i_new - i) < 1e-15:
+            break
+        i = i_new
+    p_out = dict(p, supply=vs, resistor=r, vf=vf, imax=imax, led=color, n=n, rating=val(p, "rating", "0.25", "si_power"))
+    return Template("led", net, ["i(v1)", "v(a)"], p_out, "dc",
+                    expect={"i_led": i, "i_simple": max((vs - vf) / r, 0.0)})
+
+
+def rc(p: dict) -> Template:
+    r = val(p, "r", "10k", "resistance")
+    c = val(p, "c", "10u", "capacitance")
+    v = val(p, "v", "5", "voltage")
+    tau = r * c
+    net = f"""* RC charging
+V1 in 0 PULSE(0 {v} 0 1n 1n 1 2)
+R1 in out {r}
+C1 out 0 {c} IC=0
+.end
+"""
+    return Template("rc", net, ["v(out)"], dict(p, r=r, c=c, v=v, tau=tau), "tran", (tau / 400, 5 * tau),
+                    expect={"v_at_tau": v * (1 - math.exp(-1)), "tau": tau, "t99": tau * math.log(100)})
+
+
+def buck(p: dict) -> Template:
+    vin = val(p, "vin", "12", "voltage")
+    vout = val(p, "vout", "5", "voltage")
+    iout = val(p, "current", "1", "current")
+    f = val(p, "frequency", "500k", "frequency")
+    L = val(p, "inductor", "10u", "inductance")
+    C = val(p, "capacitor", "22u", "capacitance")
+    esr = val(p, "esr", "0.01", "resistance")
+    rds = val(p, "rds", "0.05", "resistance")
+    vd = 0.35  # Schottky catch diode
+    duty = (vout + vd + iout * 0.0) / (vin - iout * rds + vd)
+    period = 1.0 / f
+    ton = duty * period
+    rload = vout / iout
+    di = (vin - vout) * (vout / vin) / (L * f)
+    dv = _ripple(di, vout / vin, f, C, esr)
+    cycles = int(p.get("cycles", 300))
+    net = f"""* Buck converter power stage, open loop at the steady state duty cycle
+V1 vin 0 DC {vin}
+VG g 0 PULSE(0 5 0 {period / 200:.4e} {period / 200:.4e} {ton:.6e} {period:.6e})
+S1 vin sw g 0 SWMOD
+.model SWMOD SW(VT=2.5 VH=0.1 RON={rds} ROFF=1e6)
+D1 0 sw SCHOTTKY
+.model SCHOTTKY D(IS=5e-5 N=1.05 RS=0.02)
+L1 sw out {L} IC={iout}
+C1 out cmid {C} IC={vout}
+R2 cmid 0 {esr}
+R1 out 0 {rload}
+.end
+"""
+    return Template("buck", net, ["v(out)", "i(l1)"], dict(p, vin=vin, vout=vout, current=iout, frequency=f,
+                                                          inductor=L, capacitor=C, esr=esr, duty=duty, cycles=cycles),
+                    "tran", (period / 400, cycles * period),
+                    expect={"ripple_v": dv, "ripple_i": di, "ccm": iout > di / 2})
+
+
+def _ripple(di: float, duty: float, f: float, C: float, esr: float) -> float:
+    """Exact peak to peak output ripple for a triangular capacitor current: ESR and charge terms out of phase."""
+    T = 1.0 / f
+    t = np.linspace(0, T, 4001)
+    rise = duty * T
+    ic = np.where(t < rise, -di / 2 + di * t / rise, di / 2 - di * (t - rise) / (T - rise))
+    q = np.concatenate([[0.0], np.cumsum(0.5 * (ic[1:] + ic[:-1]) * np.diff(t))])
+    v = esr * ic + q / C
+    return float(v.max() - v.min())
+
+
+def mosfet(p: dict) -> Template:
+    i = val(p, "current", "10", "current")
+    rds = val(p, "rds_on", "0.01", "resistance")
+    vbus = val(p, "vbus", "12", "voltage")
+    f = val(p, "frequency", "0", "frequency")
+    duty = float(p.get("duty", 1.0 if f == 0 else 0.5))
+    rload = max(vbus / i - rds, 1e-3)
+    if f > 0:
+        period = 1 / f
+        drive = f"PULSE(0 10 0 {period / 500:.4e} {period / 500:.4e} {duty * period:.6e} {period:.6e})"
+        tran = (period / 500, 40 * period)
+    else:
+        drive = "DC 10"
+        tran = (1e-6, 1e-4)
+    net = f"""* MOSFET conduction with a resistive load
+V1 vbus 0 DC {vbus}
+RL vbus d {rload}
+VG g 0 {drive}
+S1 d s g 0 SWMOD
+.model SWMOD SW(VT=5 VH=0.1 RON={rds} ROFF=1e7)
+VS s 0 DC 0
+.end
+"""
+    return Template("mosfet", net, ["v(d)", "i(vs)"], dict(p, current=i, rds_on=rds, vbus=vbus, frequency=f,
+                                                            duty=duty), "tran", tran)
+
+
+TEMPLATES = {"led": led, "rc": rc, "buck": buck, "mosfet": mosfet}