BCurrent

Bases: Component

Behavioral current source with arbitrary expression.

SPICE card: B

I=

The expression is passed directly to the SPICE engine.

Parameters:

Name	Type	Description	Default
ref	str	Reference designator	required
expr	str	Current expression (e.g., "I(Vref)*10", "V(in)/1k")	required

Ports

p: positive terminal (current flows out) n: negative terminal (current flows in)

Example

Current mirror with gain

b1 = BCurrent("1", expr="I(Vref)*10")

Voltage-to-current conversion

b2 = BCurrent("2", expr="V(in)/1000")

Source code in spicelab/core/components.py

class BCurrent(Component):
    """Behavioral current source with arbitrary expression.

    SPICE card: B<ref> <p> <n> I=<expression>

    The expression is passed directly to the SPICE engine.

    Args:
        ref: Reference designator
        expr: Current expression (e.g., "I(Vref)*10", "V(in)/1k")

    Ports:
        p: positive terminal (current flows out)
        n: negative terminal (current flows in)

    Example:
        # Current mirror with gain
        b1 = BCurrent("1", expr="I(Vref)*10")

        # Voltage-to-current conversion
        b2 = BCurrent("2", expr="V(in)/1000")
    """

    def __init__(self, ref: str, expr: str) -> None:
        super().__init__(ref=ref, value=expr)
        self.expr = expr
        self._ports = (
            Port(self, "p", PortRole.POSITIVE),
            Port(self, "n", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        return f"B{self.ref} {net_of(p)} {net_of(n)} I={self.expr}"

BVoltage

Bases: Component

Behavioral voltage source with arbitrary expression.

SPICE card: B

V=

The expression is passed directly to the SPICE engine.

Parameters:

Name	Type	Description	Default
ref	str	Reference designator	required
expr	str	Voltage expression (e.g., "V(in)*2", "IF(V(ctrl)>2.5, 5, 0)")	required

Ports

p: positive terminal n: negative terminal

Example

Voltage doubler

b1 = BVoltage("1", expr="V(in)*2")

Conditional output

b2 = BVoltage("2", expr="IF(V(ctrl)>2.5, 5, 0)")

Source code in spicelab/core/components.py

class BVoltage(Component):
    """Behavioral voltage source with arbitrary expression.

    SPICE card: B<ref> <p> <n> V=<expression>

    The expression is passed directly to the SPICE engine.

    Args:
        ref: Reference designator
        expr: Voltage expression (e.g., "V(in)*2", "IF(V(ctrl)>2.5, 5, 0)")

    Ports:
        p: positive terminal
        n: negative terminal

    Example:
        # Voltage doubler
        b1 = BVoltage("1", expr="V(in)*2")

        # Conditional output
        b2 = BVoltage("2", expr="IF(V(ctrl)>2.5, 5, 0)")
    """

    def __init__(self, ref: str, expr: str) -> None:
        super().__init__(ref=ref, value=expr)
        self.expr = expr
        self._ports = (
            Port(self, "p", PortRole.POSITIVE),
            Port(self, "n", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        return f"B{self.ref} {net_of(p)} {net_of(n)} V={self.expr}"

Capacitor

Bases: Component

Capacitor de 2 terminais; portas: a (positivo), b (negativo).

Parameters:

Name	Type	Description	Default
ref	str	Reference designator (e.g., "1" for C1)	required
value	str | float	Legacy stringly-typed value (backward compat)	''
capacitance	float | ParameterRef | None	Typed capacitance value (float or ParameterRef)	None

Use either value OR capacitance, not both.

Source code in spicelab/core/components.py

class Capacitor(Component):
    """Capacitor de 2 terminais; portas: a (positivo), b (negativo).

    Args:
        ref: Reference designator (e.g., "1" for C1)
        value: Legacy stringly-typed value (backward compat)
        capacitance: Typed capacitance value (float or ParameterRef)

    Use either `value` OR `capacitance`, not both.
    """

    def __init__(
        self,
        ref: str,
        value: str | float = "",
        capacitance: float | ParameterRef | None = None,
    ) -> None:
        super().__init__(ref=ref, value=value)
        self.capacitance = capacitance
        self._ports = (Port(self, "a", PortRole.POSITIVE), Port(self, "b", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        a, b = self.ports
        # Use typed field if present, otherwise fall back to value
        val = str(self.capacitance) if self.capacitance is not None else self.value
        return f"C{self.ref} {net_of(a)} {net_of(b)} {val}"

Circuit dataclass

Logical circuit composed of components, nets and raw SPICE directives.

Source code in spicelab/core/circuit.py

@dataclass
class Circuit:
    """Logical circuit composed of components, nets and raw SPICE directives."""

    name: str
    _net_ids: dict[Net, int] = field(default_factory=dict, init=False)
    _port_to_net: dict[Port, Net] = field(default_factory=dict, init=False)
    _components: list[Component] = field(default_factory=list, init=False)
    _directives: list[str] = field(default_factory=list, init=False)
    # metadata captured when loading from existing netlists
    _subckt_defs: dict[str, str] = field(default_factory=dict, init=False)
    _subckt_instances: list[dict[str, object]] = field(default_factory=list, init=False)
    _port_labels: dict[Port, str] = field(default_factory=dict, init=False)
    # Union-Find for O(α(n)) net merging (M2 performance optimization)
    _net_union: UnionFind[Net] = field(default_factory=UnionFind, init=False)
    # Cache invalidation version counter
    _cache_version: int = field(default=0, init=False)

    # ----------------------------------------------------------------------------------
    # Building blocks
    # ----------------------------------------------------------------------------------
    def add(self, *components: Component) -> Circuit:
        """Append one or more components to the circuit."""

        self._components.extend(components)
        return self

    def add_directive(self, line: str) -> Circuit:
        """Append a raw SPICE directive (``.model``, ``.param`` ...)."""

        self._directives.append(line.rstrip("\n"))
        return self

    def add_directive_once(self, line: str) -> Circuit:
        """Add a directive if an identical line (ignoring whitespace) is absent."""

        normalized = line.strip()
        for existing in self._directives:
            if existing.strip() == normalized:
                return self
        return self.add_directive(line)

    def connect(self, a: Port, b: Net | Port) -> Circuit:
        """Connect a port to another port or to a logical net.

        Uses Union-Find for O(α(n)) amortized net merging (M2 optimization).
        """
        self._invalidate_cache()

        if isinstance(b, Port):
            net_a = self._port_to_net.get(a)
            net_b = self._port_to_net.get(b)

            if net_a and net_b and net_a is not net_b:
                # Merge using Union-Find: O(α(n)) instead of O(n)
                # Ensure both nets are in union-find
                if net_a not in self._net_union:
                    is_named_a = getattr(net_a, "name", None) is not None
                    self._net_union.make_set(net_a, net_a if is_named_a else None)
                if net_b not in self._net_union:
                    is_named_b = getattr(net_b, "name", None) is not None
                    self._net_union.make_set(net_b, net_b if is_named_b else None)

                # Prefer named net as canonical
                prefer = None
                if getattr(net_a, "name", None):
                    prefer = net_a
                elif getattr(net_b, "name", None):
                    prefer = net_b

                self._net_union.union(net_a, net_b, prefer=prefer)
            else:
                shared = net_a or net_b or Net()
                self._port_to_net[a] = shared
                self._port_to_net[b] = shared
                # Register in union-find
                if shared not in self._net_union:
                    is_named = getattr(shared, "name", None) is not None
                    self._net_union.make_set(shared, shared if is_named else None)
            self._port_labels.pop(b, None)
        else:
            self._port_to_net[a] = b
            # Register named net in union-find
            if b not in self._net_union:
                is_named = getattr(b, "name", None) is not None
                self._net_union.make_set(b, b if is_named else None)
        self._port_labels.pop(a, None)
        return self

    def _invalidate_cache(self) -> None:
        """Invalidate cached properties when circuit is modified."""
        self._cache_version += 1
        # Clear cached net IDs
        self._net_ids.clear()

    def connect_with_label(self, port: Port, net: Net, label: str | None = None) -> Circuit:
        """Connect ``port`` to ``net`` while recording a display label."""

        self.connect(port, net)
        if label:
            self._port_labels[port] = label
        return self

    # ----------------------------------------------------------------------------------
    # Net handling
    # ----------------------------------------------------------------------------------
    def _assign_node_ids(self) -> None:
        """Assign node IDs, using Union-Find for canonical net resolution."""
        self._net_ids.clear()
        self._net_ids[GND] = 0

        next_id = 1
        seen: set[Net] = {GND}

        def canonical_nets_from_components() -> Iterable[Net]:
            for comp in self._components:
                for port in comp.ports:
                    net = self._port_to_net.get(port)
                    if net is not None:
                        # Use canonical net for proper merging
                        yield self._get_canonical_net(net)

        for net in canonical_nets_from_components():
            if net in seen:
                continue
            seen.add(net)
            if getattr(net, "name", None) and net.name != "0":
                # preserve named nets but still assign an id for bookkeeping
                self._net_ids[net] = next_id
            else:
                self._net_ids[net] = next_id
            next_id += 1

    def _net_of(self, port: Port) -> str:
        net = self._port_to_net.get(port)
        if net is None:
            raise ValueError(f"Unconnected port: {port.owner.ref}.{port.name}")

        # Use Union-Find to get the canonical net (handles merged nets)
        canonical_net = self._get_canonical_net(net)

        if canonical_net is GND or getattr(canonical_net, "name", None) == "0":
            return "0"

        if getattr(canonical_net, "name", None):
            return str(canonical_net.name)

        node_id = self._net_ids.get(canonical_net)
        if node_id is None:
            raise RuntimeError("Node IDs not assigned")
        return str(node_id)

    def _get_canonical_net(self, net: Net) -> Net:
        """Get the canonical net for a possibly-merged net using Union-Find."""
        if net not in self._net_union:
            return net
        return self._net_union.get_canonical(net)

    # ----------------------------------------------------------------------------------
    # Netlist helpers
    # ----------------------------------------------------------------------------------
    def build_netlist(self) -> str:
        """Return a SPICE netlist representation of this circuit."""

        self._assign_node_ids()

        lines: list[str] = [f"* {self.name}"]

        for comp in self._components:
            card = comp.spice_card(self._net_of)
            # components such as AnalogMux may emit multi-line cards
            for ln in card.splitlines():
                if ln.strip():
                    lines.append(ln)

        for directive in self._directives:
            lines.extend(directive.splitlines())

        if not any(line.strip().lower() == ".end" for line in lines):
            lines.append(".end")

        return "\n".join(lines) + "\n"

    def save_netlist(self, path: str | Path) -> Path:
        """Persist the netlist to ``path`` and return the resolved ``Path``."""

        p = Path(path)
        p.write_text(self.build_netlist(), encoding="utf-8")
        return p

    # ----------------------------------------------------------------------------------
    # Hash (deterministic) - part of M1 contract
    # ----------------------------------------------------------------------------------
    def hash(self, *, extra: dict[str, object] | None = None) -> str:  # pragma: no cover - thin
        """Return a deterministic short hash for this circuit.

        Wrapper around ``spicelab.core.types.circuit_hash`` so callers do not need
        to import the helper directly. ``extra`` can include engine/version/analysis
        args to bind caches firmly to execution context.
        """
        from .types import circuit_hash  # local import to avoid cycle during module init

        return circuit_hash(self, extra=extra)

    # ----------------------------------------------------------------------------------
    # Validation (M4 DX improvement)
    # ----------------------------------------------------------------------------------
    def validate(self, strict: bool = False) -> ValidationResult:
        """Validate circuit topology and component values.

        Performs checks:
        - Ground reference exists
        - No floating nodes (connected to only one component)
        - No unusual component values
        - No voltage source shorts (parallel voltage sources)

        Args:
            strict: If True, treat warnings as errors

        Returns:
            ValidationResult with errors and warnings

        Example:
            >>> result = circuit.validate()
            >>> if result.has_issues():
            ...     print(result)
            >>> if not result.is_valid:
            ...     raise ValueError("Circuit has errors")
        """
        from ..validators.circuit_validation import validate_circuit

        return validate_circuit(self, strict=strict)

    # ----------------------------------------------------------------------------------
    # Introspection helpers
    # ----------------------------------------------------------------------------------
    def _net_label(self, net: Net | None) -> str:
        if net is None:
            return "<unconnected>"

        # Use canonical net for merged nets
        canonical = self._get_canonical_net(net)

        if canonical is GND or getattr(canonical, "name", None) == "0":
            return "0"
        if getattr(canonical, "name", None):
            return str(canonical.name)
        node_id = self._net_ids.get(canonical)
        if node_id is None:
            self._assign_node_ids()
            node_id = self._net_ids.get(canonical)
        return f"N{node_id:03d}" if node_id is not None else "<unnamed>"

    def summary(self) -> str:
        """Return a human-readable summary of the circuit and connectivity."""

        self._assign_node_ids()

        lines: list[str] = []
        warnings: list[str] = []

        lines.append(f"Circuit: {self.name}")
        lines.append(f"Components ({len(self._components)}):")

        for comp in self._components:
            port_descriptions: list[str] = []
            for port in comp.ports:
                net = self._port_to_net.get(port)
                label = self._port_labels.get(port) or self._net_label(net)
                if label == "<unconnected>":
                    warnings.append(f"Port {comp.ref}.{port.name} is unconnected")
                port_descriptions.append(f"{port.name}->{label}")
            port_info = ", ".join(port_descriptions) if port_descriptions else "<no ports>"
            lines.append(f"  - {comp.ref} ({type(comp).__name__}): {port_info}")

        net_names = sorted({self._net_label(net) for net in self._port_to_net.values() if net})
        if net_names:
            lines.append(f"Nets ({len(net_names)}): {', '.join(net_names)}")

        if warnings:
            lines.append("Warnings:")
            for msg in warnings:
                lines.append(f"  * {msg}")
        else:
            lines.append("Warnings: none")

        return "\n".join(lines)

    def to_dot(self) -> str:
        """Return a Graphviz DOT representation of the circuit."""

        self._assign_node_ids()

        lines: list[str] = ["graph circuit {", "  rankdir=LR;"]

        comp_ids: dict[Component, str] = {}
        for idx, comp in enumerate(self._components, start=1):
            comp_id = f"comp_{idx}"
            comp_ids[comp] = comp_id
            label = f"{comp.ref}\\n{type(comp).__name__}"
            lines.append(f'  "{comp_id}" [shape=box,label="{label}"];')

        net_ids: dict[Net | None, str] = {}
        net_counter = 1

        def _net_node(net: Net | None) -> str:
            nonlocal net_counter
            if net in net_ids:
                return net_ids[net]
            node_id = f"net_{net_counter}"
            net_counter += 1
            label = self._net_label(net)
            shape = "ellipse" if label != "<unconnected>" else "point"
            net_ids[net] = node_id
            lines.append(f'  "{node_id}" [shape={shape},label="{label}"];')
            return node_id

        for comp in self._components:
            comp_id = comp_ids[comp]
            for port in comp.ports:
                net = self._port_to_net.get(port)
                net_id = _net_node(net)
                lines.append(f'  "{comp_id}" -- "{net_id}" [label="{port.name}",fontsize=10];')

        lines.append("}")
        return "\n".join(lines)

    # ----------------------------------------------------------------------------------
    # Notebook-friendly helpers
    # ----------------------------------------------------------------------------------
    def connectivity_dataframe(self, *, sort: bool = True, include_type: bool = True):
        """Return a pandas DataFrame describing component/net connectivity.

        Columns: ``component``, ``type`` (optional), ``port`` and ``net``. The
        returned DataFrame is ideal for Jupyter notebooks where an interactive
        table is easier to scan than the plain text summary.
        """

        try:
            import pandas as pd
        except Exception as exc:  # pragma: no cover - optional dependency guard
            raise RuntimeError("pandas is required for connectivity_dataframe()") from exc

        self._assign_node_ids()

        rows: list[dict[str, object]] = []
        for comp in self._components:
            for order, port in enumerate(comp.ports):
                net = self._port_to_net.get(port)
                label = self._port_labels.get(port) or self._net_label(net)
                rows.append(
                    {
                        "component": comp.ref,
                        "type": type(comp).__name__,
                        "port": port.name,
                        "net": label,
                        "_order": order,
                    }
                )

        if not rows:
            columns = ["component", "port", "net"]
            if include_type:
                columns.insert(1, "type")
            return pd.DataFrame(columns=columns)

        df = pd.DataFrame(rows)
        if sort:
            df = df.sort_values(["component", "_order", "port"]).reset_index(drop=True)
        if not include_type:
            df = df.drop(columns=["type"])
        return df.drop(columns=["_order"])

    def summary_table(self, *, indent: int = 2) -> str:
        """Return a fixed-width table describing component connections."""

        df = self.connectivity_dataframe()
        if df.empty:
            return "(circuit is empty)"

        headers = list(df.columns)
        display_names = {col: col.capitalize() for col in headers}
        widths = {
            col: max(len(display_names[col]), *(len(str(val)) for val in df[col]))
            for col in headers
        }

        def fmt_row(row: dict[str, object]) -> str:
            cells = [str(row[col]).ljust(widths[col]) for col in headers]
            return " " * indent + "  ".join(cells)

        header_line = " " * indent + "  ".join(
            display_names[col].ljust(widths[col]) for col in headers
        )
        sep_line = " " * indent + "  ".join("-" * widths[col] for col in headers)
        body = "\n".join(fmt_row(df.iloc[idx]) for idx in range(len(df)))
        return f"{header_line}\n{sep_line}\n{body}"

    # ----------------------------------------------------------------------------------
    # Netlist import
    # ----------------------------------------------------------------------------------
    @classmethod
    def from_netlist(cls, path: str | Path) -> Circuit:
        """Load a circuit from a plain SPICE netlist file."""

        p = Path(path)
        text = p.read_text(encoding="utf-8")

        from spicelab.io.spice_parser import parse_lines_to_ast, preprocess_netlist

        lines = preprocess_netlist(text)
        ast = parse_lines_to_ast(lines)

        name = p.stem
        if lines and lines[0].lstrip().startswith("*"):
            maybe_title = lines[0].lstrip()[1:].strip()
            if maybe_title:
                name = maybe_title

        circ = cls(name=name)

        for node in ast:
            kind_obj = node.get("type")
            kind = str(kind_obj) if isinstance(kind_obj, str) else None
            raw_obj = node.get("raw")
            raw = str(raw_obj) if isinstance(raw_obj, str) else ""

            if kind == "subckt":
                header = raw.splitlines()[0]
                parts = header.split()
                if len(parts) >= 2:
                    circ._subckt_defs[parts[1]] = raw
                circ.add_directive(raw)
                continue

            if kind == "comment" or kind == "directive":
                circ.add_directive(raw)
                continue

            if kind != "component":
                continue

            tokens_obj = node.get("tokens")
            tokens: list[str] = [str(t) for t in tokens_obj] if isinstance(tokens_obj, list) else []
            if not tokens:
                continue

            card = tokens[0]
            letter = cast(str | None, node.get("letter"))
            ref = cast(str | None, node.get("ref"))

            try:
                comp = cls._component_from_tokens(letter, ref, tokens)
                if comp is None:
                    circ.add_directive(raw)
                    continue
                circ.add(comp)
                circ._connect_from_tokens(comp, tokens[1:])
                if letter == "X":
                    circ._subckt_instances.append(
                        {"inst": card, "subckt": tokens[-1], "tokens": tokens}
                    )
            except Exception as exc:  # pragma: no cover - defensive fallback
                log.warning("Failed to parse component '%s': %s", card, exc)
                circ.add_directive(raw)

        return circ

    # ----------------------------------------------------------------------------------
    # Helpers for from_netlist
    # ----------------------------------------------------------------------------------
    @staticmethod
    def _component_from_tokens(
        letter: str | None, ref: str | None, tokens: list[str]
    ) -> Component | None:
        if not letter or not ref:
            return None

        letter = letter.upper()
        value = " ".join(tokens[3:]) if len(tokens) > 3 else ""

        if letter == "R":
            return Resistor(ref=ref, value=value)
        if letter == "C":
            return Capacitor(ref=ref, value=value)
        if letter == "L":
            return Inductor(ref=ref, value=value)
        if letter == "V":
            return Vdc(ref=ref, value=value)
        if letter == "I":
            return Idc(ref=ref, value=value)
        if letter == "E":
            gain = " ".join(tokens[5:]) if len(tokens) > 5 else ""
            return VCVS(ref=ref, gain=gain)
        if letter == "G":
            gm = " ".join(tokens[5:]) if len(tokens) > 5 else ""
            return VCCS(ref=ref, gm=gm)
        if letter == "F":
            gain = " ".join(tokens[4:]) if len(tokens) > 4 else ""
            ctrl = tokens[3] if len(tokens) > 3 else ""
            return CCCS(ref=ref, ctrl_vsrc=ctrl, gain=gain)
        if letter == "H":
            r = " ".join(tokens[4:]) if len(tokens) > 4 else ""
            ctrl = tokens[3] if len(tokens) > 3 else ""
            return CCVS(ref=ref, ctrl_vsrc=ctrl, r=r)
        if letter == "D":
            model = tokens[3] if len(tokens) > 3 else ""
            return Diode(ref=ref, model=model)
        if letter == "S":
            model = " ".join(tokens[5:]) if len(tokens) > 5 else ""
            return VSwitch(ref=ref, model=model)
        if letter == "W":
            model = " ".join(tokens[4:]) if len(tokens) > 4 else ""
            ctrl = tokens[3] if len(tokens) > 3 else ""
            return ISwitch(ref=ref, ctrl_vsrc=ctrl, model=model)

        # Subcircuits and unsupported devices are preserved as directives
        return None

    def _connect_from_tokens(self, component: Component, node_tokens: list[str]) -> None:
        port_iter = iter(component.ports)
        for node_name in node_tokens:
            try:
                port = next(port_iter)
            except StopIteration:
                break
            net = self._get_or_create_net(node_name)
            self.connect(port, net)

    def _get_or_create_net(self, name: str) -> Net:
        if name == "0":
            return GND
        for net in self._port_to_net.values():
            if getattr(net, "name", None) == name:
                return net
        new = Net(name)
        return new

add(*components)

Append one or more components to the circuit.

Source code in spicelab/core/circuit.py

def add(self, *components: Component) -> Circuit:
    """Append one or more components to the circuit."""

    self._components.extend(components)
    return self

add_directive(line)

Append a raw SPICE directive (.model, .param ...).

Source code in spicelab/core/circuit.py

def add_directive(self, line: str) -> Circuit:
    """Append a raw SPICE directive (``.model``, ``.param`` ...)."""

    self._directives.append(line.rstrip("\n"))
    return self

add_directive_once(line)

Add a directive if an identical line (ignoring whitespace) is absent.

Source code in spicelab/core/circuit.py

def add_directive_once(self, line: str) -> Circuit:
    """Add a directive if an identical line (ignoring whitespace) is absent."""

    normalized = line.strip()
    for existing in self._directives:
        if existing.strip() == normalized:
            return self
    return self.add_directive(line)

build_netlist()

Return a SPICE netlist representation of this circuit.

Source code in spicelab/core/circuit.py

def build_netlist(self) -> str:
    """Return a SPICE netlist representation of this circuit."""

    self._assign_node_ids()

    lines: list[str] = [f"* {self.name}"]

    for comp in self._components:
        card = comp.spice_card(self._net_of)
        # components such as AnalogMux may emit multi-line cards
        for ln in card.splitlines():
            if ln.strip():
                lines.append(ln)

    for directive in self._directives:
        lines.extend(directive.splitlines())

    if not any(line.strip().lower() == ".end" for line in lines):
        lines.append(".end")

    return "\n".join(lines) + "\n"

connect(a, b)

Connect a port to another port or to a logical net.

Uses Union-Find for O(α(n)) amortized net merging (M2 optimization).

Source code in spicelab/core/circuit.py

def connect(self, a: Port, b: Net | Port) -> Circuit:
    """Connect a port to another port or to a logical net.

    Uses Union-Find for O(α(n)) amortized net merging (M2 optimization).
    """
    self._invalidate_cache()

    if isinstance(b, Port):
        net_a = self._port_to_net.get(a)
        net_b = self._port_to_net.get(b)

        if net_a and net_b and net_a is not net_b:
            # Merge using Union-Find: O(α(n)) instead of O(n)
            # Ensure both nets are in union-find
            if net_a not in self._net_union:
                is_named_a = getattr(net_a, "name", None) is not None
                self._net_union.make_set(net_a, net_a if is_named_a else None)
            if net_b not in self._net_union:
                is_named_b = getattr(net_b, "name", None) is not None
                self._net_union.make_set(net_b, net_b if is_named_b else None)

            # Prefer named net as canonical
            prefer = None
            if getattr(net_a, "name", None):
                prefer = net_a
            elif getattr(net_b, "name", None):
                prefer = net_b

            self._net_union.union(net_a, net_b, prefer=prefer)
        else:
            shared = net_a or net_b or Net()
            self._port_to_net[a] = shared
            self._port_to_net[b] = shared
            # Register in union-find
            if shared not in self._net_union:
                is_named = getattr(shared, "name", None) is not None
                self._net_union.make_set(shared, shared if is_named else None)
        self._port_labels.pop(b, None)
    else:
        self._port_to_net[a] = b
        # Register named net in union-find
        if b not in self._net_union:
            is_named = getattr(b, "name", None) is not None
            self._net_union.make_set(b, b if is_named else None)
    self._port_labels.pop(a, None)
    return self

connect_with_label(port, net, label=None)

Connect port to net while recording a display label.

Source code in spicelab/core/circuit.py

def connect_with_label(self, port: Port, net: Net, label: str | None = None) -> Circuit:
    """Connect ``port`` to ``net`` while recording a display label."""

    self.connect(port, net)
    if label:
        self._port_labels[port] = label
    return self

connectivity_dataframe(*, sort=True, include_type=True)

Return a pandas DataFrame describing component/net connectivity.

Columns: component, type (optional), port and net. The returned DataFrame is ideal for Jupyter notebooks where an interactive table is easier to scan than the plain text summary.

Source code in spicelab/core/circuit.py

def connectivity_dataframe(self, *, sort: bool = True, include_type: bool = True):
    """Return a pandas DataFrame describing component/net connectivity.

    Columns: ``component``, ``type`` (optional), ``port`` and ``net``. The
    returned DataFrame is ideal for Jupyter notebooks where an interactive
    table is easier to scan than the plain text summary.
    """

    try:
        import pandas as pd
    except Exception as exc:  # pragma: no cover - optional dependency guard
        raise RuntimeError("pandas is required for connectivity_dataframe()") from exc

    self._assign_node_ids()

    rows: list[dict[str, object]] = []
    for comp in self._components:
        for order, port in enumerate(comp.ports):
            net = self._port_to_net.get(port)
            label = self._port_labels.get(port) or self._net_label(net)
            rows.append(
                {
                    "component": comp.ref,
                    "type": type(comp).__name__,
                    "port": port.name,
                    "net": label,
                    "_order": order,
                }
            )

    if not rows:
        columns = ["component", "port", "net"]
        if include_type:
            columns.insert(1, "type")
        return pd.DataFrame(columns=columns)

    df = pd.DataFrame(rows)
    if sort:
        df = df.sort_values(["component", "_order", "port"]).reset_index(drop=True)
    if not include_type:
        df = df.drop(columns=["type"])
    return df.drop(columns=["_order"])

from_netlist(path) classmethod

Load a circuit from a plain SPICE netlist file.

Source code in spicelab/core/circuit.py

@classmethod
def from_netlist(cls, path: str | Path) -> Circuit:
    """Load a circuit from a plain SPICE netlist file."""

    p = Path(path)
    text = p.read_text(encoding="utf-8")

    from spicelab.io.spice_parser import parse_lines_to_ast, preprocess_netlist

    lines = preprocess_netlist(text)
    ast = parse_lines_to_ast(lines)

    name = p.stem
    if lines and lines[0].lstrip().startswith("*"):
        maybe_title = lines[0].lstrip()[1:].strip()
        if maybe_title:
            name = maybe_title

    circ = cls(name=name)

    for node in ast:
        kind_obj = node.get("type")
        kind = str(kind_obj) if isinstance(kind_obj, str) else None
        raw_obj = node.get("raw")
        raw = str(raw_obj) if isinstance(raw_obj, str) else ""

        if kind == "subckt":
            header = raw.splitlines()[0]
            parts = header.split()
            if len(parts) >= 2:
                circ._subckt_defs[parts[1]] = raw
            circ.add_directive(raw)
            continue

        if kind == "comment" or kind == "directive":
            circ.add_directive(raw)
            continue

        if kind != "component":
            continue

        tokens_obj = node.get("tokens")
        tokens: list[str] = [str(t) for t in tokens_obj] if isinstance(tokens_obj, list) else []
        if not tokens:
            continue

        card = tokens[0]
        letter = cast(str | None, node.get("letter"))
        ref = cast(str | None, node.get("ref"))

        try:
            comp = cls._component_from_tokens(letter, ref, tokens)
            if comp is None:
                circ.add_directive(raw)
                continue
            circ.add(comp)
            circ._connect_from_tokens(comp, tokens[1:])
            if letter == "X":
                circ._subckt_instances.append(
                    {"inst": card, "subckt": tokens[-1], "tokens": tokens}
                )
        except Exception as exc:  # pragma: no cover - defensive fallback
            log.warning("Failed to parse component '%s': %s", card, exc)
            circ.add_directive(raw)

    return circ

hash(*, extra=None)

Return a deterministic short hash for this circuit.

Wrapper around spicelab.core.types.circuit_hash so callers do not need to import the helper directly. extra can include engine/version/analysis args to bind caches firmly to execution context.

Source code in spicelab/core/circuit.py

def hash(self, *, extra: dict[str, object] | None = None) -> str:  # pragma: no cover - thin
    """Return a deterministic short hash for this circuit.

    Wrapper around ``spicelab.core.types.circuit_hash`` so callers do not need
    to import the helper directly. ``extra`` can include engine/version/analysis
    args to bind caches firmly to execution context.
    """
    from .types import circuit_hash  # local import to avoid cycle during module init

    return circuit_hash(self, extra=extra)

save_netlist(path)

Persist the netlist to path and return the resolved Path.

Source code in spicelab/core/circuit.py

def save_netlist(self, path: str | Path) -> Path:
    """Persist the netlist to ``path`` and return the resolved ``Path``."""

    p = Path(path)
    p.write_text(self.build_netlist(), encoding="utf-8")
    return p

summary()

Return a human-readable summary of the circuit and connectivity.

Source code in spicelab/core/circuit.py

def summary(self) -> str:
    """Return a human-readable summary of the circuit and connectivity."""

    self._assign_node_ids()

    lines: list[str] = []
    warnings: list[str] = []

    lines.append(f"Circuit: {self.name}")
    lines.append(f"Components ({len(self._components)}):")

    for comp in self._components:
        port_descriptions: list[str] = []
        for port in comp.ports:
            net = self._port_to_net.get(port)
            label = self._port_labels.get(port) or self._net_label(net)
            if label == "<unconnected>":
                warnings.append(f"Port {comp.ref}.{port.name} is unconnected")
            port_descriptions.append(f"{port.name}->{label}")
        port_info = ", ".join(port_descriptions) if port_descriptions else "<no ports>"
        lines.append(f"  - {comp.ref} ({type(comp).__name__}): {port_info}")

    net_names = sorted({self._net_label(net) for net in self._port_to_net.values() if net})
    if net_names:
        lines.append(f"Nets ({len(net_names)}): {', '.join(net_names)}")

    if warnings:
        lines.append("Warnings:")
        for msg in warnings:
            lines.append(f"  * {msg}")
    else:
        lines.append("Warnings: none")

    return "\n".join(lines)

summary_table(*, indent=2)

Return a fixed-width table describing component connections.

Source code in spicelab/core/circuit.py

def summary_table(self, *, indent: int = 2) -> str:
    """Return a fixed-width table describing component connections."""

    df = self.connectivity_dataframe()
    if df.empty:
        return "(circuit is empty)"

    headers = list(df.columns)
    display_names = {col: col.capitalize() for col in headers}
    widths = {
        col: max(len(display_names[col]), *(len(str(val)) for val in df[col]))
        for col in headers
    }

    def fmt_row(row: dict[str, object]) -> str:
        cells = [str(row[col]).ljust(widths[col]) for col in headers]
        return " " * indent + "  ".join(cells)

    header_line = " " * indent + "  ".join(
        display_names[col].ljust(widths[col]) for col in headers
    )
    sep_line = " " * indent + "  ".join("-" * widths[col] for col in headers)
    body = "\n".join(fmt_row(df.iloc[idx]) for idx in range(len(df)))
    return f"{header_line}\n{sep_line}\n{body}"

to_dot()

Return a Graphviz DOT representation of the circuit.

Source code in spicelab/core/circuit.py

def to_dot(self) -> str:
    """Return a Graphviz DOT representation of the circuit."""

    self._assign_node_ids()

    lines: list[str] = ["graph circuit {", "  rankdir=LR;"]

    comp_ids: dict[Component, str] = {}
    for idx, comp in enumerate(self._components, start=1):
        comp_id = f"comp_{idx}"
        comp_ids[comp] = comp_id
        label = f"{comp.ref}\\n{type(comp).__name__}"
        lines.append(f'  "{comp_id}" [shape=box,label="{label}"];')

    net_ids: dict[Net | None, str] = {}
    net_counter = 1

    def _net_node(net: Net | None) -> str:
        nonlocal net_counter
        if net in net_ids:
            return net_ids[net]
        node_id = f"net_{net_counter}"
        net_counter += 1
        label = self._net_label(net)
        shape = "ellipse" if label != "<unconnected>" else "point"
        net_ids[net] = node_id
        lines.append(f'  "{node_id}" [shape={shape},label="{label}"];')
        return node_id

    for comp in self._components:
        comp_id = comp_ids[comp]
        for port in comp.ports:
            net = self._port_to_net.get(port)
            net_id = _net_node(net)
            lines.append(f'  "{comp_id}" -- "{net_id}" [label="{port.name}",fontsize=10];')

    lines.append("}")
    return "\n".join(lines)

validate(strict=False)

Validate circuit topology and component values.

Performs checks: - Ground reference exists - No floating nodes (connected to only one component) - No unusual component values - No voltage source shorts (parallel voltage sources)

Parameters:

Name	Type	Description	Default
strict	bool	If True, treat warnings as errors	False

Returns:

Type	Description
ValidationResult	ValidationResult with errors and warnings

Example

result = circuit.validate() if result.has_issues(): ... print(result) if not result.is_valid: ... raise ValueError("Circuit has errors")

Source code in spicelab/core/circuit.py

def validate(self, strict: bool = False) -> ValidationResult:
    """Validate circuit topology and component values.

    Performs checks:
    - Ground reference exists
    - No floating nodes (connected to only one component)
    - No unusual component values
    - No voltage source shorts (parallel voltage sources)

    Args:
        strict: If True, treat warnings as errors

    Returns:
        ValidationResult with errors and warnings

    Example:
        >>> result = circuit.validate()
        >>> if result.has_issues():
        ...     print(result)
        >>> if not result.is_valid:
        ...     raise ValueError("Circuit has errors")
    """
    from ..validators.circuit_validation import validate_circuit

    return validate_circuit(self, strict=strict)

CurrentProbe

Bases: Component

Zero-volt voltage source for current measurement.

SPICE card: V

DC 0

A zero-volt source allows measuring current through a branch without affecting circuit behavior. Current flows from p to n.

Parameters:

Name	Type	Description	Default
ref	str	Reference designator (e.g., "sense1")	required

Ports

p: Positive terminal (current enters here) n: Negative terminal (current exits here)

Example

Measure current through a resistor

probe = CurrentProbe("sense")

Connect in series with the component to measure

Access current as I(Vsense) in simulation results

Source code in spicelab/core/components.py

class CurrentProbe(Component):
    """Zero-volt voltage source for current measurement.

    SPICE card: V<ref> <p> <n> DC 0

    A zero-volt source allows measuring current through a branch
    without affecting circuit behavior. Current flows from p to n.

    Args:
        ref: Reference designator (e.g., "sense1")

    Ports:
        p: Positive terminal (current enters here)
        n: Negative terminal (current exits here)

    Example:
        # Measure current through a resistor
        probe = CurrentProbe("sense")
        # Connect in series with the component to measure
        # Access current as I(Vsense) in simulation results
    """

    def __init__(self, ref: str) -> None:
        super().__init__(ref=ref, value="0")
        self._ports = (
            Port(self, "p", PortRole.POSITIVE),
            Port(self, "n", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        return f"V{self.ref} {net_of(p)} {net_of(n)} DC 0"

Inductor

Bases: Component

Indutor de 2 terminais; portas: a (positivo), b (negativo).

Parameters:

Name	Type	Description	Default
ref	str	Reference designator (e.g., "1" for L1)	required
value	str | float	Legacy stringly-typed value (backward compat)	''
inductance	float | ParameterRef | None	Typed inductance value (float or ParameterRef)	None

Use either value OR inductance, not both.

Source code in spicelab/core/components.py

class Inductor(Component):
    """Indutor de 2 terminais; portas: a (positivo), b (negativo).

    Args:
        ref: Reference designator (e.g., "1" for L1)
        value: Legacy stringly-typed value (backward compat)
        inductance: Typed inductance value (float or ParameterRef)

    Use either `value` OR `inductance`, not both.
    """

    def __init__(
        self,
        ref: str,
        value: str | float = "",
        inductance: float | ParameterRef | None = None,
    ) -> None:
        super().__init__(ref=ref, value=value)
        self.inductance = inductance
        self._ports = (Port(self, "a", PortRole.POSITIVE), Port(self, "b", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        a, b = self.ports
        # Use typed field if present, otherwise fall back to value
        val = str(self.inductance) if self.inductance is not None else self.value
        return f"L{self.ref} {net_of(a)} {net_of(b)} {val}"

Ipulse

Bases: Component

Fonte de corrente PULSE(I1 I2 TD TR TF PW PER).

Source code in spicelab/core/components.py

class Ipulse(Component):
    """Fonte de corrente PULSE(I1 I2 TD TR TF PW PER)."""

    def __init__(
        self,
        ref: str,
        i1: str | float,
        i2: str | float,
        td: str | float,
        tr: str | float,
        tf: str | float,
        pw: str | float,
        per: str | float,
    ) -> None:
        super().__init__(ref=ref, value="")
        self.i1, self.i2, self.td, self.tr, self.tf, self.pw, self.per = (
            i1,
            i2,
            td,
            tr,
            tf,
            pw,
            per,
        )
        self._ports = (Port(self, "p", PortRole.POSITIVE), Port(self, "n", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        return (
            f"I{self.ref} {net_of(p)} {net_of(n)} "
            f"PULSE({self.i1} {self.i2} {self.td} {self.tr} {self.tf} {self.pw} {self.per})"
        )

Ipwl

Bases: Component

Fonte de corrente PWL(args_raw).

Source code in spicelab/core/components.py

class Ipwl(Component):
    """Fonte de corrente PWL(args_raw)."""

    def __init__(self, ref: str, args_raw: str) -> None:
        super().__init__(ref=ref, value="")
        self.args_raw = args_raw
        self._ports = (Port(self, "p", PortRole.POSITIVE), Port(self, "n", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        return f"I{self.ref} {net_of(p)} {net_of(n)} PWL({self.args_raw})"

JFET

Bases: Component

Junction Field-Effect Transistor (N-channel or P-channel).

SPICE card: J

Parameters:

Name	Type	Description	Default
ref	str	Reference designator (e.g., "1" for J1)	required
model	str	SPICE model name (e.g., "2N5457", "J2N5459")	required

Ports

d: drain g: gate s: source

Source code in spicelab/core/components.py

class JFET(Component):
    """Junction Field-Effect Transistor (N-channel or P-channel).

    SPICE card: J<ref> <drain> <gate> <source> <model>

    Args:
        ref: Reference designator (e.g., "1" for J1)
        model: SPICE model name (e.g., "2N5457", "J2N5459")

    Ports:
        d: drain
        g: gate
        s: source
    """

    def __init__(self, ref: str, model: str) -> None:
        super().__init__(ref=ref, value=model)
        self._ports = (
            Port(self, "d", PortRole.POSITIVE),
            Port(self, "g", PortRole.NODE),
            Port(self, "s", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        d, g, s = self.ports
        return f"J{self.ref} {net_of(d)} {net_of(g)} {net_of(s)} {self.value}"

MutualInductance

Bases: Component

Mutual inductance coupling between two inductors.

SPICE card: K

This component does not have physical ports - it references existing inductors.

Parameters:

Name	Type	Description	Default
ref	str	Reference designator (e.g., "1" for K1)	required
l1	str	Reference to first inductor (e.g., "L1")	required
l2	str	Reference to second inductor (e.g., "L2")	required
coupling	float	Coupling coefficient (0 to 1, typically 0.95-0.999)	required

Example

Create two inductors and couple them

l1 = Inductor("1", "10m") l2 = Inductor("2", "10m") k1 = MutualInductance("1", l1="L1", l2="L2", coupling=0.99)

Source code in spicelab/core/components.py

class MutualInductance(Component):
    """Mutual inductance coupling between two inductors.

    SPICE card: K<ref> <L1_ref> <L2_ref> <coupling>

    This component does not have physical ports - it references existing inductors.

    Args:
        ref: Reference designator (e.g., "1" for K1)
        l1: Reference to first inductor (e.g., "L1")
        l2: Reference to second inductor (e.g., "L2")
        coupling: Coupling coefficient (0 to 1, typically 0.95-0.999)

    Example:
        # Create two inductors and couple them
        l1 = Inductor("1", "10m")
        l2 = Inductor("2", "10m")
        k1 = MutualInductance("1", l1="L1", l2="L2", coupling=0.99)
    """

    def __init__(
        self,
        ref: str,
        l1: str,
        l2: str,
        coupling: float,
    ) -> None:
        if not 0 <= coupling <= 1:
            raise ValueError(f"Coupling coefficient must be 0-1, got {coupling}")
        super().__init__(ref=ref, value=str(coupling))
        self.l1 = l1
        self.l2 = l2
        self.coupling = coupling
        # No physical ports - this references other components
        self._ports = ()

    def spice_card(self, net_of: NetOf) -> str:
        return f"K{self.ref} {self.l1} {self.l2} {self.coupling}"

Net dataclass

Logical node. Name is optional and used for debug; '0' is reserved for GND.

Source code in spicelab/core/net.py

@dataclass(frozen=True)
class Net:
    """Logical node. Name is optional and used for debug; '0' is reserved for GND."""

    name: str | None = None

OpAmpIdeal

Bases: Component

Op-amp ideal de 3 pinos (inp, inn, out) modelado por VCVS de alto ganho.

Carta: E out 0 inp inn

Source code in spicelab/core/components.py

class OpAmpIdeal(Component):
    """Op-amp ideal de 3 pinos (inp, inn, out) modelado por VCVS de alto ganho.

    Carta: E<ref> out 0 inp inn <gain>
    """

    def __init__(self, ref: str, gain: str | float = 1e6) -> None:
        super().__init__(ref=ref, value=str(gain))
        self._ports = (
            Port(self, "inp", PortRole.POSITIVE),
            Port(self, "inn", PortRole.NEGATIVE),
            Port(self, "out", PortRole.POSITIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        inp, inn, out = self.ports
        return f"E{self.ref} {net_of(out)} 0 {net_of(inp)} {net_of(inn)} {self.value}"

Resistor

Bases: Component

Resistor de 2 terminais; portas: a (positivo), b (negativo).

Parameters:

Name	Type	Description	Default
ref	str	Reference designator (e.g., "1" for R1)	required
value	str | float	Legacy stringly-typed value (backward compat)	''
resistance	float | ParameterRef | None	Typed resistance value (float or ParameterRef)	None

Use either value OR resistance, not both.

Source code in spicelab/core/components.py

class Resistor(Component):
    """Resistor de 2 terminais; portas: a (positivo), b (negativo).

    Args:
        ref: Reference designator (e.g., "1" for R1)
        value: Legacy stringly-typed value (backward compat)
        resistance: Typed resistance value (float or ParameterRef)

    Use either `value` OR `resistance`, not both.
    """

    def __init__(
        self,
        ref: str,
        value: str | float = "",
        resistance: float | ParameterRef | None = None,
    ) -> None:
        super().__init__(ref=ref, value=value)
        self.resistance = resistance
        self._ports = (Port(self, "a", PortRole.POSITIVE), Port(self, "b", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        a, b = self.ports
        # Use typed field if present, otherwise fall back to value
        val = str(self.resistance) if self.resistance is not None else self.value
        return f"R{self.ref} {net_of(a)} {net_of(b)} {val}"

SubcktInstance

Bases: Component

Subcircuit instance (X element).

SPICE card: X ... [param=value ...]

Parameters:

Name	Type	Description	Default
ref	str	Reference designator	required
subckt_name	str	Name of the subcircuit to instantiate	required
nodes	list[str]	List of node names to connect to subcircuit ports	required
params	dict[str, str | float] | None	Optional dict of parameter overrides	None

Example

Instantiate an op-amp subcircuit

x1 = SubcktInstance("1", "LM741", ["inp", "inn", "vcc", "vee", "out"])

With parameters

x2 = SubcktInstance("2", "RES_VAR", ["a", "b"], params={"R": "1k"})

Source code in spicelab/core/components.py

class SubcktInstance(Component):
    """Subcircuit instance (X element).

    SPICE card: X<ref> <node1> <node2> ... <subckt_name> [param=value ...]

    Args:
        ref: Reference designator
        subckt_name: Name of the subcircuit to instantiate
        nodes: List of node names to connect to subcircuit ports
        params: Optional dict of parameter overrides

    Example:
        # Instantiate an op-amp subcircuit
        x1 = SubcktInstance("1", "LM741", ["inp", "inn", "vcc", "vee", "out"])

        # With parameters
        x2 = SubcktInstance("2", "RES_VAR", ["a", "b"], params={"R": "1k"})
    """

    def __init__(
        self,
        ref: str,
        subckt_name: str,
        nodes: list[str],
        params: dict[str, str | float] | None = None,
    ) -> None:
        super().__init__(ref=ref, value=subckt_name)
        self.subckt_name = subckt_name
        self.nodes = nodes
        self.params = params or {}
        # Create ports dynamically based on nodes
        self._ports = tuple(Port(self, f"n{i}", PortRole.NODE) for i in range(len(nodes)))
        # Store node names for spice_card
        self._node_names = nodes

    def spice_card(self, net_of: NetOf) -> str:
        # Use provided node names directly (they represent circuit nodes)
        nodes_str = " ".join(self._node_names)
        params_str = ""
        if self.params:
            params_str = " " + " ".join(f"{k}={v}" for k, v in self.params.items())
        return f"X{self.ref} {nodes_str} {self.subckt_name}{params_str}"

TLine

Bases: Component

Lossless transmission line (T element).

SPICE card: T Z0= TD=

Parameters:

Name	Type	Description	Default
ref	str	Reference designator	required
z0	str | float	Characteristic impedance (ohms)	required
td	str | float	Time delay (e.g., "1n" for 1ns)	required

Ports

p1p, p1n: Port 1 positive and negative p2p, p2n: Port 2 positive and negative

Source code in spicelab/core/components.py

class TLine(Component):
    """Lossless transmission line (T element).

    SPICE card: T<ref> <p1+> <p1-> <p2+> <p2-> Z0=<z0> TD=<td>

    Args:
        ref: Reference designator
        z0: Characteristic impedance (ohms)
        td: Time delay (e.g., "1n" for 1ns)

    Ports:
        p1p, p1n: Port 1 positive and negative
        p2p, p2n: Port 2 positive and negative
    """

    def __init__(
        self,
        ref: str,
        z0: str | float,
        td: str | float,
    ) -> None:
        super().__init__(ref=ref, value="")
        self.z0 = z0
        self.td = td
        self._ports = (
            Port(self, "p1p", PortRole.POSITIVE),
            Port(self, "p1n", PortRole.NEGATIVE),
            Port(self, "p2p", PortRole.POSITIVE),
            Port(self, "p2n", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        p1p, p1n, p2p, p2n = self.ports
        return (
            f"T{self.ref} {net_of(p1p)} {net_of(p1n)} {net_of(p2p)} {net_of(p2n)} "
            f"Z0={self.z0} TD={self.td}"
        )

TLineLossy

Bases: Component

Lossy transmission line (O element) - LTRA model.

SPICE card: O

Requires a .model statement with LTRA parameters.

Parameters:

Name	Type	Description	Default
ref	str	Reference designator	required
model	str	LTRA model name	required

Ports

p1p, p1n: Port 1 positive and negative p2p, p2n: Port 2 positive and negative

Source code in spicelab/core/components.py

class TLineLossy(Component):
    """Lossy transmission line (O element) - LTRA model.

    SPICE card: O<ref> <p1+> <p1-> <p2+> <p2-> <model>

    Requires a .model statement with LTRA parameters.

    Args:
        ref: Reference designator
        model: LTRA model name

    Ports:
        p1p, p1n: Port 1 positive and negative
        p2p, p2n: Port 2 positive and negative
    """

    def __init__(self, ref: str, model: str) -> None:
        super().__init__(ref=ref, value=model)
        self._ports = (
            Port(self, "p1p", PortRole.POSITIVE),
            Port(self, "p1n", PortRole.NEGATIVE),
            Port(self, "p2p", PortRole.POSITIVE),
            Port(self, "p2n", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        p1p, p1n, p2p, p2n = self.ports
        return f"O{self.ref} {net_of(p1p)} {net_of(p1n)} {net_of(p2p)} {net_of(p2n)} {self.value}"

TLineRC

Bases: Component

Uniform distributed RC line (U element) - URC model.

SPICE card: U L=

Parameters:

Name	Type	Description	Default
ref	str	Reference designator	required
model	str	URC model name	required
length	str | float	Line length parameter	1

Ports

n1: Node 1 n2: Node 2 n3: Node 3 (typically ground reference)

Source code in spicelab/core/components.py

class TLineRC(Component):
    """Uniform distributed RC line (U element) - URC model.

    SPICE card: U<ref> <n1> <n2> <n3> <model> L=<len>

    Args:
        ref: Reference designator
        model: URC model name
        length: Line length parameter

    Ports:
        n1: Node 1
        n2: Node 2
        n3: Node 3 (typically ground reference)
    """

    def __init__(self, ref: str, model: str, length: str | float = 1) -> None:
        super().__init__(ref=ref, value=model)
        self.length = length
        self._ports = (
            Port(self, "n1", PortRole.NODE),
            Port(self, "n2", PortRole.NODE),
            Port(self, "n3", PortRole.NODE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        n1, n2, n3 = self.ports
        return f"U{self.ref} {net_of(n1)} {net_of(n2)} {net_of(n3)} {self.value} L={self.length}"

Transformer

Bases: Component

Ideal transformer using coupled inductors.

SPICE implementation uses two inductors coupled via K element. The turns ratio determines the inductance ratio (L2/L1 = n^2).

Parameters:

Name	Type	Description	Default
ref	str	Reference designator (e.g., "1" for XFMR1)	required
turns_ratio	float	Secondary/Primary turns ratio (n = Ns/Np)	required
l_primary	str	Primary inductance value (default "1m")	'1m'
coupling	float	Coupling coefficient (default 0.9999 for ideal)	0.9999

Ports

p1: Primary positive p2: Primary negative s1: Secondary positive s2: Secondary negative

Example

Create 1:10 step-up transformer

xfmr = Transformer("1", turns_ratio=10)

Note

The spice_card method returns multiple lines (L1, L2, K statements).

Source code in spicelab/core/components.py

class Transformer(Component):
    """Ideal transformer using coupled inductors.

    SPICE implementation uses two inductors coupled via K element.
    The turns ratio determines the inductance ratio (L2/L1 = n^2).

    Args:
        ref: Reference designator (e.g., "1" for XFMR1)
        turns_ratio: Secondary/Primary turns ratio (n = Ns/Np)
        l_primary: Primary inductance value (default "1m")
        coupling: Coupling coefficient (default 0.9999 for ideal)

    Ports:
        p1: Primary positive
        p2: Primary negative
        s1: Secondary positive
        s2: Secondary negative

    Example:
        # Create 1:10 step-up transformer
        xfmr = Transformer("1", turns_ratio=10)

    Note:
        The spice_card method returns multiple lines (L1, L2, K statements).
    """

    def __init__(
        self,
        ref: str,
        turns_ratio: float,
        l_primary: str = "1m",
        coupling: float = 0.9999,
    ) -> None:
        if turns_ratio <= 0:
            raise ValueError(f"Turns ratio must be positive, got {turns_ratio}")
        if not 0 < coupling <= 1:
            raise ValueError(f"Coupling must be 0 < k <= 1, got {coupling}")
        super().__init__(ref=ref, value=str(turns_ratio))
        self.turns_ratio = turns_ratio
        self.l_primary = l_primary
        self.coupling = coupling
        self._ports = (
            Port(self, "p1", PortRole.POSITIVE),
            Port(self, "p2", PortRole.NEGATIVE),
            Port(self, "s1", PortRole.POSITIVE),
            Port(self, "s2", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        p1, p2, s1, s2 = self.ports
        # L2 = L1 * n^2 for ideal transformer
        l_sec = f"{float(self.l_primary.rstrip('m')) * self.turns_ratio**2}m"
        lines = [
            f"L{self.ref}p {net_of(p1)} {net_of(p2)} {self.l_primary}",
            f"L{self.ref}s {net_of(s1)} {net_of(s2)} {l_sec}",
            f"K{self.ref} L{self.ref}p L{self.ref}s {self.coupling}",
        ]
        return "\n".join(lines)

Vdc

Bases: Component

Fonte de tensão DC; portas: p (positivo), n (negativo).

Source code in spicelab/core/components.py

class Vdc(Component):
    """Fonte de tensão DC; portas: p (positivo), n (negativo)."""

    def __init__(self, ref: str, value: str | float = "") -> None:
        super().__init__(ref=ref, value=value)
        self._ports = (Port(self, "p", PortRole.POSITIVE), Port(self, "n", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        # Para DC, escrevemos o valor diretamente
        return f"V{self.ref} {net_of(p)} {net_of(n)} {self.value}"

VoltageProbe

Bases: Component

Explicit voltage measurement point marker.

This is a virtual component that doesn't generate a SPICE card. It serves as a marker for voltage measurement between two nodes.

In SPICE, voltages are measured directly as V(node) or V(node1, node2). This class provides a semantic way to mark measurement points.

Parameters:

Name	Type	Description	Default
ref	str	Reference designator/name for the probe	required
differential	bool	If True, measures voltage between p and n. If False, measures p relative to ground.	False

Ports

p: Positive measurement point n: Negative/reference measurement point

Example

Single-ended measurement (relative to ground)

vprobe = VoltageProbe("out")

Differential measurement

vprobe_diff = VoltageProbe("diff", differential=True)

Source code in spicelab/core/components.py

class VoltageProbe(Component):
    """Explicit voltage measurement point marker.

    This is a virtual component that doesn't generate a SPICE card.
    It serves as a marker for voltage measurement between two nodes.

    In SPICE, voltages are measured directly as V(node) or V(node1, node2).
    This class provides a semantic way to mark measurement points.

    Args:
        ref: Reference designator/name for the probe
        differential: If True, measures voltage between p and n.
                     If False, measures p relative to ground.

    Ports:
        p: Positive measurement point
        n: Negative/reference measurement point

    Example:
        # Single-ended measurement (relative to ground)
        vprobe = VoltageProbe("out")

        # Differential measurement
        vprobe_diff = VoltageProbe("diff", differential=True)
    """

    def __init__(self, ref: str, differential: bool = False) -> None:
        super().__init__(ref=ref, value="probe")
        self.differential = differential
        self._ports = (
            Port(self, "p", PortRole.POSITIVE),
            Port(self, "n", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        # VoltageProbe is a virtual component - no SPICE element generated
        # Voltage measurement happens via .PROBE or direct node reference
        return f"* Voltage probe {self.ref}: V({net_of(self.ports[0])})"

Vpulse

Bases: Component

Fonte de tensão PULSE(V1 V2 TD TR TF PW PER).

Source code in spicelab/core/components.py

class Vpulse(Component):
    """Fonte de tensão PULSE(V1 V2 TD TR TF PW PER)."""

    def __init__(
        self,
        ref: str,
        v1: str | float,
        v2: str | float,
        td: str | float,
        tr: str | float,
        tf: str | float,
        pw: str | float,
        per: str | float,
    ) -> None:
        super().__init__(ref=ref, value="")
        self.v1, self.v2, self.td, self.tr, self.tf, self.pw, self.per = (
            v1,
            v2,
            td,
            tr,
            tf,
            pw,
            per,
        )
        self._ports = (Port(self, "p", PortRole.POSITIVE), Port(self, "n", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        return (
            f"V{self.ref} {net_of(p)} {net_of(n)} "
            f"PULSE({self.v1} {self.v2} {self.td} {self.tr} {self.tf} {self.pw} {self.per})"
        )

Vpwl

Bases: Component

Fonte de tensão PWL(args_raw).

Source code in spicelab/core/components.py

class Vpwl(Component):
    """Fonte de tensão PWL(args_raw)."""

    def __init__(self, ref: str, args_raw: str) -> None:
        super().__init__(ref=ref, value="")
        self.args_raw = args_raw
        self._ports = (Port(self, "p", PortRole.POSITIVE), Port(self, "n", PortRole.NEGATIVE))

    def spice_card(self, net_of: NetOf) -> str:
        p, n = self.ports
        return f"V{self.ref} {net_of(p)} {net_of(n)} PWL({self.args_raw})"

ZenerDiode

Bases: Component

Zener diode for voltage reference/regulation.

SPICE card: D

Same as regular Diode but semantically distinct for clarity.

Parameters:

Name	Type	Description	Default
ref	str	Reference designator	required
model	str	Zener model name (e.g., "1N4733" for 5.1V Zener)	required

Ports

a: anode c: cathode (connected to reference voltage in reverse bias)

Source code in spicelab/core/components.py

class ZenerDiode(Component):
    """Zener diode for voltage reference/regulation.

    SPICE card: D<ref> <anode> <cathode> <model>

    Same as regular Diode but semantically distinct for clarity.

    Args:
        ref: Reference designator
        model: Zener model name (e.g., "1N4733" for 5.1V Zener)

    Ports:
        a: anode
        c: cathode (connected to reference voltage in reverse bias)
    """

    def __init__(self, ref: str, model: str) -> None:
        super().__init__(ref=ref, value=model)
        self._ports = (
            Port(self, "a", PortRole.POSITIVE),
            Port(self, "c", PortRole.NEGATIVE),
        )

    def spice_card(self, net_of: NetOf) -> str:
        a, c = self.ports
        return f"D{self.ref} {net_of(a)} {net_of(c)} {self.value}"

Include the core public API (Circuit, Component base types, net utilities).

Core API

This section will be populated by mkdocstrings from the spicelab.core package.

Example:

Logical circuit composed of components, nets and raw SPICE directives.

Source code in spicelab/core/circuit.py

@dataclass
class Circuit:
    """Logical circuit composed of components, nets and raw SPICE directives."""

    name: str
    _net_ids: dict[Net, int] = field(default_factory=dict, init=False)
    _port_to_net: dict[Port, Net] = field(default_factory=dict, init=False)
    _components: list[Component] = field(default_factory=list, init=False)
    _directives: list[str] = field(default_factory=list, init=False)
    # metadata captured when loading from existing netlists
    _subckt_defs: dict[str, str] = field(default_factory=dict, init=False)
    _subckt_instances: list[dict[str, object]] = field(default_factory=list, init=False)
    _port_labels: dict[Port, str] = field(default_factory=dict, init=False)
    # Union-Find for O(α(n)) net merging (M2 performance optimization)
    _net_union: UnionFind[Net] = field(default_factory=UnionFind, init=False)
    # Cache invalidation version counter
    _cache_version: int = field(default=0, init=False)

    # ----------------------------------------------------------------------------------
    # Building blocks
    # ----------------------------------------------------------------------------------
    def add(self, *components: Component) -> Circuit:
        """Append one or more components to the circuit."""

        self._components.extend(components)
        return self

    def add_directive(self, line: str) -> Circuit:
        """Append a raw SPICE directive (``.model``, ``.param`` ...)."""

        self._directives.append(line.rstrip("\n"))
        return self

    def add_directive_once(self, line: str) -> Circuit:
        """Add a directive if an identical line (ignoring whitespace) is absent."""

        normalized = line.strip()
        for existing in self._directives:
            if existing.strip() == normalized:
                return self
        return self.add_directive(line)

    def connect(self, a: Port, b: Net | Port) -> Circuit:
        """Connect a port to another port or to a logical net.

        Uses Union-Find for O(α(n)) amortized net merging (M2 optimization).
        """
        self._invalidate_cache()

        if isinstance(b, Port):
            net_a = self._port_to_net.get(a)
            net_b = self._port_to_net.get(b)

            if net_a and net_b and net_a is not net_b:
                # Merge using Union-Find: O(α(n)) instead of O(n)
                # Ensure both nets are in union-find
                if net_a not in self._net_union:
                    is_named_a = getattr(net_a, "name", None) is not None
                    self._net_union.make_set(net_a, net_a if is_named_a else None)
                if net_b not in self._net_union:
                    is_named_b = getattr(net_b, "name", None) is not None
                    self._net_union.make_set(net_b, net_b if is_named_b else None)

                # Prefer named net as canonical
                prefer = None
                if getattr(net_a, "name", None):
                    prefer = net_a
                elif getattr(net_b, "name", None):
                    prefer = net_b

                self._net_union.union(net_a, net_b, prefer=prefer)
            else:
                shared = net_a or net_b or Net()
                self._port_to_net[a] = shared
                self._port_to_net[b] = shared
                # Register in union-find
                if shared not in self._net_union:
                    is_named = getattr(shared, "name", None) is not None
                    self._net_union.make_set(shared, shared if is_named else None)
            self._port_labels.pop(b, None)
        else:
            self._port_to_net[a] = b
            # Register named net in union-find
            if b not in self._net_union:
                is_named = getattr(b, "name", None) is not None
                self._net_union.make_set(b, b if is_named else None)
        self._port_labels.pop(a, None)
        return self

    def _invalidate_cache(self) -> None:
        """Invalidate cached properties when circuit is modified."""
        self._cache_version += 1
        # Clear cached net IDs
        self._net_ids.clear()

    def connect_with_label(self, port: Port, net: Net, label: str | None = None) -> Circuit:
        """Connect ``port`` to ``net`` while recording a display label."""

        self.connect(port, net)
        if label:
            self._port_labels[port] = label
        return self

    # ----------------------------------------------------------------------------------
    # Net handling
    # ----------------------------------------------------------------------------------
    def _assign_node_ids(self) -> None:
        """Assign node IDs, using Union-Find for canonical net resolution."""
        self._net_ids.clear()
        self._net_ids[GND] = 0

        next_id = 1
        seen: set[Net] = {GND}

        def canonical_nets_from_components() -> Iterable[Net]:
            for comp in self._components:
                for port in comp.ports:
                    net = self._port_to_net.get(port)
                    if net is not None:
                        # Use canonical net for proper merging
                        yield self._get_canonical_net(net)

        for net in canonical_nets_from_components():
            if net in seen:
                continue
            seen.add(net)
            if getattr(net, "name", None) and net.name != "0":
                # preserve named nets but still assign an id for bookkeeping
                self._net_ids[net] = next_id
            else:
                self._net_ids[net] = next_id
            next_id += 1

    def _net_of(self, port: Port) -> str:
        net = self._port_to_net.get(port)
        if net is None:
            raise ValueError(f"Unconnected port: {port.owner.ref}.{port.name}")

        # Use Union-Find to get the canonical net (handles merged nets)
        canonical_net = self._get_canonical_net(net)

        if canonical_net is GND or getattr(canonical_net, "name", None) == "0":
            return "0"

        if getattr(canonical_net, "name", None):
            return str(canonical_net.name)

        node_id = self._net_ids.get(canonical_net)
        if node_id is None:
            raise RuntimeError("Node IDs not assigned")
        return str(node_id)

    def _get_canonical_net(self, net: Net) -> Net:
        """Get the canonical net for a possibly-merged net using Union-Find."""
        if net not in self._net_union:
            return net
        return self._net_union.get_canonical(net)

    # ----------------------------------------------------------------------------------
    # Netlist helpers
    # ----------------------------------------------------------------------------------
    def build_netlist(self) -> str:
        """Return a SPICE netlist representation of this circuit."""

        self._assign_node_ids()

        lines: list[str] = [f"* {self.name}"]

        for comp in self._components:
            card = comp.spice_card(self._net_of)
            # components such as AnalogMux may emit multi-line cards
            for ln in card.splitlines():
                if ln.strip():
                    lines.append(ln)

        for directive in self._directives:
            lines.extend(directive.splitlines())

        if not any(line.strip().lower() == ".end" for line in lines):
            lines.append(".end")

        return "\n".join(lines) + "\n"

    def save_netlist(self, path: str | Path) -> Path:
        """Persist the netlist to ``path`` and return the resolved ``Path``."""

        p = Path(path)
        p.write_text(self.build_netlist(), encoding="utf-8")
        return p

    # ----------------------------------------------------------------------------------
    # Hash (deterministic) - part of M1 contract
    # ----------------------------------------------------------------------------------
    def hash(self, *, extra: dict[str, object] | None = None) -> str:  # pragma: no cover - thin
        """Return a deterministic short hash for this circuit.

        Wrapper around ``spicelab.core.types.circuit_hash`` so callers do not need
        to import the helper directly. ``extra`` can include engine/version/analysis
        args to bind caches firmly to execution context.
        """
        from .types import circuit_hash  # local import to avoid cycle during module init

        return circuit_hash(self, extra=extra)

    # ----------------------------------------------------------------------------------
    # Validation (M4 DX improvement)
    # ----------------------------------------------------------------------------------
    def validate(self, strict: bool = False) -> ValidationResult:
        """Validate circuit topology and component values.

        Performs checks:
        - Ground reference exists
        - No floating nodes (connected to only one component)
        - No unusual component values
        - No voltage source shorts (parallel voltage sources)

        Args:
            strict: If True, treat warnings as errors

        Returns:
            ValidationResult with errors and warnings

        Example:
            >>> result = circuit.validate()
            >>> if result.has_issues():
            ...     print(result)
            >>> if not result.is_valid:
            ...     raise ValueError("Circuit has errors")
        """
        from ..validators.circuit_validation import validate_circuit

        return validate_circuit(self, strict=strict)

    # ----------------------------------------------------------------------------------
    # Introspection helpers
    # ----------------------------------------------------------------------------------
    def _net_label(self, net: Net | None) -> str:
        if net is None:
            return "<unconnected>"

        # Use canonical net for merged nets
        canonical = self._get_canonical_net(net)

        if canonical is GND or getattr(canonical, "name", None) == "0":
            return "0"
        if getattr(canonical, "name", None):
            return str(canonical.name)
        node_id = self._net_ids.get(canonical)
        if node_id is None:
            self._assign_node_ids()
            node_id = self._net_ids.get(canonical)
        return f"N{node_id:03d}" if node_id is not None else "<unnamed>"

    def summary(self) -> str:
        """Return a human-readable summary of the circuit and connectivity."""

        self._assign_node_ids()

        lines: list[str] = []
        warnings: list[str] = []

        lines.append(f"Circuit: {self.name}")
        lines.append(f"Components ({len(self._components)}):")

        for comp in self._components:
            port_descriptions: list[str] = []
            for port in comp.ports:
                net = self._port_to_net.get(port)
                label = self._port_labels.get(port) or self._net_label(net)
                if label == "<unconnected>":
                    warnings.append(f"Port {comp.ref}.{port.name} is unconnected")
                port_descriptions.append(f"{port.name}->{label}")
            port_info = ", ".join(port_descriptions) if port_descriptions else "<no ports>"
            lines.append(f"  - {comp.ref} ({type(comp).__name__}): {port_info}")

        net_names = sorted({self._net_label(net) for net in self._port_to_net.values() if net})
        if net_names:
            lines.append(f"Nets ({len(net_names)}): {', '.join(net_names)}")

        if warnings:
            lines.append("Warnings:")
            for msg in warnings:
                lines.append(f"  * {msg}")
        else:
            lines.append("Warnings: none")

        return "\n".join(lines)

    def to_dot(self) -> str:
        """Return a Graphviz DOT representation of the circuit."""

        self._assign_node_ids()

        lines: list[str] = ["graph circuit {", "  rankdir=LR;"]

        comp_ids: dict[Component, str] = {}
        for idx, comp in enumerate(self._components, start=1):
            comp_id = f"comp_{idx}"
            comp_ids[comp] = comp_id
            label = f"{comp.ref}\\n{type(comp).__name__}"
            lines.append(f'  "{comp_id}" [shape=box,label="{label}"];')

        net_ids: dict[Net | None, str] = {}
        net_counter = 1

        def _net_node(net: Net | None) -> str:
            nonlocal net_counter
            if net in net_ids:
                return net_ids[net]
            node_id = f"net_{net_counter}"
            net_counter += 1
            label = self._net_label(net)
            shape = "ellipse" if label != "<unconnected>" else "point"
            net_ids[net] = node_id
            lines.append(f'  "{node_id}" [shape={shape},label="{label}"];')
            return node_id

        for comp in self._components:
            comp_id = comp_ids[comp]
            for port in comp.ports:
                net = self._port_to_net.get(port)
                net_id = _net_node(net)
                lines.append(f'  "{comp_id}" -- "{net_id}" [label="{port.name}",fontsize=10];')

        lines.append("}")
        return "\n".join(lines)

    # ----------------------------------------------------------------------------------
    # Notebook-friendly helpers
    # ----------------------------------------------------------------------------------
    def connectivity_dataframe(self, *, sort: bool = True, include_type: bool = True):
        """Return a pandas DataFrame describing component/net connectivity.

        Columns: ``component``, ``type`` (optional), ``port`` and ``net``. The
        returned DataFrame is ideal for Jupyter notebooks where an interactive
        table is easier to scan than the plain text summary.
        """

        try:
            import pandas as pd
        except Exception as exc:  # pragma: no cover - optional dependency guard
            raise RuntimeError("pandas is required for connectivity_dataframe()") from exc

        self._assign_node_ids()

        rows: list[dict[str, object]] = []
        for comp in self._components:
            for order, port in enumerate(comp.ports):
                net = self._port_to_net.get(port)
                label = self._port_labels.get(port) or self._net_label(net)
                rows.append(
                    {
                        "component": comp.ref,
                        "type": type(comp).__name__,
                        "port": port.name,
                        "net": label,
                        "_order": order,
                    }
                )

        if not rows:
            columns = ["component", "port", "net"]
            if include_type:
                columns.insert(1, "type")
            return pd.DataFrame(columns=columns)

        df = pd.DataFrame(rows)
        if sort:
            df = df.sort_values(["component", "_order", "port"]).reset_index(drop=True)
        if not include_type:
            df = df.drop(columns=["type"])
        return df.drop(columns=["_order"])

    def summary_table(self, *, indent: int = 2) -> str:
        """Return a fixed-width table describing component connections."""

        df = self.connectivity_dataframe()
        if df.empty:
            return "(circuit is empty)"

        headers = list(df.columns)
        display_names = {col: col.capitalize() for col in headers}
        widths = {
            col: max(len(display_names[col]), *(len(str(val)) for val in df[col]))
            for col in headers
        }

        def fmt_row(row: dict[str, object]) -> str:
            cells = [str(row[col]).ljust(widths[col]) for col in headers]
            return " " * indent + "  ".join(cells)

        header_line = " " * indent + "  ".join(
            display_names[col].ljust(widths[col]) for col in headers
        )
        sep_line = " " * indent + "  ".join("-" * widths[col] for col in headers)
        body = "\n".join(fmt_row(df.iloc[idx]) for idx in range(len(df)))
        return f"{header_line}\n{sep_line}\n{body}"

    # ----------------------------------------------------------------------------------
    # Netlist import
    # ----------------------------------------------------------------------------------
    @classmethod
    def from_netlist(cls, path: str | Path) -> Circuit:
        """Load a circuit from a plain SPICE netlist file."""

        p = Path(path)
        text = p.read_text(encoding="utf-8")

        from spicelab.io.spice_parser import parse_lines_to_ast, preprocess_netlist

        lines = preprocess_netlist(text)
        ast = parse_lines_to_ast(lines)

        name = p.stem
        if lines and lines[0].lstrip().startswith("*"):
            maybe_title = lines[0].lstrip()[1:].strip()
            if maybe_title:
                name = maybe_title

        circ = cls(name=name)

        for node in ast:
            kind_obj = node.get("type")
            kind = str(kind_obj) if isinstance(kind_obj, str) else None
            raw_obj = node.get("raw")
            raw = str(raw_obj) if isinstance(raw_obj, str) else ""

            if kind == "subckt":
                header = raw.splitlines()[0]
                parts = header.split()
                if len(parts) >= 2:
                    circ._subckt_defs[parts[1]] = raw
                circ.add_directive(raw)
                continue

            if kind == "comment" or kind == "directive":
                circ.add_directive(raw)
                continue

            if kind != "component":
                continue

            tokens_obj = node.get("tokens")
            tokens: list[str] = [str(t) for t in tokens_obj] if isinstance(tokens_obj, list) else []
            if not tokens:
                continue

            card = tokens[0]
            letter = cast(str | None, node.get("letter"))
            ref = cast(str | None, node.get("ref"))

            try:
                comp = cls._component_from_tokens(letter, ref, tokens)
                if comp is None:
                    circ.add_directive(raw)
                    continue
                circ.add(comp)
                circ._connect_from_tokens(comp, tokens[1:])
                if letter == "X":
                    circ._subckt_instances.append(
                        {"inst": card, "subckt": tokens[-1], "tokens": tokens}
                    )
            except Exception as exc:  # pragma: no cover - defensive fallback
                log.warning("Failed to parse component '%s': %s", card, exc)
                circ.add_directive(raw)

        return circ

    # ----------------------------------------------------------------------------------
    # Helpers for from_netlist
    # ----------------------------------------------------------------------------------
    @staticmethod
    def _component_from_tokens(
        letter: str | None, ref: str | None, tokens: list[str]
    ) -> Component | None:
        if not letter or not ref:
            return None

        letter = letter.upper()
        value = " ".join(tokens[3:]) if len(tokens) > 3 else ""

        if letter == "R":
            return Resistor(ref=ref, value=value)
        if letter == "C":
            return Capacitor(ref=ref, value=value)
        if letter == "L":
            return Inductor(ref=ref, value=value)
        if letter == "V":
            return Vdc(ref=ref, value=value)
        if letter == "I":
            return Idc(ref=ref, value=value)
        if letter == "E":
            gain = " ".join(tokens[5:]) if len(tokens) > 5 else ""
            return VCVS(ref=ref, gain=gain)
        if letter == "G":
            gm = " ".join(tokens[5:]) if len(tokens) > 5 else ""
            return VCCS(ref=ref, gm=gm)
        if letter == "F":
            gain = " ".join(tokens[4:]) if len(tokens) > 4 else ""
            ctrl = tokens[3] if len(tokens) > 3 else ""
            return CCCS(ref=ref, ctrl_vsrc=ctrl, gain=gain)
        if letter == "H":
            r = " ".join(tokens[4:]) if len(tokens) > 4 else ""
            ctrl = tokens[3] if len(tokens) > 3 else ""
            return CCVS(ref=ref, ctrl_vsrc=ctrl, r=r)
        if letter == "D":
            model = tokens[3] if len(tokens) > 3 else ""
            return Diode(ref=ref, model=model)
        if letter == "S":
            model = " ".join(tokens[5:]) if len(tokens) > 5 else ""
            return VSwitch(ref=ref, model=model)
        if letter == "W":
            model = " ".join(tokens[4:]) if len(tokens) > 4 else ""
            ctrl = tokens[3] if len(tokens) > 3 else ""
            return ISwitch(ref=ref, ctrl_vsrc=ctrl, model=model)

        # Subcircuits and unsupported devices are preserved as directives
        return None

    def _connect_from_tokens(self, component: Component, node_tokens: list[str]) -> None:
        port_iter = iter(component.ports)
        for node_name in node_tokens:
            try:
                port = next(port_iter)
            except StopIteration:
                break
            net = self._get_or_create_net(node_name)
            self.connect(port, net)

    def _get_or_create_net(self, name: str) -> Net:
        if name == "0":
            return GND
        for net in self._port_to_net.values():
            if getattr(net, "name", None) == name:
                return net
        new = Net(name)
        return new

add(*components)

Append one or more components to the circuit.

Source code in spicelab/core/circuit.py

def add(self, *components: Component) -> Circuit:
    """Append one or more components to the circuit."""

    self._components.extend(components)
    return self

add_directive(line)

Append a raw SPICE directive (.model, .param ...).

Source code in spicelab/core/circuit.py

def add_directive(self, line: str) -> Circuit:
    """Append a raw SPICE directive (``.model``, ``.param`` ...)."""

    self._directives.append(line.rstrip("\n"))
    return self

add_directive_once(line)

Add a directive if an identical line (ignoring whitespace) is absent.

Source code in spicelab/core/circuit.py

def add_directive_once(self, line: str) -> Circuit:
    """Add a directive if an identical line (ignoring whitespace) is absent."""

    normalized = line.strip()
    for existing in self._directives:
        if existing.strip() == normalized:
            return self
    return self.add_directive(line)

build_netlist()

Return a SPICE netlist representation of this circuit.

Source code in spicelab/core/circuit.py

def build_netlist(self) -> str:
    """Return a SPICE netlist representation of this circuit."""

    self._assign_node_ids()

    lines: list[str] = [f"* {self.name}"]

    for comp in self._components:
        card = comp.spice_card(self._net_of)
        # components such as AnalogMux may emit multi-line cards
        for ln in card.splitlines():
            if ln.strip():
                lines.append(ln)

    for directive in self._directives:
        lines.extend(directive.splitlines())

    if not any(line.strip().lower() == ".end" for line in lines):
        lines.append(".end")

    return "\n".join(lines) + "\n"

connect(a, b)

Connect a port to another port or to a logical net.

Uses Union-Find for O(α(n)) amortized net merging (M2 optimization).

Source code in spicelab/core/circuit.py

def connect(self, a: Port, b: Net | Port) -> Circuit:
    """Connect a port to another port or to a logical net.

    Uses Union-Find for O(α(n)) amortized net merging (M2 optimization).
    """
    self._invalidate_cache()

    if isinstance(b, Port):
        net_a = self._port_to_net.get(a)
        net_b = self._port_to_net.get(b)

        if net_a and net_b and net_a is not net_b:
            # Merge using Union-Find: O(α(n)) instead of O(n)
            # Ensure both nets are in union-find
            if net_a not in self._net_union:
                is_named_a = getattr(net_a, "name", None) is not None
                self._net_union.make_set(net_a, net_a if is_named_a else None)
            if net_b not in self._net_union:
                is_named_b = getattr(net_b, "name", None) is not None
                self._net_union.make_set(net_b, net_b if is_named_b else None)

            # Prefer named net as canonical
            prefer = None
            if getattr(net_a, "name", None):
                prefer = net_a
            elif getattr(net_b, "name", None):
                prefer = net_b

            self._net_union.union(net_a, net_b, prefer=prefer)
        else:
            shared = net_a or net_b or Net()
            self._port_to_net[a] = shared
            self._port_to_net[b] = shared
            # Register in union-find
            if shared not in self._net_union:
                is_named = getattr(shared, "name", None) is not None
                self._net_union.make_set(shared, shared if is_named else None)
        self._port_labels.pop(b, None)
    else:
        self._port_to_net[a] = b
        # Register named net in union-find
        if b not in self._net_union:
            is_named = getattr(b, "name", None) is not None
            self._net_union.make_set(b, b if is_named else None)
    self._port_labels.pop(a, None)
    return self

connect_with_label(port, net, label=None)

Connect port to net while recording a display label.

Source code in spicelab/core/circuit.py

def connect_with_label(self, port: Port, net: Net, label: str | None = None) -> Circuit:
    """Connect ``port`` to ``net`` while recording a display label."""

    self.connect(port, net)
    if label:
        self._port_labels[port] = label
    return self

connectivity_dataframe(*, sort=True, include_type=True)

Return a pandas DataFrame describing component/net connectivity.

Columns: component, type (optional), port and net. The returned DataFrame is ideal for Jupyter notebooks where an interactive table is easier to scan than the plain text summary.

Source code in spicelab/core/circuit.py

def connectivity_dataframe(self, *, sort: bool = True, include_type: bool = True):
    """Return a pandas DataFrame describing component/net connectivity.

    Columns: ``component``, ``type`` (optional), ``port`` and ``net``. The
    returned DataFrame is ideal for Jupyter notebooks where an interactive
    table is easier to scan than the plain text summary.
    """

    try:
        import pandas as pd
    except Exception as exc:  # pragma: no cover - optional dependency guard
        raise RuntimeError("pandas is required for connectivity_dataframe()") from exc

    self._assign_node_ids()

    rows: list[dict[str, object]] = []
    for comp in self._components:
        for order, port in enumerate(comp.ports):
            net = self._port_to_net.get(port)
            label = self._port_labels.get(port) or self._net_label(net)
            rows.append(
                {
                    "component": comp.ref,
                    "type": type(comp).__name__,
                    "port": port.name,
                    "net": label,
                    "_order": order,
                }
            )

    if not rows:
        columns = ["component", "port", "net"]
        if include_type:
            columns.insert(1, "type")
        return pd.DataFrame(columns=columns)

    df = pd.DataFrame(rows)
    if sort:
        df = df.sort_values(["component", "_order", "port"]).reset_index(drop=True)
    if not include_type:
        df = df.drop(columns=["type"])
    return df.drop(columns=["_order"])

from_netlist(path) classmethod

Load a circuit from a plain SPICE netlist file.

Source code in spicelab/core/circuit.py

@classmethod
def from_netlist(cls, path: str | Path) -> Circuit:
    """Load a circuit from a plain SPICE netlist file."""

    p = Path(path)
    text = p.read_text(encoding="utf-8")

    from spicelab.io.spice_parser import parse_lines_to_ast, preprocess_netlist

    lines = preprocess_netlist(text)
    ast = parse_lines_to_ast(lines)

    name = p.stem
    if lines and lines[0].lstrip().startswith("*"):
        maybe_title = lines[0].lstrip()[1:].strip()
        if maybe_title:
            name = maybe_title

    circ = cls(name=name)

    for node in ast:
        kind_obj = node.get("type")
        kind = str(kind_obj) if isinstance(kind_obj, str) else None
        raw_obj = node.get("raw")
        raw = str(raw_obj) if isinstance(raw_obj, str) else ""

        if kind == "subckt":
            header = raw.splitlines()[0]
            parts = header.split()
            if len(parts) >= 2:
                circ._subckt_defs[parts[1]] = raw
            circ.add_directive(raw)
            continue

        if kind == "comment" or kind == "directive":
            circ.add_directive(raw)
            continue

        if kind != "component":
            continue

        tokens_obj = node.get("tokens")
        tokens: list[str] = [str(t) for t in tokens_obj] if isinstance(tokens_obj, list) else []
        if not tokens:
            continue

        card = tokens[0]
        letter = cast(str | None, node.get("letter"))
        ref = cast(str | None, node.get("ref"))

        try:
            comp = cls._component_from_tokens(letter, ref, tokens)
            if comp is None:
                circ.add_directive(raw)
                continue
            circ.add(comp)
            circ._connect_from_tokens(comp, tokens[1:])
            if letter == "X":
                circ._subckt_instances.append(
                    {"inst": card, "subckt": tokens[-1], "tokens": tokens}
                )
        except Exception as exc:  # pragma: no cover - defensive fallback
            log.warning("Failed to parse component '%s': %s", card, exc)
            circ.add_directive(raw)

    return circ

hash(*, extra=None)

Return a deterministic short hash for this circuit.

Wrapper around spicelab.core.types.circuit_hash so callers do not need to import the helper directly. extra can include engine/version/analysis args to bind caches firmly to execution context.

Source code in spicelab/core/circuit.py

def hash(self, *, extra: dict[str, object] | None = None) -> str:  # pragma: no cover - thin
    """Return a deterministic short hash for this circuit.

    Wrapper around ``spicelab.core.types.circuit_hash`` so callers do not need
    to import the helper directly. ``extra`` can include engine/version/analysis
    args to bind caches firmly to execution context.
    """
    from .types import circuit_hash  # local import to avoid cycle during module init

    return circuit_hash(self, extra=extra)

save_netlist(path)

Persist the netlist to path and return the resolved Path.

Source code in spicelab/core/circuit.py

def save_netlist(self, path: str | Path) -> Path:
    """Persist the netlist to ``path`` and return the resolved ``Path``."""

    p = Path(path)
    p.write_text(self.build_netlist(), encoding="utf-8")
    return p

summary()

Return a human-readable summary of the circuit and connectivity.

Source code in spicelab/core/circuit.py

def summary(self) -> str:
    """Return a human-readable summary of the circuit and connectivity."""

    self._assign_node_ids()

    lines: list[str] = []
    warnings: list[str] = []

    lines.append(f"Circuit: {self.name}")
    lines.append(f"Components ({len(self._components)}):")

    for comp in self._components:
        port_descriptions: list[str] = []
        for port in comp.ports:
            net = self._port_to_net.get(port)
            label = self._port_labels.get(port) or self._net_label(net)
            if label == "<unconnected>":
                warnings.append(f"Port {comp.ref}.{port.name} is unconnected")
            port_descriptions.append(f"{port.name}->{label}")
        port_info = ", ".join(port_descriptions) if port_descriptions else "<no ports>"
        lines.append(f"  - {comp.ref} ({type(comp).__name__}): {port_info}")

    net_names = sorted({self._net_label(net) for net in self._port_to_net.values() if net})
    if net_names:
        lines.append(f"Nets ({len(net_names)}): {', '.join(net_names)}")

    if warnings:
        lines.append("Warnings:")
        for msg in warnings:
            lines.append(f"  * {msg}")
    else:
        lines.append("Warnings: none")

    return "\n".join(lines)

summary_table(*, indent=2)

Return a fixed-width table describing component connections.

Source code in spicelab/core/circuit.py

def summary_table(self, *, indent: int = 2) -> str:
    """Return a fixed-width table describing component connections."""

    df = self.connectivity_dataframe()
    if df.empty:
        return "(circuit is empty)"

    headers = list(df.columns)
    display_names = {col: col.capitalize() for col in headers}
    widths = {
        col: max(len(display_names[col]), *(len(str(val)) for val in df[col]))
        for col in headers
    }

    def fmt_row(row: dict[str, object]) -> str:
        cells = [str(row[col]).ljust(widths[col]) for col in headers]
        return " " * indent + "  ".join(cells)

    header_line = " " * indent + "  ".join(
        display_names[col].ljust(widths[col]) for col in headers
    )
    sep_line = " " * indent + "  ".join("-" * widths[col] for col in headers)
    body = "\n".join(fmt_row(df.iloc[idx]) for idx in range(len(df)))
    return f"{header_line}\n{sep_line}\n{body}"

to_dot()

Return a Graphviz DOT representation of the circuit.

Source code in spicelab/core/circuit.py

def to_dot(self) -> str:
    """Return a Graphviz DOT representation of the circuit."""

    self._assign_node_ids()

    lines: list[str] = ["graph circuit {", "  rankdir=LR;"]

    comp_ids: dict[Component, str] = {}
    for idx, comp in enumerate(self._components, start=1):
        comp_id = f"comp_{idx}"
        comp_ids[comp] = comp_id
        label = f"{comp.ref}\\n{type(comp).__name__}"
        lines.append(f'  "{comp_id}" [shape=box,label="{label}"];')

    net_ids: dict[Net | None, str] = {}
    net_counter = 1

    def _net_node(net: Net | None) -> str:
        nonlocal net_counter
        if net in net_ids:
            return net_ids[net]
        node_id = f"net_{net_counter}"
        net_counter += 1
        label = self._net_label(net)
        shape = "ellipse" if label != "<unconnected>" else "point"
        net_ids[net] = node_id
        lines.append(f'  "{node_id}" [shape={shape},label="{label}"];')
        return node_id

    for comp in self._components:
        comp_id = comp_ids[comp]
        for port in comp.ports:
            net = self._port_to_net.get(port)
            net_id = _net_node(net)
            lines.append(f'  "{comp_id}" -- "{net_id}" [label="{port.name}",fontsize=10];')

    lines.append("}")
    return "\n".join(lines)

validate(strict=False)

Validate circuit topology and component values.

Performs checks: - Ground reference exists - No floating nodes (connected to only one component) - No unusual component values - No voltage source shorts (parallel voltage sources)

Parameters:

Name	Type	Description	Default
strict	bool	If True, treat warnings as errors	False

Returns:

Type	Description
ValidationResult	ValidationResult with errors and warnings

Example

result = circuit.validate() if result.has_issues(): ... print(result) if not result.is_valid: ... raise ValueError("Circuit has errors")

Source code in spicelab/core/circuit.py

def validate(self, strict: bool = False) -> ValidationResult:
    """Validate circuit topology and component values.

    Performs checks:
    - Ground reference exists
    - No floating nodes (connected to only one component)
    - No unusual component values
    - No voltage source shorts (parallel voltage sources)

    Args:
        strict: If True, treat warnings as errors

    Returns:
        ValidationResult with errors and warnings

    Example:
        >>> result = circuit.validate()
        >>> if result.has_issues():
        ...     print(result)
        >>> if not result.is_valid:
        ...     raise ValueError("Circuit has errors")
    """
    from ..validators.circuit_validation import validate_circuit

    return validate_circuit(self, strict=strict)