qamomile.cudaq.materializer

Materialize circuit-family IR as CUDA-Q decorator kernels.

Overview¶

Classes¶

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 measurement_mode property controls measurement behaviour:

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

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

Parameters:

Constructor¶

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

Attributes¶

• measurement_mode: MeasurementMode Return the current measurement mode.

Methods¶

begin_source_block¶

def begin_source_block(self, header: str) -> int

Open an indented source block and return its initial line count.

Parameters:

Returns:

int — Line count used to detect an empty block at close time.

clbit_ref¶

def clbit_ref(self, index: int) -> str

Return the generated source reference for a classical bit slot.

Parameters:

Returns:

str — CUDA-Q source expression for the bit.

configure_runtime_clbits¶

def configure_runtime_clbits(self, num_clbits: int) -> None

Represent every runtime classical bit as a mutable one-item list.

Parameters:

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 the materializer can compose gate-angle expressions such as gamma * Jij without operating directly on raw strings.

Parameters:

Returns:

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

define_adjoint_helper¶

def define_adjoint_helper(self, helper_name: str, num_qubits: int) -> str

Define a reusable adjoint wrapper around another CUDA-Q kernel.

Parameters:

Returns:

str — Generated adjoint-wrapper name.

define_helper¶

def define_helper(
    self,
    key: Hashable,
    display_name: str,
    num_qubits: int,
    emit_body: Callable[[], None],
) -> str

Define one reusable CUDA-Q kernel without flattening its call site.

Parameters:

Returns:

str — Unique generated CUDA-Q kernel name.

Raises:

• ValueError — If recursive helper generation is detected.

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.

Mirrors the CH_DECOMPOSITION recipe from qamomile.circuit.transpiler.decompositions. Inlined here (rather than calling :func:emit_decomposition) so that the string-based codegen produces the exact source contract expected by the tracing test emitter, without double-recording primitive gate calls.

emit_cp¶

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

Emit controlled phase through CUDA-Q’s exact controlled R1.

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.

Mirrors the CY_DECOMPOSITION recipe from qamomile.circuit.transpiler.decompositions. See :meth:emit_ch for why this is inlined rather than delegating to :func:emit_decomposition.

emit_cz¶

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

Emit controlled-Z gate.

emit_exp_pauli¶

def emit_exp_pauli(
    self,
    circuit: CudaqKernelArtifact,
    qubit_indices: list[int],
    pauli_str: str,
    angle: float | Any,
) -> None

Emit a native exp_pauli Pauli evolution term.

Implements exp(i * angle * P) for a single Pauli term P, where pauli_str[k] acts on qubit_indices[k]. CUDA-Q applies the j-th character of the word to the j-th qubit in the passed list, so the word and qubit list share the same order and no reversal is needed (verified against the Qiskit PauliEvolutionGate reference for asymmetric multi-qubit terms such as X0 Z1).

Parameters:

emit_global_phase¶

def emit_global_phase(
    self,
    circuit: CudaqKernelArtifact,
    angle: float | Any,
    carrier: int | None = None,
) -> None

Synthesize exp(i * angle) I on an existing CUDA-Q qubit.

The exact identity is R1(2a) RZ(-2a) = exp(ia) I; it preserves an arbitrary state of the selected carrier qubit.

Parameters:

Raises:

• EmitError — If the artifact has no qubit or carrier is outside its physical width.

emit_global_phase_on_clean_carrier¶

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

Synthesize exp(i * angle) on a dedicated clean carrier.

Because the carrier is known to remain in |0>, the single gate RZ(-2a) produces exp(ia)|0> exactly. This specialized form is not valid for an arbitrary-state logical qubit.

Parameters:

Raises:

• EmitError — If carrier is outside the artifact’s physical width.

emit_h¶

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

Emit Hadamard gate.

emit_measure¶

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

Emit measurement, respecting the current mode.

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

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

emit_multi_controlled_p¶

def emit_multi_controlled_p(
    self,
    circuit: CudaqKernelArtifact,
    control_indices: list[int],
    target_idx: int,
    angle: float | Any,
) -> None

Emit a multi-controlled phase rotation.

Parameters:

emit_multi_controlled_rx¶

def emit_multi_controlled_rx(
    self,
    circuit: CudaqKernelArtifact,
    control_indices: list[int],
    target_idx: int,
    angle: float | Any,
) -> None

Emit a multi-controlled RX rotation.

Parameters:

emit_multi_controlled_ry¶

def emit_multi_controlled_ry(
    self,
    circuit: CudaqKernelArtifact,
    control_indices: list[int],
    target_idx: int,
    angle: float | Any,
) -> None

Emit a multi-controlled RY rotation.

Parameters:

emit_multi_controlled_rz¶

def emit_multi_controlled_rz(
    self,
    circuit: CudaqKernelArtifact,
    control_indices: list[int],
    target_idx: int,
    angle: float | Any,
) -> None

Emit a multi-controlled RZ rotation.

Parameters:

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_reset¶

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

Emit reset to the |0> state.

emit_reusable_call¶

def emit_reusable_call(
    self,
    helper_name: str,
    targets: tuple[int, ...],
    controls: tuple[int, ...] = (),
) -> None

Emit one direct or controlled named CUDA-Q kernel invocation.

Parameters:

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_source_line¶

def emit_source_line(self, line: str) -> None

Append one source line through the materializer-facing API.

Parameters:

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 one implementation.

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.

end_source_block¶

def end_source_block(self, initial_line_count: int) -> None

Close a source block, inserting pass when it is empty.

Parameters:

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.

qubit_ref¶

def qubit_ref(self, index: int) -> str

Return the generated source reference for a qubit slot.

Parameters:

Returns:

str — CUDA-Q source expression for the qubit.

set_parametric¶

def set_parametric(self, parametric: bool) -> None

Set whether the generated entrypoint accepts a parameter vector.

Parameters:

CudaqMaterializer [source]¶

class CudaqMaterializer

Convert verified circuit IR to a CUDA-Q source-built kernel.

Attributes¶

• capabilities: CircuitCapabilities Declare CUDA-Q’s circuit-IR capabilities.

Methods¶

materialize¶

def materialize(
    self,
    program: CircuitProgram,
    parameter_names: tuple[str, ...] = (),
) -> MaterializedCircuit[Any]

Build a CUDA-Q kernel and its execution metadata.

Parameters:

Returns:

MaterializedCircuit[Any] — MaterializedCircuit[Any]: CUDA-Q artifact, runtime parameters, and static measurement mapping.

Raises:

• EmitError — If CUDA-Q cannot represent an instruction.

EmitError [source]¶

class EmitError(QamomileCompileError)

Error during backend code emission.

Constructor¶

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

Initialize a backend emission diagnosis.

Parameters:

Attributes¶

• operation

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

GateKind [source]¶

class GateKind(Enum)

Classification of gates for emission.

Attributes¶

• CH

• CP

• CRX

• CRY

• CRZ

• CX

• CY

• CZ

• H

• MEASURE

• P

• RX

• RY

• RZ

• RZZ

• S

• SDG

• SWAP

• T

• TDG

• TOFFOLI

• X

• Y

• Z

MeasurementMode [source]¶

class MeasurementMode(Enum)

How a backend handles measurement operations.

Attributes¶

• NATIVE

• RUNNABLE

• STATIC