模块构造器

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

dict[str, RegType] 的别名

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

基类：object

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

变量:

• 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 itself unchanged; an RIR operation is itself unitary evolution on the full register space.

返回类型:

Operation

state_preparation()

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

返回:

state preparation object obtained by wrapping this operation via from_unitary.

返回类型:

StatePreparation

block_encoding()

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

返回:

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

返回类型:

BlockEncoding

classmethod from_program(program)

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

参数:

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

返回:

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

返回类型:

Operation

program()

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

返回:

program with module.name as its entry.

返回类型:

Program

抛出:

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.

返回:

quantikz LaTeX source produced by rendering the entry module.

返回类型:

str

estimate(**kwargs)

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

返回:

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

返回类型:

ResourceEstimate

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

基类：object

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

参数:

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

参数:

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

• type -- type and bit width of the register.

返回:

reference covering the entire new register.

返回类型:

Ref

抛出:

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

emit(instruction)

Append one RIR instruction to the current innermost scope.

参数:

instruction -- RIR Instruction node.

抛出:

ValidationError -- the builder is already closed.

gate(name, target, angle=None)

Emit a single-target Primitive gate.

参数:

• name -- gate name.

• target -- target view.

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

h(target)

Emit a Hadamard gate.

参数:

target -- target view the gate acts on.

x(target)

Emit a Pauli-X gate.

参数:

target -- target view the gate acts on.

z(target)

Emit a Pauli-Z gate.

参数:

target -- target view the gate acts on.

ry(target, angle)

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

参数:

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

参数:

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

参数:

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

参数:

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

参数:

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

参数:

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.

参数:

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

参数:

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

参数:

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

抛出:

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.

参数:

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

返回:

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.

参数:

• register -- control view.

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

返回:

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.

返回:

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.

返回:

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

返回类型:

Operation

抛出:

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