pyqir

class pyqir.ArrayType

Bases: Type

An array type.

count

The number of elements in the array.

Type:

int

element

The type of the array elements.

Type:

Type

class pyqir.Attribute

Bases: object

An attribute.

string_kind

The id of this attribute as a string.

Type:

str

string_value

The value of this attribute as a string, or None if this is not a string attribute.

Type:

Optional[str]

class pyqir.AttributeList

Bases: object

The attribute list for a function.

func

The attributes for the function itself.

Type:

AttributeDict

param(n)

The attributes for a parameter.

Parameters:

n (int) – The parameter number, starting from zero.

Returns:

The parameter attributes.

Return type:

AttributeDict

ret

The attributes for the return type.

Type:

AttributeDict

class pyqir.AttributeSet

Bases: object

A set of attributes for a specific part of a function.

class pyqir.BasicBlock

Bases: Value

A basic block.

If the before block is given, this basic block is inserted directly before it. If no before block is given, a parent function must be given, and this basic block is appended to the end of that function.

Parameters:
instructions

The instructions in this basic block.

Type:

List[Instruction]

terminator

The terminating instruction of this basic block if there is one.

Type:

Optional[Instruction]

class pyqir.BasicQisBuilder(builder: Builder)

Bases: object

An instruction builder that generates instructions from the basic quantum instruction set.

cx(control: Value, target: Value) → None

Inserts a controlled Pauli \(X\) gate.

Parameters:

  • control – The control qubit.

  • target – The target qubit.

cz(control: Value, target: Value) → None

Inserts a controlled Pauli \(Z\) gate.

Parameters:

  • control – The control qubit.

  • target – The target qubit.

h(qubit: Value) → None

Inserts a Hadamard gate.

Parameters:

qubit – The target qubit.

if_result(cond: Value, one: ~typing.Callable[[], None] = <function BasicQisBuilder.<lambda>>, zero: ~typing.Callable[[], None] = <function BasicQisBuilder.<lambda>>) → None

Inserts a branch conditioned on a measurement result.

Instructions inserted when one is called will be inserted into the one branch. Instructions inserted when zero is called will be inserted into the zero branch. The one and zero callables should use this module’s builder to build instructions.

Parameters:

  • cond – The result condition to branch on.

  • one – A callable that inserts instructions for the branch where the result is one.

  • zero – A callable that inserts instructions for the branch where the result is zero.

mz(qubit: Value, result: Value) → None

Inserts a Z-basis measurement operation.

Parameters:

  • qubit – The qubit to measure.

  • result – A result where the measurement result will be written to.

reset(qubit: Value) → None

Inserts a reset operation.

Parameters:

qubit – The qubit to reset.

rx(theta: Value | float, qubit: Value) → None

Inserts a rotation gate about the \(x\) axis.

Parameters:

  • theta – The angle to rotate by.

  • qubit – The qubit to rotate.

ry(theta: Value | float, qubit: Value) → None

Inserts a rotation gate about the \(y\) axis.

Parameters:

  • theta – The angle to rotate by.

  • qubit – The qubit to rotate.

rz(theta: Value | float, qubit: Value) → None

Inserts a rotation gate about the \(z\) axis.

Parameters:

  • theta – The angle to rotate by.

  • qubit – The qubit to rotate.

s(qubit: Value) → None

Inserts an \(S\) gate.

Parameters:

qubit – The target qubit.

s_adj(qubit: Value) → None

Inserts an adjoint \(S\) gate.

Parameters:

qubit – The target qubit.

t(qubit: Value) → None

Inserts a \(T\) gate.

Parameters:

qubit – The target qubit.

t_adj(qubit: Value) → None

Inserts an adjoint \(T\) gate.

Parameters:

qubit – The target qubit.

x(qubit: Value) → None

Inserts a Pauli \(X\) gate.

Parameters:

qubit – The target qubit.

y(qubit: Value) → None

Inserts a Pauli \(Y\) gate.

Parameters:

qubit – The target qubit.

z(qubit: Value) → None

Inserts a Pauli \(Z\) gate.

Parameters:

qubit – The target qubit.

class pyqir.Builder

Bases: object

An instruction builder.

