traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/sim/circuit.py

@@ -0,0 +1,499 @@
+"""A SPICE circuit as editable data: parse, change values, write, or import from KiCad."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge import sexpr
+from traceforge.kicad.pcb import pin_function
+from traceforge.sim import models
+
+
+class SimError(Exception):
+    """A simulation problem the caller can act on."""
+
+
+# --------------------------------------------------------------------------- numbers
+_SUFFIX = {
+    "t": 1e12,
+    "g": 1e9,
+    "meg": 1e6,
+    "k": 1e3,
+    "m": 1e-3,
+    "u": 1e-6,
+    "n": 1e-9,
+    "p": 1e-12,
+    "f": 1e-15,
+}
+_NUM = re.compile(r"^\s*([-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)\s*([a-zµμ]*)", re.I)
+
+
+def parse_value(text: str | float | int) -> float:
+    """SPICE/KiCad number: ``4.7k``, ``10u``, ``100nF``, ``1meg``, ``4k7``, ``2.2µ``."""
+    if isinstance(text, int | float):
+        return float(text)
+    s = str(text).strip().replace("µ", "u").replace("μ", "u")
+    m = re.fullmatch(r"(\d+)(meg|[tgkmunpf])(\d+)", s, re.I)  # 4k7 style
+    if m:
+        s = f"{m.group(1)}.{m.group(3)}{m.group(2)}"
+    m = _NUM.match(s)
+    if not m:
+        raise ValueError(f"not a number: {text!r}")
+    number, suffix = float(m.group(1)), m.group(2).lower()
+    if not suffix:
+        return number
+    if suffix.startswith("meg"):
+        return number * 1e6
+    return number * _SUFFIX.get(suffix[0], 1.0)  # trailing unit letters (F, H, ohm) ignored
+
+
+def format_value(x: float, digits: int = 6) -> str:
+    """Shortest SPICE-safe number (``31.83k`` style would hide digits, so plain notation)."""
+    return f"{x:.{digits}g}"
+
+
+# ---------------------------------------------------------------------------- model
+_NODES = {"R": 2, "C": 2, "L": 2, "V": 2, "I": 2, "D": 2, "B": 2, "F": 2, "H": 2, "Q": 3, "M": 4}
+_NODES |= {"E": 4, "G": 4, "S": 4, "W": 2, "J": 3, "Z": 3, "O": 4, "T": 4, "K": 0}
+GROUND_NAMES = {"0", "GND", "GNDA", "GNDD", "AGND", "DGND", "GROUND", "VSS"}
+
+
+@dataclass
+class Element:
+    ref: str
+    nodes: list[str]
+    value: str = ""
+    note: str = ""  # e.g. "generic LED model"
+
+    @property
+    def kind(self) -> str:
+        return self.ref[:1].upper()
+
+    def line(self) -> str:
+        return " ".join([self.ref, *self.nodes, self.value]).strip()
+
+
+@dataclass
+class Circuit:
+    title: str = "traceforge circuit"
+    elements: list[Element] = field(default_factory=list)
+    params: dict[str, str] = field(default_factory=dict)  # .param name=value
+    blocks: dict[str, str] = field(default_factory=dict)  # .model / .subckt text by name
+    includes: list[str] = field(default_factory=list)  # full .include / .lib lines
+    directives: list[str] = field(default_factory=list)  # other dot lines (.ic, .options, ...)
+    node_map: dict[str, str] = field(default_factory=dict)  # schematic net -> SPICE node
+    skipped: list[str] = field(default_factory=list)  # parts left out, with the reason
+    generic: list[str] = field(default_factory=list)  # parts on a generic stand-in model
+    warnings: list[str] = field(default_factory=list)
+
+    # ----------------------------------------------------------------- access
+    def element(self, ref: str) -> Element:
+        for el in self.elements:
+            if el.ref.upper() == ref.upper():
+                return el
+        raise SimError(f"no element {ref!r} in the circuit")
+
+    def number(self, ref: str) -> float:
+        """Numeric value of R/C/L element or of ``param:NAME``."""
+        if ref.lower().startswith("param:"):
+            return parse_value(self.params[ref[6:]])
+        return parse_value(self.element(ref).value.split()[0])
+
+    def set_value(self, ref: str, value: float | str) -> None:
+        """Set an element value (``R1``), a tied group (``R1,R2``) or ``param:NAME``."""
+        text = value if isinstance(value, str) else format_value(value)
+        for name in (n.strip() for n in ref.split(",") if n.strip()):
+            if name.lower().startswith("param:"):
+                self.params[name[6:]] = text
+                continue
+            el = self.element(name)
+            rest = el.value.split(maxsplit=1)
+            el.value = text + (" " + rest[1] if len(rest) > 1 else "")
+
+    def copy(self) -> Circuit:
+        import copy
+
+        return copy.deepcopy(self)
+
+    def node(self, net: str) -> str:
+        """SPICE node name for a schematic net or an already-SPICE node."""
+        return self.node_map.get(net, net)
+
+    # ------------------------------------------------------------------ output
+    def to_spice(self, extra: list[str] | None = None, control: list[str] | None = None) -> str:
+        out = [f"* {self.title}" if not self.title.startswith("*") else self.title]
+        out += [f"* generic: {g}" for g in self.generic]
+        out += [f"* skipped: {s}" for s in self.skipped]
+        out += self.includes
+        out += [f".param {k}={v}" for k, v in self.params.items()]
+        out += list(self.blocks.values())
+        out += self.directives
+        out += [el.line() for el in self.elements]
+        out += extra or []
+        if control:
+            out += [".control", *control, ".endc"]
+        out.append(".end")
+        return "\n".join(out) + "\n"
+
+    # ----------------------------------------------------------------- parsing
+    @classmethod
+    def from_text(cls, text: str, base: Path | None = None) -> Circuit:
+        """Parse a SPICE deck.  Analysis lines (.ac, .tran, ...) and .control blocks are kept
+        out of the circuit; pass them as an analysis instead."""
+        lines: list[str] = []
+        for raw in text.replace("\r", "").split("\n"):
+            if raw.startswith("+") and lines:
+                lines[-1] += " " + raw[1:].strip()
+            else:
+                lines.append(raw.rstrip())
+        circuit = cls()
+        if lines and not lines[0].lstrip().startswith(("*", ".")) and lines[0].strip():
+            first = lines[0].strip()
+            circuit.title = first
+            lines = lines[1:]
+        elif lines and lines[0].lower().startswith(".title"):
+            circuit.title = lines[0][6:].strip()
+            lines = lines[1:]
+        elif lines and lines[0].startswith("*"):
+            circuit.title = lines[0].lstrip("* ").strip()
+            lines = lines[1:]
+        block: list[str] | None = None
+        block_name = ""
+        in_control = False
+        for line in lines:
+            s = line.strip()
+            low = s.lower()
+            if not s or s.startswith(("*", ";")):
+                continue
+            if in_control:
+                in_control = not low.startswith(".endc")
+                continue
+            if low.startswith(".control"):
+                in_control = True
+                continue
+            if block is not None:
+                block.append(s)
+                if low.startswith(".ends"):
+                    circuit.blocks[block_name] = "\n".join(block)
+                    block = None
+                continue
+            if low.startswith(".subckt"):
+                block, block_name = [s], s.split()[1]
+                continue
+            if low.startswith(".end"):
+                break
+            if low.startswith(".model"):
+                circuit.blocks[s.split()[1]] = s
+            elif low.startswith((".include", ".inc", ".lib")):
+                circuit.includes.append(_absolute_include(s, base))
+            elif low.startswith(".param"):
+                for k, v in re.findall(r"([A-Za-z_]\w*)\s*=\s*(\{[^}]*\}|\S+)", s[6:]):
+                    circuit.params[k] = v
+            elif low.startswith((".ac", ".tran", ".dc", ".op", ".noise", ".pz", ".tf", ".meas")):
+                circuit.directives.append(s)  # kept so a deck round-trips; analyses are re-added
+            elif s.startswith("."):
+                circuit.directives.append(s)
+            else:
+                circuit.elements.append(_parse_element(s))
+        return circuit
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> Circuit:
+        path = Path(path)
+        return cls.from_text(path.read_text(encoding="utf-8", errors="replace"), path.parent)
+
+    # ------------------------------------------------------------ analysis lines
+    def deck_directives(self) -> tuple[list[str], list[str]]:
+        """Split stored dot lines into (analysis/.meas lines, others)."""
+        analysis = [d for d in self.directives if d.lower().startswith(_ANALYSIS_DOTS)]
+        return analysis, [d for d in self.directives if d not in analysis]
+
+
+_ANALYSIS_DOTS = (".ac", ".tran", ".dc", ".op", ".noise", ".pz", ".tf", ".meas")
+
+
+def _absolute_include(line: str, base: Path | None) -> str:
+    if base is None:
+        return line
+    m = re.match(r'(\.\w+)\s+("?)([^"\s]+)\2(.*)', line)
+    if not m:
+        return line
+    path = Path(m.group(3))
+    if not path.is_absolute() and (base / path).exists():
+        path = (base / path).resolve()
+    return f'{m.group(1)} "{path}"{m.group(4)}'
+
+
+def _parse_element(line: str) -> Element:
+    tokens = line.split()
+    ref = tokens[0]
+    kind = ref[0].upper()
+    if kind == "X":
+        end = len(tokens)
+        while end > 2 and "=" in tokens[end - 1]:
+            end -= 1
+        # the subcircuit name is the last token before any NAME=value parameters
+        return Element(ref, tokens[1 : end - 1], " ".join(tokens[end - 1 :]))
+    count = _NODES.get(kind, 2)
+    return Element(ref, tokens[1 : 1 + count], " ".join(tokens[1 + count :]))
+
+
+# ------------------------------------------------------------------ KiCad import
+_NET_BAD = re.compile(r"[^A-Za-z0-9_]")
+
+
+def spice_node(net: str, ground: set[str]) -> str:
+    """Legal SPICE node name for a schematic net name (``+3V3`` -> ``P3V3``, GND -> ``0``)."""
+    name = net.strip().lstrip("/")
+    if name.upper() in ground:
+        return "0"
+    if name.startswith("+"):
+        name = "P" + name[1:]
+    elif name.startswith("-"):
+        name = "N" + name[1:]
+    name = _NET_BAD.sub("_", name)
+    return name if name and not name[0].isdigit() else "n" + name
+
+
+_PIN_ROLES = {
+    "D": {"A": "a", "K": "k", "1": "k", "2": "a"},
+    "OPAMP": {"+": "p", "-": "n", "~": "o", "OUT": "o", "1": "o", "2": "n", "3": "p"},
+    "LDO": {"VI": "i", "IN": "i", "VIN": "i", "VO": "o", "OUT": "o", "VOUT": "o", "GND": "g"},
+    "M": {"D": "d", "G": "g", "S": "s"},
+    "Q": {"C": "c", "B": "b", "E": "e"},
+}
+_OPAMP_NAMES = re.compile(
+    r"opamp|op_amp|lm358|lm324|lm741|tl07|tl08|mcp60|opa\d|ne5532|ad8\d\d|lt\d{4}", re.I
+)
+_LDO_NAMES = re.compile(
+    r"ams1117|lm1117|ld1117|ap2112|ap7\d|mcp1700|xc6206|lm78|l78|ld3985|ncp1117", re.I
+)
+
+
+def circuit_from_netlist_text(
+    netlist: str,
+    symbols: dict[str, dict],
+    *,
+    title: str = "",
+    ground: set[str] | None = None,
+    sources: list[dict] | None = None,
+    base: Path | None = None,
+) -> Circuit:
+    """Build a Circuit from KiCad's ``kicadsexpr`` netlist plus schematic symbol fields.
+
+    ``symbols`` maps reference -> {"value", "lib_id", "fields", "dnp", "exclude"}.
+    """
+    ground = {g.upper() for g in (ground or set())} | GROUND_NAMES
+    root = sexpr.parse(netlist)
+    pins: dict[str, dict[str, str]] = {}  # ref -> {pin number / function -> node}
+    nets_node = sexpr.find(root, "nets")
+    circuit = Circuit(title=title or "KiCad schematic")
+    for net in sexpr.find_all(nets_node, "net") if nets_node else []:
+        name = str(sexpr.value(net, "name", ""))
+        node = spice_node(name, ground)
+        circuit.node_map[name] = node
+        if name.startswith("/"):
+            circuit.node_map[name.lstrip("/")] = node
+        for n in sexpr.find_all(net, "node"):
+            ref = str(sexpr.value(n, "ref", ""))
+            pin = str(sexpr.value(n, "pin", ""))
+            func = pin_function(sexpr.value(n, "pinfunction", ""), pin).upper()
+            table = pins.setdefault(ref, {})
+            table["#" + pin] = node
+            if func:
+                table.setdefault(func, node)
+    comps = {
+        str(sexpr.value(c, "ref", "")): c
+        for c in sexpr.find_all(sexpr.find(root, "components"), "comp")
+    }
+    for ref in sorted(comps, key=lambda r: (r.rstrip("0123456789"), len(r), r)):
+        info = symbols.get(ref, {})
+        lib = str(sexpr.value(sexpr.find(comps[ref], "libsource"), "part", ""))
+        _add_part(circuit, ref, info, lib, pins.get(ref, {}), base)
+    for i, src in enumerate(sources or [], 1):
+        circuit.elements.append(_source_element(src, i, circuit, ground))
+    return circuit
+
+
+def _source_element(src: dict, index: int, circuit: Circuit, ground: set[str]) -> Element:
+    name = str(src.get("name") or f"Vsrc{index}")
+    kind = str(src.get("kind") or "V").upper()
+    pos = circuit.node_map.get(src["pos"]) or spice_node(src["pos"], ground)
+    neg = circuit.node_map.get(src.get("neg", "GND")) or spice_node(src.get("neg", "GND"), ground)
+    spec = src.get("spec")
+    if not spec:
+        spec = f"DC {src.get('dc', 0)}"
+        if "ac" in src:
+            spec += f" AC {src['ac']}"
+    ref = name if name[:1].upper() == kind else kind + name
+    return Element(ref, [pos, neg], str(spec), "analysis source from the simulation spec")
+
+
+def _sim_params(text: str) -> dict[str, str]:
+    return {k.lower(): v for k, v in re.findall(r"([A-Za-z_]\w*)\s*=\s*(\S+)", text or "")}
+
+
+def _source_spec(fields: dict[str, str], value: str) -> str:
+    kind = fields.get("Sim.Type", "").upper()
+    p = _sim_params(fields.get("Sim.Params", ""))
+    ac = f" AC {p['ac']}" if "ac" in p else ""
+    if kind == "SIN":
+        args = [p.get(k, d) for k, d in (("dc", "0"), ("ampl", "1"), ("f", "1k"), ("td", "0"))]
+        return f"SIN({' '.join(args)}){ac}"
+    if kind == "PULSE":
+        keys = ("y1", "y2", "td", "tr", "tf", "tw", "per")
+        defaults = ("0", "1", "0", "1n", "1n", "0.5m", "1m")
+        return f"PULSE({' '.join(p.get(k, d) for k, d in zip(keys, defaults, strict=True))}){ac}"
+    if p.get("dc") or kind == "DC":
+        return f"DC {p.get('dc', value or 0)}{ac}"
+    return (
+        value if re.match(r"(?i)\s*(dc|ac|sin|pulse|pwl|exp)", value or "") else f"DC {value or 0}"
+    ) + ac
+
+
+def _add_part(
+    circuit: Circuit, ref: str, info: dict, lib: str, pins: dict[str, str], base: Path | None
+) -> None:
+    fields: dict[str, str] = info.get("fields", {})
+    value = str(info.get("value", ""))
+    prefix = ref.rstrip("0123456789")[:1].upper()
+    if info.get("dnp") or info.get("exclude") or fields.get("Sim.Enable", "1") == "0":
+        circuit.skipped.append(f"{ref}: not fitted or excluded from simulation")
+        return
+
+    def pin(*names: str) -> str | None:
+        for n in names:
+            key = n if n.startswith("#") else n.upper()
+            if key in pins:
+                return pins[key]
+        return None
+
+    def two(first: str = "#1", second: str = "#2") -> list[str] | None:
+        a, b = pin(first), pin(second)
+        return [a, b] if a and b else None
+
+    library, subckt = fields.get("Sim.Library", ""), fields.get("Sim.Name", "")
+    if library and subckt and fields.get("Sim.Device", "").upper() in {"SUBCKT", "SPICE", ""}:
+        lib_path = Path(library)
+        if base and not lib_path.is_absolute():
+            lib_path = (base / lib_path).resolve()
+        line = f'.include "{lib_path}"'
+        if line not in circuit.includes:
+            circuit.includes.append(line)
+        mapping = fields.get("Sim.Pins", "")
+        order = sorted(
+            (m.groups() for m in re.finditer(r"(\w+)=(\w+)", mapping)),
+            key=lambda g: (int(g[1]) if g[1].isdigit() else 999, g[1]),
+        )
+        nodes = (
+            [pins.get("#" + a) for a, _ in order]
+            if order
+            else [
+                pins[k]
+                for k in sorted((k for k in pins if k.startswith("#")), key=lambda k: (len(k), k))
+            ]
+        )
+        if None in nodes:
+            circuit.warnings.append(f"{ref}: Sim.Pins names a pin that is not connected")
+            return
+        extra = " ".join(f"{k}={v}" for k, v in _sim_params(fields.get("Sim.Params", "")).items())
+        circuit.elements.append(Element("X" + ref.lstrip("X"), nodes, f"{subckt} {extra}".strip()))
+        return
+    if prefix in {"R", "C", "L"}:
+        nodes = two()
+        if nodes:
+            params = fields.get("Sim.Params", "")
+            val = _sim_params(params).get(prefix.lower()) or value or "0"
+            circuit.elements.append(Element(ref, nodes, val.replace("µ", "u")))
+        return
+    if prefix == "F":  # fuse / polyfuse
+        nodes = two()
+        if nodes:
+            circuit.elements.append(Element("R" + ref, nodes, "0.1", "generic fuse resistance"))
+            circuit.generic.append(f"{ref}: fuse as 0.1 ohm resistor (generic)")
+        return
+    if prefix in {"V", "I"} and fields.get("Sim.Device", "") != "":
+        nodes = [pin("+", "#1"), pin("-", "#2")]
+        if all(nodes):
+            circuit.elements.append(Element(ref, nodes, _source_spec(fields, value)))
+            return
+    if prefix in {"V", "I"} and re.match(r"(?i)\s*(dc|ac|sin|pulse|pwl|[-+\d.])", value or ""):
+        nodes = [pin("+", "#1"), pin("-", "#2")]
+        if all(nodes):
+            circuit.elements.append(Element(ref, nodes, _source_spec(fields, value)))
+            return
+    if prefix == "D":
+        a, k = pin("A", "#2"), pin("K", "#1")
+        if a and k:
+            is_led = "led" in lib.lower() or "led" in str(info.get("lib_id", "")).lower()
+            if is_led:
+                color = models.led_color(value, lib, fields.get("Color", ""))
+                name, text, vf = models.led_model(color)
+                circuit.blocks[name] = text
+                circuit.generic.append(
+                    f"{ref}: generic {color.lower()} LED model, Vf about {vf:g} V at 2 mA (not the real part)"
+                )
+            else:
+                low = (value + " " + lib).lower()
+                name = (
+                    "D_ZENER"
+                    if "zener" in low or re.search(r"bzx|\bz\d", low)
+                    else "D_SCHOTTKY"
+                    if "schottky" in low or re.search(r"bat|ss\d|1n58|b5819", low)
+                    else "D_RECTIFIER"
+                    if re.search(r"1n400|rectif|s1[a-m]\b|m7", low)
+                    else "D_SIGNAL"
+                )
+                circuit.blocks[name] = models.DIODES[name]
+                circuit.generic.append(
+                    f"{ref}: generic {name[2:].lower()} diode model (not {value})"
+                )
+            circuit.elements.append(Element(ref, [a, k], name))
+        return
+    if prefix == "Q" and re.search(r"mos|fet", (lib + value).lower()):
+        d, g, s = pin("D"), pin("G"), pin("S")
+        if d and g and s:
+            name = (
+                "PMOS_GENERIC"
+                if re.search(r"pmos|p_?ch", (lib + value).lower())
+                else "NMOS_GENERIC"
+            )
+            circuit.blocks[name] = models.MOS[name]
+            circuit.elements.append(Element("M" + ref, [d, g, s, s], name + " W=1m L=1u"))
+            circuit.generic.append(f"{ref}: generic level-1 {name[:4]} model (not {value})")
+        return
+    if prefix == "Q":
+        c, b, e = pin("C"), pin("B"), pin("E")
+        if c and b and e:
+            name = "PNP_GENERIC" if re.search(r"pnp", (lib + value).lower()) else "NPN_GENERIC"
+            circuit.blocks[name] = models.BJT[name]
+            circuit.elements.append(Element(ref, [c, b, e], name))
+            circuit.generic.append(f"{ref}: generic {name[:3]} model (not {value})")
+        return
+    if prefix == "U" and _LDO_NAMES.search(value + lib):
+        i, o, g = pin("VI", "IN", "VIN"), pin("VO", "OUT", "VOUT"), pin("GND")
+        if i and o and g:
+            m = re.search(r"(\d+(?:\.\d+)?)\s*$", re.sub(r"(?i)[-_ ]?(sot|to|\d+mm).*", "", value))
+            vset = m.group(1) if m else fields.get("Sim.Params", "vset=3.3").split("=")[-1]
+            circuit.blocks["LDO_GENERIC"] = models.LDO
+            circuit.elements.append(Element("X" + ref, [i, o, g], f"LDO_GENERIC vset={vset}"))
+            circuit.generic.append(f"{ref}: generic LDO, {vset} V out, 1 V dropout (not {value})")
+        else:
+            circuit.warnings.append(f"{ref}: regulator pins not recognised; give Sim.Pins")
+        return
+    if prefix == "U" and (
+        _OPAMP_NAMES.search(value + lib) or fields.get("Sim.Name") == "OPAMP_IDEAL"
+    ):
+        p, n, o = pin("+"), pin("-"), pin("~", "OUT")
+        if p and n and o:
+            circuit.blocks["OPAMP_IDEAL"] = models.OPAMP
+            circuit.elements.append(Element("X" + ref, [p, n, o], "OPAMP_IDEAL"))
+            circuit.generic.append(
+                f"{ref}: generic op-amp (gain 1e6, GBW 10 MHz, ideal output; not {value})"
+            )
+        else:
+            circuit.warnings.append(f"{ref}: multi-unit or unrecognised op-amp pins; give Sim.Pins")
+        return
+    circuit.skipped.append(f"{ref} ({value or lib}): no simulation model")

traceforge/sim/cli.py

@@ -0,0 +1,162 @@
+"""``traceforge sim run|tune|plot``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from traceforge.sim.circuit import SimError
+from traceforge.sim.engine import parse_analysis
+from traceforge.sim.project import export_ltspice, load_circuit, replot, simulate
+from traceforge.sim.tune import tune
+
+
+def add_parser(sub) -> None:
+    sim = sub.add_parser("sim", help="simulate with ngspice: run, tune a value, plot a rawfile")
+    actions = sim.add_subparsers(dest="sim_action", required=True)
+
+    def circuit_flags(p: argparse.ArgumentParser) -> None:
+        p.add_argument("file", help="KiCad .kicad_sch or a SPICE deck (.cir/.sp/.net)")
+        p.add_argument(
+            "--source",
+            action="append",
+            default=[],
+            metavar="NET=VOLTS",
+            help="DC source from NET to GND (repeatable); NET=VOLTS:AC adds an AC magnitude",
+        )
+        p.add_argument(
+            "--ground", action="append", default=[], help="extra net name to treat as ground"
+        )
+        p.add_argument(
+            "--set", action="append", default=[], metavar="REF=VALUE", help="override a value"
+        )
+        p.add_argument("--ac", metavar="'dec 20 10 100k'")
+        p.add_argument("--tran", metavar="'1u 5m'")
+        p.add_argument("--dc", metavar="'V1 0 5 0.1'")
+        p.add_argument("--noise", metavar="'v(out) V1 dec 10 10 100k'")
+        p.add_argument("--op", action="store_true")
+        p.add_argument("--meas", action="append", default=[], help="a .meas line (repeatable)")
+        p.add_argument("--out", default=".traceforge/sim")
+        p.add_argument("--json", action="store_true")
+
+    run = actions.add_parser("run", help="run one analysis and print the results")
+    circuit_flags(run)
+    run.add_argument("--probe", action="append", default=[], help="v(out), i(R5) ... (repeatable)")
+    run.add_argument("--export", nargs="*", default=[], choices=["csv", "vcd", "svg"])
+    run.add_argument("--loop-gain", help="AC signal that is the loop gain (phase/gain margin)")
+    run.add_argument("--pz", help="IN,OUT nodes for an ngspice pole-zero analysis")
+    run.add_argument("--engine", choices=["ngspice", "ltspice"], default="ngspice")
+
+    tun = actions.add_parser("tune", help="change a value until a measurement meets a target")
+    circuit_flags(tun)
+    tun.add_argument("--param", required=True, help="R1, a tied group R1,R2, or param:NAME")
+    tun.add_argument("--target", required=True, help="e.g. 'f3db(v(out))=500'")
+    tun.add_argument("--tol", type=float, default=0.01, help="relative tolerance (default 0.01)")
+    tun.add_argument("--bounds", help="LOW,HIGH for the parameter")
+
+    plot = actions.add_parser("plot", help="plot or export a rawfile")
+    plot.add_argument("raw")
+    plot.add_argument("--signal", action="append", default=[])
+    plot.add_argument("--formats", nargs="*", default=["svg"], choices=["svg", "csv", "vcd"])
+    plot.add_argument("--out", default=".traceforge/sim")
+    plot.add_argument("--json", action="store_true")
+
+
+def _analysis(args) -> object:
+    for kind in ("ac", "tran", "dc", "noise"):
+        text = getattr(args, kind, None)
+        if text:
+            return parse_analysis(f".{kind} {text}")
+    if args.op:
+        return parse_analysis(".op")
+    raise SimError("choose an analysis: --ac, --tran, --dc, --noise or --op")
+
+
+def _sources(items: list[str]) -> list[dict]:
+    out = []
+    for item in items:
+        net, _, rest = item.partition("=")
+        dc, _, ac = rest.partition(":")
+        src = {"pos": net, "dc": dc or "0"}
+        if ac:
+            src["ac"] = ac
+        out.append(src)
+    return out
+
+
+def _circuit(args):
+    circuit = load_circuit(args.file, args.out, sources=_sources(args.source), ground=args.ground)
+    for item in args.set:
+        ref, _, value = item.partition("=")
+        circuit.set_value(ref, value)
+    return circuit
+
+
+def cmd_sim(args) -> int:
+    try:
+        if args.sim_action == "plot":
+            data = replot(args.raw, args.out, args.signal or None, args.formats)
+        else:
+            circuit = _circuit(args)
+            analysis = _analysis(args)
+            if args.sim_action == "run":
+                if args.pz:
+                    analysis.pz = tuple(args.pz.split(",", 1))
+                if args.engine == "ltspice":
+                    data = export_ltspice(circuit, [analysis], args.out, Path(args.file).stem)
+                else:
+                    data = simulate(
+                        circuit,
+                        analysis,
+                        args.out,
+                        meas=args.meas,
+                        probes=args.probe,
+                        export=args.export,
+                        loop=args.loop_gain,
+                    )
+            else:
+                bounds = tuple(float(v) for v in args.bounds.split(",")) if args.bounds else None
+                result = tune(
+                    circuit,
+                    args.param,
+                    args.target,
+                    args.tol,
+                    analysis=analysis,
+                    bounds=bounds,
+                    workdir=args.out,
+                    meas=args.meas or None,
+                )
+                data = result.to_dict()
+    except (SimError, ValueError, KeyError, OSError) as exc:
+        print(f"sim: {exc}")
+        return 1
+    if args.json:
+        print(json.dumps(data, indent=2, default=str))
+        return 0
+    _print(data)
+    return 0 if data.get("converged", True) else 2
+
+
+def _print(data: dict) -> None:
+    if "iterations" in data:
+        print(f"tune {data['parameter']}: {data['quantity']} -> {data['target']:g}")
+        for it in data["iterations"]:
+            print(
+                f"  {it['n']:>2}  value {it['value']:<12.6g} measured {it['measured']:<12.6g} error {it['error_pct']:+.3f} %"
+            )
+        verdict = "met" if data["converged"] else "NOT met"
+        print(
+            f"target {verdict}: {data['final_value']:.6g} gives {data['measured']:.6g} ({data['reason']})"
+        )
+        return
+    if "summary" in data:
+        print(data["summary"])
+    for key in ("bandwidth", "poles", "second_order", "margins", "operating_point"):
+        if key in data:
+            print(f"{key}: {json.dumps(data[key], default=str)}")
+    for key, value in (data.get("files") or {}).items():
+        print(f"{key}: {value}")
+    for key in ("netlist", "schematic", "note"):
+        if key in data:
+            print(f"{key}: {data[key]}")