qamomile.circuit

Overview¶

Functions¶

bit [source]¶

def bit(arg: bool | str | int) -> Bit

Create a Bit handle from a boolean/int literal or declare a named Bit parameter.

cast [source]¶

def cast(source: Vector[Qubit], target_type: type, *, int_bits: int = 0) -> QFixed

Cast a quantum value to a different type without allocating new qubits.

The cast performs a move: the source handle is consumed and cannot be reused after the cast. The returned handle references the same physical qubits.

Parameters:

Returns:

QFixed — A new handle of the target type referencing the same qubits.

Example:

@qmc.qkernel
def my_circuit():
    phase_register = qmc.qubit_array(5, name="phase")
    # ... apply some operations ...

    # Cast the qubit array to QFixed for measurement
    phase_qfixed = qmc.cast(phase_register, qmc.QFixed, int_bits=0)
    phase_value = qmc.measure(phase_qfixed)
    return phase_value

Raises:

• TypeError — If the source type or target type is not supported

• ValueError — If int_bits is negative or larger than the number of qubits

ccx [source]¶

def ccx(control1: Qubit, control2: Qubit, target: Qubit) -> tuple[Qubit, Qubit, Qubit]

Toffoli (CCX) gate: flips target when both controls are |1>.

Parameters:

Returns:

tuple[Qubit, Qubit, Qubit] — Tuple of (control1_out, control2_out, target_out) after CCX.

composite_gate [source]¶

def composite_gate(
    func: Callable | None = None,
    *,
    stub: bool = False,
    name: str = '',
    num_qubits: int | None = None,
    num_controls: int = 0,
    resource_metadata: ResourceMetadata | None = None,
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
) -> _WrappedCompositeGate | _StubCompositeGate | Callable[[Callable], _WrappedCompositeGate | _StubCompositeGate]

Decorator to create a CompositeGate from a qkernel function or as a stub.

Usage with qkernel (implementation provided): composite_gate [source](name=“my_qft”) qkernel [source] def my_qft(q0: Qubit, q1: Qubit) -> tuple[Qubit, Qubit]: q0 = h(q0) q0, q1 = cp(q0, q1, pi/2) q1 = h(q1) return q0, q1

# Usage:
q0, q1 = my_qft(q0, q1)

Usage as stub (no implementation, for resource estimation): composite_gate [source]( stub=True, name=“oracle”, num_qubits=5, resource_metadata=ResourceMetadata(query_complexity=100, t_gates=10), ) def oracle(): pass

# Usage:
results = oracle(*qubits)
metadata = oracle.get_resource_metadata()

Parameters:

Returns:

_WrappedCompositeGate | _StubCompositeGate | Callable[[Callable], _WrappedCompositeGate | _StubCompositeGate] — A CompositeGate instance that can be called like a gate function.

controlled [source]¶

def controlled(
    qkernel: QKernel | Callable[..., Any],
    num_controls: int | UInt = 1,
) -> ControlledGate

Create a controlled version of a quantum gate.

Accepts either a @qmc.qkernel-decorated function or a plain built-in gate callable (qmc.rx, qmc.h, qmc.cp, ...). When given a plain callable, a thin @qkernel wrapper is synthesized automatically by inspecting the callable’s signature, so users no longer need to write a one-line wrapper just to control a primitive gate.

Parameters:

Returns:

ControlledGate — A ControlledGate that can be called with ControlledGate — (*controls, *targets, **params).

Raises:

• TypeError — If qkernel is a callable that cannot be auto-wrapped (missing annotations, unsupported types, or no qubit parameters).

• ValueError — If num_controls is a concrete int less than 1.

Example:

Built-in gates can be controlled directly, with no wrapper::

    crx = qmc.controlled(qmc.rx)
    ctrl_out, tgt_out = crx(ctrl, target, angle=0.5)

    cch = qmc.controlled(qmc.h, num_controls=2)
    c0, c1, tgt = cch(ctrl0, ctrl1, target)