Parameters:

context (Context) – The LLVM context.

add(lhs, rhs)

Inserts an addition instruction.

Parameters:

  • lhs (Value) – The left-hand side.

  • rhs (Value) – The right-hand side.

Returns:

The sum.

Return type:

Value

and_(lhs, rhs)

Inserts a bitwise logical and instruction.

Parameters:

  • lhs (Value) – The left-hand side.

  • rhs (Value) – The right-hand side.

Returns:

The result.

Return type:

Value

br()

Inserts an unconditional branch instruction.

Parameters:

dest (BasicBlock) – The destination block.

Returns:

The branch instruction.

Return type:

Instruction

call(callee, args)

Inserts a call instruction.

Parameters:
Returns:

The return value, or None if the function has a void return type.

Return type:

Value

condbr(then, else_)

Inserts an conditional branch instruction.

Parameters:

  • if (BasicBlock) – The condition

  • then (BasicBlock) – The destination block if condition is 1

  • else (BasicBlock) – The destination block if condition is 0

Returns:

The branch instruction.

Return type:

Instruction

icmp(pred, lhs, rhs)

Inserts an integer comparison instruction.

Parameters:

  • pred (IntPredicate) – The predicate to compare by.

  • lhs (Value) – The left-hand side.

  • rhs (Value) – The right-hand side.

Returns:

The boolean result.

Return type:

Value

if_(cond, true, false)

Inserts a branch conditioned on a boolean.

Instructions inserted when true is called will be inserted into the true branch. Instructions inserted when false is called will be inserted into the false branch. The true and false callables should use this module’s builder to build instructions.

Parameters:

  • cond (Value) – The boolean condition to branch on.

  • true (Callable[[], None]) – A callable that inserts instructions for the branch where the condition is true.

  • false (Callable[[], None]) – A callable that inserts instructions for the branch where the condition is false.

insert_at_end()

Tells this builder to insert subsequent instructions at the end of the block.

Parameters:

block (BasicBlock) – The block to insert into.

Return type:

None

lshr(lhs, rhs)

Inserts a logical (zero fill) shift right instruction.

Parameters:

  • lhs (Value) – The value to shift.

  • rhs (Value) – The number of bits to shift by.

Returns:

The result.

Return type:

Value

mul(lhs, rhs)

Inserts a multiplication instruction.

Parameters:

  • lhs (Value) – The left-hand side.

  • rhs (Value) – The right-hand side.

Returns:

The product.

Return type:

Value

or_(lhs, rhs)

Inserts a bitwise logical or instruction.

Parameters:

  • lhs (Value) – The left-hand side.

  • rhs (Value) – The right-hand side.

Returns:

The result.

Return type:

Value

phi()

Inserts a phi node.

Returns:

The phi node.

Return type:

Instruction

ret()

Inserts a return instruction.

Parameters:

value (Value) – The value to return. If None, returns void.

Returns:

The return instruction.

Return type:

Instruction

shl(lhs, rhs)

Inserts a shift left instruction.

Parameters:

  • lhs (Value) – The value to shift.

  • rhs (Value) – The number of bits to shift by.

Returns:

The result.

Return type:

Value

sub(lhs, rhs)

Inserts a subtraction instruction.

Parameters:

  • lhs (Value) – The left-hand side.

  • rhs (Value) – The right-hand side.

Returns:

The difference.

Return type:

Value

xor(lhs, rhs)

Inserts a bitwise logical exclusive or instruction.

Parameters:

  • lhs (Value) – The left-hand side.

  • rhs (Value) – The right-hand side.

Returns:

The result.

Return type:

Value

class pyqir.Call

Bases: Instruction

A call instruction.

args

The arguments to the call.

Type:

List[Value]

callee

The value being called.

Type:

Value

class pyqir.Constant

Bases: Value

A constant value.

is_null

Whether this value is the null value for its type.

Type:

bool

static null(ty)

Creates the null or zero constant for the given type.

Parameters:

type (Type) – The type of the constant.

Returns:

The null or zero constant.

Return type:

Constant

class pyqir.ConstantAsMetadata

Bases: Metadata

A metadata constant value.

value

The value.

Type:

Constant

