Hooks

Extra-check hooks referenced by hook.

A hook is a "module:function" path, resolved dynamically by circuitgenome.recognizer.subcircuit_recognizer.recognize(). It is called once per base-template match with (assignment, pins, netlist):

• assignment – dict[str, Device] mapping each PatternDevice ref to the actual matched device.

• pins – the base template’s resolved pins, before any hook extension.

• netlist – the full ParsedNetlist being recognized.

It returns either None (reject the match) or a HookMatch (accept, optionally appending devices/pins) – see HookMatch for the full contract.

circuitgenome.recognizer.hooks.constructed_bias_legs(assignment, pins, netlist)

Discover the legs of a constructed multi-reference bias generator.

Hook for the constructed_bias pattern (config/opamp_patterns.yaml). The synthesizer constructs its bias generator per combination (circuitgenome.synthesizer.bias_construction.construct_bias_generation()): an NMOS master reference on ibias (the base template’s mref), NMOS-referenced legs mirroring it, and – when any rail needs a PMOS-referenced level – a pref branch whose diode-connected PMOS gates further PMOS-referenced legs. This hook discovers all of them:

• Pass 1 (NMOS-referenced): every nmos with gate on mref’s diode node (the ibias net) and source on mref’s source (gnd) mirrors the master. What sits on its drain names the leg:

  • a plain diode-connected pmos (d == g, s == b): a vdd-flavored leg or the pref branch’s diode (structurally identical – both are claimed; which is which doesn’t matter for sizing); the pmos-diode node is remembered as a potential PMOS-side reference gate;

  • a riding pmos diode (d == g on the drain, s on an internal node) whose source returns to its bulk supply through an unclaimed resistor: a cascode_vdd leg (diode + floor resistor, out = vdd - |V_GSP| - I*R) – all three devices are claimed;

  • an nmos cascode (source on the drain node) topped by a plain pmos diode: the cascoded pref branch (the cascode pins the mirror’s Vds; its gate rides the wide-swing ncasc level, whose generator branch is claimed by pass 2 as an ordinary gnd-flavored leg) – the cascode and diode are claimed, the diode node becomes a reference gate;

  • nothing: a bare mirror, claimed alone – a current-sink leg into a consumer’s own diode.

• Pass 2 (PMOS-referenced): every pmos gated on a pass-1 pmos-diode node with source on that diode’s supply is a leg only if its drain hosts a diode-connected nmos (a gnd-flavored leg – including the pref branch’s ncasc generator – a cascode_gnd leg when the diode rides an unclaimed resistor to gnd, or a current-source leg into a mirror tail’s own reference diode) or a resistor returning to mref’s gnd (a tunable resistor leg). The drain condition keeps consumer devices out: a second-stage PMOS gated by a vdd-flavored rail has neither on its drain.

Returns None when neither pass finds constructed-only evidence (no PMOS-referenced leg and no cascode_vdd leg): the structure is then the exact shape diode_connected_mosfet_bias_legs() discovers, and that pattern (listed after this one) claims it instead – keeping legacy single-flavor netlists recognized under their historical names.

Parameters:

• assignment (dict[str, Device]) – Must contain key "mref" – the matched diode-connected nmos master reference.

• pins (dict[str, str]) – Unused; accepted for signature consistency with other hooks.

• netlist (ParsedNetlist) – The full parsed netlist to search for legs in.

Returns:

A HookMatch with every discovered leg’s devices in extra_devices and its output net as legN_out in extra_pins (1-indexed by discovery order; rail indices are not a structural property of a leg), plus vdd from the first pmos diode found. None if no PMOS-referenced leg exists.

Return type:

HookMatch | None

circuitgenome.recognizer.hooks.diode_connected_mosfet_bias_legs(assignment, pins, netlist)

Discover the output “legs” attached to a diode-connected bias reference.

Hook for the diode_connected_mosfet_bias pattern (config/opamp_patterns.yaml). That pattern’s base template matches only a single diode-connected nmos (template ref mref: d == g, tied to gnd via s/b) – the shared reference of the historical diode_connected_mosfet_bias variant, which the constructed_bias pattern’s constructed_bias_legs() also shares (that hook rejects the purely-NMOS-referenced shape so this one can claim it under the historical name).

This hook does the rest: it walks the netlist looking for “legs” – self-contained 2-device groups that mirror mref and deliver one output rail. A leg consists of:

• an nmos device whose gate ties to mref’s diode-connected node (mref.g == mref.d, i.e. the ibias net) and whose source/bulk tie to mref.s (the gnd net) – this mirrors mref’s reference current; paired with

• a pmos device that is itself diode-connected (d == g) at that nmos leg’s drain, with s == b (its own supply net) – this is the leg’s output node.

Each discovered leg’s nmos+pmos pair is appended to HookMatch.extra_devices, and its output net is recorded as legN_out in HookMatch.extra_pins (1-indexed by discovery order – which of the eight canonical bias rails (out1..``out8``) a leg corresponds to is not a structural property of the leg itself, and is left for FBR/topology context to determine if needed). The first discovered leg’s supply net is also recorded as vdd.

Parameters:

• assignment (dict[str, Device]) – Must contain key "mref" – the matched diode-connected nmos reference device.

• pins (dict[str, str]) – Unused; accepted for signature consistency with other hooks.

• netlist (ParsedNetlist) – The full parsed netlist to search for legs in.

Returns:

