寄存器参考执行器

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.

参数:

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

返回:

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

返回类型:

dict

抛出:

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.

参数:

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

返回:

saturated estimate of the expanded step count.

返回类型:

int

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

基类：object

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

变量:

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

基类：object

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

变量:

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

参数:

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

返回:

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

返回类型:

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.

参数:

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

返回:

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.

返回类型:

Iterator

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

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

参数:

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

返回:

2x2 complex matrix given as a tuple of rows.

返回类型:

tuple

抛出:

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

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

基类：object

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

变量:

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

参数:

max_qubits -- maximum total bit count allowed.

返回:

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

返回类型:

list

抛出:

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.

参数:

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

返回:

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

返回类型:

RegisterState

抛出:

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.