qamomile.qbraid

Overview¶

Classes¶

QBraidExecutor [source]¶

class QBraidExecutor(QuantumExecutor['QuantumCircuit'])

Quantum executor that runs Qiskit circuits on qBraid-supported devices.

This executor implements the QuantumExecutor[QuantumCircuit] contract, allowing ExecutableProgram.sample(), measured run(), and expectation-value run() to work with any qBraid-accessible backend.

The estimate() method uses a counts-based measurement approach. It only supports circuits with num_clbits == 0 (no pre-existing classical bits). Circuits with existing classical bits are rejected with an ExecutionError to prevent silent wrong results caused by qBraid’s counts normalization removing register separators.

Endian convention:

execute() returns canonical Qiskit-style bitstring keys after normalization. Keys are big-endian classical-bit strings: the leftmost character is the highest classical-bit index and the rightmost character is classical bit 0. QBraidExecutor never reverses or permutes the bit order; normalization only removes spaces and zero-pads under-width keys.

estimate() uses the same bitstring convention when reconstructing expectation values from counts. Since it applies measure_all() to a circuit with no pre-existing classical bits, classical bit i measures qubit i. Therefore, in estimate() the rightmost count character corresponds to qubit 0 and the leftmost character to the highest qubit index.

Parameters:

Raises:

• ValueError — If constructor arguments are inconsistent (e.g., device combined with device_id).

Example (device_id + api_key)::

executor = QBraidExecutor(
    device_id="qbraid_qir_simulator",
    api_key="your-api-key",
)

Example (pre-configured device)::

from qbraid import QbraidProvider
provider = QbraidProvider(api_key="...")
device = provider.get_device("qbraid_qir_simulator")
executor = QBraidExecutor(device=device)

Constructor¶

def __init__(
    self,
    device: Any | None = None,
    *,
    device_id: str | None = None,
    provider: Any | None = None,
    api_key: str | None = None,
    expval_shots: int = 4096,
    timeout: int | None = None,
    poll_interval: int = 5,
    run_kwargs: dict[str, Any] | None = None,
)

Attributes¶

• device

• expval_shots

• poll_interval

• run_kwargs

• timeout

Methods¶

bind_parameters¶

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

Bind parameter values to the Qiskit circuit.

Uses the same indexed-binding semantics as QiskitExecutor.

Parameters:

Returns:

'QuantumCircuit' — New circuit with parameters bound.

estimate¶

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

Estimate the expectation value of a Hamiltonian using counts.

This method decomposes the Hamiltonian into Pauli terms, groups them by measurement basis, applies basis-rotation gates, and reconstructs the expectation value from measurement counts.

Only circuits with num_clbits == 0 are supported. Circuits with pre-existing classical bits are rejected because qBraid’s counts normalization removes register separators, making it impossible to reliably identify which measured bits correspond to which qubits.

Count bitstrings are interpreted using the same big-endian convention as Qiskit counts: the leftmost character is the highest measured qubit index and the rightmost character is qubit 0. This follows directly from calling measure_all() on a circuit whose classical-bit indices match its qubit indices.

Parameters:

Returns:

float — The estimated real-valued expectation value.

Raises:

• ExecutionError — If the circuit has existing classical bits, if the Hamiltonian references qubit indices outside the circuit width, if the circuit has unbound parameters after binding, or if the result has a non-negligible imaginary part.

execute¶

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

Execute circuit and return bitstring counts.

If the circuit has no classical bits, measure_all() is added automatically (on a copy).

Returned keys use canonical Qiskit-style big-endian classical-bit order: the leftmost character is the highest classical-bit index and the rightmost character is classical bit 0. execute() does not reinterpret those keys as qubit-ordered strings.

Parameters:

Returns:

dict[str, int] — Dictionary mapping canonical big-endian classical-bit strings dict[str, int] — to counts.

qamomile.qbraid.executor¶

qBraid backend executor for Qamomile.

This module provides QBraidExecutor, which bridges Qamomile’s compiled Qiskit circuits to qBraid-supported quantum devices via the qBraid runtime.

Example:

from qamomile.qbraid import QBraidExecutor

executor = QBraidExecutor(device_id="qbraid_qir_simulator")
counts = executor.execute(circuit, shots=1000)

Overview¶

Classes¶

ExecutionError [source]¶

class ExecutionError(QamomileCompileError)

Error during program execution.

QBraidExecutor [source]¶

class QBraidExecutor(QuantumExecutor['QuantumCircuit'])

Quantum executor that runs Qiskit circuits on qBraid-supported devices.

This executor implements the QuantumExecutor[QuantumCircuit] contract, allowing ExecutableProgram.sample(), measured run(), and expectation-value run() to work with any qBraid-accessible backend.

The estimate() method uses a counts-based measurement approach. It only supports circuits with num_clbits == 0 (no pre-existing classical bits). Circuits with existing classical bits are rejected with an ExecutionError to prevent silent wrong results caused by qBraid’s counts normalization removing register separators.

Endian convention:

execute() returns canonical Qiskit-style bitstring keys after normalization. Keys are big-endian classical-bit strings: the leftmost character is the highest classical-bit index and the rightmost character is classical bit 0. QBraidExecutor never reverses or permutes the bit order; normalization only removes spaces and zero-pads under-width keys.

estimate() uses the same bitstring convention when reconstructing expectation values from counts. Since it applies measure_all() to a circuit with no pre-existing classical bits, classical bit i measures qubit i. Therefore, in estimate() the rightmost count character corresponds to qubit 0 and the leftmost character to the highest qubit index.

Parameters:

Raises:

• ValueError — If constructor arguments are inconsistent (e.g., device combined with device_id).

Example (device_id + api_key)::

executor = QBraidExecutor(
    device_id="qbraid_qir_simulator",
    api_key="your-api-key",
)

Example (pre-configured device)::

from qbraid import QbraidProvider
provider = QbraidProvider(api_key="...")
device = provider.get_device("qbraid_qir_simulator")
executor = QBraidExecutor(device=device)

Constructor¶

def __init__(
    self,
    device: Any | None = None,
    *,
    device_id: str | None = None,
    provider: Any | None = None,
    api_key: str | None = None,
    expval_shots: int = 4096,
    timeout: int | None = None,
    poll_interval: int = 5,
    run_kwargs: dict[str, Any] | None = None,
)

Attributes¶

• device

• expval_shots

• poll_interval

• run_kwargs

• timeout

Methods¶

bind_parameters¶

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

Bind parameter values to the Qiskit circuit.

Uses the same indexed-binding semantics as QiskitExecutor.

Parameters:

Returns:

'QuantumCircuit' — New circuit with parameters bound.

estimate¶

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

Estimate the expectation value of a Hamiltonian using counts.

This method decomposes the Hamiltonian into Pauli terms, groups them by measurement basis, applies basis-rotation gates, and reconstructs the expectation value from measurement counts.

Only circuits with num_clbits == 0 are supported. Circuits with pre-existing classical bits are rejected because qBraid’s counts normalization removes register separators, making it impossible to reliably identify which measured bits correspond to which qubits.

Count bitstrings are interpreted using the same big-endian convention as Qiskit counts: the leftmost character is the highest measured qubit index and the rightmost character is qubit 0. This follows directly from calling measure_all() on a circuit whose classical-bit indices match its qubit indices.

Parameters:

Returns:

float — The estimated real-valued expectation value.

Raises:

• ExecutionError — If the circuit has existing classical bits, if the Hamiltonian references qubit indices outside the circuit width, if the circuit has unbound parameters after binding, or if the result has a non-negligible imaginary part.

execute¶

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

Execute circuit and return bitstring counts.

If the circuit has no classical bits, measure_all() is added automatically (on a copy).

Returned keys use canonical Qiskit-style big-endian classical-bit order: the leftmost character is the highest classical-bit index and the rightmost character is classical bit 0. execute() does not reinterpret those keys as qubit-ordered strings.

Parameters:

Returns:

dict[str, int] — Dictionary mapping canonical big-endian classical-bit strings dict[str, int] — to counts.