‘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.input_name records the source-level name of a function input. 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 allocation. 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. mqt.unitary marks a private function that defines a unitary operation. Its body admits unitary operations and memory-effect-free, region-free classical computation, matching the quantum modifier-body contract. 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
>

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. 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`

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

Passes¶

See Passes for shared metadata and modifier passes.