sycan.components.blocks.subcircuit

Hierarchical subcircuit (SPICE X).

A SubCircuit wraps an inner Circuit (the body) and exposes a subset of its internal nodes as external pins via SubCircuit.port_map. When the parent circuit is solved, every SubCircuit is recursively flattened: each leaf component inside the body is cloned with

• its name prefixed by the instance name (X1.E1);

• every node attribute rewritten — pins map to the parent-scope node given by port_map, internal-only nodes are namespaced <instance>.<inner>, and ground ("0") is left untouched.

The clones then stamp into the parent MNA exactly as if the user had inlined them. Auxiliary branch-currents and nonlinear residuals come along for free because each clone reports its own aux_count / has_nonlinear flags.

Subcircuits can nest — a body may itself contain SubCircuit instances, and the rewriting is composed at expansion time.

Parameter propagation

A SubCircuit may carry a params dict whose entries substitute symbolic placeholders inside the body at expansion time. The body’s leaves reference parameters as plain cas.Symbol("R") expressions; the wrapper’s params={"R": value, ...} replaces those symbols on every cloned leaf. Nested subcircuits inherit the outer scope’s params automatically — a child’s own params takes precedence for matching keys, while inherited entries flow through unchanged. This mirrors SPICE’s .SUBCKT name pins... PARAMS: / Xinst pins... name PARAMS: semantics.

Classes

SubCircuit(name, body, port_map, *[, ...])

Hierarchical subcircuit instance (SPICE X element).

class sycan.components.blocks.subcircuit.SubCircuit(name, body, port_map, *, params=<factory>, include_noise=None)

Bases: Component

Hierarchical subcircuit instance (SPICE X element).

Parameters:

• name (str) – Instance designator (e.g. "X1").

• body (Circuit) – Inner Circuit defining the subcircuit’s contents. The body must already contain the components it needs at construction time so that pin validation can run.

• port_map (Mapping[str, str]) – {body_pin: parent_node} — keys are node names that exist in body; values are the parent-scope nodes the pins connect to.

• params (Mapping[str, Value])

• include_noise (NoiseSpec)

name: str

body: Circuit

port_map: Mapping[str, str]

params: Mapping[str, Value]

include_noise: NoiseSpec = None

has_aux: ClassVar[bool] = False

SUPPORTED_NOISE: ClassVar[frozenset[str]] = frozenset({})

iter_node_names()

Every node name the parent must register for this subcircuit.

Includes both the parent-scope endpoints (port_map.values()) and the namespaced internal nodes that the flattened leaves will reference.

Return type:

Iterator[str]

aux_count(mode)

Number of auxiliary branch currents the component needs in mode.

Parameters:

mode (str)

Return type:

int

stamp(ctx)

Parameters:

ctx (StampContext)

Return type:

None

child_subcircuits()

Direct child SubCircuit instances inside this body.

Return type:

list[SubCircuit]

effective_params(inherited=None)

Merge inherited params with this instance’s own params.

Own params take precedence on key collision; inherited values flow through unchanged for keys this instance does not set.

Parameters:

inherited (Mapping[str, Expr] | None)

Return type:

dict[str, Expr]

expand_leaves(name_prefix=None, node_remap=None, inherited_params=None, group_path=(), collapse_paths=None)

Return the recursively-flattened leaf components.

name_prefix and node_remap are used internally when this subcircuit is itself nested inside another; callers normally omit them. inherited_params carries the outer-scope parameter bindings that this instance’s params can override. group_path is the chain of enclosing SubCircuit instance names — each leaf is tagged with a _group_path attribute extending this chain by self.name, which downstream renderers (autodraw) use to keep grouped components clustered and to draw a bounding box around them. collapse_paths is the set of fully-qualified group paths (tuples like ("X1", "U1")) that should be replaced by a single _CollapsedGroup placeholder instead of expanded — used by autodraw’s collapse= parameter to hide implementation detail.

Parameters:

• name_prefix (str | None)

• node_remap (dict[str, str] | None)

• inherited_params (Mapping[str, Expr] | None)

• group_path (tuple[str, ...])

• collapse_paths (frozenset[tuple[str, ...]] | None)

Return type:

list