Register reference executor

oracq.infrastructure.execution

On-demand traversal of the module graph, plus a small-scale reference executor based on tuples of register integers.

oracq.infrastructure.execution.check_memory(program, memory)

Validate and normalize the QRAM binding data of the entry.

Parameters:

• program – closed RIR program.

• memory – data provided by resource name; each item is a word sequence or a sparse address -> word dict, and None is treated as all zeros.

Returns:

dictionary from resource names to sparse cell maps; cells with value zero are dropped, and missing cells are interpreted as zero.

Return type:

dict

Raises:

ValidationError – the data is not a mapping by resource name, the resource set does not match the entry declaration, an address is out of range, or a word is not an unsigned integer within the bit width.

oracq.infrastructure.execution.expanded_steps(program, limit=1000000, native_modules=frozenset({}))

Estimate the execution step count of the fully expanded program, for budget checks before execution.

Primitives are weighted by total operand bit width and Load/Store count as 1 step; module calls recursively include the callee body, and Repeat multiplies by the count. Once the count reaches the limit it is clamped at limit + 1 and stops growing.

Parameters:

• program – RIR program.

• limit – clamping limit of the count.

• native_modules – set of native module names counted as a single step; returns 1 directly when the entry itself is a native module.

Returns:

saturated estimate of the expanded step count.

Return type:

int

class oracq.infrastructure.execution.LocalEnter(name, type)

Bases: object

Event of a local register entering scope; the register joins the execution state at value zero.

Variables:

• name (str) – unique synthesized name assigned to the local register.

• type (oracq.infrastructure.ir.RegType) – type of the local register.

name

type

class oracq.infrastructure.execution.LocalExit(name, width)

Bases: object

Event of a local register leaving scope; at exit all branches are required to be restored to zero.

Variables:

• name (str) – name of the released local register.

• width (int) – bit width of the local register.

name

width

oracq.infrastructure.execution.remap(ref, mapping)

Rewrite a reference by a register-name substitution table, used at module calls to bind formal parameters to argument views.

Parameters:

• ref – Ref to rewrite.

• mapping – mapping from register names to Ref; each span of the original reference is sliced from the corresponding range of the replacement and concatenated in order.

Returns:

rewritten new reference, with the same type as the original.

Return type:

Ref

oracq.infrastructure.execution.events(program, *, max_steps=1000000, native_modules=frozenset({}))

Expand calls layer by layer into an iterator while leaving the original RIR unchanged.

Parameters:

• program – RIR program to expand for execution; must be closed when there are no native modules.

• max_steps – budget limit on the expanded instruction step count.

• native_modules – set of module names treated as natively executed and no longer inlined.

Returns:

lazily yields (event, control chain, inverse flag) triples; the event is a primitive, a QRAM read/write, a local register entering or leaving, or a native call site, the control chain is a tuple of (Ref, int) pairs, and the inverse flag indicates an Adjoint context.

Return type:

Iterator

oracq.infrastructure.execution.gate_matrix(op, angle=None, inverse=False)

Return the standard 2x2 unitary matrix of a single-qubit gate.

Parameters:

• op – gate name; one of h, x, y, z, s, t, phase, rx, ry, rz.

• angle – angle in radians for rotation and phase gates; s and t use fixed angles and ignore this argument.

• inverse – when true, return the conjugate transpose, i.e. the inverse matrix of the gate.

Returns:

2x2 complex matrix given as a tuple of rows.

Return type:

tuple

Raises:

ValidationError – the gate name is not in the supported list.

class oracq.infrastructure.execution.RegisterState(registers, amplitudes)

Bases: object

Final state of a reference execution: entry register layout and sparse amplitudes.

Variables:

• registers (tuple) – register tuple of the entry module, fixing the order of value tuples.

• amplitudes (dict[tuple[int, ...], complex]) – mapping from register value tuples to complex amplitudes.

registers

amplitudes

statevector(max_qubits=20)

Pack the sparse state into a dense state vector, with each register occupying an index bit segment LSB-first in declaration order.

Parameters:

max_qubits – maximum total bit count allowed.

Returns:

list of complex amplitudes of length 2**total bits.

Return type:

list

Raises:

ValidationError – the total register bit count exceeds max_qubits.

oracq.infrastructure.execution.simulate(program, memory=None, *, initial=None, max_steps=1000000, max_states=65536)

Reference-execute a closed program on sparse register states, depending only on the standard library.

The initial state is a single basis vector with each register at its given integer value (all zero by default), and the state is kept as a sparse dictionary from tuples of register integer values to complex amplitudes. The instruction stream is lazily expanded by events: single-qubit gates act bit by bit on the first operand, while xor, swap, add_const and gphase update register values or amplitudes per RIR semantics; Control conditions restrict the affected branches by logical conjunction, Adjoint inverts in reverse order, and Repeat repeats by the count. A QRAM Load is an XOR read, naturally supporting superposed addresses; Store is a random write requiring the address and data to be in a definite basis state. Local registers are zeroed on entry, and all branches are checked to be restored on exit.

Parameters:

• program – closed RIR program to execute.

• memory – QRAM data provided by resource name, in the same format as check_memory.

• initial – mapping from register names to initial integer values, all zero by default.

• max_steps – expansion step budget; exceeding it raises an error.

• max_states – sparse basis vector budget; exceeding it raises an error.

Returns:

entry register layout and final sparse amplitudes; components with magnitude at most 1e-15 are truncated.

Return type:

RegisterState

Raises:

ValidationError – program or QRAM data validation failed, an initial register is unknown or out of range, a Store is not in a definite basis state, a local register is not restored to zero, or the step or sparse state count budget is exceeded.