``@qmc.qkernel`` arguments are still supported for cases that need
custom logic::

    @qmc.qkernel
    def rx_then_h(q: Qubit, theta: float) -> Qubit:
        q = qmc.rx(q, theta)
        q = qmc.h(q)
        return q

    ctrl_out, tgt_out = qmc.controlled(rx_then_h)(ctrl, target, theta=0.5)

cp [source]¶

def cp(control: Qubit, target: Qubit, theta: float | Float) -> tuple[Qubit, Qubit]

Controlled-Phase gate.

cx [source]¶

def cx(control: Qubit, target: Qubit) -> tuple[Qubit, Qubit]

CNOT (Controlled-X) gate.

cz [source]¶

def cz(control: Qubit, target: Qubit) -> tuple[Qubit, Qubit]

CZ (Controlled-Z) gate.

expval [source]¶

def expval(qubits: Vector[Qubit] | tuple[Qubit, ...], hamiltonian: Observable) -> Float

Compute the expectation value of an observable on a quantum state.

This function computes <psi|H|psi> where psi is the quantum state represented by the qubits and H is the Hamiltonian observable.

The quantum state (qubits) is NOT consumed by this operation - the qubits can still be used for further operations after expval.

Parameters:

Returns:

Float — Float containing the expectation value.

Example:

import qamomile.circuit as qm
import qamomile.observable as qm_o

# Build Hamiltonian in Python
H = qm_o.Z(0) * qm_o.Z(1) + 0.5 * (qm_o.X(0) + qm_o.X(1))