class pyqir.Context

Bases: object

The context owns global state needed by most LLVM objects.

class pyqir.FCmp

Bases: Instruction

A floating-point comparison instruction.

predicate

The comparison predicate.

Type:

FloatPredicate

class pyqir.FloatConstant

Bases: Constant

A constant floating-point value.

value

The value.

Type:

float

class pyqir.FloatPredicate

Bases: object

A floating-point comparison predicate.

FALSE = FloatPredicate.FALSE
OEQ = FloatPredicate.OEQ
OGE = FloatPredicate.OGE
OGT = FloatPredicate.OGT
OLE = FloatPredicate.OLE
OLT = FloatPredicate.OLT
ONE = FloatPredicate.ONE
ORD = FloatPredicate.ORD
TRUE = FloatPredicate.TRUE
UEQ = FloatPredicate.UEQ
UGE = FloatPredicate.UGE
UGT = FloatPredicate.UGT
ULE = FloatPredicate.ULE
ULT = FloatPredicate.ULT
UNE = FloatPredicate.UNE
UNO = FloatPredicate.UNO
class pyqir.Function

Bases: Constant

A function value.

Parameters:

  • ty (FunctionType) – The function type.

  • linkage (Linkage) – The linkage kind.

  • name (str) – The function name.

  • module (Module) – The parent module.

attributes

The attributes for this function.

basic_blocks

The basic blocks in this function.

Type:

List[BasicBlock]

params

The parameters to this function.

Type:

List[Value]

type
class pyqir.FunctionType

Bases: Type

A function type.

Parameters:

  • ret (Type) – The return type.

  • params (Sequence[Type]) – The parameter types.

params

The types of the function parameters.

Type:

List[Type]

ret

The return type of the function.

Type:

Type

class pyqir.ICmp

Bases: Instruction

An integer comparison instruction.

predicate

The comparison predicate.

Type:

IntPredicate

class pyqir.Instruction

Bases: Value

An instruction.

erase()

Removes this instruction from its parent basic block, then deletes it from memory.

Warning

Using this instruction after erasing it is undefined behavior.

Return type:

None

opcode

The instruction opcode.

Type:

Opcode

operands

The operands to the instruction.

Type:

List[Value]

successors

The basic blocks that are successors to this instruction. If this is not a terminator, the list is empty.

Type:

List[BasicBlock]

class pyqir.IntConstant

Bases: Constant

A constant integer value.

value

The value.

Type:

int

class pyqir.IntPredicate

Bases: object

An integer comparison predicate.

EQ = IntPredicate.EQ
NE = IntPredicate.NE
SGE = IntPredicate.SGE
SGT = IntPredicate.SGT
SLE = IntPredicate.SLE
SLT = IntPredicate.SLT
UGE = IntPredicate.UGE
UGT = IntPredicate.UGT
ULE = IntPredicate.ULE
ULT = IntPredicate.ULT
class pyqir.IntType

Bases: Type

An integer type.

Parameters:

  • context (Context) – The LLVM context.

  • width (int) – The number of bits in the integer.

width

The number of bits in the integer.

Type:

int

class pyqir.Linkage

Bases: object

The linkage kind for a global value in a module.

APPENDING = Linkage.APPENDING
AVAILABLE_EXTERNALLY = Linkage.AVAILABLE_EXTERNALLY
COMMON = Linkage.COMMON
EXTERNAL = Linkage.EXTERNAL
EXTERNAL_WEAK = Linkage.EXTERNAL_WEAK
INTERNAL = Linkage.INTERNAL
PRIVATE = Linkage.PRIVATE
WEAK_ANY = Linkage.WEAK_ANY
WEAK_ODR = Linkage.WEAK_ODR
class pyqir.Metadata

Bases: object

A metadata value or node.

class pyqir.MetadataString

Bases: Metadata

A metadata string

value

The underlying metadata string value.

Type:

str

class pyqir.Module

Bases: object

A module is a collection of global values.

Parameters:

  • context (Context) – The LLVM context.

  • name (str) – The module name.

add_flag(id, flag)

Adds a flag to the llvm.module.flags metadata

See https://llvm.org/docs/LangRef.html#module-flags-metadata

