qamomile.quri_parts.transpiler

QURI Parts backend transpiler implementation.

This module provides QuriPartsTranspiler for converting Qamomile QKernels into QURI Parts quantum circuits.

Overview¶

Classes¶

EmitPass [source]¶

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

Base class for backend-specific emission passes.

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

Input: ProgramPlan 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: ProgramPlan) -> ExecutableProgram[T]

Emit backend code from a program plan.

QamomileQuriPartsTranspileError [source]¶

class QamomileQuriPartsTranspileError(QamomileCompileError)

Exception raised for errors in the Qamomile to QURI Parts conversion process.

QuriPartsEmitPass [source]¶

class QuriPartsEmitPass(StandardEmitPass['qp_c.LinearMappedUnboundParametricQuantumCircuit'])

QURI Parts-specific emission pass.

Uses StandardEmitPass with QuriPartsGateEmitter for gate emission. QURI Parts does not support native control flow, so all loops are unrolled.

Constructor¶

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

Initialize the QURI Parts emit pass.

Parameters:

QuriPartsExecutor [source]¶

class QuriPartsExecutor(QuantumExecutor['qp_c.LinearMappedUnboundParametricQuantumCircuit'])

QURI Parts quantum executor.

Supports both sampling and expectation value estimation. Uses Qulacs backend by default for efficient simulation.

Example:

executor = QuriPartsExecutor()  # Uses Qulacs by default
counts = executor.execute(circuit, shots=1000)
# counts: {"00": 512, "11": 512}

Constructor¶

def __init__(self, sampler: Any = None, estimator: Any = None)

Initialize executor with optional sampler and estimator.

Parameters:

Attributes¶

• non_parametric_estimator: Any Lazy initialization of non-parametric estimator.

• parametric_estimator: Any Lazy initialization of parametric estimator for optimization.

• sampler: Any Lazy initialization of sampler.

Methods¶

bind_parameters¶

def bind_parameters(
    self,
    circuit: 'qp_c.LinearMappedUnboundParametricQuantumCircuit',
    bindings: dict[str, Any],
    parameter_metadata: ParameterMetadata,
) -> 'ImmutableBoundParametricQuantumCircuit'

Bind parameter values to the QURI Parts circuit.

QURI Parts requires parameter values as a sequence in the order parameters were added to the circuit.

Parameters:

Returns:

'ImmutableBoundParametricQuantumCircuit' — Bound parametric circuit

Raises:

• QamomileQuriPartsTranspileError — If a required parameter binding is missing from bindings.

estimate¶

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

Estimate expectation value <psi|H|psi>.

Also accepts a native quri_parts.core.operator.Operator at runtime for convenience (auto-conversion is skipped in that case).

Parameters:

Returns:

float — Real part of the expectation value

estimate_expectation¶

def estimate_expectation(
    self,
    circuit: 'qp_c.LinearMappedUnboundParametricQuantumCircuit',
    hamiltonian: 'qp_o.Operator',
    param_values: Sequence[float],
) -> float

Estimate expectation value of hamiltonian for a circuit.

Handles both unbound parametric circuits (used during optimization) and already-bound or non-parametric circuits. When the circuit has already been bound (e.g., by _run_expval in ExecutableProgram), apply_circuit produces a GeneralCircuitQuantumState instead of a ParametricCircuitQuantumState, so we dispatch to the non-parametric estimator automatically.

Parameters:

Returns:

float — Real part of the expectation value

execute¶

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

Execute circuit and return bitstring counts.

Parameters:

Returns:

dict[str, int] — Dictionary mapping bitstrings to counts (e.g., {“00”: 512, “11”: 512})

QuriPartsGateEmitter [source]¶

class QuriPartsGateEmitter

GateEmitter implementation for QURI Parts.

Emits individual quantum gates to QURI Parts circuits.

QURI Parts parametric circuits accept angles in dictionary form: {parameter: coefficient, CONST: constant_offset}

Constructor¶

def __init__(self) -> None

Initialize the emitter.

Attributes¶

• measurement_mode: MeasurementMode QURI Parts always uses STATIC measurement (sampler handles it).

Methods¶

append_gate¶

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

Append a gate to the circuit.

Since circuit_to_gate returns None, this is only called with QURI Parts native gates which can be extended into the circuit.

circuit_to_gate¶

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

QURI Parts doesn’t support converting circuits to gates.

Returns None to signal that manual decomposition should be used.

combine_symbolic¶

def combine_symbolic(self, kind: BinOpKind, lhs: Any, rhs: Any) -> 'dict[Parameter, float]'

Combine two angle operands as a QURI Parts linear-combination dict.