@qm.qkernel
def vqe_step(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    # Ansatz
    q[0] = qm.ry(q[0], theta)
    q[0], q[1] = qm.cx(q[0], q[1])

    # Expectation value -> Float
    return qm.expval(q, H)

# Pass Hamiltonian via bindings
executable = transpiler.transpile(vqe_step, bindings={"H": H})

float_ [source]¶

def float_(arg: float | str) -> Float

Create a Float handle from a float literal or declare a named Float parameter.

for_items [source]¶

def for_items(
    d: Dict,
    key_var_names: list[str],
    value_var_name: str,
) -> Generator[tuple[Any, Any], None, None]

Builder function to create a for-items loop in Qamomile frontend.

This context manager creates a ForItemsOperation that iterates over dictionary (key, value) pairs. The operation is always unrolled at transpile time since quantum backends cannot natively iterate over classical data structures.

Parameters:

Yields:

tuple[typing.Any, typing.Any] — Tuple of (key_handles, value_handle) for use in loop body

Example:

@qkernel
def ising_cost(
    q: Vector[Qubit],
    ising: Dict[Tuple[UInt, UInt], Float],
    gamma: Float,
) -> Vector[Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

h [source]¶

def h(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Hadamard gate.

Applied to a single Qubit it returns the transformed qubit. Applied to a Vector[Qubit] it broadcasts the gate over every element via a transpile-time loop, equivalent to for i in qmc.range(n): qs[i] = h(qs[i]).

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

items [source]¶

def items(d: Dict) -> DictItemsIterator

Iterate over dictionary key-value pairs.

This function returns an iterator over (key, value) pairs from a Dict. Used for iterating over Ising coefficients and similar data structures.

Example:

for (i, j), Jij in qmc.items(ising):
    q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)

Parameters:

Returns:

DictItemsIterator — DictItemsIterator yielding (key, value) pairs

measure [source]¶

def measure(target: Union[Qubit, QFixed, Vector[Qubit]]) -> Union[Bit, Float, Vector[Bit]]

Measure a qubit or QFixed in the computational basis.

Performs a projective measurement in the Z-basis. The quantum resource is consumed by this operation and cannot be used afterwards.

Parameters:

Returns:

Union[Bit, Float, Vector[Bit]] — Bit for Qubit input, Float for QFixed input.

Example:

@qkernel
def measure_qubit(q: Qubit) -> Bit:
    q = h(q)
    return measure(q)

@qkernel
def measure_qfixed(qf: QFixed) -> Float:
    # After QPE, qf holds phase bits
    return measure(qf)

p [source]¶

def p(
    target: Union[Qubit, Vector[Qubit]],
    theta: float | Float,
) -> Union[Qubit, Vector[Qubit]]

Phase gate: P(theta)|1> = e^{i*theta}|1>.

Broadcasts the same theta over every qubit when called with a Vector[Qubit].

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

pauli_evolve [source]¶

def pauli_evolve(q: Vector[Qubit], hamiltonian: Observable, gamma: Float) -> Vector[Qubit]

Apply exp(-i * gamma * H) to a qubit register.

Implements Hamiltonian time evolution using the Pauli gadget technique. The actual Hamiltonian is provided via bindings at transpile time.

Each backend can use native implementations:

• Qiskit: PauliEvolutionGate

• QuriParts: PauliRotation gates

• Others: fallback decomposition (basis change + CNOT ladder + RZ)

Parameters:

Returns:

Vector[Qubit] — Vector[Qubit]: The evolved qubit register.

Example:

import qamomile.circuit as qmc
import qamomile.observable as qm_o

H = 0.5 * qm_o.X(0) * qm_o.Z(1) + qm_o.Z(0)

@qmc.qkernel
def cost_layer(
    q: qmc.Vector[qmc.Qubit],
    H: qmc.Observable,
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    q = qmc.pauli_evolve(q, H, gamma)
    return q

transpiler = QiskitTranspiler()
exe = transpiler.transpile(cost_layer, bindings={"H": H, "gamma": 0.5})

qkernel [source]¶

def qkernel(func: Callable[P, R]) -> QKernel[P, R]

Decorator to define a Qamomile quantum kernel.

Parameters:

Returns:

QKernel[P, R] — An instance of QKernel wrapping the function.

qubit [source]¶

def qubit(name: str) -> Qubit

Create a new qubit and emit a QInitOperation.

qubit_array [source]¶

def qubit_array(
    shape: UInt | int | tuple[UInt | int, ...],
    name: str,
) -> Vector[Qubit] | Matrix[Qubit] | Tensor[Qubit]

Create a new qubit array (vector/matrix/tensor) and emit QInitOperations.

range [source]¶

def range(
    stop_or_start: int | UInt,
    stop: int | UInt | None = None,
    step: int | UInt = 1,
) -> Iterator[UInt]

Symbolic range for use in qkernel for-loops.

This function accepts UInt (symbolic) values and is transformed by the AST transformer into for_loop() calls.

Example:

for i in qmc.range(n):          # 0 to n-1
for i in qmc.range(start, stop):  # start to stop-1
for i in qmc.range(start, stop, step):

rx [source]¶

def rx(
    target: Union[Qubit, Vector[Qubit]],
    angle: float | Float,
) -> Union[Qubit, Vector[Qubit]]

Rotation around X-axis: RX(angle) = exp(-i * angle/2 * X).

Broadcasts the same angle over every qubit when called with a Vector[Qubit].

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

ry [source]¶

def ry(
    target: Union[Qubit, Vector[Qubit]],
    angle: float | Float,
) -> Union[Qubit, Vector[Qubit]]

Rotation around Y-axis: RY(angle) = exp(-i * angle/2 * Y).

Broadcasts the same angle over every qubit when called with a Vector[Qubit].

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

rz [source]¶

def rz(
    target: Union[Qubit, Vector[Qubit]],
    angle: float | Float,
) -> Union[Qubit, Vector[Qubit]]

Rotation around Z-axis: RZ(angle) = exp(-i * angle/2 * Z).

Broadcasts the same angle over every qubit when called with a Vector[Qubit].

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

rzz [source]¶

def rzz(qubit_0: Qubit, qubit_1: Qubit, angle: float | Float) -> tuple[Qubit, Qubit]

RZZ gate: exp(-i * angle/2 * Z ⊗ Z).

The RZZ gate applies a rotation around the ZZ axis on two qubits.

Parameters:

Returns:

tuple[Qubit, Qubit] — Tuple of (qubit_0_out, qubit_1_out) after RZZ.

s [source]¶

def s(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

S gate (square root of Z).

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

sdg [source]¶

def sdg(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

S-dagger gate (inverse of S gate).

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

swap [source]¶

def swap(qubit_0: Qubit, qubit_1: Qubit) -> tuple[Qubit, Qubit]

SWAP gate: exchanges two qubits.

The SWAP gate swaps the states of two qubits.

Parameters:

Returns:

tuple[Qubit, Qubit] — Tuple of (qubit_0_out, qubit_1_out) after SWAP.

t [source]¶

def t(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

T gate (fourth root of Z).

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

tdg [source]¶

def tdg(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

T-dagger gate (inverse of T gate).

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

uint [source]¶

def uint(arg: int | str) -> UInt

Create a UInt handle from an integer literal or declare a named UInt parameter.

x [source]¶

def x(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-X gate (NOT gate).

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

y [source]¶

def y(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-Y gate.

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

z [source]¶

def z(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-Z gate.

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

Classes¶

CompositeGate [source]¶

class CompositeGate(abc.ABC)

Base class for user-facing composite gate definitions.

Subclasses can define composite gates in two ways:

1. Using _decompose() (recommended for users): Define the gate decomposition using frontend syntax (same as qkernel [source]).

   class QFT(CompositeGate):
       def __init__(self, num_qubits: int):
           self._num_qubits = num_qubits
   
       @property
       def num_target_qubits(self) -> int:
           return self._num_qubits
   
       def _decompose(self, qubits: Vector[Qubit]) -> Vector[Qubit]:
           # Use frontend syntax: qm.h(), qm.cp(), qm.range(), etc.
           n = self._num_qubits
           for j in qmc.range(n - 1, -1, -1):
               qubits[j] = qmc.h(qubits[j])
               for k in qmc.range(j - 1, -1, -1):
                   angle = math.pi / (2 ** (j - k))
                   qubits[j], qubits[k] = qmc.cp(qubits[j], qubits[k], angle)
           return qubits
   
       def _resources(self) -> ResourceMetadata:
           return ResourceMetadata(t_gates=0)

2. Using get_implementation() (advanced): Return a pre-built Block directly.

Example usage:

# Factory function pattern
def qft(qubits: Vector[Qubit]) -> Vector[Qubit]:
    n = _get_size(qubits)
    return QFT(n)(qubits)

# Direct class usage
result = QFT(3)(*qubit_list)

Attributes¶

• custom_name: str

• gate_type: CompositeGateType

• num_control_qubits: int Number of control qubits (default: 0).

• num_target_qubits: int Number of target qubits this gate operates on.

Methods¶

build_decomposition¶

def build_decomposition(self, *qubits: Qubit = (), **params: Any = {}) -> Block | None

Build the decomposition circuit dynamically.

Override this method to provide a decomposition that depends on runtime arguments (e.g., QPE needs the unitary Block).

This method is called by InlinePass when inlining composite gates that have dynamic implementations.

Parameters:

Returns:

Block | None — Block containing the decomposition, or None if not available.

Example:

class QPE(CompositeGate):
    def build_decomposition(self, *qubits, **params):
        unitary = params.get("unitary")
        # Build QPE circuit using the unitary
        return self._build_qpe_impl(qubits, unitary)

get_implementation¶

def get_implementation(self) -> Block | None

Get the implementation Block, if any.

Return None for stub gates (used in resource estimation). Override in subclasses to provide implementation.

Note: If _decompose() is defined, it takes precedence over this method.

get_resource_metadata¶

def get_resource_metadata(self) -> ResourceMetadata | None

Get resource estimation metadata.

Returns _resources() if defined, otherwise None. Override _resources() to provide resource hints.

get_resources_for_strategy¶

def get_resources_for_strategy(self, strategy_name: str | None = None) -> ResourceMetadata | None

Get resource metadata for a specific strategy.

Parameters:

Returns:

ResourceMetadata | None — ResourceMetadata for the strategy, or None if not available

get_strategy¶

@classmethod
def get_strategy(cls, name: str | None = None) -> 'DecompositionStrategy | None'

Get a registered decomposition strategy.

Parameters:

Returns:

'DecompositionStrategy | None' — DecompositionStrategy instance, or None if not found

list_strategies¶

@classmethod
def list_strategies(cls) -> list[str]

List all registered strategy names.

Returns:

list[str] — List of strategy names

register_strategy¶

@classmethod
def register_strategy(cls, name: str, strategy: 'DecompositionStrategy') -> None

Register a decomposition strategy for this gate type.

Parameters:

Example:

QFT.register_strategy("approximate", ApproximateQFTStrategy(k=3))

set_default_strategy¶

@classmethod
def set_default_strategy(cls, name: str) -> None

Set the default decomposition strategy.

Parameters:

Raises:

• ValueError — If strategy is not registered

QKernel [source]¶

class QKernel(Generic[P, R])

Decorator class for Qamomile quantum kernels.

Constructor¶

def __init__(self, func: Callable[P, R]) -> None

Attributes¶

• block: Block Compile the function to a hierarchical Block if not already compiled.

• func

• input_types

• name

• output_types

• raw_func

• signature

Methods¶

build¶

def build(self, parameters: list[str] | None = None, **kwargs: Any = {}) -> Block

Build a traced Block by tracing this kernel.

Parameters:

Returns:

Block — The traced block ready for transpilation, estimation, or visualization.

Raises:

• TypeError — If a non-parameterizable type is specified as parameter.

• ValueError — If required arguments are missing.

Example:

@qm.qkernel
def circuit(q: Qubit, theta: float) -> Qubit:
    q = qm.rx(q, theta)
    return q

# Auto-detect theta as parameter
block = circuit.build()

# Explicit parameter list
block = circuit.build(parameters=["theta"])

# theta bound to concrete value
block = circuit.build(theta=0.5)

# Transpile with binding
transpiler = QiskitTranspiler()
result = transpiler.emit(graph, binding={"theta": 0.5})

draw¶

def draw(
    self,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
    **kwargs: Any = {},
) -> Any

Visualize the circuit using Matplotlib.

This method builds the computation graph and creates a static visualization. Parameters are auto-detected: non-Qubit arguments without concrete values are shown as symbolic parameters.

Parameters:

Returns:

Any — matplotlib.figure.Figure object.

Raises:

• ImportError — If matplotlib is not installed.

Example:

import qamomile.circuit as qm

@qm.qkernel
def inner(q: qm.Qubit) -> qm.Qubit:
    return qm.x(q)

@qm.qkernel
def circuit(q: qm.Qubit, theta: float) -> qm.Qubit:
    q = inner(q)
    q = qm.h(q)
    q = qm.rx(q, theta)
    return q

# Draw with auto-detected symbolic parameter (theta)
fig = circuit.draw()

# Draw with bound parameter
fig = circuit.draw(theta=0.5)

# Draw with blocks as boxes (default)
fig = circuit.draw()

# Draw with blocks expanded (inlined)
fig = circuit.draw(inline=True)

# Draw with loops folded (shown as blocks)
fig = circuit.draw(fold_loops=True)

# Draw with composite gates expanded
fig = circuit.draw(expand_composite=True)

estimate_resources¶

def estimate_resources(self, *, bindings: dict[str, Any] | None = None) -> ResourceEstimate

Estimate all resources for this kernel’s circuit.

Convenience method that delegates to the module-level estimate_resources function, eliminating the need to access .block directly.

Parameters:

Returns:

ResourceEstimate — ResourceEstimate with qubits, gates, and parameters.

Example:

>>> @qm.qkernel
... def bell() -> qm.Vector[qm.Qubit]:
...     q = qm.qubit_array(2)
...     q[0] = qm.h(q[0])
...     q[0], q[1] = qm.cx(q[0], q[1])
...     return q
>>> est = bell.estimate_resources()
>>> print(est.qubits)  # 2

Submodules¶

• qamomile.circuit.algorithm

• qamomile.circuit.estimator

• qamomile.circuit.frontend

• qamomile.circuit.ir

• qamomile.circuit.qft

• qamomile.circuit.qpe

• qamomile.circuit.stdlib

• qamomile.circuit.transpiler

• qamomile.circuit.visualization