Parameters:

  • behavior (ModuleFlagBehavior) – flag specifying the behavior when two (or more) modules are merged together

  • id (str) – string that is a unique ID for the metadata.

  • flag (Union[Metadata, Value]) – value of the flag

bitcode

The LLVM bitcode for this module.

Type:

bytes

context

The LLVM context.

Type:

Context

static from_bitcode(context, bitcode, name='')

Creates a module from LLVM bitcode.

Parameters:

  • bitcode (bytes) – The LLVM bitcode for a module.

  • name (Optional[str]) – The name of the module.

Returns:

The module.

Return type:

Module

static from_ir(context, ir, name='')

Creates a module from LLVM IR.

Parameters:

  • ir (str) – The LLVM IR for a module.

  • name (Optional[str]) – The name of the module.

Returns:

The module.

Return type:

Module

functions

The functions declared in this module.

Type:

List[Function]

get_flag()

Gets the flag value from the llvm.module.flags metadata for a given id

See https://llvm.org/docs/LangRef.html#module-flags-metadata

Parameters:

id (str) – metadata string that is a unique ID for the metadata.

Returns:

value of the flag if found, otherwise None

Return type:

Optional[Metadata]

source_filename

The name of the original source file that this module was compiled from.

Type:

str

verify()

Verifies that this module is valid.

Returns:

An error description if this module is invalid or None if this module is valid.

Return type:

Optional[str]

class pyqir.ModuleFlagBehavior

Bases: object

Module flag behavior choices

APPEND = ModuleFlagBehavior.APPEND
APPEND_UNIQUE = ModuleFlagBehavior.APPEND_UNIQUE
ERROR = ModuleFlagBehavior.ERROR
MAX = ModuleFlagBehavior.MAX
OVERRIDE = ModuleFlagBehavior.OVERRIDE
REQUIRE = ModuleFlagBehavior.REQUIRE
WARNING = ModuleFlagBehavior.WARNING
class pyqir.Opcode

Bases: object

An instruction opcode.

ADD = Opcode.ADD
ADDR_SPACE_CAST = Opcode.ADDR_SPACE_CAST
ALLOCA = Opcode.ALLOCA
AND = Opcode.AND
ASHR = Opcode.ASHR
ATOMIC_CMP_XCHG = Opcode.ATOMIC_CMP_XCHG
ATOMIC_RMW = Opcode.ATOMIC_RMW
BIT_CAST = Opcode.BIT_CAST
BR = Opcode.BR
CALL = Opcode.CALL
CALL_BR = Opcode.CALL_BR
CATCH_PAD = Opcode.CATCH_PAD
CATCH_RET = Opcode.CATCH_RET
CATCH_SWITCH = Opcode.CATCH_SWITCH
CLEANUP_PAD = Opcode.CLEANUP_PAD
CLEANUP_RET = Opcode.CLEANUP_RET
EXTRACT_ELEMENT = Opcode.EXTRACT_ELEMENT
EXTRACT_VALUE = Opcode.EXTRACT_VALUE
FADD = Opcode.FADD
FCMP = Opcode.FCMP
FDIV = Opcode.FDIV
FENCE = Opcode.FENCE
FMUL = Opcode.FMUL
FNEG = Opcode.FNEG
FP_EXT = Opcode.FP_EXT
FP_TO_SI = Opcode.FP_TO_SI
FP_TO_UI = Opcode.FP_TO_UI
FP_TRUNC = Opcode.FP_TRUNC
FREEZE = Opcode.FREEZE
FREM = Opcode.FREM
FSUB = Opcode.FSUB
GET_ELEMENT_PTR = Opcode.GET_ELEMENT_PTR
ICMP = Opcode.ICMP
INDIRECT_BR = Opcode.INDIRECT_BR
INSERT_ELEMENT = Opcode.INSERT_ELEMENT
INSERT_VALUE = Opcode.INSERT_VALUE
INT_TO_PTR = Opcode.INT_TO_PTR
INVOKE = Opcode.INVOKE
LANDING_PAD = Opcode.LANDING_PAD
LOAD = Opcode.LOAD
LSHR = Opcode.LSHR
MUL = Opcode.MUL
OR = Opcode.OR
PHI = Opcode.PHI
PTR_TO_INT = Opcode.PTR_TO_INT
RESUME = Opcode.RESUME
RET = Opcode.RET
SDIV = Opcode.SDIV
SELECT = Opcode.SELECT
SEXT = Opcode.SEXT
SHL = Opcode.SHL
SHUFFLE_VECTOR = Opcode.SHUFFLE_VECTOR
SI_TO_FP = Opcode.SI_TO_FP
SREM = Opcode.SREM
STORE = Opcode.STORE
SUB = Opcode.SUB
SWITCH = Opcode.SWITCH
TRUNC = Opcode.TRUNC
UDIV = Opcode.UDIV
UI_TO_FP = Opcode.UI_TO_FP
UNREACHABLE = Opcode.UNREACHABLE
UREM = Opcode.UREM
USER_OP_1 = Opcode.USER_OP_1
USER_OP_2 = Opcode.USER_OP_2
VA_ARG = Opcode.VA_ARG
XOR = Opcode.XOR
ZEXT = Opcode.ZEXT
class pyqir.Phi

