traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/sim/engine.py

@@ -0,0 +1,172 @@
+"""Run ngspice in batch mode and collect the rawfile, ``.meas`` values and pole/zero output."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge.sim.circuit import Circuit, SimError
+from traceforge.sim.rawfile import Plot, read_raw
+
+
+def find_ngspice() -> str | None:
+    return os.environ.get("TRACEFORGE_NGSPICE") or shutil.which("ngspice")
+
+
+@dataclass
+class Analysis:
+    kind: str  # op | dc | ac | tran | noise
+    line: str  # the SPICE directive
+    pz: tuple[str, str] | None = None  # (input node, output node) for a .pz estimate
+
+
+_KINDS = {"op", "dc", "ac", "tran", "noise"}
+
+
+def parse_analysis(spec: object) -> Analysis:
+    """Accept an Analysis, a directive (``.ac dec 20 10 100k`` or ``ac dec 20 10 100k``) or a dict
+    such as ``{"type": "tran", "step": "1u", "stop": "5m"}``."""
+    if isinstance(spec, Analysis):
+        return spec
+    if isinstance(spec, str):
+        text = spec.strip()
+        text = text if text.startswith(".") else "." + text
+        kind = text[1:].split()[0].lower() if text[1:].split() else ""
+        if kind not in _KINDS:
+            raise SimError(f"unknown analysis {spec!r}; use op, dc, ac, tran or noise")
+        return Analysis(kind, text)
+    if isinstance(spec, dict):
+        d = {k.lower(): v for k, v in spec.items()}
+        kind = str(d.get("type") or d.get("kind") or "").lower()
+        pz = (str(d["pz"][0]), str(d["pz"][1])) if d.get("pz") else None
+        if kind == "op":
+            return Analysis("op", ".op", pz)
+        if kind == "dc":
+            line = f".dc {d['source']} {d['start']} {d['stop']} {d['step']}"
+        elif kind == "ac":
+            line = f".ac {d.get('sweep', 'dec')} {d.get('points', 20)} {d['start']} {d['stop']}"
+        elif kind == "tran":
+            line = f".tran {d['step']} {d['stop']}"
+            if d.get("tstart") or d.get("max_step"):
+                line += f" {d.get('tstart', 0)}"
+                line += f" {d['max_step']}" if d.get("max_step") else ""
+            if d.get("uic"):
+                line += " uic"
+        elif kind == "noise":
+            line = (
+                f".noise {d['output']} {d['source']} {d.get('sweep', 'dec')} "
+                f"{d.get('points', 10)} {d['start']} {d['stop']}"
+            )
+        else:
+            raise SimError("analysis 'type' must be op, dc, ac, tran or noise")
+        return Analysis(kind, line, pz)
+    raise SimError(f"cannot read analysis {spec!r}")
+
+
+@dataclass
+class SimRun:
+    deck: Path
+    log: Path
+    raw: Path | None
+    plots: list[Plot]
+    analysis: Analysis
+    measures: dict[str, float | None] = field(default_factory=dict)
+    poles: list[complex] = field(default_factory=list)
+    zeros: list[complex] = field(default_factory=list)
+    problems: list[str] = field(default_factory=list)
+    circuit: Circuit | None = None
+    version: str = ""
+
+    @property
+    def plot(self) -> Plot:
+        return self.plots[0]
+
+
+_MEAS = re.compile(r"^\s*([A-Za-z_]\w*)\s*=\s*([-+]?[0-9.]+(?:e[-+]?\d+)?|failed)\b", re.I)
+_PZ = re.compile(r"^\s*(pole|zero)\(\d+\)\s*=\s*([-+0-9.eE]+),\s*([-+0-9.eE]+)")
+_PROBLEM = re.compile(
+    r"^\s*(error|warning|fatal|.*singular matrix|.*timestep too small|.*no such vector|"
+    r".*could not find|.*unknown subckt|.*can't find|.*doesn't exist).*",
+    re.I,
+)
+
+
+def run_ngspice(
+    circuit: Circuit | str,
+    analysis: object,
+    workdir: str | Path,
+    *,
+    meas: list[str] | None = None,
+    save: list[str] | None = None,
+    timeout: float = 120,
+    name: str = "run",
+) -> SimRun:
+    """Run one analysis.  ``meas`` are ``.meas`` lines; ``save`` extra vectors such as ``@r1[i]``."""
+    exe = find_ngspice()
+    if exe is None:
+        raise SimError(
+            "ngspice not found: install it (apt/brew/choco install ngspice) or set TRACEFORGE_NGSPICE"
+        )
+    work = Path(workdir)
+    work.mkdir(parents=True, exist_ok=True)
+    ana = parse_analysis(analysis)
+    circ = Circuit.from_text(circuit) if isinstance(circuit, str) else circuit
+    other = [
+        d
+        for d in circ.directives
+        if not d.lower().startswith((".ac", ".tran", ".dc", ".op", ".noise", ".pz", ".tf"))
+    ]
+    saved = [f".save all {' '.join(save)}"] if save else []
+    extra = [ana.line, *(meas or []), *saved]
+    raw_name = f"{name}.raw"
+    control = ["set filetype=binary", "run"]
+    if ana.kind == "noise":
+        control.append("setplot noise1")
+    control.append(f"write {raw_name} all")
+    if ana.pz:
+        control += [f"pz {ana.pz[0]} 0 {ana.pz[1]} 0 vol pz", "print all"]
+    control.append("quit")
+    shadow = Circuit(**{**circ.__dict__, "directives": other})
+    deck = work / f"{name}.cir"
+    deck.write_text(shadow.to_spice(extra, control), encoding="utf-8")
+    log = work / f"{name}.log"
+    raw = work / raw_name
+    raw.unlink(missing_ok=True)
+    try:
+        done = subprocess.run(  # noqa: S603 - fixed executable, list args
+            [exe, "-b", "-o", log.name, deck.name],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=work,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise SimError(f"ngspice timed out after {timeout:g} s") from exc
+    except OSError as exc:
+        raise SimError(f"ngspice failed to start: {exc}") from exc
+    text = (log.read_text(encoding="utf-8", errors="replace") if log.exists() else "") + done.stdout
+    problems = [m.group(0).strip() for m in map(_PROBLEM.match, text.splitlines()) if m]
+    if not raw.exists() or raw.stat().st_size == 0:
+        detail = "; ".join(problems[:4]) or text.strip()[-400:]
+        raise SimError(f"ngspice produced no results: {detail}")
+    all_meas = [*(meas or []), *(d for d in circ.directives if d.lower().startswith(".meas"))]
+    wanted = {m.split()[2] for m in all_meas if len(m.split()) > 2}
+    measures: dict[str, float | None] = {}
+    poles: list[complex] = []
+    zeros: list[complex] = []
+    for line in text.splitlines():
+        if pz := _PZ.match(line):
+            (poles if pz.group(1) == "pole" else zeros).append(
+                complex(float(pz.group(2)), float(pz.group(3)))
+            )
+        elif (m := _MEAS.match(line)) and m.group(1).lower() in {w.lower() for w in wanted}:
+            measures[m.group(1).lower()] = None if m.group(2) == "failed" else float(m.group(2))
+    version = next((ln.strip("* ").strip() for ln in text.splitlines() if "ngspice-" in ln), "")
+    return SimRun(
+        deck, log, raw, read_raw(raw), ana, measures, poles, zeros, problems, circ, version
+    )

traceforge/sim/ltspice.py

@@ -0,0 +1,175 @@
+"""LTspice support: netlist and ``.asc`` generation, compatibility warnings, ``.raw`` reader.
+
+LTspice does not run on Linux, so nothing here runs it.  The files are written for LTspice
+to open; the generated ``.asc`` has not been opened in LTspice by the author of this code.
+Models that only LTspice understands cannot run in ngspice; ``compat_warnings`` lists the
+usual markers.
+"""
+
+from __future__ import annotations
+
+import re
+import struct
+from pathlib import Path
+
+from traceforge.sim.circuit import Circuit, SimError
+from traceforge.sim.rawfile import Plot
+
+# (pattern, what is wrong for the other simulator)
+_LTSPICE_ONLY = [
+    (
+        r"\b(Rser|Lser|Cpar|Rpar|Rdamp|Ipk|Vpk)\s*=",
+        "LTspice-only component parameters (Rser, Cpar, ...)",
+    ),
+    (r"\bmfg\s*=|\bVDMOS\b", "LTspice-only model syntax (mfg=, VDMOS)"),
+    (r"\.backanno|\.wave\b|\.savebias", "LTspice-only dot command"),
+    (r"\btable\s*\(", "LTspice table() function; ngspice uses a different table syntax"),
+    (
+        r"\bltc\w*\.(lib|sub)|\blib\b.*\\LTC\\|\bstandard\.(dio|bjt|mos|jft|cap|ind|res)\b",
+        "LTspice installation library; not available to ngspice",
+    ),
+]
+# What ngspice (as used here) cannot read from an LTspice-flavoured deck.
+_NGSPICE_ONLY = [(r"^\s*\.control\b", "ngspice .control block; LTspice ignores or rejects it")]
+
+
+def compat_warnings(text: str, target: str = "ngspice") -> list[str]:
+    """Markers of models the other simulator cannot run."""
+    rules = _LTSPICE_ONLY if target == "ngspice" else _NGSPICE_ONLY
+    return [msg for pat, msg in rules if re.search(pat, text, re.I | re.M)]
+
+
+def write_netlist(circuit: Circuit, analysis: list[str], path: str | Path) -> Path:
+    """A SPICE netlist LTspice can open (File > Open) and run.  Generic models are included."""
+    text = circuit.to_spice(list(analysis))
+    path = Path(path)
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+# symbol name, pin offsets from the symbol origin (R0), node index order
+_SYMBOLS = {
+    "R": ("res", [(16, 16), (16, 96)]),
+    "C": ("cap", [(16, 0), (16, 64)]),
+    "L": ("ind", [(16, 16), (16, 80)]),
+    "D": ("diode", [(16, 0), (16, 64)]),  # anode, cathode (circuit order: anode first)
+    "V": ("voltage", [(0, 16), (0, 96)]),
+}
+
+
+def write_asc(circuit: Circuit, analysis: list[str], path: str | Path) -> Path:
+    """An LTspice schematic: R, C, L, D and V as symbols with net flags on every pin (no wires
+    needed), everything else as SPICE directives with the same node names."""
+    lines = ["Version 4", "SHEET 1 1400 1000"]
+    texts: list[str] = []
+    placed = 0
+    for el in circuit.elements:
+        sym = _SYMBOLS.get(el.kind)
+        if sym is None or len(el.nodes) != 2 or el.ref.upper().startswith("X"):
+            texts.append(el.line())
+            continue
+        name, pins = sym
+        x, y = 96 + (placed % 6) * 200, 96 + (placed // 6) * 200
+        placed += 1
+        lines.append(f"SYMBOL {name} {x} {y} R0")
+        lines.append(f"SYMATTR InstName {el.ref}")
+        lines.append(f"SYMATTR Value {el.value}")
+        for (dx, dy), node in zip(pins, el.nodes, strict=True):
+            lines.append(f"FLAG {x + dx} {y + dy} {node}")
+    ty = 96 + ((placed + 5) // 6) * 200 + 40
+    for block in circuit.blocks.values():
+        lines.append(f"TEXT 96 {ty} Left 2 !" + block.replace("\n", "\\n"))
+        ty += 40
+    for text in [*texts, *circuit.includes, *analysis]:
+        lines.append(f"TEXT 96 {ty} Left 2 !{text}")
+        ty += 40
+    path = Path(path)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return path
+
+
+def read_ltspice_raw(path: str | Path) -> Plot:
+    """Read an LTspice binary ``.raw`` (UTF-16 or ASCII header, ``Binary:`` data).
+
+    Real analyses store the sweep variable as a double and the others as single floats;
+    complex (AC) analyses store every value as two doubles.  The ``fastaccess`` layout and
+    stepped runs are not supported and raise a clear error.
+    """
+    blob = Path(path).read_bytes()
+    wide = blob[:4] == b"T\x00i\x00"
+    marker = "Binary:\n".encode("utf-16-le" if wide else "latin-1")
+    cut = blob.find(marker)
+    if cut < 0:
+        raise SimError(f"{path}: no 'Binary:' section (ASCII LTspice raw files are not supported)")
+    header = blob[:cut].decode("utf-16-le" if wide else "latin-1")
+    body = blob[cut + len(marker) :]
+    fields: dict[str, str] = {}
+    names: list[str] = []
+    types: list[str] = []
+    in_vars = False
+    for line in header.splitlines():
+        if in_vars and line[:1] in " \t":
+            parts = line.split()
+            names.append(parts[1])
+            types.append(parts[2] if len(parts) > 2 else "")
+            continue
+        key, _, rest = line.partition(":")
+        in_vars = key.strip() == "Variables"
+        if not in_vars:
+            fields[key.strip()] = rest.strip()
+    flags = fields.get("Flags", "").lower()
+    if "fastaccess" in flags:
+        raise SimError("LTspice 'fastaccess' raw files are not supported; save without Fast Access")
+    n_vars, n_points = int(fields["No. Variables"]), int(fields["No. Points"])
+    if n_points and any(n == names[0] for n in names[1:]) and "stepped" in flags:
+        raise SimError("stepped LTspice runs are not supported")
+    cplx = "complex" in flags
+    plot = Plot(fields.get("Plotname", ""), fields.get("Title", ""), cplx, names, types)
+    cols: list[list] = [[] for _ in names]
+    off = 0
+    for _ in range(n_points):
+        for j in range(n_vars):
+            if cplx:
+                re_, im = struct.unpack_from("<dd", body, off)
+                off += 16
+                cols[j].append(complex(re_, im))
+            elif j == 0:
+                cols[j].append(abs(struct.unpack_from("<d", body, off)[0]))  # negative = compressed
+                off += 8
+            else:
+                cols[j].append(struct.unpack_from("<f", body, off)[0])
+                off += 4
+    plot.data = {n.lower(): c for n, c in zip(names, cols, strict=True)}
+    return plot
+
+
+def write_ltspice_raw(plot: Plot, path: str | Path) -> Path:
+    """Write ``plot`` in LTspice's layout.  Used to test the reader on a synthetic file."""
+    n = len(plot.names)
+    head = [
+        f"Title: {plot.title}",
+        "Date: Thu Jan 01 00:00:00 2026",
+        f"Plotname: {plot.name}",
+        f"Flags: {'complex' if plot.complex else 'real'}",
+        f"No. Variables: {n}",
+        f"No. Points: {len(plot.x)}",
+        "Offset: 0.0000000000000000e+000",
+        "Command: synthetic",
+        "Variables:",
+        *[
+            f"\t{i}\t{nm}\t{tp}"
+            for i, (nm, tp) in enumerate(zip(plot.names, plot.types, strict=True))
+        ],
+        "Binary:\n",
+    ]
+    out = bytearray("\n".join(head).encode("utf-16-le"))
+    for k in range(len(plot.x)):
+        for j, nm in enumerate(plot.names):
+            v = plot.data[nm.lower()][k]
+            if plot.complex:
+                out += struct.pack("<dd", v.real, v.imag)
+            else:
+                out += struct.pack("<d", v) if j == 0 else struct.pack("<f", v)
+    path = Path(path)
+    path.write_bytes(bytes(out))
+    return path

