‘mqt’ Dialect¶

Shared metadata for MQT quantum programs.

The MQT dialect owns frontend-neutral metadata that must remain meaningful across quantum dialect conversions. It defines no operations or types.

mqt.layout is a dictionary on the program module. The dictionary records layout metadata:

initial: a complete dense i64 permutation from program qubits to device positions, including workspace qubits.
routing (optional): a complete dense i64 permutation from placed device positions to final positions. Without it, positions do not change.
input_count: number of program qubits before workspace qubits.
sites (optional): distinct nonnegative target site IDs in device-position order, one per position. Target compilation sets this field. Without it, positions refer to circuit wires, as for imported Qiskit layouts.

The final position of program qubit i is routing[initial[i]] when routing is present. Qiskit input register names and partial layouts are not retained. The metadata does not affect gates or store SDK objects. Copies and plain QC/QCO conversions retain it. Compiler pipeline runners clear it before transformations that may change qubit identity. Raw IR editors must preserve, update, or discard the layout when changing qubit identity or order.

mqt.source_qubit_count records the input count during target preparation. Placement consumes it when publishing the completed layout. mqt.source_qubit_indices tracks native input slots: a dense i64 array of distinct nonnegative indices, one per qco.alloc or fixed-size qtensor.alloc slot. Tensor shrinking retains surviving entries; placement consumes them. Removed slots remain in the attached layout.

mqt.input_name records the source-level name of a function input. mqt.input_id optionally records an opaque 128-bit source identity on a named function input. It is an i128 attribute, unique within the function; every bit pattern is valid. Transformations carry it with the input and remove it when removing the input. It does not identify an SSA value or change execution semantics. mqt.source_name records a source-level function name when the IR symbol must be uniquified. mqt.parameter_group optionally preserves the source-level vector identity, name, element index, and size of a function input or a lexically bound scf.for parameter. mqt.register_name records the source-level name of a quantum or classical register declaration, including local reference buffers created during conversion. Input and register names share one function-wide namespace. mqt.entry_point marks the single public, defined func.func program entry in a module. Dynamic quantum allocations (qc.alloc, qco.alloc, qubit memref.alloc, and qtensor.alloc) must appear directly in its entry block. Other functions receive quantum resources as arguments; they cannot allocate them. Classical allocations and static qubit references are not subject to this restriction. A program cannot mix static and dynamic qubit allocation modes. mqt.unitary marks a private function that defines a unitary operation. Its body admits unitary operations and memory-effect-free, region-free classical computation. Statically bounded scf.for loops may contain these operations and nested bounded loops. QCO loop results must continue their loop-carried qubits positionally. Other control flow is unsupported; quantum modifier bodies exclude loops. Parameter computation is evaluated eagerly when the invocation is reached; it need not be speculatable. The quantum action is unitary on the computation’s defined input domain. Modifiers transform that action, not the parameter computation: inverse does not reverse it, control does not conditionally evaluate it, and power does not repeat it, including at exponent zero. Undefined inputs do not guarantee traps. Unitary operations may retain effects such as a scoped global-phase contribution. #mqt.compilation_target records compiler-target facts as typed IR. mqt.target_env records compiler-target facts and the selected payload execution contract.

Attributes¶

CompilationTargetAttr¶

Typed compiler-target facts

Syntax:

#mqt.compilation_target<
  StringAttr,   # name
  ::llvm::ArrayRef<SiteAttr>,   # sites
  DurationUnitAttr,   # duration_unit
  `all_to_all` | `explicit`,   # connectivity
  ::llvm::ArrayRef<CouplingAttr>,   # couplings
  `unrestricted` | `explicit`,   # native_operations
  ::llvm::ArrayRef<NativeOperationAttr>   # operations
>

Records source target facts without derived routing or synthesis caches. Ordered sites define dense compiler vertices. Connectivity and native operation support is unrestricted or explicit.

The following target has two explicitly connected sites and one native operation:

#mqt.compilation_target<
    name = "device", sites = [<id = 4>, <id = 7>],
    connectivity = explicit, couplings = [<source = 4, target = 7>],
    native_operations = explicit,
    operations = [<name = "cx",
        arity = #mqt.operation_arity<kind = fixed, value = 2>,
        num_parameters = 0, site_tuples = [<[4, 7]>]>]>

Parameters:¶

