qat.experimental.dialect.pulse.transforms.partition_by_frame module

Partition Pulse entry blocks by logical frame lineage.

The analysis in this module keeps logical frame identity separate from physical port identity. This allows later passes to reason about lineages without losing the hardware- facing port metadata attached to each frame.

class FrameLineage(frame, port, operations=<factory>)

Bases: object

Operations associated with one logical frame lineage.

A lineage is rooted at one pulse.create_frame result and collects the operations that remain associated with that frame through the entry block.

Variables:

  • frame – pulse.create_frame result representing this lineage.

  • port – Physical-port token carried by FrameType.

  • operations – Operations associated with this lineage, in entry-block encounter order.

frame: SSAValue
operations: list[Operation]
port: str
class FrameLineageAnalysis(frame_to_operations, frame_to_port, port_to_frames, value_to_frame)

Bases: object

Frame-lineage analysis for Pulse IR.

The analysis separates logical frame identity from physical port identity. The former drives partitioning. The latter is preserved as metadata for subsequent lowering stages.

Variables:

  • frame_to_operations – Ordered operations per lineage frame. This records the lineage membership in the entry block, not a ready-made sequence body. A lowering pass may still need to clone supporting definitions before materialising a q1_sequence.sequence envelope.

  • frame_to_port – Physical port metadata per lineage frame.

  • port_to_frames – Lineage frames grouped by physical port.

  • value_to_frame – Lineage frame associated with each frame SSA value.

frame_to_operations: Mapping[SSAValue, tuple[Operation, ...]]
frame_to_port: Mapping[SSAValue, str]
port_to_frames: Mapping[str, tuple[SSAValue, ...]]
value_to_frame: Mapping[SSAValue, SSAValue]
class FrameLineagePass

Bases: ModulePass

Compute frame-lineage analysis for pulse-level lowering.

property analysis: FrameLineageAnalysis | None

Return the most recent frame-lineage analysis computed by this pass.

apply(ctx, op)
Return type:

None

name: ClassVar[str] = 'pulse.compute-frame-lineage'
state: _LineageState
build_frame_lineage_analysis(module)

Analyze pulse operations by frame lineage.

The partition key is the logical frame identity rooted at pulse.create_frame. Physical port identity is retained as metadata so later lowering stages can recover the hardware-facing view without collapsing distinct logical frames. Region-bearing entry operations are rejected because the analysis currently runs on a flat instruction stream.

Parameters:

module (ModuleOp) – Module containing pulse operations.

Return type:

FrameLineageAnalysis

Returns:

Frame-lineage analysis maps.

Raises:

PassFailedException – If frame lineage cannot be resolved.