traceforge/sim/measure.py

@@ -0,0 +1,123 @@
+"""Named measurements on a result, e.g. ``f3db(v(out))`` or ``i(R5)``."""
+
+from __future__ import annotations
+
+import math
+import re
+
+from traceforge.sim import acmath
+from traceforge.sim.circuit import SimError, parse_value
+from traceforge.sim.results import Result
+
+FUNCTIONS = (
+    "f3db, dc_gain_db(v), gain_db(v, f), phase_deg(v, f), peak_db(v), f_peak(v), "
+    "unity_gain_freq(v), phase_margin(v), gain_margin(v), value(v), final(v), max(v), min(v), "
+    "pp(v), mean(v), rms(v), rise_time(v), meas(name), v(node), i(Rref)"
+)
+
+
+def _split(args: str) -> list[str]:
+    out, depth, cur = [], 0, ""
+    for ch in args:
+        depth += ch == "("
+        depth -= ch == ")"
+        if ch == "," and depth == 0:
+            out.append(cur.strip())
+            cur = ""
+        else:
+            cur += ch
+    return [*out, cur.strip()] if cur.strip() else out
+
+
+def _real(values: list) -> list[float]:
+    return [v.real if isinstance(v, complex) else v for v in values]
+
+
+def _time_avg(t: list[float], y: list[float], square: bool = False) -> float:
+    total = 0.0
+    for i in range(1, len(t)):
+        a, b = (y[i - 1] ** 2, y[i] ** 2) if square else (y[i - 1], y[i])
+        total += (a + b) / 2 * (t[i] - t[i - 1])
+    span = t[-1] - t[0]
+    return total / span if span > 0 else y[-1]
+
+
+def measure(result: Result, spec: str) -> float:
+    text = spec.strip()
+    m = re.fullmatch(r"(\w+)\((.*)\)", text)
+    if not m:
+        m = re.fullmatch(r"(\w+)", text)
+        if not m:
+            raise SimError(f"cannot read measurement {spec!r}; known: {FUNCTIONS}")
+        name, args = m.group(1).lower(), []
+    else:
+        name, args = m.group(1).lower(), _split(m.group(2))
+    if name in {"v", "i"}:
+        return float(_real([result.value(text)])[0])
+    if name == "meas":
+        run = result.run
+        value = run.measures.get(args[0].lower()) if run else None
+        if value is None:
+            raise SimError(f".meas {args[0]!r} did not produce a value")
+        return value
+    if not args and name == "f3db":
+        args = [result.table()[0]]
+    sig = result.signal(args[0])
+    x = result.x
+    if name in {"value", "final"}:
+        return float(_real([sig[-1]])[0])
+    if result.plot.complex:
+        return _ac(name, x, sig, args)
+    y = _real(sig)
+    if name == "max":
+        return max(y)
+    if name == "min":
+        return min(y)
+    if name == "pp":
+        return max(y) - min(y)
+    if name == "mean":
+        return _time_avg(x, y)
+    if name == "rms":
+        return math.sqrt(_time_avg(x, y, square=True))
+    if name == "rise_time":
+        lo, hi = min(y), max(y)
+        t10 = _first_cross(x, y, lo + 0.1 * (hi - lo))
+        t90 = _first_cross(x, y, lo + 0.9 * (hi - lo))
+        if t10 is None or t90 is None:
+            raise SimError("no rising edge to time")
+        return t90 - t10
+    raise SimError(f"{name!r} needs an AC result or is unknown; known: {FUNCTIONS}")
+
+
+def _first_cross(x: list[float], y: list[float], level: float) -> float | None:
+    for i in range(1, len(x)):
+        if y[i - 1] < level <= y[i]:
+            return x[i - 1] + (level - y[i - 1]) / (y[i] - y[i - 1]) * (x[i] - x[i - 1])
+    return None
+
+
+def _ac(name: str, f: list[float], h: list[complex], args: list[str]) -> float:
+    if name in {"f3db", "fc"}:
+        v = acmath.bandwidth(f, h)["f3db"]
+    elif name == "dc_gain_db":
+        return acmath.mag_db(h[0])
+    elif name == "gain_db":
+        return acmath.interp_log(f, [acmath.mag_db(v) for v in h], parse_value(args[1]))
+    elif name == "phase_deg":
+        return acmath.interp_log(f, acmath.phase_deg(h), parse_value(args[1]))
+    elif name in {"peak_db", "f_peak"}:
+        db = [acmath.mag_db(v) for v in h]
+        return max(db) if name == "peak_db" else f[db.index(max(db))]
+    else:
+        margins = acmath.stability_margins(f, h)
+        key = {
+            "unity_gain_freq": "unity_gain_freq",
+            "phase_margin": "phase_margin_deg",
+            "gain_margin": "gain_margin_db",
+        }.get(name)
+        if key is None:
+            raise SimError(f"unknown measurement {name!r}; known: {FUNCTIONS}")
+        v = margins[key]
+    if v is None:
+        raise SimError(f"{name} does not exist in this response (no crossing in the swept range)")
+    return float(v)

