uniqc.circuit_builder.named_circuit module

Named circuit definitions for reusable quantum subroutines.

This module provides: - @circuit_def: Decorator to create named circuit definitions - NamedCircuit: Reusable circuit definition with signature

Named circuits can be applied to parent circuits with qubit mapping and parameter binding, similar to QASM3 gate definitions.

Example usage:

@circuit_def(name="bell_pair", qregs={"q": 2})
def bell_pair(circ, q):
    circ.h(q[0])
    circ.cnot(q[0], q[1])
    return circ

# Apply to parent circuit
c = Circuit(qregs={"data": 4})
bell_pair(c, qreg_mapping={"q": [c.get_qreg("data")[0], c.get_qreg("data")[1]]})

class uniqc.circuit_builder.named_circuit.NamedCircuit(name, qregs=None, params=None, builder=None)

Bases: object

Reusable circuit definition with named qregs and parameters.

A NamedCircuit is a template for a quantum subroutine that can be instantiated multiple times with different qubit mappings and parameter values.

Variables:

• name – Circuit definition name

• qregs – Dictionary mapping qreg names to sizes

• params – List of parameter names

• builder – Function that builds the circuit body

Example

>>> @circuit_def(name="u3", qregs={"q": 1}, params=["theta", "phi", "lam"])
... def u3_gate(circ, q, theta, phi, lam):
...     circ.rz(q[0], phi)
...     circ.ry(q[0], theta)
...     circ.rz(q[0], lam)
...     return circ
...
>>> u3_gate.num_qubits  # 1
>>> u3_gate.num_parameters  # 3

build_standalone(param_values=None)

Build a standalone Circuit with this definition.

Creates a new Circuit with qregs matching this definition’s signature.

Parameters:

param_values – Optional parameter values

Returns:

A new Circuit instance

property name

property num_parameters

Number of parameters.

property num_qubits

Total number of qubits used by this circuit.

property params

property qregs

to_originir_def()

Export as an OriginIR-ext DEF block.

The header reuses the named-register declaration syntax (DEF name(a[2], b[1]) (theta1, theta2)): one reg[size] entry per named quantum register, followed by an optional parenthesised list of scalar parameter names. Body lines reference the formal registers (a[0], b[0], …) and the scalar parameter names, so the emitted block round-trips through OriginIR_BaseParser.

uniqc.circuit_builder.named_circuit.circuit_def(name, qregs=None, params=None)

Decorator to create a NamedCircuit definition.

Parameters:

• name – Circuit definition name

• qregs – Qubit register specification - dict: {name: size} pairs - list: Names (each with size 1)

• params – Parameter names

Returns:

Decorator that wraps a function into a NamedCircuit

Example

>>> @circuit_def(name="bell_pair", qregs={"q": 2})
... def bell_pair(circ, q):
...     circ.h(q[0])
...     circ.cnot(q[0], q[1])
...     return circ
...
>>> c = Circuit(2)
>>> bell_pair(c, qreg_mapping={"q": [0, 1]})