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(create_frame, port, related_ops=None)

Bases: object

Full lineage of a single pulse.create_frame, including all related operations.

Variables:

• create_frame – Root CreateFrameOp.

• port – Physical-port token from CreateFrameOp.

• related_ops – Ordered list of FrameNode objects, one per operation that interacts with this lineage, recorded at its own nesting depth. Each node’s parent is the region-bearing op enclosing it, so walking the chain yields the path out to the entry block.

add_node(op, enclosing=None)

Append a FrameNode for op unless the tail already records it.

enclosing is the node of the region-bearing op containing op, or None when op sits in the entry block. A single walk attaches op once per frame operand resolving to this lineage, so repeats are always adjacent and checking the tail is enough to deduplicate them.

Return type:

None

property entry_ops: tuple[Operation, ...]

Entry-block operations this lineage passes through, in encounter order.

Each node’s FrameNode.root is its outermost enclosing operation, which is the entry-block op that has to be carried along to bring this lineage’s work with it. Deduplicated, since several lineage ops commonly share one enclosing op.

property frame: SSAValue

Shorthand for create_frame.result.

property ops: tuple[Operation, ...]

Ops from related_ops in encounter order.

class FrameLineageAnalysis

Bases: object

Module-level frame-lineage analysis; one FrameLineage per CreateFrameOp.

Value ownership and operation membership are tracked centrally in this object. Operations may intentionally belong to multiple lineages, for example when a synchronization coordinates several frames. Consumers that require independent partitions can inspect shared_ops without reconstructing membership from the lineages.

Variables:

lineages – All discovered lineages in encounter order.

attach(op, lineage, result=None, enclosing=None)

Record op’s use of lineage, optionally claiming result.

Return type:

None

begin_lineage(create_frame, node)

Start a new lineage rooted at create_frame, seeded with node.

Return type:

FrameLineage

classmethod from_lineages(lineages)

Construct an analysis from previously assembled lineages.

Normal analysis construction uses begin_lineage() and attach(). This factory is useful when a caller already owns complete lineage records.

Parameters:

lineages (Iterable[FrameLineage]) – Complete lineages to register in encounter order.

Return type:

FrameLineageAnalysis

Returns:

An analysis containing lineages and their derived indexes.

lineage_for_frame(frame)

Return the FrameLineage whose root value is frame, or None.

Return type:

FrameLineage | None

lineage_for_result(value)

Return the FrameLineage that owns value, or None.

Return type:

FrameLineage | None

lineages_for_op(op)

Return every lineage op is attached to, in encounter order.

Empty for operations the analysis does not track, such as constants and the region- bearing operations that merely enclose a lineage.

Return type:

tuple[FrameLineage, ...]

property port_counts: dict[str, int]

Return the number of lineages sharing each port token.

property shared_ops: tuple[Operation, ...]

Return operations attached to more than one lineage, in encounter order.

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

class FrameNode(op, parent)

Bases: object

One operation in a frame lineage, positioned in the IR nesting hierarchy.

Variables:

• op – The operation this node records.

• parent – Node of the region-bearing operation enclosing op; None when op sits directly in the entry block.

chain()

Yield this node and each enclosing operation, outwards to the entry block.

Return type:

Iterator[FrameNode]

property root: FrameNode

The outermost node, whose op is an entry-block operation.

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 operations are traversed recursively. Membership records the pulse operations themselves at whatever depth they occur, so ownership stays decidable per operation. Each node’s parent is the enclosing region-bearing op, so FrameLineage.entry_ops recovers the entry-block ops a lineage passes through.

Parameters:

module (ModuleOp) – Module containing pulse operations.

Return type:

FrameLineageAnalysis

Returns:

Frame-lineage analysis.

Raises:

PassFailedException – If frame lineage cannot be resolved.