Bases: Instruction

A phi node instruction.

add_incoming(block)

Adds an incoming value to the end of the phi list.

incoming

The incoming values and their preceding basic blocks.

Type:

List[Tuple[Value, BasicBlock]]

class pyqir.PointerType

Bases: Type

A pointer type.

Parameters:

pointee (Type) – The type being pointed to.

address_space

The pointer address space.

Type:

int

pointee

The type being pointed to.

Type:

Type

class pyqir.SimpleModule(name: str, num_qubits: int, num_results: int, context: Context | None = None, entry_point_name: str = 'main')

Bases: object

A simple module represents a QIR program with the following assumptions:

  • All qubits and results are statically allocated.

  • There is exactly one function that is not externally linked, which is the entry point.

add_byte_string(value: bytes) → Constant

Adds a global null-terminated byte string constant to the module.

Parameters:

Value – The byte string value without a null terminator.

Returns:

A pointer to the start of the null-terminated byte string.

add_external_function(name: str, ty: FunctionType) → Function

Adds a declaration for an externally linked function to the module.

Parameters:

  • name – The name of the function.

  • ty – The type of the function.

Returns:

The function value.

bitcode() → bytes

Emits the LLVM bitcode for the module as a sequence of bytes.

property builder: Builder

The instruction builder.

property context: Context

The LLVM context.

property entry_block: BasicBlock

The first basic block of the entry point (automatically generated).

property entry_point: Function

The entry point function (automatically generated).

ir() → str

Emits the LLVM IR for the module as plain text.

property qubits: List[Value]

The list of statically allocated qubits indexed by their numeric ID.

property results: List[Value]

The list of statically allocated results indexed by their numeric ID.

class pyqir.StructType

Bases: Type

A structure type.

fields

The types of the structure fields.

Type:

List[Type]

name

The name of the structure or the empty string if the structure is anonymous.

class pyqir.Switch

Bases: Instruction

A switch instruction.

cases

The switch cases.

Type:

List[Tuple[Value, BasicBlock]]

cond

The condition of the switch.

Type:

Value

default

The default successor block if none of the cases match.

Type:

BasicBlock

class pyqir.Type

Bases: object

A type.

static double(context)

The double type.

Parameters:

context (Context) – The LLVM context.

Returns:

The double type.

Return type:

Type

is_double

Whether this type is the bool type.

Type:

bool

is_void

Whether this type is the void type.

Type:

bool

static void(context)

The void type.

Parameters:

context (Context) – The LLVM context.

Returns:

The void type.

Return type:

Type

class pyqir.Value

Bases: object

A value.

name

The name of this value or the empty string if this value is anonymous.

type

The type of this value.

Type:

Type

pyqir.add_string_attribute(function, key, value, index)
pyqir.const(ty, value)

Creates a constant value.

Parameters:
Returns:

The constant value.

Return type:

Value

pyqir.dynamic_qubit_management(module)

Whether this module supports dynamic qubit management. None if unspecified.

pyqir.dynamic_result_management(module)

Whether this module supports dynamic result management. None if unspecified.