traceforge/sim/models.py

@@ -0,0 +1,76 @@
+"""Generic SPICE models used when a part has no vendor model.
+
+Every model here is a *generic stand-in*, not the real part: an ideal-ish op-amp, a
+behavioural linear regulator, a typical small-signal diode, an LED with a colour-typical
+forward voltage, level-1 MOSFETs and simple BJTs.  The netlist exporter records each one
+in ``Circuit.generic`` so results can say so.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+OPAMP = """.subckt OPAMP_IDEAL inp inn out PARAMS: gain=1e6 gbw=10meg
+* GENERIC single-pole op-amp: open-loop gain, gain-bandwidth product, ideal output
+Gm 0 p inp inn {gain/1k}
+Rp p 0 1k
+Cp p 0 {gain/(6.283185307*gbw*1k)}
+Eo out 0 p 0 1
+.ends OPAMP_IDEAL"""
+
+LDO = """.subckt LDO_GENERIC vin vout gnd PARAMS: vset=3.3 vdo=1.0 rout=0.05 iq=5m
+* GENERIC behavioural linear regulator: fixed output, dropout, output resistance, quiescent current
+Bv x gnd V=max(0, min(V(vin,gnd)-{vdo}, {vset}))
+Ro x vout {rout}
+Iq vin gnd {iq}
+.ends LDO_GENERIC"""
+
+DIODES = {
+    "D_SIGNAL": ".model D_SIGNAL D(IS=2.5n N=1.75 RS=0.6 CJO=4p TT=5n BV=100 IBV=0.1u)",
+    "D_RECTIFIER": ".model D_RECTIFIER D(IS=5n N=1.7 RS=0.04 CJO=40p TT=5u BV=100 IBV=5u)",
+    "D_SCHOTTKY": ".model D_SCHOTTKY D(IS=1u N=1.05 RS=0.08 CJO=100p TT=1n BV=40 IBV=10u)",
+    "D_ZENER": ".model D_ZENER D(IS=5n N=1.7 RS=2 BV=5.1 IBV=5m)",
+}
+MOS = {
+    "NMOS_GENERIC": ".model NMOS_GENERIC NMOS(LEVEL=1 VTO=2 KP=0.2 LAMBDA=0.01 CBD=50p CGSO=1n)",
+    "PMOS_GENERIC": ".model PMOS_GENERIC PMOS(LEVEL=1 VTO=-2 KP=0.1 LAMBDA=0.01 CBD=50p CGSO=1n)",
+}
+BJT = {
+    "NPN_GENERIC": ".model NPN_GENERIC NPN(BF=200 IS=1e-14 VAF=100 CJE=10p CJC=5p TF=0.4n)",
+    "PNP_GENERIC": ".model PNP_GENERIC PNP(BF=150 IS=1e-14 VAF=60 CJE=10p CJC=5p TF=0.5n)",
+}
+
+# Typical forward voltage at 2 mA for common LED colours (volts).
+LED_VF = {
+    "RED": 1.9,
+    "ORANGE": 2.0,
+    "AMBER": 2.0,
+    "YELLOW": 2.0,
+    "GREEN": 2.1,
+    "BLUE": 3.0,
+    "WHITE": 3.0,
+    "UV": 3.3,
+    "IR": 1.3,
+}
+_VT = 0.025852
+
+
+def led_model(color: str) -> tuple[str, str, float]:
+    """(model name, .model line, Vf at 2 mA) for a colour name; unknown colours use red."""
+    color = color.upper()
+    vf = LED_VF.get(color)
+    key = color if vf else "RED"
+    vf = vf or LED_VF["RED"]
+    n = 2.0
+    isat = 2e-3 / math.exp(vf / (n * _VT))
+    name = f"LED_{key}"
+    return name, f".model {name} D(IS={isat:.3e} N={n} RS=4 CJO=30p BV=5 IBV=10u)", vf
+
+
+def led_color(*texts: str) -> str:
+    for text in texts:
+        for word in re.split(r"[^A-Za-z]+", text.upper()):
+            if word in LED_VF:
+                return word
+    return "RED"