Parameter	C++ type	Description
name	`StringAttr`
sites	`::llvm::ArrayRef<SiteAttr>`
duration_unit	`DurationUnitAttr`
connectivity	`::mlir::mqt::ConnectivityKind`	an enum of type ConnectivityKind
couplings	`::llvm::ArrayRef<CouplingAttr>`
native_operations	`::mlir::mqt::NativeOperationsKind`	an enum of type NativeOperationsKind
operations	`::llvm::ArrayRef<NativeOperationAttr>`

CouplingAttr¶

One undirected compiler-target coupling

Syntax:

#mqt.coupling<
  int64_t,   # source
  int64_t   # target
>

A coupling joins two target site identifiers. For example, #mqt.coupling<source = 4, target = 7> permits interactions between sites 4 and 7.

Parameters:¶

Parameter	C++ type	Description
source	`int64_t`
target	`int64_t`

DurationUnitAttr¶

Unit for raw compiler-target durations

Syntax:

#mqt.duration_unit<
  StringAttr,   # unit
  FloatAttr   # scale_factor
>

The scale factor converts each raw duration to the named unit. For example, #mqt.duration_unit<unit = "ns", scale_factor = 1.000000e+00 : f64> records durations in nanoseconds.

Parameters:¶

Parameter	C++ type	Description
unit	`StringAttr`
scale_factor	`FloatAttr`

NativeOperationAttr¶

One native compiler-target operation

Syntax:

#mqt.native_operation<
  StringAttr,   # name
  OperationArityAttr,   # arity
  uint64_t,   # num_parameters
  ::llvm::ArrayRef<SiteTupleAttr>,   # site_tuples
  std::optional<uint64_t>,   # duration
  FloatAttr,   # fidelity
  ArrayAttr,   # fixed_parameters
  StringAttr,   # canonical_name
  ArrayAttr   # parameter_bounds
>

The operation records its spelling, arity, parameter count, and optional global or site-specific calibration data. An empty site-tuple list means general applicability; a nonempty list gives all supported ordered placements. Optional fixed_parameters contains one entry per parameter: a finite f64 value for a fixed parameter, or unit for an unrestricted one. Optional canonical_name identifies the compiler operation when the reported name is a device-specific instruction name. Optional parameter_bounds contains one inclusive two-element f64 array per parameter, or unit for an unbounded parameter. The following example records a directional controlled-X operation:

#mqt.native_operation<name = "cx",
    arity = #mqt.operation_arity<kind = fixed, value = 2>,
    num_parameters = 0, site_tuples = [<[4, 7]>]>

Parameters:¶

Parameter	C++ type	Description
name	`StringAttr`
arity	`OperationArityAttr`
num_parameters	`uint64_t`
site_tuples	`::llvm::ArrayRef<SiteTupleAttr>`
duration	`std::optional<uint64_t>`
fidelity	`FloatAttr`
fixed_parameters	`ArrayAttr`
canonical_name	`StringAttr`
parameter_bounds	`ArrayAttr`

OperationArityAttr¶

Accepted width of a compiler-target operation

Syntax:

#mqt.operation_arity<
  `fixed` | `variadic`,   # kind
  uint64_t   # value
>

A fixed arity accepts exactly its value. A variadic arity accepts its value or any larger width. For example, #mqt.operation_arity<kind = variadic, value = 1> accepts a gate with one target and any number of controls.

Parameters:¶

Parameter	C++ type	Description
kind	`::mlir::mqt::OperationArityKind`	an enum of type OperationArityKind
value	`uint64_t`

PayloadFormatAttr¶

Exact payload identity

Syntax:

#mqt.payload_format<
  StringAttr,   # id
  StringAttr,   # version
  StringAttr,   # profile
  `text` | `binary`   # encoding
>

Identifies a payload by format ID, exact version, optional profile ID, and encoding. Every field takes part in identity. An empty profile denotes a payload without a named profile.

The following identity selects binary QIR 2.1 with the base profile:

#mqt.payload_format<id = "qir", version = "2.1",
    profile = "base", encoding = binary>

Parameters:¶

Parameter	C++ type	Description
id	`StringAttr`
version	`StringAttr`
profile	`StringAttr`
encoding	`::mlir::mqt::PayloadEncoding`	an enum of type PayloadEncoding

PayloadSpecAttr¶

Selected payload execution contract

Syntax:

#mqt.payload_spec<
  PayloadFormatAttr,   # format
  ::llvm::ArrayRef<ProgramCapabilityAttr>,   # capabilities
  bool   # optional_capabilities_known
>

Records the exact payload and its effective capabilities. Producers expand format baselines before creating this attribute. The capability list remains available when optional capability metadata is unknown; optional_capabilities_known records whether that optional metadata is complete.

The following producer-defined format reports bounded forward branching. Its optional capability metadata is incomplete:

#mqt.payload_spec<
    format = <id = "vendor-ir", version = "1.0.0", profile = "",
        encoding = binary>,
    capabilities = [<id = "forward-branching", value = 0,
        constraints = [<id = "max-control-flow-nesting-depth", value = 4>]>],
    optional_capabilities_known = false>

Parameters:¶

Parameter	C++ type	Description
format	`PayloadFormatAttr`
capabilities	`::llvm::ArrayRef<ProgramCapabilityAttr>`
optional_capabilities_known	`bool`

ProgramCapabilityAttr¶

One payload execution capability

Syntax:

#mqt.program_capability<
  StringAttr,   # id
  uint64_t,   # value
  ::llvm::ArrayRef<ProgramConstraintAttr>   # constraints
>

Records one extensible capability ID, its feature-specific value, and all constraints on that capability. Unknown IDs remain valid so newer producers can round-trip through older consumers.

Parameters:¶

Parameter	C++ type	Description
id	`StringAttr`
value	`uint64_t`
constraints	`::llvm::ArrayRef<ProgramConstraintAttr>`

ProgramConstraintAttr¶

One constraint on a payload capability

Syntax:

#mqt.program_constraint<
  StringAttr,   # id
  uint64_t   # value
>

Records one extensible constraint ID and its constraint-specific value.

Parameters:¶

Parameter	C++ type	Description
id	`StringAttr`
value	`uint64_t`

SiteAttr¶

One ordered compiler-target site

Syntax:

#mqt.site<
  int64_t,   # id
  StringAttr,   # name
  std::optional<uint64_t>,   # t1
  std::optional<uint64_t>   # t2
>

Site identifiers come from the target. The array order defines dense compiler vertices. For example, #mqt.site<id = 4, name = "q4"> records one named site.

Parameters:¶

Parameter	C++ type	Description
id	`int64_t`
name	`StringAttr`
t1	`std::optional<uint64_t>`
t2	`std::optional<uint64_t>`

SiteTupleAttr¶

One supported ordered placement with optional calibration

Syntax:

#mqt.site_tuple<
  ::llvm::ArrayRef<int64_t>,   # sites
  std::optional<uint64_t>,   # duration
  FloatAttr   # fidelity
>

The tuple records one supported ordered placement and optional calibration overrides. Missing calibration values inherit the operation defaults. For example, #mqt.site_tuple<[4, 7], duration = 40> records an ordered two-site placement with a raw duration of 40.

Parameters:¶

Parameter	C++ type	Description
sites	`::llvm::ArrayRef<int64_t>`
duration	`std::optional<uint64_t>`
fidelity	`FloatAttr`

TargetEnvAttr¶

Selected compilation and payload specification

Syntax:

#mqt.target_env<
  CompilationTargetAttr,   # compilation_target
  PayloadSpecAttr   # payload_specification
>

Combines typed compiler-target facts with the selected payload contract.

The following environment pairs a one-site target with a producer-defined payload:

#mqt.target_env<
    compilation_target = #mqt.compilation_target<
        sites = [<id = 0>], connectivity = all_to_all, couplings = [],
        native_operations = unrestricted, operations = []>,
    payload_specification = #mqt.payload_spec<
        format = <id = "vendor-ir", version = "1.0.0", profile = "",
            encoding = binary>,
        capabilities = [], optional_capabilities_known = false>>

Parameters:¶

Parameter	C++ type	Description
compilation_target	`CompilationTargetAttr`
payload_specification	`PayloadSpecAttr`

Enums¶

ConnectivityKind¶

Target connectivity

Cases:¶

Symbol	Value	String
AllToAll	`0`	all_to_all
Explicit	`1`	explicit

NativeOperationsKind¶

Native-operation support

Cases:¶

Symbol	Value	String
Unrestricted	`0`	unrestricted
Explicit	`1`	explicit

OperationArityKind¶

Operation arity kind

Cases:¶

Symbol	Value	String
Fixed	`0`	fixed
Variadic	`1`	variadic

PayloadEncoding¶

Payload encoding

Cases:¶

Symbol	Value	String
Text	`0`	text
Binary	`1`	binary

Compilation seed¶

mqt.compilation_seed is a signless i64 module attribute used by the compiler while running passes. Its bits encode an unsigned 64-bit seed and override pass-local seeds, including passes on nested modules. An outer override takes precedence. The driver restores the original attribute after compilation; crash reproducers retain the effective value as input metadata.

Passes¶

See Passes for shared metadata and modifier passes.