A HookMatch with one (nmos, pmos) pair per discovered leg appended to extra_devices, and legN_out/vdd entries in extra_pins. If zero legs are found, still returns HookMatch(extra_devices=[], extra_pins={}) – a constructed bias generator with no consumed rails collapses to exactly this bare mref, with no legs to find. A spurious bare-diode-connected-nmos match elsewhere (e.g. current_mirror_tail_nmos’s m1) is harmless: its ibias pin won’t equal the real ibias net, so _connectivity_score() ranks it below the genuine bias-generation candidate.

Return type:

HookMatch | None

circuitgenome.recognizer.hooks.magic_battery_bias_legs(assignment, pins, netlist)

Discover the output “legs” attached to a magic-battery bias reference.

Hook for the magic_battery_bias pattern (config/opamp_patterns.yaml). That pattern’s base template matches only a single diode-connected pmos (template ref mref: d == g, tied to vdd via s/b). This mirrors diode_connected_mosfet_bias_legs() with polarities flipped: a leg here is a (pmos, nmos) pair, where the pmos mirrors mref from the vdd rail and the nmos is diode-connected at the leg’s output node.

A leg consists of:

• a pmos device whose gate ties to mref’s diode-connected node (mref.g == mref.d, i.e. the ibias net) and whose source/bulk tie to mref.s (the vdd net) – this mirrors mref’s reference current; paired with

• an nmos device that is itself diode-connected (d == g) at that pmos leg’s drain, with s == b (its own reference net) – this is the leg’s output node.

Each discovered leg’s pmos+nmos pair is appended to HookMatch.extra_devices, and its output net is recorded as legN_out in HookMatch.extra_pins (1-indexed by discovery order). The first discovered leg’s nmos-side reference net is also recorded as gnd.

Parameters:

• assignment (dict[str, Device]) – Must contain key "mref" – the matched diode-connected pmos reference device.

• pins (dict[str, str]) – Unused; accepted for signature consistency with other hooks.

• netlist (ParsedNetlist) – The full parsed netlist to search for legs in.

Returns:

A HookMatch with one (pmos, nmos) pair per discovered leg appended to extra_devices, and legN_out/gnd entries in extra_pins. Returns None (rejecting the match) if zero legs are found – a bare diode-connected pmos with no legs is structurally identical to resistor_bias’s mref in the same 0-rail case, and diode_connected_mosfet_bias already claims it then.

Return type:

HookMatch | None

circuitgenome.recognizer.hooks.resistor_bias_legs(assignment, pins, netlist)

Discover the output “legs” attached to a resistor-bias reference.

Hook for the resistor_bias pattern (config/opamp_patterns.yaml). Like magic_battery_bias_legs(), the base template matches only a single diode-connected pmos (mref: d == g, tied to vdd via s/b). Here, each leg is a (pmos, resistor) pair: a pmos mirrors mref from the vdd rail, and a resistor drops the leg’s output node down to its gnd-referenced terminal.

A leg consists of:

• a pmos device whose gate ties to mref’s diode-connected node (mref.g == mref.d, i.e. the ibias net) and whose source/bulk tie to mref.s (the vdd net) – this mirrors mref’s reference current; paired with

• a resistor device with one terminal at that pmos leg’s drain – this is the leg’s output node, and the resistor’s other terminal is the leg’s gnd reference.

Each discovered leg’s pmos+resistor pair is appended to HookMatch.extra_devices, and its output net is recorded as legN_out in HookMatch.extra_pins (1-indexed by discovery order). The first discovered leg’s resistor-side reference net is also recorded as gnd.

Parameters:

• assignment (dict[str, Device]) – Must contain key "mref" – the matched diode-connected pmos reference device.

• pins (dict[str, str]) – Unused; accepted for signature consistency with other hooks.

• netlist (ParsedNetlist) – The full parsed netlist to search for legs in.

Returns:

A HookMatch with one (pmos, resistor) pair per discovered leg appended to extra_devices, and legN_out/gnd entries in extra_pins. Returns None (rejecting the match) if zero legs are found – a bare diode-connected pmos with no legs is structurally identical to magic_battery_bias’s mref in the same 0-rail case, and diode_connected_mosfet_bias already claims it then.

Return type:

HookMatch | None

circuitgenome.recognizer.hooks.resistor_tail_vdd_check(assignment, pins, netlist)

Accept only if the matched resistor’s t1 is the global vdd! rail.

Hook for the resistor_tail_vdd pattern (config/opamp_patterns.yaml). That pattern’s template is a single, unconstrained resistor – without this check it would match every resistor in the netlist (e.g. a resistor_load_*’s, a resistor_bias’s, or a degenerated input pair’s degeneration resistor), most of which have nothing to do with the tail current source.

Parameters:

• assignment (dict[str, Device]) – Must contain key "r1" – the matched resistor.

• pins (dict[str, str]) – Unused; accepted for signature consistency with other hooks.

• netlist (ParsedNetlist) – Unused; accepted for signature consistency with other hooks.

Returns:

HookMatch(extra_devices=[], extra_pins={}) if r1.t1 == "vdd!", else None (reject).

Return type:

HookMatch | None

circuitgenome.recognizer.hooks.resistor_tail_gnd_check(assignment, pins, netlist)

Accept only if the matched resistor’s t2 is the global gnd! rail.

Mirror of resistor_tail_vdd_check() for the resistor_tail_gnd pattern.

Parameters:

• assignment (dict[str, Device]) – Must contain key "r1" – the matched resistor.

• pins (dict[str, str]) – Unused; accepted for signature consistency with other hooks.

• netlist (ParsedNetlist) – Unused; accepted for signature consistency with other hooks.

Returns:

HookMatch(extra_devices=[], extra_pins={}) if r1.t2 == "gnd!", else None (reject).

Return type:

HookMatch | None