pyqir.entry_point(module: Module, name: str, required_num_qubits: int, required_num_results: int, qir_profiles: str = 'custom', output_labeling_schema: str | None = None) → Function

Creates an entry point.

Parameters:

  • module (Module) – The parent module.

  • name (str) – The entry point name.

  • required_num_qubits (int) – The number of qubits required by the entry point.

  • required_num_results (int) – The number of results required by the entry point.

  • qir_profiles (Optional[str]) – Value identifying the profile the entry point has been compiled for. Use base_profile when QIR is compliant.

  • output_labeling_schema (Optional[str]) – An arbitrary string value that identifies the schema used by a compiler frontend that produced the IR to label the recorded output

Returns:

An entry point.

pyqir.extract_byte_string(value)

If the value is a pointer to a constant byte string, extracts it.

Parameters:

value (Value) – The value.

Returns:

The constant byte string.

Return type:

Optional[bytes]

pyqir.global_byte_string(module, value)

Creates a global null-terminated byte string constant in a module.

Parameters:

  • module (Module) – The parent module.

  • value (bytes) – The byte string value without a null terminator.

Returns:

A pointer to the start of the null-terminated byte string.

Return type:

Constant

pyqir.is_entry_point(function)

Whether the function is an entry point.

Parameters:

function (Function) – The function.

Returns:

True if the function is an entry point.

Return type:

bool

pyqir.is_interop_friendly(function)

Whether the function is interop-friendly.

Parameters:

function (Function) – The function.

Returns:

True if the function is interop-friendly.

Return type:

bool

pyqir.is_qubit_type(ty)

Whether the type is the QIR qubit type.

Parameters:

ty (Type) – The type.

Returns:

True if the type is the QIR qubit type.

Return type:

bool

pyqir.is_result_type(ty)

Whether the type is the QIR result type.

Parameters:

ty (Type) – The type.

Returns:

True if the type is the QIR result type.

Return type:

bool

pyqir.qir_major_version(module)

The QIR major version this module is built for. None if unspecified.

pyqir.qir_minor_version(module)

The QIR minor version this module is built for. None if unspecified.

pyqir.qir_module(context, name, qir_major_version, qir_minor_version, dynamic_qubit_management, dynamic_result_management)

Creates a module with required QIR module flag metadata

Parameters:

  • context (Context) – The parent context.

  • name (str) – The module name.

  • qir_major_version (int) – The QIR major version this module is built for. Default 1.

  • qir_minor_version (int) – The QIR minor version this module is built for. Default 0.

  • dynamic_qubit_management (bool) – Whether this module supports dynamic qubit management. Default False.

  • dynamic_result_management (bool) – Whether this module supports dynamic result management. Default False.

Return type:

Module

pyqir.qubit(context, id)

Creates a static qubit value.

Parameters:

  • context (Context) – The LLVM context.

  • id (int) – The static qubit ID.

Returns:

A static qubit value.

Return type:

Value

pyqir.qubit_id(value)

If the value is a static qubit ID, extracts it.

Parameters:

value (Value) – The value.

Returns:

The static qubit ID.

Return type:

Optional[int]

pyqir.qubit_type(context)

The QIR qubit type.

Parameters:

context (Context) – The LLVM context.

Returns:

The qubit type.

Return type:

Type

pyqir.required_num_qubits(function)

If the function declares a required number of qubits, extracts it.

Parameters:

function (Function) – The function.

Returns:

The required number of qubits.

Return type:

Optional[int]

pyqir.required_num_results(function)

If the function declares a required number of results, extracts it.

Parameters:

function (Function) – The function.

Returns:

The required number of results.

Return type:

Optional[int]

pyqir.result(context, id)

Creates a static result value.

Parameters:

  • context (Context) – The LLVM context.

  • id (int) – The static result ID.

Returns:

A static result value.

Return type:

Value

pyqir.result_id(value)

If the value is a static result ID, extracts it.

Parameters:

value (Value) – The value.

Returns:

The static result ID.

Return type:

Optional[int]

pyqir.result_type(context)

The QIR result type.

Parameters:

context (Context) – The LLVM context.

Returns:

The result type.

Return type:

Type