quchip.chip.transformations.plumbing¶

Shared control-plane and chip-rebuild plumbing for quchip.chip.transformations.

Every transformation of shape Chip -> (Chip + diagnostics) faces the same control-plane problem: a control line whose target has no image in the reduced model (its device was eliminated, or its coupling touched the eliminated mode) must either be converted by a registered retarget rule or fail fast. It also rebuilds a reduced Chip from surviving devices and couplings, reattaches the converted equipment, and detaches the intermediate clone. These four steps are identical across the device and coupling reduction paths, so they live here as single-purpose functions reused by any Chip -> EliminationResult transformation without touching dispatch — the same shared-plumbing role quchip.chip.retarget plays for the rule lookup itself.

The two reduction paths differ only in how a doomed line is detected and what fail-fast message it raises; both feed a per-path classify closure into plan_stranded_lines(), which owns the detection order and the rule lookup.

Functions

`detach_intermediate_clone`(devices, clone)	Detach the intermediate clone from the surviving devices deterministically.
`plan_stranded_lines`(equipment, classify, ...)	Partition control lines into survivors and a retarget plan, failing fast on missing rules.
`reattach_equipment`(source_chip, final_chip, ...)	Apply the retarget plan and attach the survivor plus converted lines to the reduced chip.
`rebuild_chip`(source_chip, *, devices, couplings)	Construct a reduced chip carrying the source chip's frame, RWA, backend, and baths.

Classes

StrandedLine(rule_target, missing_rule_message)

One doomed control line's retarget target and its fail-fast message.

class quchip.chip.transformations.plumbing.StrandedLine(rule_target, missing_rule_message)[source]¶

Bases: object

One doomed control line’s retarget target and its fail-fast message.

Parameters:

rule_target (Any)
missing_rule_message (str)

rule_target¶

The eliminated target a converter would retarget the line onto — a coupling object for a coupling reduction, a device or an edge coupling for a device reduction. Its type drives the MRO lookup in lookup_retarget_rule().

Type:: Any

missing_rule_message¶

The exact ValueError message plan_stranded_lines() raises when no rule converts the line. Each reduction path builds its own message so the wording matches the target it eliminated.

Type:: str

rule_target: Any¶

missing_rule_message: str¶

quchip.chip.transformations.plumbing.plan_stranded_lines(equipment, classify, result_kind)[source]¶

Partition control lines into survivors and a retarget plan, failing fast on missing rules.

Each line is classified: a survivor (classify returns None) passes through untouched; a doomed line (classify returns a StrandedLine) has its converter looked up now, before any fold work, so a missing rule raises immediately. Rule application is deferred to reattach_equipment() (a converter may need an edge the reduction has not emitted yet), so this pass only detects and fails fast — the same ordering the device and coupling paths rely on.

Parameters:

equipment (Any) – The source chip’s ControlEquipment, or None when no equipment is wired.
classify (Callable[[Any], StrandedLine | None]) – classify(line) -> StrandedLine | None: None marks a survivor, a StrandedLine marks a doomed line.
result_kind (str) – The reduction’s result kind ("edge", "leaf-fold", or "crosskerr"), matched exactly by the rule lookup.

Returns:

(survivor_lines, retarget_plan) in original line order: survivor_lines is the list of pass-through lines, retarget_plan is a list of (line, rule) pairs.

Return type:

tuple

Raises:

ValueError – With the doomed line’s missing_rule_message when no registered rule converts it.

quchip.chip.transformations.plumbing.rebuild_chip(source_chip, *, devices, couplings)[source]¶

Construct a reduced chip carrying the source chip’s frame, RWA, backend, and baths.

The label, frame (deep-copied when a per-device dict), RWA flag, backend, and baths are copied off source_chip; devices and couplings are the reduction’s survivors. An empty couplings becomes None (a chip with no couplings), matching the constructor’s own convention.

Parameters:

source_chip (Any) – The chip being reduced; never mutated.
devices (Any) – The surviving devices for the reduced chip.
couplings (Any) – The surviving (and emitted) couplings; an empty iterable yields a coupling-free chip.

Returns:

The reduced chip, before control equipment is attached.

Return type:

Chip

quchip.chip.transformations.plumbing.reattach_equipment(source_chip, final_chip, equipment, survivor_lines, retarget_plan, *, mode_label, result_kind, edges, notes)[source]¶

Apply the retarget plan and attach the survivor plus converted lines to the reduced chip.

A no-op when equipment is None. Otherwise each (line, rule) in retarget_plan is converted against a RetargetContext built from the reduction’s mode_label, result_kind, and emitted edges; every converter’s note is appended to notes. The survivor lines and the converted lines are then combined and connected to final_chip.

Parameters:

source_chip (Any) – The original (pre-reduction) chip the converters read from.
final_chip (Any) – The reduced chip the equipment is attached to.
equipment (Any) – The source chip’s control equipment, or None.
survivor_lines (list[Any]) – Lines that pass through unchanged, from plan_stranded_lines().
retarget_plan (list[tuple[Any, Any]]) – (line, rule) pairs from plan_stranded_lines().
mode_label (str) – The eliminated device (or coupling) label, for the retarget context.
result_kind (str) – The reduction’s result kind, for the retarget context.
edges (Any) – The per-pair emitted-edge entries ("edge"/"crosskerr") or None ("leaf-fold"), for the retarget context.
notes (list[str]) – The result’s note list, extended in place with each converter’s note.

Return type:

None

quchip.chip.transformations.plumbing.detach_intermediate_clone(devices, clone)[source]¶

Detach the intermediate clone from the surviving devices deterministically.

Parameters:

devices (Any) – The surviving devices, now owned by the reduced chip.
clone (Any) – The intermediate clone the reduction built the survivors from.

Return type:

None