qamomile.cudaq

CUDA-Q backend for Qamomile.

This module provides transpiler, executor, and observable conversion for the CUDA-Q quantum computing platform.

All circuits are emitted through a unified CudaqKernelEmitter codegen path, producing CudaqKernelArtifact instances. The artifact’s ExecutionMode (STATIC or RUNNABLE) determines which CUDA-Q runtime API is used for execution.

Public symbols are exported lazily so that a mere import qamomile.cudaq does not fail in environments where the cudaq package is absent. Accessing any public symbol (e.g. qamomile.cudaq.CudaqTranspiler) will raise an :class:ImportError with actionable install guidance when cudaq is not available.

Overview¶

Constants¶

• BoundCudaqCircuit = BoundCudaqKernelArtifact Alias for backward compatibility. Use BoundCudaqKernelArtifact instead.

• BoundCudaqRuntimeCircuit = BoundCudaqKernelArtifact Alias for backward compatibility. Use BoundCudaqKernelArtifact instead.

• CudaqCircuit = CudaqKernelArtifact Alias for backward compatibility. Use CudaqKernelArtifact instead.

• CudaqCodegenEmitter = CudaqKernelEmitter Alias for backward compatibility. Use CudaqKernelEmitter instead.

• CudaqGateEmitter = CudaqKernelEmitter Alias for backward compatibility. Use CudaqKernelEmitter instead.

• CudaqRuntimeCircuit = CudaqKernelArtifact Alias for backward compatibility. Use CudaqKernelArtifact instead.

Functions¶

hamiltonian_to_cudaq_spin_op [source]¶

def hamiltonian_to_cudaq_spin_op(hamiltonian: qm_o.Hamiltonian) -> Any

Convert qamomile.observable.Hamiltonian to cudaq.SpinOperator.

Parameters:

Returns:

Any — A CUDA-Q SpinOperator built from cudaq.spin primitives.

Example:

import qamomile.observable as qm_o
from qamomile.cudaq.observable import hamiltonian_to_cudaq_spin_op

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

Classes¶

BoundCudaqKernelArtifact [source]¶

class BoundCudaqKernelArtifact

CUDA-Q kernel artifact with bound parameter values.

Used as the return type of CudaqExecutor.bind_parameters. The executor dispatches to the appropriate CUDA-Q runtime API based on execution_mode.

Parameters:

Constructor¶

def __init__(
    self,
    kernel_func: Any,
    num_qubits: int,
    num_clbits: int,
    param_values: list[float],
    execution_mode: ExecutionMode = ExecutionMode.STATIC,
) -> None

Attributes¶

• execution_mode: ExecutionMode

• kernel: Any Backward-compatibility alias for kernel_func.

• kernel_func: Any

• num_clbits: int

• num_qubits: int

• param_values: list[float]

CudaqEmitPass [source]¶

class CudaqEmitPass(StandardEmitPass[CudaqKernelArtifact])

CUDA-Q-specific emission pass.

Uses a single CudaqKernelEmitter for all circuits. The emitter generates @cudaq.kernel decorated Python source for both static and runtime control flow circuits. The execution mode (STATIC or RUNNABLE) is determined by a pre-scan of the operations.

Constructor¶

def __init__(
    self,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
)

CudaqExecutor [source]¶

class CudaqExecutor(QuantumExecutor[CudaqKernelArtifact])

CUDA-Q quantum executor.

Supports sampling via cudaq.sample and expectation value estimation via cudaq.observe. Dispatches to the appropriate CUDA-Q runtime API based on the artifact’s execution_mode.

Parameters:

Constructor¶

def __init__(self, target: str | None = None)

Methods¶

bind_parameters¶

def bind_parameters(
    self,
    circuit: Any,
    bindings: dict[str, Any],
    parameter_metadata: ParameterMetadata,
) -> BoundCudaqKernelArtifact

Bind parameters to a circuit for execution.

Returns a BoundCudaqKernelArtifact with the execution mode inherited from the source artifact.

estimate¶

def estimate(
    self,
    circuit: Any,
    hamiltonian: 'qm_o.Hamiltonian',
    params: Sequence[float] | None = None,
) -> float

Estimate expectation value using cudaq.observe.

Only supported for STATIC-mode artifacts. RUNNABLE-mode artifacts are not compatible with cudaq.observe() and raise TypeError.

execute¶

def execute(self, circuit: Any, shots: int) -> dict[str, int]

Execute circuit and return canonical big-endian bitstring counts.

Dispatches based on execution_mode:

• STATIC: uses cudaq.sample() on the decorator kernel.

• RUNNABLE: uses cudaq.run() on the runnable kernel.

Both paths return bitstrings in big-endian format (highest qubit index = leftmost bit).

CudaqKernelArtifact [source]¶

class CudaqKernelArtifact

Compiled CUDA-Q decorator-kernel artifact.

Wraps a @cudaq.kernel decorated function produced by CudaqKernelEmitter. The execution_mode field determines which CUDA-Q runtime APIs are valid for this artifact.

Parameters:

Constructor¶

def __init__(
    self,
    kernel_func: Any,
    num_qubits: int,
    num_clbits: int,
    source: str = '',
    execution_mode: ExecutionMode = ExecutionMode.STATIC,
    param_count: int = 0,
) -> None

Attributes¶

• execution_mode: ExecutionMode

• kernel: Any Backward-compatibility alias for kernel_func.

• kernel_func: Any

• num_clbits: int

• num_qubits: int

• param_count: int

• source: str

CudaqKernelEmitter [source]¶

class CudaqKernelEmitter

Unified GateEmitter that generates @cudaq.kernel Python source code.

Used for all CUDA-Q circuits. Gate calls are accumulated as Python source lines forming a @cudaq.kernel decorated function. The finalize() method compiles the source via exec() and populates the artifact’s kernel_func.

The noop_measurement flag controls measurement behaviour:

• True (STATIC mode): emit_measure is a no-op; cudaq.sample() auto-measures all qubits.

• False (RUNNABLE mode): emit_measure emits explicit mz() calls for mid-circuit measurement variables.

Parameters:

Constructor¶

def __init__(self, parametric: bool = False) -> None

Attributes¶

• noop_measurement: bool

Methods¶

append_gate¶

def append_gate(self, circuit: CudaqKernelArtifact, gate: Any, qubits: list[int]) -> None

No-op: not supported by CUDA-Q codegen path.

circuit_to_gate¶

def circuit_to_gate(self, circuit: CudaqKernelArtifact, name: str = 'U') -> Any

No-op: not supported by CUDA-Q codegen path.

create_circuit¶

def create_circuit(self, num_qubits: int, num_clbits: int) -> CudaqKernelArtifact

Start building a @cudaq.kernel function.

Resets internal state and emits the q = cudaq.qvector(N) allocation line.

Parameters:

Returns:

CudaqKernelArtifact — A new CudaqKernelArtifact with kernel_func=None CudaqKernelArtifact — (populated by finalize()).

create_parameter¶

def create_parameter(self, name: str) -> CudaqExpr

Return a CudaqExpr referencing thetas[i].

Returns an arithmetic-capable expression object so that StandardEmitPass._evaluate_binop() can compose gate-angle expressions (e.g. gamma * Jij) without triggering a TypeError on raw string operands.

Parameters:

Returns:

CudaqExpr — CudaqExpr wrapping a source expression like CudaqExpr — "thetas[0]".

emit_barrier¶

def emit_barrier(self, circuit: CudaqKernelArtifact, qubits: list[int]) -> None

No-op: CUDA-Q does not support barrier instructions.

emit_ch¶

