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.
safe_get_driver –

Safely get wire segment driver.
safe_get_wire_path –

Safely get wire segment path.
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.
remove_degenerate_gates –

Remove degenerate gates (only constant inputs) from a module.
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.

safe_get_driver ¶

safe_get_driver(segment: PortSegment) -> Any

Safely get wire segment driver.

safe_get_wire_path ¶

safe_get_wire_path(segment: PortSegment) -> Optional[WireSegmentPath]

Safely get wire segment path.

is_valid_wire_path ¶

is_valid_wire_path(wire_path: Optional[WireSegmentPath]) -> bool

Check if wire path is valid.

is_constant_wire ¶

is_constant_wire(wire_path: Optional[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.

remove_degenerate_gates ¶

remove_degenerate_gates(module: Module, cfg: GateConfig) -> int

Remove degenerate gates (only constant inputs) from a module.

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,
    remove_degenerate: bool = False
) -> CircuitOptimizationResult

Optimize circuit by replacing gate chains with balanced trees.