qat.experimental.frontend.importer.base module

class BaseLinearImporter

Bases: ABC

Abstract base for linear, instruction-stream importers into the Pulse dialect.

Provides the common machinery shared by concrete importers (e.g. PurrImporter):

  • ModuleOp is progressively populated. The module is initialised with a main function as an entry-point. All translated operations are inserted into the body of this function.

  • This class tracks the current insertion block (initially the body of main) and environment variables to build a structure control flow from a flat IR. Environment variables maps source-language variables the latest SSA value.

  • Handle opening and closing scf.for regions which pass every tracked environment variable into the loop body as iter-args / block arguments and yield them all back out so the environment map. Threading global access of variables through blocks. This will be optimised in a later pass (COMPILER-1253).

The environment is intentionally global (no scoped stack): every binding is visible everywhere and updates done inside an scf.for body are reflected in the enclosing scope through the loop’s iter-args/results. This is sufficient for structured for loops; if statements will need some more careful tracking of variables.

Initialise an empty module with a main function and empty environment.

Creates a fresh ModuleOp containing a single func.FuncOp named main, sets the function body’s block as the current insertion point, and installs an empty bidict as the environment-variable map.

abstract build(ir)

Translate a source-language IR object into Pulse-dialect ops.

Parameters:

ir – The source IR to import (e.g. a Purr QuantumInstructionBuilder).

Return type:

ModuleOp

Returns:

The populated ModuleOp.

abstract create_frame(target, freq_op)

Create a Pulse-dialect frame for the given source target.

Parameters:

  • target – The source-language object describing the channel to be turned into a frame.

  • freq_op (Operation | SSAValue | None) – An optional pre-built op or SSA value providing the frame’s frequency. When None the implementation should synthesise an appropriate constant from the target.

Return type:

SSAValue

Returns:

The SSA value representing the newly created frame.

enter_for_loop(start, stop, step)

Open a new scf.for region threading all env vars as iter-args.

Creates arith.constant ops for start, stop, and step, gathers every currently-tracked environment variable, and emits an scf.for op whose body block takes an index induction variable followed by one block argument per environment variable. The loop body is set as the current insertion point.

Parameters:

  • start (int) – Loop lower bound (inclusive).

  • stop (int) – Loop upper bound (exclusive).

  • step (int) – Loop step size.

Return type:

None

exit_for_loop()

Close the innermost scf.for region and propagate results out.

Emits an scf.yield for every currently-tracked environment variable (in the same order they were passed in as iter-args), restores the parent block as the current insertion point, and rebinds each environment variable to the corresponding result of the enclosing scf.for op so the post-loop environment observes the loop’s effects.

Return type:

None

abstract get_frames(quantum_targets)

Look up or create Pulse-dialect frames for source-language frame objects.

Implementations are responsible for converting frequency-carrying source objects into frame SSA values, reusing already-created frames where possible.

Parameters:

quantum_targets – Source-language frequency-carrying objects.

Return type:

list[SSAValue]

Returns:

Ordered list of SSA frame values corresponding to each target.

module: ModuleOp
abstract translate(instruction)

Dispatch a single source-language instruction.

Concrete subclasses typically implement this with functools.singledispatchmethod() so that handlers are selected by the instruction’s runtime type.

Parameters:

instruction – The source-language instruction to translate into Pulse-dialect operations.

Return type:

None

update_frames_from_ops(ops)

Refresh the environment-variable map after frame-mutating ops.

For operations that produce a new frame SSA value (e.g. PulseOp), the binding for the consumed frame is replaced with the freshly produced result so subsequent translations see the latest SSA value for each frame.

Parameters:

ops (list[Operation]) – Frame-carrying operations whose results need tracking.

Raises:

KeyError – If a consumed frame cannot be found in the environment-variable map.

Return type:

None