RIR objects¶

oracq.infrastructure.ir

RIR v0.1: immutable, serializable register-level operation graph.

oracq.infrastructure.ir.VERSION = '0.1'¶: Current RIR specification version; the default version value for newly created Program objects.

exception oracq.infrastructure.ir.ValidationError[source]¶

Bases: ValueError

Input violates a structural or semantic rule of RIR.

class oracq.infrastructure.ir.RegType(kind, width)[source]¶

Bases: object

Storage type of a register, consisting of a bit pattern interpretation and a bit width.

Variables:

kind (str) – bit pattern interpretation; one of bits, uint, sint or rational.
width (int) – bit width in 0..64; zero width denotes an empty interface.

kind¶

width¶

oracq.infrastructure.ir.Bits(width)[source]¶

Return a RegType with the bits interpretation, denoting a bit string without numeric meaning.

Parameters:: width – bit width in 0..64; zero width denotes an empty interface.
Returns:: storage type with kind bits and bit width equal to width.
Return type:: RegType

oracq.infrastructure.ir.UInt(width)[source]¶

Return a RegType with the uint interpretation, denoting an unsigned integer from 0 to 2^width-1.

Parameters:: width – bit width in 0..64; zero width denotes an empty interface.
Returns:: storage type with kind uint and bit width equal to width.
Return type:: RegType

oracq.infrastructure.ir.SInt(width)[source]¶

Return a RegType with the sint interpretation, denoting a two’s-complement integer; bit operations still act on the raw word.

Parameters:: width – bit width in 0..64; zero width denotes an empty interface.
Returns:: storage type with kind sint and bit width equal to width.
Return type:: RegType

oracq.infrastructure.ir.Rational(width)[source]¶

Return a RegType with the rational interpretation, denoting an unsigned word divided by 2^width.

Parameters:: width – bit width in 0..64; also the base-2 exponent of the denominator.
Returns:: storage type with kind rational and bit width equal to width.
Return type:: RegType

class oracq.infrastructure.ir.Register(name, type)[source]¶

Bases: object

Formal quantum register declaration of a module.

Variables:

name (str) – register name; unique within the module and free of conflicts with resource names.
type (oracq.infrastructure.ir.RegType) – storage type of the register.

name¶

type¶

class oracq.infrastructure.ir.Span(register, start, width)[source]¶

Bases: object

A contiguous qubit range within a root register.

Variables:

register (str) – root register name.
start (int) – index of the range start; index 0 is the least significant bit.
width (int) – bit width of the range.

register¶

start¶

width¶

class oracq.infrastructure.ir.Ref(parts, type)[source]¶

Bases: object

parts¶

type¶

property width¶: Total bit width of the view, i.e. the bit width of type.

reinterpret(kind)[source]¶

Change the interpretation of the view without altering its bit width or quantum state.

Parameters:: kind – target interpretation; one of bits, uint, sint or rational.
Returns:: view reusing the original parts, seen under the new interpretation.
Return type:: Ref

oracq.infrastructure.ir.fuse(*refs)[source]¶

Concatenate multiple views from least to most significant bit into a composite view that may cross root registers.

Parameters:: *refs – sequence of views occupying low to high bits in order.
Returns:: new view whose parts are concatenated in order, interpreted as bits.
Return type:: Ref

class oracq.infrastructure.ir.QRAM(address_width, data_width)[source]¶

Bases: object

Type declaration of a QRAM resource.

Memory is a mapping from addresses to unsigned data words with unspecified cells equal to zero; contents are not written into the program JSON and are bound separately as execution input.

Variables:

address_width (int) – bit width of an address word in 1..64.
data_width (int) – bit width of a data word in 1..64.

address_width¶

data_width¶

class oracq.infrastructure.ir.Resource(name, type)[source]¶

Bases: object

Formal QRAM parameter declaration of a module.

Variables:

name (str) – resource name; unique within the module and free of conflicts with register names.
type (oracq.infrastructure.ir.QRAM) – QRAM type of the resource.

name¶

type¶

class oracq.infrastructure.ir.Primitive(op, operands, angle=None, value=None)[source]¶

Bases: object

A broadcast gate stays a single register-level operation in the IR and is not split for containing multiple physical gates.

Variables:

op (str) – gate name, such as h, rx, phase, xor, swap, add_const.
operands (tuple[oracq.infrastructure.ir.Ref, ...]) – tuple of operand views.
angle (float | None) – rotation or phase angle in radians; None for gates that do not use it.
value (int | None) – modular addend of add_const; None for gates that do not use it.

op¶

operands¶

angle = None¶

value = None¶

class oracq.infrastructure.ir.Load(resource, address, data)[source]¶

Bases: object

QRAM query instruction: data is XORed with the content of the addressed cell.

The instruction is self-inverse, does not require the target to start at zero, and does not modify the address or the classical memory.

Variables:

resource (str) – formal QRAM resource name being queried.
address (oracq.infrastructure.ir.Ref) – address view; its width must match the resource declaration.
data (oracq.infrastructure.ir.Ref) – data view; its width must match the resource declaration and it must not overlap the address.

resource¶

address¶

data¶

class oracq.infrastructure.ir.Store(resource, address, data)[source]¶

Bases: object

QRAM random-write instruction: at execution time assigns the classical cell to the data view.

