Module builder

oracq.infrastructure.builder

Python generation-stage builder. Generated results contain no Python callables.

oracq.infrastructure.builder.RegisterSpec

a mapping from register names to storage types.

Type:

Register specification for the Builder constructor

alias of dict[str, RegType]

class oracq.infrastructure.builder.Operation(module, dependencies=())

Bases: object

A complete RIR operation consisting of an entry module and its dependency modules.

Variables:

• module (oracq.infrastructure.ir.Module) – entry module definition.

• dependencies (tuple[oracq.infrastructure.ir.Module, ...]) – all dependency module definitions other than the entry.

module

dependencies = ()

unitary()

Full-register unitary action of the RIR operation; does not claim any target matrix is itself unitary.

Returns:

returns itself unchanged; an RIR operation is itself unitary evolution on the full register space.

Return type:

Operation

state_preparation()

Prepare U|0> with the full public register space as target.

Returns:

state preparation object obtained by wrapping this operation via from_unitary.

Return type:

StatePreparation

block_encoding()

Trivial alpha=1, zero-signal block encoding of the full unitary itself; keeps the original module calls.

Returns:

trivial block encoding with scaling factor 1.0 and a zero-width signal register.

Return type:

BlockEncoding

classmethod from_program(program)

Recover the entry operation and module dependencies from a serialized program, keeping open declarations.

Parameters:

program – complete RIR program to recover; modules other than the entry become dependencies.

Returns:

operation whose entry is program.main and whose dependencies are all remaining modules.

Return type:

Operation

program()

Merge the entry module and dependencies into a validated Program with modules sorted by name.

Returns:

program with module.name as its entry.

Return type:

Program

Raises:

ValidationError – conflicting definitions exist for a dependency module name, or the merged result violates RIR rules.

quantikz(**kwargs)

Render the entry module as quantikz code; structure stays RIR with no call expansion.

Returns:

quantikz LaTeX source produced by rendering the entry module.

Return type:

str

estimate(**kwargs)

Composable Toffoli+Clifford+T+QRAM level resource estimation with Repeat counts multiplied symbolically.

Returns:

estimate summarized by Toffoli, Clifford, T and QRAM query counts.

Return type:

ResourceEstimate

class oracq.infrastructure.builder.Builder(name, registers, resources=None, *, attributes=None)

Bases: object

Generation-stage builder that constructs an RIR module instruction by instruction; generated results contain no Python callables.

Parameters:

• name – name of the module to generate.

• registers – mapping from public register names to bit width types.

• resources – mapping from public QRAM resource names to specifications; omitted means the module has no resources.

• attributes – attribute key-value pairs appended to the module; omitted means empty.

Public registers are accessed as Ref views via builder[name], local declares module-private work registers, and finish closes the builder and returns a validated Operation.

name

attributes

registers

resources

locals

local(name, type)

Declare a module-private work register and return the full view covering it.

Parameters:

• name – register name; must not collide with a public register, a resource or another local register.

• type – type and bit width of the register.

Returns:

reference covering the entire new register.

Return type:

Ref

Raises:

ValidationError – name conflict, or the builder is already closed.

emit(instruction)

Append one RIR instruction to the current innermost scope.

Parameters:

instruction – RIR Instruction node.

Raises:

ValidationError – the builder is already closed.

gate(name, target, angle=None)

Emit a single-target Primitive gate.

Parameters:

• name – gate name.

• target – target view.

• angle – angle in radians for rotation gates; omitted for non-rotation gates.

h(target)

Emit a Hadamard gate.

Parameters:

target – target view the gate acts on.

x(target)

Emit a Pauli-X gate.

Parameters:

target – target view the gate acts on.

z(target)

Emit a Pauli-Z gate.

Parameters:

target – target view the gate acts on.

ry(target, angle)

Emit a gate rotating by angle radians about the Y axis.

Parameters:

• target – target view the rotation acts on.

• angle – rotation angle in radians.

rz(target, angle)

Emit a gate rotating by angle radians about the Z axis.

Parameters:

• target – target view the rotation acts on.

• angle – rotation angle in radians.

xor(source, target)

Emit a bitwise XOR gate that XORs the value of source into the equal-width target.

Parameters:

• source – source view providing the value to XOR in.

• target – target view of the same width as source that accumulates the XOR result.

swap(first, second)

Emit a swap gate between the two equal-width views first and second.

Parameters:

• first – first view participating in the swap.

• second – second view of the same width as first.

add_const(target, value)

Emit a constant-addition gate that adds value to target with wraparound by bit width.

Parameters:

• target – target view that undergoes the addition and wraps by its bit width.

• value – integer constant to add.

global_phase(angle)

Emit a global phase gate that multiplies the overall amplitude by exp(i*angle).

Parameters:

angle – overall phase angle in radians.

qram(resource, address, data)

Emit a QRAM read: query resource at address and XOR the hit word into data.

Parameters:

• resource – name of the QRAM resource to query.

• address – view providing the address of the cell to query.

• data – equal-width target view into which the hit data word is XORed.

store(resource, address, data)

Emit a QRAM write: store data into cell address of resource.

Parameters:

• resource – name of the target QRAM resource to write.

• address – address view specifying the cell to write.

• data – source view providing the data to write.

call(operation, *, resources=None, **arguments)

Call another Operation as-is; the callee stays a Call node and is not expanded at generation time.

Parameters:

• operation – operation to call; its module and dependencies are registered as dependencies of this module.

• resources – mapping from callee resource formal parameter names to this module’s resource names.

• **arguments – argument views keyed by callee register names.

Raises:

ValidationError – quantum or resource argument names do not match, or conflicting definitions exist for a dependency module name.

repeat(count)

Open a scope repeated count times; body instructions aggregate into a Repeat node whose count stays symbolic and is not expanded at generation time.

Parameters:

count – number of times the body scope repeats; stored symbolically in the Repeat node.

Returns:

scope context for use with a with statement; all blocks must be closed per their with nesting before finish.

control(register, value=None)

Open a controlled scope; body instructions aggregate into a Control node.

Parameters:

• register – control view.

• value – integer mask that activates the scope; omitted means the all-ones mask of the register.

Returns:

scope context for use with a with statement; all blocks must be closed per their with nesting before finish.

adjoint()

Open an inverse scope; body instructions aggregate into an Adjoint block executed in reverse order with each operation inverted.

Returns:

scope context for use with a with statement; all blocks must be closed per their with nesting before finish.

finish()

Finish construction: assemble the module with all registered dependencies, validate and return an Operation, then close the builder.

Returns:

operation whose entry is the module built here and whose dependencies are the registered callees.

Return type:

Operation

Raises:

ValidationError – the builder is already closed, scopes are still open, or the assembled result violates RIR rules.