QURI Parts’ Parameter is Rust-backed and exposes no Python arithmetic operators (param * float raises TypeError). The only supported representation for parametric angles is the linear-combination dict consumed by LinearMappedUnboundParametricQuantumCircuit.add_Parametric*, which fundamentally cannot express non-linear combinations (parameter × parameter, parameter ** n, etc.). This override produces such a dict for every linear case and raises a clear QamomileQuriPartsTranspileError for non-linear cases instead of letting the underlying TypeError bubble up.

Parameters:

Returns:

'dict[Parameter, float]' — A fresh dict[Parameter, float] representing the linear 'dict[Parameter, float]' — combination of the operands.

Raises:

• QamomileQuriPartsTranspileError — When the operation cannot be expressed as a linear combination (e.g. param * param, param / param, param ** n, param // n, division by zero in the symbolic path).

create_circuit¶

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

Create a new QURI Parts parametric circuit.

Note: QURI Parts does not support classical bits in circuits. The num_clbits parameter is accepted for interface compatibility but is not used.

create_parameter¶

def create_parameter(self, name: str) -> 'Parameter'

Create a QURI Parts parameter and register it with the circuit.

emit_barrier¶

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

No-op: QURI Parts doesn’t support barrier instructions.

emit_ch¶

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

Emit controlled-Hadamard gate using decomposition.

Follows the shared CH_DECOMPOSITION recipe from qamomile.circuit.transpiler.decompositions.

emit_cp¶

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

Emit controlled-Phase gate using decomposition.

Follows the shared CP_DECOMPOSITION recipe from qamomile.circuit.transpiler.decompositions. Inlined here because QURI Parts parametric angles use dict representation.

emit_crx¶

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

Emit controlled-RX gate using decomposition.

CRX(ctrl, tgt, θ) = RZ(tgt, π/2) CNOT(ctrl, tgt) RY(tgt, -θ/2) CNOT(ctrl, tgt) RY(tgt, θ/2) RZ(tgt, -π/2)

emit_cry¶

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

Emit controlled-RY gate using decomposition.

Follows the shared CRY_DECOMPOSITION recipe from qamomile.circuit.transpiler.decompositions. Inlined here because QURI Parts parametric angles use dict representation.

emit_crz¶

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

Emit controlled-RZ gate using decomposition.

Follows the shared CRZ_DECOMPOSITION recipe from qamomile.circuit.transpiler.decompositions. Inlined here because QURI Parts parametric angles use dict representation.

emit_cx¶

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

Emit CNOT (controlled-X) gate.

emit_cy¶

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

Emit controlled-Y gate using decomposition.

Follows the shared CY_DECOMPOSITION recipe from qamomile.circuit.transpiler.decompositions.

emit_cz¶

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

Emit controlled-Z gate.

emit_h¶

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

Emit Hadamard gate.

emit_measure¶

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

No-op: QURI Parts circuits don’t support measurement gates.

Measurement is handled separately by samplers/estimators.

emit_p¶

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

Emit Phase gate using U1.

P(θ) = U1(θ) = diag(1, e^{iθ}). For non-parametric angles we use the native U1 gate which is mathematically identical to the Phase gate. For parametric angles we fall back to ParametricRZ because QURI Parts does not provide a ParametricU1 gate. RZ differs only by a global phase: P(θ) = e^{iθ/2} · RZ(θ), which is physically irrelevant for single-qubit usage. Controlled-phase (CP) has its own decomposition and does not go through this path.

emit_rx¶

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

Emit RX rotation gate.

emit_ry¶

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

Emit RY rotation gate.

emit_rz¶

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

Emit RZ rotation gate.

emit_rzz¶

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

Emit RZZ gate using ParametricPauliRotation.

emit_s¶

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

Emit S (phase) gate.

emit_sdg¶

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

Emit S-dagger (inverse S) gate.

emit_swap¶

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

Emit SWAP gate.

emit_t¶

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

Emit T gate.

emit_tdg¶

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

Emit T-dagger (inverse T) gate.

emit_toffoli¶

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

Emit Toffoli (CCX) gate.

emit_x¶

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

Emit Pauli-X gate.

emit_y¶

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

Emit Pauli-Y gate.

emit_z¶

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

Emit Pauli-Z gate.

gate_controlled¶

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

Create controlled version of a gate.

Returns None since QURI Parts doesn’t support this natively.

gate_power¶

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

Create gate raised to a power.

Returns None since QURI Parts doesn’t support this natively.

supports_for_loop¶

def supports_for_loop(self) -> bool

QURI Parts does not support native for loops.

supports_if_else¶

def supports_if_else(self) -> bool

QURI Parts does not support native if/else.

supports_while_loop¶

def supports_while_loop(self) -> bool

QURI Parts does not support native while loops.

QuriPartsTranspiler [source]¶

class QuriPartsTranspiler(Transpiler['qp_c.LinearMappedUnboundParametricQuantumCircuit'])

QURI Parts transpiler for qamomile.circuit module.

Converts Qamomile QKernels into QURI Parts quantum circuits.

Example:

from qamomile.quri_parts import QuriPartsTranspiler
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 = QuriPartsTranspiler()
circuit = transpiler.to_circuit(bell_state)

Methods¶

executor¶

def executor(self, sampler: Any = None, estimator: Any = None) -> QuriPartsExecutor

Create a QURI Parts executor.

Parameters:

Returns:

QuriPartsExecutor — QuriPartsExecutor configured for this backend

SegmentationPass [source]¶

class SegmentationPass(Pass[Block, ProgramPlan])

Segment a block into a strategy-specific executable program plan.

This pass:

1. Materializes return operations (syncs output_values from ReturnOperation)

2. Splits the operation list into quantum and classical segments

3. Builds a ProgramPlan via the configured segmentation strategy

Input: Block (typically ANALYZED or AFFINE) Output: ProgramPlan

Constructor¶

def __init__(self, strategy: SegmentationStrategy | None = None) -> None

Attributes¶

• name: str

Methods¶

run¶

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

Segment the block into a ProgramPlan.

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.

Subclasses (QiskitEmitPass, CudaqEmitPass) override specific methods to provide native backend support. The thin wrappers here delegate to module functions in emit_support/ by default.

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) plan = transpiler.plan(analyzed) executable = transpiler.emit(plan, 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¶

• MAX_UNROLL_DEPTH: int

• 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.

classical_lowering¶

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

Pass 2.25: Lower measurement-derived classical ops.

Identifies CompOp / CondOp / NotOp / BinOp instances whose operand dataflow traces back to a measurement and rewrites them to RuntimeClassicalExpr. Compile-time-foldable and emit-time-foldable (loop-bound, parameter-bound) classical ops are left unchanged.

Runs after analyze so the measurement-taint analysis has the full dependency graph available, and before validate_symbolic_shapes / plan / emit so downstream passes can rely on the cleaner IR (in particular: future segmentation work can dispatch on RuntimeClassicalExpr type instead of the BitType-only heuristic).

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: ProgramPlan,
    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 SegmentationPass from seeing classical-only compile-time IfOperations that would otherwise split quantum segments.

partial_eval¶

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

Pass 1.75: Fold constants and lower compile-time control flow.

plan¶

def plan(self, block: Block) -> ProgramPlan

Pass 3: Lower and split into a program plan.

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

resolve_parameter_shapes¶

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

Pass 0.75: Resolve symbolic Vector parameter shape dims.

Qamomile circuits are compile-time fixed-structure. Parameter Vector[Float] / Vector[UInt] inputs carry symbolic {name}_dim{i} shape Values so frontend code like arr.shape[0] returns a usable handle. This pass looks at bindings and, for every parameter array that has a concrete binding, substitutes those symbolic dims with constants so that downstream loop-bound resolution sees fixed lengths.

Parameters without a concrete binding are left as-is; their symbolic dims are harmless as long as no compile-time structure decision depends on them (the library QAOA pattern).

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 hierarchical block 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:

• ValueError — If a name appears in both bindings and parameters. A name being in both is ambiguous (placeholder value vs runtime symbol) and used to silently miscompile control-flow predicates that depended on parameter-array elements; rejecting the overlap up front keeps the contract unambiguous.

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

Pipeline:

1. to_block: Convert QKernel to Block

2. substitute: Apply substitutions (if configured)

3. resolve_parameter_shapes: Constant-fold symbolic Vector param dims

4. inline: Inline CallBlockOperations

5. affine_validate: Validate affine type semantics

6. partial_eval: Fold constants and lower compile-time control flow

7. analyze: Validate and analyze dependencies

8. validate_symbolic_shapes: Reject unresolved parameter shape dims

9. plan: Build ProgramPlan (segment into C->Q->C steps)

10. emit: Generate backend-specific code

unroll_recursion¶

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

Fixed-point loop of inline ↔ partial_eval for self-recursive kernels.

Each iteration unrolls one layer of self-referential CallBlockOperation and then folds the base-case IfOperation via partial_eval. Terminates when no CallBlockOperation remains (success), when the call count stops decreasing (symbolic driver — self-calls are left in the IR and handled by downstream passes), or when MAX_UNROLL_DEPTH is reached (non-terminating recursion — raises).

validate_symbolic_shapes¶

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

Pass 2.5: Reject unresolved parameter shape dims in loop bounds.

Runs after analyze so dependency info is complete. Raises QamomileCompileError with an actionable message when a gamma_dim0-style symbolic Value reaches a ForOperation bound without being folded to a constant by ParameterShapeResolutionPass.