The address and data views must be in a definite basis state; the instruction changes no qubits, may only appear in a module body or a Repeat body, and is forbidden inside Control and Adjoint bodies.

Variables:

resource (str) – formal QRAM resource name being written.
address (oracq.infrastructure.ir.Ref) – address view; its width must match the resource declaration.
data (oracq.infrastructure.ir.Ref) – data view; its width must match the resource declaration and it must not overlap the address.

resource¶

address¶

data¶

class oracq.infrastructure.ir.Call(module, arguments, resources=())[source]¶

Bases: object

Module call instruction; the callee definition is shared in the Program and not inlined at call sites.

Variables:

module (str) – callee module name.
arguments (tuple[oracq.infrastructure.ir.Ref, ...]) – quantum argument views bound in callee signature order.
resources (tuple[str, ...]) – resource argument names bound in callee signature order.

module¶

arguments¶

resources = ()¶

class oracq.infrastructure.ir.Repeat(count, body)[source]¶

Bases: object

Static repetition instruction: applies the body instructions in order count times.

The generation and serialization stages do not copy the instruction body by count.

Variables:

count (int) – repeat count in 0..2^63-1; zero repetitions is the identity operation.
body (tuple[oracq.infrastructure.ir.Primitive | oracq.infrastructure.ir.Load | oracq.infrastructure.ir.Store | oracq.infrastructure.ir.Call | oracq.infrastructure.ir.Repeat | oracq.infrastructure.ir.Control | oracq.infrastructure.ir.Adjoint, ...]) – tuple of instructions being repeated; it must be structurally valid even when count is zero.

count¶

body¶

class oracq.infrastructure.ir.Control(register, value, body)[source]¶

Bases: object

Coherent control instruction: applies the body instructions when the control view equals the given value, otherwise is the identity.

The control register participates in coherent control as a quantum condition and is not measured; the control bits are protected throughout the body.

Variables:

register (oracq.infrastructure.ir.Ref) – nonempty control view.
value (int) – unsigned comparison value for the control view.
body (tuple[oracq.infrastructure.ir.Primitive | oracq.infrastructure.ir.Load | oracq.infrastructure.ir.Store | oracq.infrastructure.ir.Call | oracq.infrastructure.ir.Repeat | oracq.infrastructure.ir.Control | oracq.infrastructure.ir.Adjoint, ...]) – tuple of instructions executed under control.

register¶

value¶

body¶

class oracq.infrastructure.ir.Adjoint(body)[source]¶

Bases: object

Adjoint instruction: reverses the order of the body instructions and takes the adjoint of each operation.

Creation does not rewrite or expand its body; a double adjoint recovers the original operation.

Variables:: body (tuple[oracq.infrastructure.ir.Primitive | oracq.infrastructure.ir.Load | oracq.infrastructure.ir.Store | oracq.infrastructure.ir.Call | oracq.infrastructure.ir.Repeat | oracq.infrastructure.ir.Control | oracq.infrastructure.ir.Adjoint, ...]) – tuple of instructions being adjointed.

body¶

oracq.infrastructure.ir.Instruction = oracq.infrastructure.ir.Primitive | oracq.infrastructure.ir.Load | oracq.infrastructure.ir.Store | oracq.infrastructure.ir.Call | oracq.infrastructure.ir.Repeat | oracq.infrastructure.ir.Control | oracq.infrastructure.ir.Adjoint¶: Union type alias of RIR instruction nodes.

class oracq.infrastructure.ir.Module(name, registers, resources, body, attributes=(), locals=())[source]¶

Bases: object

Module definition consisting of a call signature, QRAM resources and an ordered instruction body.

Variables:

name (str) – module name; unique within the Program.
registers (tuple[oracq.infrastructure.ir.Register, ...]) – ordered list of public quantum parameters.
resources (tuple[oracq.infrastructure.ir.Resource, ...]) – ordered list of formal QRAM parameters.
body (tuple[oracq.infrastructure.ir.Primitive | oracq.infrastructure.ir.Load | oracq.infrastructure.ir.Store | oracq.infrastructure.ir.Call | oracq.infrastructure.ir.Repeat | oracq.infrastructure.ir.Control | oracq.infrastructure.ir.Adjoint, ...] | None) – ordered instruction body; None denotes an open declaration, i.e. an oracle slot whose implementation is not yet bound.
attributes (tuple[tuple[str, str | int | float | bool], ...]) – ordered attribute pairs with values limited to strings, integers, finite floats or booleans.
locals (tuple[oracq.infrastructure.ir.Register, ...]) – module-private work registers with zero input and zero output, not part of the public call signature.

name¶

registers¶

resources¶

body¶

attributes = ()¶

locals = ()¶

class oracq.infrastructure.ir.Program(entry, modules, version='0.1')[source]¶

Bases: object

Complete program: the module table plus the entry module name.

Variables:

entry (str) – entry module name; must refer to a module defined in modules.
modules (tuple[oracq.infrastructure.ir.Module, ...]) – all module definitions; definitions are shared across call sites without copying bodies.
version (str) – RIR version string; the reader additionally accepts historic versions 0.1 and 0.2.

entry¶

modules¶

version = '0.1'¶

property module_map¶: Index of module definitions keyed by module name.

property main¶: Definition of the entry module.