def emit_ch(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Hadamard via decomposition.

emit_cp¶

def emit_cp(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-Phase via decomposition.

CP(ctrl, tgt, theta) = RZ(tgt, theta/2) CNOT(ctrl, tgt) RZ(tgt, -theta/2) CNOT(ctrl, tgt) RZ(ctrl, theta/2)

emit_crx¶

def emit_crx(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RX gate.

emit_cry¶

def emit_cry(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RY gate.

emit_crz¶

def emit_crz(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RZ gate.

emit_cx¶

def emit_cx(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit CNOT (controlled-X) gate.

emit_cy¶

def emit_cy(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Y via decomposition.

emit_cz¶

def emit_cz(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Z gate.

emit_else_start¶

def emit_else_start(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Emit else: block.

emit_for_loop_end¶

def emit_for_loop_end(self, circuit: CudaqKernelArtifact, context: Any) -> None

Not supported: for-loops are unrolled by the transpiler.

emit_for_loop_start¶

def emit_for_loop_start(self, circuit: CudaqKernelArtifact, indexset: range) -> Any

Not supported: for-loops are unrolled by the transpiler.

emit_h¶

def emit_h(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Hadamard gate.

emit_if_end¶

def emit_if_end(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Close if block by decreasing indentation.

emit_if_start¶

def emit_if_start(
    self,
    circuit: CudaqKernelArtifact,
    clbit: int,
    value: int = 1,
) -> dict[str, Any]

Emit if __b{clbit}: and increase indentation.

emit_measure¶

def emit_measure(self, circuit: CudaqKernelArtifact, qubit: int, clbit: int) -> None

Emit measurement, respecting the current mode.

In STATIC mode (noop_measurement=True), this is a no-op: cudaq.sample() auto-measures all qubits.

In RUNNABLE mode (noop_measurement=False), emits explicit mz() to capture mid-circuit measurement results as local variables for if / while conditions.

emit_multi_controlled_x¶

def emit_multi_controlled_x(
    self,
    circuit: CudaqKernelArtifact,
    control_indices: list[int],
    target_idx: int,
) -> None

Emit multi-controlled X using x.ctrl(c0, c1, ..., target).

emit_p¶

def emit_p(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit phase gate (R1).

emit_rx¶

def emit_rx(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RX rotation gate.

emit_ry¶

def emit_ry(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RY rotation gate.

emit_rz¶

def emit_rz(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RZ rotation gate.

emit_rzz¶

def emit_rzz(
    self,
    circuit: CudaqKernelArtifact,
    qubit1: int,
    qubit2: int,
    angle: float | Any,
) -> None

Emit RZZ via CNOT + RZ decomposition.

RZZ(q1, q2, theta) = CNOT(q1, q2) RZ(q2, theta) CNOT(q1, q2)

emit_s¶

def emit_s(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit S (phase) gate.

emit_sdg¶

def emit_sdg(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit S-dagger gate.

emit_swap¶

def emit_swap(self, circuit: CudaqKernelArtifact, qubit1: int, qubit2: int) -> None

Emit SWAP gate.

emit_t¶

def emit_t(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit T gate.

emit_tdg¶

def emit_tdg(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit T-dagger gate.

emit_toffoli¶

def emit_toffoli(
    self,
    circuit: CudaqKernelArtifact,
    control1: int,
    control2: int,
    target: int,
) -> None

Emit Toffoli (CCX) gate.

Delegates to :meth:emit_multi_controlled_x so that all multi-controlled X emission flows through a single canonical helper.

emit_while_end¶

def emit_while_end(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Close while block by decreasing indentation.

emit_while_start¶

def emit_while_start(
    self,
    circuit: CudaqKernelArtifact,
    clbit: int,
    value: int = 1,
) -> dict[str, Any]

Emit while __b{clbit}: and increase indentation.

emit_x¶

def emit_x(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-X gate.

emit_y¶

def emit_y(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-Y gate.

emit_z¶

def emit_z(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-Z gate.

finalize¶

def finalize(self, circuit: CudaqKernelArtifact, mode: ExecutionMode) -> CudaqKernelArtifact

Compile accumulated source into a @cudaq.kernel function.

For RUNNABLE mode, appends return [__b0, __b1, ...] to return per-shot logical clbit values. For STATIC mode, generates a void function with no explicit terminal measurement.

Parameters:

Returns:

CudaqKernelArtifact — The same artifact with kernel_func and source populated.

gate_controlled¶

def gate_controlled(self, gate: Any, num_controls: int) -> Any

No-op: not supported by CUDA-Q codegen path.

gate_power¶

def gate_power(self, gate: Any, power: int) -> Any

No-op: not supported by CUDA-Q codegen path.

supports_for_loop¶

def supports_for_loop(self) -> bool

Return False: for-loops are unrolled by the transpiler.

supports_if_else¶

def supports_if_else(self) -> bool

Return True only in RUNNABLE mode (measurement-dependent branching).

supports_while_loop¶

def supports_while_loop(self) -> bool

Return True only in RUNNABLE mode.

CudaqTranspiler [source]¶

class CudaqTranspiler(Transpiler[CudaqKernelArtifact])

CUDA-Q transpiler for qamomile.circuit module.

Converts Qamomile QKernels into CUDA-Q decorator-kernel artifacts.

Example:

from qamomile.cudaq import CudaqTranspiler
import qamomile.circuit as qm

@qm.qkernel
def bell_state(q0: qm.Qubit, q1: qm.Qubit) -> tuple[qm.Bit, qm.Bit]:
    q0 = qm.h(q0)
    q0, q1 = qm.cx(q0, q1)
    return qm.measure(q0), qm.measure(q1)

transpiler = CudaqTranspiler()
executable = transpiler.transpile(bell_state)

Methods¶

executor¶

def executor(self, target: str | None = None) -> CudaqExecutor

Create a CUDA-Q executor.

Parameters:

ExecutionMode [source]¶

class ExecutionMode(enum.Enum)

Execution mode for a CUDA-Q kernel artifact.

Determines which CUDA-Q runtime API is used for execution:

• STATIC: Compatible with cudaq.sample(), cudaq.get_state(), and cudaq.observe(). The kernel has no explicit terminal measurements and no return value.

• RUNNABLE: Compatible with cudaq.run(). The kernel has explicit mid-circuit measurements and returns mz(q) (list[bool]).

Attributes¶

• RUNNABLE

• STATIC

qamomile.cudaq.emitter¶

CUDA-Q emitter implementation.

This module provides a unified emitter for the CUDA-Q backend:

• CudaqKernelEmitter: Generates @cudaq.kernel decorated Python source code for all circuits. The emitter supports two execution modes:

  • STATIC: Measurement-free kernels compatible with cudaq.sample(), cudaq.get_state(), and cudaq.observe().

  • RUNNABLE: Kernels with explicit mid-circuit measurements and a final return mz(q), compatible with cudaq.run().

The execution mode is determined by the emit pass based on whether the circuit contains runtime measurement-dependent control flow.

Overview¶

Constants¶

• CudaqCircuit = CudaqKernelArtifact Alias for backward compatibility. Use CudaqKernelArtifact instead.

• CudaqCodegenEmitter = CudaqKernelEmitter Alias for backward compatibility. Use CudaqKernelEmitter instead.

• CudaqGateEmitter = CudaqKernelEmitter Alias for backward compatibility. Use CudaqKernelEmitter instead.

• CudaqRuntimeCircuit = CudaqKernelArtifact Alias for backward compatibility. Use CudaqKernelArtifact instead.

Classes¶

CudaqExpr [source]¶

class CudaqExpr

Arithmetic-capable wrapper for CUDA-Q source expressions.

Enables operator-overload-based expression building in StandardEmitPass._evaluate_binop(). Each arithmetic operation returns a new CudaqExpr with a properly parenthesized string representation. str(expr) yields the raw source expression suitable for embedding directly in generated @cudaq.kernel code.

Parameters:

Constructor¶

def __init__(self, expr: str) -> None

CudaqKernelArtifact [source]¶

class CudaqKernelArtifact

Compiled CUDA-Q decorator-kernel artifact.

Wraps a @cudaq.kernel decorated function produced by CudaqKernelEmitter. The execution_mode field determines which CUDA-Q runtime APIs are valid for this artifact.

Parameters:

Constructor¶

def __init__(
    self,
    kernel_func: Any,
    num_qubits: int,
    num_clbits: int,
    source: str = '',
    execution_mode: ExecutionMode = ExecutionMode.STATIC,
    param_count: int = 0,
) -> None

Attributes¶

• execution_mode: ExecutionMode

• kernel: Any Backward-compatibility alias for kernel_func.

• kernel_func: Any

• num_clbits: int

• num_qubits: int

• param_count: int

• source: str

CudaqKernelEmitter [source]¶

class CudaqKernelEmitter

Unified GateEmitter that generates @cudaq.kernel Python source code.

Used for all CUDA-Q circuits. Gate calls are accumulated as Python source lines forming a @cudaq.kernel decorated function. The finalize() method compiles the source via exec() and populates the artifact’s kernel_func.

The noop_measurement flag controls measurement behaviour:

• True (STATIC mode): emit_measure is a no-op; cudaq.sample() auto-measures all qubits.

• False (RUNNABLE mode): emit_measure emits explicit mz() calls for mid-circuit measurement variables.

Parameters:

Constructor¶

def __init__(self, parametric: bool = False) -> None

Attributes¶

• noop_measurement: bool

Methods¶

append_gate¶

def append_gate(self, circuit: CudaqKernelArtifact, gate: Any, qubits: list[int]) -> None

No-op: not supported by CUDA-Q codegen path.

circuit_to_gate¶

def circuit_to_gate(self, circuit: CudaqKernelArtifact, name: str = 'U') -> Any

No-op: not supported by CUDA-Q codegen path.

create_circuit¶

def create_circuit(self, num_qubits: int, num_clbits: int) -> CudaqKernelArtifact

Start building a @cudaq.kernel function.

Resets internal state and emits the q = cudaq.qvector(N) allocation line.

Parameters:

Returns:

CudaqKernelArtifact — A new CudaqKernelArtifact with kernel_func=None CudaqKernelArtifact — (populated by finalize()).

create_parameter¶

def create_parameter(self, name: str) -> CudaqExpr

Return a CudaqExpr referencing thetas[i].

Returns an arithmetic-capable expression object so that StandardEmitPass._evaluate_binop() can compose gate-angle expressions (e.g. gamma * Jij) without triggering a TypeError on raw string operands.

Parameters:

Returns:

CudaqExpr — CudaqExpr wrapping a source expression like CudaqExpr — "thetas[0]".

emit_barrier¶

def emit_barrier(self, circuit: CudaqKernelArtifact, qubits: list[int]) -> None

No-op: CUDA-Q does not support barrier instructions.

emit_ch¶

def emit_ch(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Hadamard via decomposition.

emit_cp¶

def emit_cp(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-Phase via decomposition.

CP(ctrl, tgt, theta) = RZ(tgt, theta/2) CNOT(ctrl, tgt) RZ(tgt, -theta/2) CNOT(ctrl, tgt) RZ(ctrl, theta/2)

emit_crx¶

def emit_crx(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RX gate.

emit_cry¶

def emit_cry(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RY gate.

emit_crz¶

def emit_crz(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RZ gate.

emit_cx¶

def emit_cx(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit CNOT (controlled-X) gate.

emit_cy¶

def emit_cy(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Y via decomposition.

emit_cz¶

def emit_cz(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Z gate.

emit_else_start¶

def emit_else_start(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Emit else: block.

emit_for_loop_end¶

def emit_for_loop_end(self, circuit: CudaqKernelArtifact, context: Any) -> None

Not supported: for-loops are unrolled by the transpiler.

emit_for_loop_start¶

def emit_for_loop_start(self, circuit: CudaqKernelArtifact, indexset: range) -> Any

Not supported: for-loops are unrolled by the transpiler.

emit_h¶

def emit_h(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Hadamard gate.

emit_if_end¶

def emit_if_end(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Close if block by decreasing indentation.

emit_if_start¶

def emit_if_start(
    self,
    circuit: CudaqKernelArtifact,
    clbit: int,
    value: int = 1,
) -> dict[str, Any]

Emit if __b{clbit}: and increase indentation.

emit_measure¶

def emit_measure(self, circuit: CudaqKernelArtifact, qubit: int, clbit: int) -> None

Emit measurement, respecting the current mode.

In STATIC mode (noop_measurement=True), this is a no-op: cudaq.sample() auto-measures all qubits.

In RUNNABLE mode (noop_measurement=False), emits explicit mz() to capture mid-circuit measurement results as local variables for if / while conditions.

emit_multi_controlled_x¶

def emit_multi_controlled_x(
    self,
    circuit: CudaqKernelArtifact,
    control_indices: list[int],
    target_idx: int,
) -> None

Emit multi-controlled X using x.ctrl(c0, c1, ..., target).

emit_p¶

def emit_p(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit phase gate (R1).

emit_rx¶

def emit_rx(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RX rotation gate.

emit_ry¶

def emit_ry(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RY rotation gate.

emit_rz¶

def emit_rz(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RZ rotation gate.

emit_rzz¶

def emit_rzz(
    self,
    circuit: CudaqKernelArtifact,
    qubit1: int,
    qubit2: int,
    angle: float | Any,
) -> None

Emit RZZ via CNOT + RZ decomposition.

RZZ(q1, q2, theta) = CNOT(q1, q2) RZ(q2, theta) CNOT(q1, q2)

emit_s¶

def emit_s(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit S (phase) gate.

emit_sdg¶

def emit_sdg(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit S-dagger gate.

emit_swap¶

def emit_swap(self, circuit: CudaqKernelArtifact, qubit1: int, qubit2: int) -> None

Emit SWAP gate.

emit_t¶

def emit_t(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit T gate.

emit_tdg¶

def emit_tdg(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit T-dagger gate.

emit_toffoli¶

def emit_toffoli(
    self,
    circuit: CudaqKernelArtifact,
    control1: int,
    control2: int,
    target: int,
) -> None

Emit Toffoli (CCX) gate.

Delegates to :meth:emit_multi_controlled_x so that all multi-controlled X emission flows through a single canonical helper.

emit_while_end¶

def emit_while_end(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Close while block by decreasing indentation.

emit_while_start¶

def emit_while_start(
    self,
    circuit: CudaqKernelArtifact,
    clbit: int,
    value: int = 1,
) -> dict[str, Any]

Emit while __b{clbit}: and increase indentation.

emit_x¶

def emit_x(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-X gate.

emit_y¶

def emit_y(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-Y gate.

emit_z¶

def emit_z(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-Z gate.

finalize¶

def finalize(self, circuit: CudaqKernelArtifact, mode: ExecutionMode) -> CudaqKernelArtifact

Compile accumulated source into a @cudaq.kernel function.

For RUNNABLE mode, appends return [__b0, __b1, ...] to return per-shot logical clbit values. For STATIC mode, generates a void function with no explicit terminal measurement.

Parameters:

Returns:

CudaqKernelArtifact — The same artifact with kernel_func and source populated.

gate_controlled¶

def gate_controlled(self, gate: Any, num_controls: int) -> Any

No-op: not supported by CUDA-Q codegen path.

gate_power¶

def gate_power(self, gate: Any, power: int) -> Any

No-op: not supported by CUDA-Q codegen path.

supports_for_loop¶

def supports_for_loop(self) -> bool

Return False: for-loops are unrolled by the transpiler.

supports_if_else¶

def supports_if_else(self) -> bool

Return True only in RUNNABLE mode (measurement-dependent branching).

supports_while_loop¶

def supports_while_loop(self) -> bool

Return True only in RUNNABLE mode.

ExecutionMode [source]¶

class ExecutionMode(enum.Enum)

Execution mode for a CUDA-Q kernel artifact.

Determines which CUDA-Q runtime API is used for execution:

• STATIC: Compatible with cudaq.sample(), cudaq.get_state(), and cudaq.observe(). The kernel has no explicit terminal measurements and no return value.

• RUNNABLE: Compatible with cudaq.run(). The kernel has explicit mid-circuit measurements and returns mz(q) (list[bool]).

Attributes¶

• RUNNABLE

• STATIC

qamomile.cudaq.observable¶

CUDA-Q observable support.

This module provides conversion from qamomile.observable.Hamiltonian to CUDA-Q SpinOperator for use with cudaq.observe.

Overview¶

Functions¶

hamiltonian_to_cudaq_spin_op [source]¶

def hamiltonian_to_cudaq_spin_op(hamiltonian: qm_o.Hamiltonian) -> Any

Convert qamomile.observable.Hamiltonian to cudaq.SpinOperator.

Parameters:

Returns:

Any — A CUDA-Q SpinOperator built from cudaq.spin primitives.

Example:

import qamomile.observable as qm_o
from qamomile.cudaq.observable import hamiltonian_to_cudaq_spin_op

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

qamomile.cudaq.transpiler¶

CUDA-Q backend transpiler implementation.

This module provides CudaqTranspiler for converting Qamomile QKernels into CUDA-Q decorator-kernel artifacts, along with CudaqEmitPass and CudaqExecutor.

All circuits (static and runtime) are emitted through a single CudaqKernelEmitter codegen path. The emitter produces CudaqKernelArtifact instances whose execution_mode determines whether cudaq.sample() / cudaq.observe() / cudaq.get_state() (STATIC) or cudaq.run() (RUNNABLE) is used for execution.

Overview¶

Constants¶

• BoundCudaqCircuit = BoundCudaqKernelArtifact Alias for backward compatibility. Use BoundCudaqKernelArtifact instead.

• BoundCudaqRuntimeCircuit = BoundCudaqKernelArtifact Alias for backward compatibility. Use BoundCudaqKernelArtifact instead.

Functions¶

resolve_if_condition [source]¶

def resolve_if_condition(condition: Any, bindings: dict[str, Any]) -> bool | None

Resolve an if-condition to a compile-time boolean.

Checks whether the condition can be statically evaluated at emit time. Plain Python values (int/bool captured by @qkernel from closure), constant-folded Values, and Values resolvable via bindings are all treated as compile-time constants.

Parameters:

Returns:

bool | None — True/False for compile-time resolvable conditions, bool | None — None for runtime conditions that must be dispatched to the bool | None — backend’s conditional branching protocol.

Classes¶

BoundCudaqKernelArtifact [source]¶

class BoundCudaqKernelArtifact

CUDA-Q kernel artifact with bound parameter values.

Used as the return type of CudaqExecutor.bind_parameters. The executor dispatches to the appropriate CUDA-Q runtime API based on execution_mode.

Parameters:

Constructor¶

def __init__(
    self,
    kernel_func: Any,
    num_qubits: int,
    num_clbits: int,
    param_values: list[float],
    execution_mode: ExecutionMode = ExecutionMode.STATIC,
) -> None

Attributes¶

• execution_mode: ExecutionMode

• kernel: Any Backward-compatibility alias for kernel_func.

• kernel_func: Any

• num_clbits: int

• num_qubits: int

• param_values: list[float]

CudaqEmitPass [source]¶

class CudaqEmitPass(StandardEmitPass[CudaqKernelArtifact])

CUDA-Q-specific emission pass.

Uses a single CudaqKernelEmitter for all circuits. The emitter generates @cudaq.kernel decorated Python source for both static and runtime control flow circuits. The execution mode (STATIC or RUNNABLE) is determined by a pre-scan of the operations.

Constructor¶

def __init__(
    self,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
)

CudaqExecutor [source]¶

class CudaqExecutor(QuantumExecutor[CudaqKernelArtifact])

CUDA-Q quantum executor.

Supports sampling via cudaq.sample and expectation value estimation via cudaq.observe. Dispatches to the appropriate CUDA-Q runtime API based on the artifact’s execution_mode.

Parameters:

Constructor¶

def __init__(self, target: str | None = None)

Methods¶

bind_parameters¶

def bind_parameters(
    self,
    circuit: Any,
    bindings: dict[str, Any],
    parameter_metadata: ParameterMetadata,
) -> BoundCudaqKernelArtifact

Bind parameters to a circuit for execution.

Returns a BoundCudaqKernelArtifact with the execution mode inherited from the source artifact.

estimate¶

def estimate(
    self,
    circuit: Any,
    hamiltonian: 'qm_o.Hamiltonian',
    params: Sequence[float] | None = None,
) -> float

Estimate expectation value using cudaq.observe.

Only supported for STATIC-mode artifacts. RUNNABLE-mode artifacts are not compatible with cudaq.observe() and raise TypeError.

execute¶

def execute(self, circuit: Any, shots: int) -> dict[str, int]

Execute circuit and return canonical big-endian bitstring counts.

Dispatches based on execution_mode:

• STATIC: uses cudaq.sample() on the decorator kernel.

• RUNNABLE: uses cudaq.run() on the runnable kernel.

Both paths return bitstrings in big-endian format (highest qubit index = leftmost bit).

CudaqKernelArtifact [source]¶

class CudaqKernelArtifact

Compiled CUDA-Q decorator-kernel artifact.

Wraps a @cudaq.kernel decorated function produced by CudaqKernelEmitter. The execution_mode field determines which CUDA-Q runtime APIs are valid for this artifact.

Parameters:

Constructor¶

def __init__(
    self,
    kernel_func: Any,
    num_qubits: int,
    num_clbits: int,
    source: str = '',
    execution_mode: ExecutionMode = ExecutionMode.STATIC,
    param_count: int = 0,
) -> None

Attributes¶

• execution_mode: ExecutionMode

• kernel: Any Backward-compatibility alias for kernel_func.

• kernel_func: Any

• num_clbits: int

• num_qubits: int

• param_count: int

• source: str

CudaqKernelEmitter [source]¶

class CudaqKernelEmitter

Unified GateEmitter that generates @cudaq.kernel Python source code.

Used for all CUDA-Q circuits. Gate calls are accumulated as Python source lines forming a @cudaq.kernel decorated function. The finalize() method compiles the source via exec() and populates the artifact’s kernel_func.

The noop_measurement flag controls measurement behaviour:

• True (STATIC mode): emit_measure is a no-op; cudaq.sample() auto-measures all qubits.

• False (RUNNABLE mode): emit_measure emits explicit mz() calls for mid-circuit measurement variables.

Parameters:

Constructor¶

def __init__(self, parametric: bool = False) -> None

Attributes¶

• noop_measurement: bool

Methods¶

append_gate¶

def append_gate(self, circuit: CudaqKernelArtifact, gate: Any, qubits: list[int]) -> None

No-op: not supported by CUDA-Q codegen path.

circuit_to_gate¶

def circuit_to_gate(self, circuit: CudaqKernelArtifact, name: str = 'U') -> Any

No-op: not supported by CUDA-Q codegen path.

create_circuit¶

def create_circuit(self, num_qubits: int, num_clbits: int) -> CudaqKernelArtifact

Start building a @cudaq.kernel function.

Resets internal state and emits the q = cudaq.qvector(N) allocation line.

Parameters:

Returns:

CudaqKernelArtifact — A new CudaqKernelArtifact with kernel_func=None CudaqKernelArtifact — (populated by finalize()).

create_parameter¶

def create_parameter(self, name: str) -> CudaqExpr

Return a CudaqExpr referencing thetas[i].

Returns an arithmetic-capable expression object so that StandardEmitPass._evaluate_binop() can compose gate-angle expressions (e.g. gamma * Jij) without triggering a TypeError on raw string operands.

Parameters:

Returns:

CudaqExpr — CudaqExpr wrapping a source expression like CudaqExpr — "thetas[0]".

emit_barrier¶

def emit_barrier(self, circuit: CudaqKernelArtifact, qubits: list[int]) -> None

No-op: CUDA-Q does not support barrier instructions.

emit_ch¶

def emit_ch(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Hadamard via decomposition.

emit_cp¶

def emit_cp(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-Phase via decomposition.

CP(ctrl, tgt, theta) = RZ(tgt, theta/2) CNOT(ctrl, tgt) RZ(tgt, -theta/2) CNOT(ctrl, tgt) RZ(ctrl, theta/2)

emit_crx¶

def emit_crx(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RX gate.

emit_cry¶

def emit_cry(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RY gate.

emit_crz¶

def emit_crz(
    self,
    circuit: CudaqKernelArtifact,
    control: int,
    target: int,
    angle: float | Any,
) -> None

Emit controlled-RZ gate.

emit_cx¶

def emit_cx(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit CNOT (controlled-X) gate.

emit_cy¶

def emit_cy(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Y via decomposition.

emit_cz¶

def emit_cz(self, circuit: CudaqKernelArtifact, control: int, target: int) -> None

Emit controlled-Z gate.

emit_else_start¶

def emit_else_start(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Emit else: block.

emit_for_loop_end¶

def emit_for_loop_end(self, circuit: CudaqKernelArtifact, context: Any) -> None

Not supported: for-loops are unrolled by the transpiler.

emit_for_loop_start¶

def emit_for_loop_start(self, circuit: CudaqKernelArtifact, indexset: range) -> Any

Not supported: for-loops are unrolled by the transpiler.

emit_h¶

def emit_h(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Hadamard gate.

emit_if_end¶

def emit_if_end(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Close if block by decreasing indentation.

emit_if_start¶

def emit_if_start(
    self,
    circuit: CudaqKernelArtifact,
    clbit: int,
    value: int = 1,
) -> dict[str, Any]

Emit if __b{clbit}: and increase indentation.

emit_measure¶

def emit_measure(self, circuit: CudaqKernelArtifact, qubit: int, clbit: int) -> None

Emit measurement, respecting the current mode.

In STATIC mode (noop_measurement=True), this is a no-op: cudaq.sample() auto-measures all qubits.

In RUNNABLE mode (noop_measurement=False), emits explicit mz() to capture mid-circuit measurement results as local variables for if / while conditions.

emit_multi_controlled_x¶

def emit_multi_controlled_x(
    self,
    circuit: CudaqKernelArtifact,
    control_indices: list[int],
    target_idx: int,
) -> None

Emit multi-controlled X using x.ctrl(c0, c1, ..., target).

emit_p¶

def emit_p(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit phase gate (R1).

emit_rx¶

def emit_rx(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RX rotation gate.

emit_ry¶

def emit_ry(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RY rotation gate.

emit_rz¶

def emit_rz(self, circuit: CudaqKernelArtifact, qubit: int, angle: float | Any) -> None

Emit RZ rotation gate.

emit_rzz¶

def emit_rzz(
    self,
    circuit: CudaqKernelArtifact,
    qubit1: int,
    qubit2: int,
    angle: float | Any,
) -> None

Emit RZZ via CNOT + RZ decomposition.

RZZ(q1, q2, theta) = CNOT(q1, q2) RZ(q2, theta) CNOT(q1, q2)

emit_s¶

def emit_s(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit S (phase) gate.

emit_sdg¶

def emit_sdg(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit S-dagger gate.

emit_swap¶

def emit_swap(self, circuit: CudaqKernelArtifact, qubit1: int, qubit2: int) -> None

Emit SWAP gate.

emit_t¶

def emit_t(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit T gate.

emit_tdg¶

def emit_tdg(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit T-dagger gate.

emit_toffoli¶

def emit_toffoli(
    self,
    circuit: CudaqKernelArtifact,
    control1: int,
    control2: int,
    target: int,
) -> None

Emit Toffoli (CCX) gate.

Delegates to :meth:emit_multi_controlled_x so that all multi-controlled X emission flows through a single canonical helper.

emit_while_end¶

def emit_while_end(self, circuit: CudaqKernelArtifact, context: dict[str, Any]) -> None

Close while block by decreasing indentation.

emit_while_start¶

def emit_while_start(
    self,
    circuit: CudaqKernelArtifact,
    clbit: int,
    value: int = 1,
) -> dict[str, Any]

Emit while __b{clbit}: and increase indentation.

emit_x¶

def emit_x(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-X gate.

emit_y¶

def emit_y(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-Y gate.

emit_z¶

def emit_z(self, circuit: CudaqKernelArtifact, qubit: int) -> None

Emit Pauli-Z gate.

finalize¶

def finalize(self, circuit: CudaqKernelArtifact, mode: ExecutionMode) -> CudaqKernelArtifact

Compile accumulated source into a @cudaq.kernel function.

For RUNNABLE mode, appends return [__b0, __b1, ...] to return per-shot logical clbit values. For STATIC mode, generates a void function with no explicit terminal measurement.

Parameters:

Returns:

CudaqKernelArtifact — The same artifact with kernel_func and source populated.

gate_controlled¶

def gate_controlled(self, gate: Any, num_controls: int) -> Any

No-op: not supported by CUDA-Q codegen path.

gate_power¶

def gate_power(self, gate: Any, power: int) -> Any

No-op: not supported by CUDA-Q codegen path.

supports_for_loop¶

def supports_for_loop(self) -> bool

Return False: for-loops are unrolled by the transpiler.

supports_if_else¶

def supports_if_else(self) -> bool

Return True only in RUNNABLE mode (measurement-dependent branching).

supports_while_loop¶

def supports_while_loop(self) -> bool

Return True only in RUNNABLE mode.

CudaqTranspiler [source]¶

class CudaqTranspiler(Transpiler[CudaqKernelArtifact])

CUDA-Q transpiler for qamomile.circuit module.

Converts Qamomile QKernels into CUDA-Q decorator-kernel artifacts.

Example:

from qamomile.cudaq import CudaqTranspiler
import qamomile.circuit as qm

@qm.qkernel
def bell_state(q0: qm.Qubit, q1: qm.Qubit) -> tuple[qm.Bit, qm.Bit]:
    q0 = qm.h(q0)
    q0, q1 = qm.cx(q0, q1)
    return qm.measure(q0), qm.measure(q1)

transpiler = CudaqTranspiler()
executable = transpiler.transpile(bell_state)

Methods¶

executor¶

def executor(self, target: str | None = None) -> CudaqExecutor

Create a CUDA-Q executor.

Parameters:

EmitError [source]¶

class EmitError(QamomileCompileError)

Error during backend code emission.

Constructor¶

def __init__(self, message: str, operation: str | None = None)

Attributes¶

• operation

EmitPass [source]¶

class EmitPass(Pass[SimplifiedProgram, ExecutableProgram[T]], Generic[T])

Base class for backend-specific emission passes.

Subclasses implement _emit_quantum_segment() to generate backend-specific quantum circuits.

Input: SimplifiedProgram (enforces C→Q→C pattern) Output: ExecutableProgram with compiled segments

Constructor¶

def __init__(
    self,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
)

Initialize with optional parameter bindings.

Parameters:

Attributes¶

• bindings

• name: str

• parameters

Methods¶

run¶

def run(self, input: SimplifiedProgram) -> ExecutableProgram[T]

Emit backend code from simplified program.

ExecutionMode [source]¶

class ExecutionMode(enum.Enum)

Execution mode for a CUDA-Q kernel artifact.

Determines which CUDA-Q runtime API is used for execution:

• STATIC: Compatible with cudaq.sample(), cudaq.get_state(), and cudaq.observe(). The kernel has no explicit terminal measurements and no return value.

• RUNNABLE: Compatible with cudaq.run(). The kernel has explicit mid-circuit measurements and returns mz(q) (list[bool]).

Attributes¶

• RUNNABLE

• STATIC

ForItemsOperation [source]¶

class ForItemsOperation(Operation)

Represents iteration over dict/iterable items.

Example:

for (i, j), Jij in qmc.items(ising):
    body

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    key_vars: list[str] = list(),
    value_var: str = '',
    key_is_vector: bool = False,
    operations: list[Operation] = list(),
) -> None

Attributes¶

• key_is_vector: bool

• key_vars: list[str]

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

• value_var: str

ForOperation [source]¶

class ForOperation(Operation)

Represents a for loop operation.

Example:

for i in range(start, stop, step):
    body

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    loop_var: str = '',
    operations: list[Operation] = list(),
) -> None

Attributes¶

• loop_var: str

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

GateOperation [source]¶

class GateOperation(Operation)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    gate_type: GateOperationType | None = None,
    theta: float | Value | None = None,
) -> None

Attributes¶

• gate_type: GateOperationType | None

• operation_kind: OperationKind

• signature: Signature

• theta: float | Value | None

GateOperationType [source]¶

class GateOperationType(enum.Enum)

Attributes¶

• CP

• CX

• CZ

• H

• P

• RX

• RY

• RZ

• RZZ

• S

• SDG

• SWAP

• T

• TDG

• TOFFOLI

• X

• Y

• Z

IfOperation [source]¶

class IfOperation(Operation)

Represents an if-else conditional operation.

Example:

if condition:
    true_body
else:
    false_body

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    true_operations: list[Operation] = list(),
    false_operations: list[Operation] = list(),
    phi_ops: list[PhiOp] = list(),
) -> None

Attributes¶

• condition: Value

• false_operations: list[Operation]

• operation_kind: OperationKind

• phi_ops: list[PhiOp]

• signature: Signature

• true_operations: list[Operation]

ReturnOperation [source]¶

class ReturnOperation(Operation)

Explicit return operation marking the end of a block with return values.

This operation represents an explicit return statement in the IR. It takes the values to be returned as operands and produces no results (it is a terminal operation that transfers control flow back to the caller).

operands: [Value, ...] - The values to return (may be empty for void returns) results: [] - Always empty (terminal operation)

Example:

A function that returns two values (a UInt and a Float):

ReturnOperation(
    operands=[uint_value, float_value],
    results=[],
)

The signature would be:
    operands=[ParamHint("return_0", UIntType()), ParamHint("return_1", FloatType())]
    results=[]

Constructor¶

def __init__(self, operands: list[Value] = list(), results: list[Value] = list()) -> None

Attributes¶

• operation_kind: OperationKind Return CLASSICAL as this is a control flow operation without quantum effects.

• signature: Signature Return the signature with operands for each return value and no results.

SeparatePass [source]¶

class SeparatePass(Pass[Block, SimplifiedProgram])

Separate a block into quantum and classical segments.

This pass:

1. Materializes return operations (syncs output_values from ReturnOperation)

2. Splits the operation list into quantum and classical segments

3. Validates single quantum segment (enforces C→Q→C pattern)

Input: Block (typically ANALYZED or AFFINE) Output: SimplifiedProgram with single quantum segment and optional prep/post

Attributes¶

• name: str

Methods¶

run¶

def run(self, input: Block) -> SimplifiedProgram

Separate the block into segments.

StandardEmitPass [source]¶

class StandardEmitPass(EmitPass[T], Generic[T])

Standard emit pass implementation using GateEmitter protocol.

This class provides the orchestration logic for circuit emission while delegating backend-specific operations to a GateEmitter.

Parameters:

Constructor¶

def __init__(
    self,
    gate_emitter: GateEmitter[T],
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
    composite_emitters: list[CompositeGateEmitter[T]] | None = None,
)

Transpiler [source]¶

class Transpiler(ABC, Generic[T])

Base class for backend-specific transpilers.

Provides the full compilation pipeline from QKernel to executable program.

Usage:

transpiler = QiskitTranspiler()

Option 1: Full pipeline¶

executable = transpiler.compile(kernel, bindings={“theta”: 0.5}) results = executable.run(transpiler.executor())

Option 2: Step-by-step¶

block = transpiler.to_block(kernel) substituted = transpiler.substitute(block) affine = transpiler.inline(substituted) validated = transpiler.affine_validate(affine) folded = transpiler.constant_fold(validated, bindings={“theta”: 0.5}) analyzed = transpiler.analyze(folded) separated = transpiler.separate(analyzed) executable = transpiler.emit(separated, bindings={“theta”: 0.5})

Option 3: Just get the circuit (no execution)¶

circuit = transpiler.to_circuit(kernel, bindings={“theta”: 0.5})

With configuration (strategy overrides)¶

config = TranspilerConfig.with_strategies({“qft”: “approximate”}) transpiler = QiskitTranspiler(config=config)

Attributes¶

• config: TranspilerConfig Get the transpiler configuration.

Methods¶

affine_validate¶

def affine_validate(self, block: Block) -> Block

Pass 1.5: Validate affine type semantics.

This is a safety net to catch affine type violations that may have bypassed frontend checks. Validates that quantum values are used at most once.

analyze¶

def analyze(self, block: Block) -> Block

Pass 2: Validate and analyze dependencies.

constant_fold¶

def constant_fold(self, block: Block, bindings: dict[str, Any] | None = None) -> Block

Pass 1.5: Fold constant expressions.

Evaluates BinOp operations when all operands are constants or bound parameters. This prevents quantum segment splitting from parametric expressions like phase * 2.

emit¶

def emit(
    self,
    separated: SimplifiedProgram,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> ExecutableProgram[T]

Pass 4: Generate backend-specific code.

Parameters:

executor¶

def executor(self, **kwargs: Any = {}) -> QuantumExecutor[T]

Create a quantum executor for this backend.

inline¶

def inline(self, block: Block) -> Block

Pass 1: Inline all CallBlockOperations.

lower_compile_time_ifs¶

def lower_compile_time_ifs(self, block: Block, bindings: dict[str, Any] | None = None) -> Block

Pass 1.75: Lower compile-time resolvable IfOperations.

Evaluates IfOperation conditions (including expression-derived conditions via CompOp/CondOp/NotOp) and replaces resolved ones with selected-branch operations. Phi outputs are substituted with selected-branch values throughout the block.

This prevents SeparatePass from seeing classical-only compile-time IfOperations that would otherwise split quantum segments.

separate¶

def separate(self, block: Block) -> SimplifiedProgram

Pass 3: Lower and split into quantum and classical segments.

Validates C→Q→C pattern with single quantum segment.

set_config¶

def set_config(self, config: TranspilerConfig) -> None

Set the transpiler configuration.

Parameters:

substitute¶

def substitute(self, block: Block) -> Block

Pass 0.5: Apply substitutions (optional).

This pass replaces CallBlockOperation targets and sets strategy names on CompositeGateOperations based on config.

Parameters:

Returns:

Block — Block with substitutions applied

to_block¶

def to_block(
    self,
    kernel: QKernel,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> Block

Convert a QKernel to a Block.

Parameters:

When bindings or parameters are provided, uses kernel.build() to properly resolve array shapes from the bound data. Otherwise uses the cached block_value for efficiency.

to_circuit¶

def to_circuit(self, kernel: QKernel, bindings: dict[str, Any] | None = None) -> T

Compile and extract just the quantum circuit.

This is a convenience method for when you just want the backend circuit without the full executable.

Parameters:

Returns:

T — Backend-specific quantum circuit

transpile¶

def transpile(
    self,
    kernel: QKernel,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> ExecutableProgram[T]

Full compilation pipeline from QKernel to executable.

Parameters:

Returns:

ExecutableProgram[T] — ExecutableProgram ready for execution

Raises:

• QamomileCompileError — If compilation fails (validation, dependency errors)

Pipeline:

1. to_block: Convert QKernel to Block

2. substitute: Apply substitutions (if configured)

3. inline: Inline CallBlockOperations

4. affine_validate: Validate affine type semantics

5. constant_fold: Fold constant expressions 5.5. lower_compile_time_ifs: Lower compile-time IfOperations 5.8. validate_while_contract: Validate while conditions are measurement-backed

6. analyze: Validate and analyze dependencies

7. separate: Split into quantum/classical segments

8. emit: Generate backend-specific code

validate_while_contract¶

def validate_while_contract(self, block: Block) -> Block

Pass 1.8: Validate WhileOperation conditions are measurement-backed.

Rejects while patterns whose condition is not a measurement result (Bit from qmc.measure()). This prevents late ValueError at emit time for unsupported while forms.

WhileOperation [source]¶

class WhileOperation(Operation)

Represents a while loop operation.

Only measurement-backed conditions are supported: the condition must be a Bit value produced by qmc.measure(). Non-measurement conditions (classical variables, constants, comparisons) are rejected by ValidateWhileContractPass before reaching backend emit.

Example::

bit = qmc.measure(q)
while bit:
    q = qmc.h(q)
    bit = qmc.measure(q)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    operations: list[Operation] = list(),
) -> None

Attributes¶

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature