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)[source]#

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

Parameters:

name (str)
qregs (dict[str, int] | list[str] | None)
params (list[str] | None)
builder (Callable | None)

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)[source]#

Build a standalone Circuit with this definition.

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

Parameters:: param_values (dict[str, float] | list[float] | None) – Optional parameter values
Returns:: A new Circuit instance
Return type:: Circuit

property name: str#

property num_parameters: int#: Number of parameters.

property num_qubits: int#: Total number of qubits used by this circuit.

property params: list[str]#

property qregs: dict[str, int]#

to_originir_def()[source]#

Export as OriginIR DEF block.

Note: This is a placeholder. Full DEF export requires symbolic parameter support in OriginIR format.

Return type:: str

uniqc.circuit_builder.named_circuit.circuit_def(name, qregs=None, params=None)[source]#

Decorator to create a NamedCircuit definition.

Parameters:

name (str) – Circuit definition name
qregs (dict[str, int] | list[str] | None) – Qubit register specification - dict: {name: size} pairs - list: Names (each with size 1)
params (list[str] | None) – Parameter names

Returns:

Decorator that wraps a function into a NamedCircuit

Return type:

Callable

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]})