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

context (Context) – The LLVM context.
name (str) – The block name.
parent (Optional[Function]) – The parent function.
before (Optional[BasicBlock]) – The block to insert this block before.

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:

value (Value) – The value to call.
args (Sequence[Union[Value, bool, int, float]]) – The arguments to the function.

Returns:

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

Return type:

Value

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

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#

LINK_ONCE_ANY = Linkage.LINK_ONCE_ANY#

LINK_ONCE_ODR = Linkage.LINK_ONCE_ODR#

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.

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)#

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.

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:

ty (Type) – The type of the value.
value (Union[bool, int, float]) – The value of the constant.

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

pyqir#

`pyqir`#