netlist_carpentry.routines.opt.floodfill.chain_optimizer ¶

Gate-Chain Optimizer - Detects and replaces linear 2-input gate chains with balanced trees.

Supports gate type (or/and) with A, B inputs and Y output. Uses subprocess-based scanning for memory safety on large designs.

Classes:

GateConfig –

Configuration for a 2-input gate type.
GateTreeBuilder –

Builds a balanced gate tree from input wires.
ChainBoundaryExtractor –

Extracts ChainBoundary and constant-input stats for a chain.
ChainReplacer –

Resolves, validates, disconnects and replaces a chain with a balanced tree.
GateChainScanner –

Subprocess-based chain scanner.
CircuitOptimizer –

Coordinates scan/replace across a circuit.

Functions:

get_gate_config –

Resolve gate string ("or" or "§or") into GateConfig.
is_gate –

Check if node is a gate instance of the configured type.
is_chain_head –

Check if node is start of a chain (no gate predecessors).
build_chain –

Build chain by following single gate successors.
find_gate_chains –

Find all gate chains (length >= 2) in graph.
extract_instance_key –

Extract instance identifier from node attributes.
is_valid_wire_path –

Check if wire path is valid.
is_constant_wire –

Check if wire path is a constant (0, 1, x, z, 1'b0, etc.).
is_target_gate –

Check if instance is a gate of the configured type.
build_gate_connectivity –

Build connectivity maps for target gates.
find_gate_chains_netlist –

Find all gate chains (length >= 2) directly from netlist.
analyze_module_gates –

Analyze gates by input count.
fuzzy_find_instance –

Performs a prioritized search to find the most relevant instance in the given module that matches a given name (search).
opt_chains –

Optimize circuit by replacing gate chains with balanced trees.

GateConfig `dataclass` ¶

GateConfig(
    name: str, nsubtype: str, chain_prefix: str, gate_cls: Type[PrimitiveGate]
)

Configuration for a 2-input gate type.

GateTreeBuilder ¶

GateTreeBuilder(
    module: Module, prefix: str, boundary: ChainBoundary, cfg: GateConfig
)

Builds a balanced gate tree from input wires.

ChainBoundaryExtractor ¶

Extracts ChainBoundary and constant-input stats for a chain.

Methods:

collect_external_inputs –

Collect external input wires. Returns (inputs, constant_count).
collect_output_wires –

Collect output wire and internal wires from chain.
extract_boundary –

Extract boundary info. Returns (boundary, constant_count, is_degenerate).

collect_external_inputs ¶

collect_external_inputs(
    chain_instances: Sequence[Instance],
    chain_ids: Set[str],
    internal_wire_paths: Optional[Set[str]] = None,
) -> Tuple[List[WireSegmentPath], int]

Collect external input wires. Returns (inputs, constant_count).

collect_output_wires ¶

collect_output_wires(
    chain_instances: Sequence[Instance],
) -> Tuple[WireSegmentPath, List[WireSegmentPath]]

Collect output wire and internal wires from chain.

extract_boundary ¶

extract_boundary(
    chain_instances: Sequence[Instance],
) -> Tuple[ChainBoundary, int, bool]

Extract boundary info. Returns (boundary, constant_count, is_degenerate).

ChainReplacer ¶

ChainReplacer(boundary_extractor: ChainBoundaryExtractor)

Resolves, validates, disconnects and replaces a chain with a balanced tree.

GateChainScanner ¶

GateChainScanner(script_path: str, python: str | None = None)

Subprocess-based chain scanner.

CircuitOptimizer ¶

CircuitOptimizer(scanner: GateChainScanner, replacer: ChainReplacer)

Coordinates scan/replace across a circuit.

get_gate_config ¶

get_gate_config(gate: str) -> GateConfig

Resolve gate string ("or" or "§or") into GateConfig.

is_gate ¶

is_gate(
    graph: ModuleGraph,
    node: str,
    cfg: GateConfig,
    *,
    exclude_chains: bool = True
) -> bool

Check if node is a gate instance of the configured type.

is_chain_head ¶

is_chain_head(graph: ModuleGraph, node: str, gate_nodes: Set[str]) -> bool

Check if node is start of a chain (no gate predecessors).

build_chain ¶

build_chain(graph: ModuleGraph, start: str, gate_nodes: Set[str]) -> List[str]

Build chain by following single gate successors.

find_gate_chains ¶

find_gate_chains(graph: ModuleGraph, cfg: GateConfig) -> List[List[str]]

Find all gate chains (length >= 2) in graph.

extract_instance_key ¶

extract_instance_key(graph: ModuleGraph, node: str) -> str

Extract instance identifier from node attributes.

is_valid_wire_path ¶

is_valid_wire_path(wire_path: WireSegmentPath) -> bool

Check if wire path is valid.

is_constant_wire ¶

is_constant_wire(wire_path: WireSegmentPath) -> bool

Check if wire path is a constant (0, 1, x, z, 1'b0, etc.).

is_target_gate ¶

is_target_gate(
    instance: Instance, cfg: GateConfig, *, exclude_chains: bool = True
) -> bool

Check if instance is a gate of the configured type.

build_gate_connectivity ¶

build_gate_connectivity(
    module: Module, cfg: GateConfig
) -> Tuple[Dict[str, Instance], Dict[str, Set[str]], Dict[str, Set[str]]]

Build connectivity maps for target gates.

find_gate_chains_netlist ¶

find_gate_chains_netlist(module: Module, cfg: GateConfig) -> List[List[str]]

Find all gate chains (length >= 2) directly from netlist.

analyze_module_gates ¶

analyze_module_gates(module: Module, cfg: GateConfig) -> GateAnalysis

Analyze gates by input count.

fuzzy_find_instance ¶

fuzzy_find_instance(module: Module, search: str) -> Optional[str]

Performs a prioritized search to find the most relevant instance in the given module that matches a given name (search).

The function is designed to find the "closest" match by prioritizing position (end of string is better than middle) and length (shorter strings are considered more specific or exact than longer ones).

opt_chains ¶

opt_chains(
    circuit: Optional[Circuit] = None,
    input_path: Optional[str] = None,
    top_module: Optional[str] = None,
    *,
    gates: Optional[List[str]] = None,
    output_path: Optional[str] = None,
    skip_modules: Optional[Set[str]] = None
) -> CircuitOptimizationResult

Optimize circuit by replacing gate chains with balanced trees.