qamomile.qiskit

Qiskit engine for Qamomile.

Design intent: this package concretizes circuit’s abstract IR for Qiskit through QiskitMaterializer. QiskitTranspiler plugs the materializer into the shared compiler pipeline, while observable.py converts Hamiltonians to SparsePauliOp.

QiskitExecutor uses a local simulator by default and adapts IBM Runtime V2 primitives for named or preconfigured IBM backends, including account access checks, ISA compilation, and remote job lifecycles.

Constraints: depend only on qamomile.circuit public APIs plus the qiskit SDK — never on qamomile.optimization or other engines. Engine-specific lowering (decompositions, runtime control flow) belongs here at emit time, not in the IR; reuse circuit’s shared decomposition recipes as the fallback for gates without a native Qiskit equivalent.

Overview¶

Functions¶

hamiltonian_to_sparse_pauli_op [source]¶

def hamiltonian_to_sparse_pauli_op(hamiltonian: qm_o.Hamiltonian) -> 'SparsePauliOp'

Convert qamomile.observable.Hamiltonian to Qiskit SparsePauliOp.

Parameters:

Returns:

'SparsePauliOp' — Qiskit SparsePauliOp representation

Example:

import qamomile.observable as qm_o
from qamomile.qiskit.observable import hamiltonian_to_sparse_pauli_op

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

# Convert to Qiskit
sparse_pauli_op = hamiltonian_to_sparse_pauli_op(H)

Classes¶

QiskitExecutionOptions [source]¶

class QiskitExecutionOptions

Configure Runtime primitives without constructing Qiskit option objects.

Per-request sampling shots and estimation precision remain arguments to the executable. Advanced mappings use Runtime’s option names; the SDK validates their supported fields when the executor is constructed.

Parameters:

Raises:

• TypeError — If advanced options are not mappings with string keys.

• ValueError — If a numeric setting is invalid or an advanced mapping contains a field exposed directly by this class.

Example:

>>> options = QiskitExecutionOptions(
...     max_execution_time=300,
...     resilience_level=1,
...     sampler_options={"dynamical_decoupling": {"enable": True}},
... )

Constructor¶

def __init__(
    self,
    max_execution_time: int | None = None,
    resilience_level: int | None = None,
    sampler_options: Mapping[str, Any] = dict(),
    estimator_options: Mapping[str, Any] = dict(),
) -> None

Attributes¶

• estimator_options: Mapping[str, Any]

• max_execution_time: int | None

• resilience_level: int | None

• sampler_options: Mapping[str, Any]

Methods¶

estimator_kwargs¶

def estimator_kwargs(self) -> dict[str, Any]

Build an independent Runtime estimator options dictionary.

Returns:

dict[str, Any] — dict[str, Any]: Estimator settings with execution and mitigation settings when supplied.

sampler_kwargs¶

def sampler_kwargs(self) -> dict[str, Any]

Build an independent Runtime sampler options dictionary.

Returns:

dict[str, Any] — dict[str, Any]: Sampler settings with the shared execution limit.

QiskitExecutor [source]¶

class QiskitExecutor(QuantumExecutor['QuantumCircuit'])

Execute Qiskit circuits locally or on a selected IBM Quantum backend.

With no backend, use AerSimulator or BasicSimulator. Named backends are resolved through QiskitRuntimeService using the supplied credentials or the SDK’s saved account. IBMBackend objects select Runtime automatically. Credentials are passed to the SDK without saving an account to disk.

Parameters:

Raises:

• TypeError — If options is not a QiskitExecutionOptions instance.

• ValueError — If credentials are incomplete, arguments conflict, or Runtime options are supplied for local execution.

• ImportError — If IBM execution is requested without its SDK extra.

• QiskitBackendNotFoundError — If the named backend cannot be found for the selected account and instance.

• Exception — If SDK authentication, lookup, or setup fails.

Example:

executor = QiskitExecutor()  # Uses AerSimulator when available
counts = executor.execute(circuit, shots=1000)
executor = QiskitExecutor(
    backend="your_backend_name",
    api_key=api_key,
    instance_crn=instance_crn,
)
job = executable.sample(executor, shots=1024)

Constructor¶

def __init__(
    self,
    backend: Any = None,
    estimator: Any = None,
    *,
    api_key: str | None = None,
    instance_crn: str | None = None,
    mode: Any = None,
    options: QiskitExecutionOptions | None = None,
    sampler_options: Any = None,
    estimator_options: Any = None,
    pass_manager: Any = None,
    service: Any = None,
) -> None

Select local execution or authenticate a named IBM backend.

Parameters:

Raises:

• TypeError — If options is not a QiskitExecutionOptions instance.

• ValueError — If credentials are incomplete, arguments conflict, or Runtime options are supplied for local execution.

• ImportError — If IBM execution is requested without its SDK extra.

• QiskitBackendNotFoundError — If the named backend cannot be found for the selected account and instance.

• Exception — If SDK authentication, lookup, or setup fails.

Attributes¶

• backend

• capabilities: ExecutionCapabilities Describe execution features of the selected local or IBM backend.

Methods¶

bind_parameters¶

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

Bind parameter values to the Qiskit circuit.

Parameters:

Returns:

'QuantumCircuit' — New circuit with parameters bound.

Raises:

• ValueError — If required Runtime values are missing.

• Exception — If Qiskit rejects a parameter assignment.

estimate¶

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

Estimate the expectation value of a Hamiltonian.

Parameters:

Returns:

float — Estimated expectation value.

Raises:

• Exception — If estimator setup, compilation, or execution fails.

execute¶

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

Execute circuit and return bitstring counts.

Parameters:

Returns:

dict[str, int] — dict[str, int]: Native dictionary mapping bitstrings to counts, without SDK-specific result metadata. A circuit without quantum or classical bits returns {"": shots}.

Raises:

• RuntimeError — If no Qiskit backend is available for execution, or if Aer would still receive an empty-parameter multiplexer after the workaround decomposition.

• Exception — If IBM compilation, submission, or execution fails.

restore¶

def restore(self, reference: ExecutionReference) -> ExecutionHandle[Any]

Reconnect to an IBM job using the selected backend’s service.

Parameters:

Returns:

ExecutionHandle[Any] — ExecutionHandle[Any]: Restored IBM sample or expectation handle.

Raises:

• NotImplementedError — If the selected backend has no restoration.

• ValueError — If the reference targets another provider or backend.

• Exception — If the SDK cannot retrieve the job.

submit_estimate¶

def submit_estimate(self, request: EstimateRequest[QuantumCircuit]) -> ExecutionHandle[float]

Submit an expectation through the selected execution adapter.

Parameters:

Returns:

ExecutionHandle[float] — ExecutionHandle[float]: Immediate local result or lazy IBM job.

Raises:

• NotImplementedError — If the selected adapter rejects the accuracy.

• Exception — If validation, compilation, or submission fails.

submit_sample¶

def submit_sample(
    self,
    request: SampleRequest[QuantumCircuit],
) -> ExecutionHandle[dict[str, int]]

Submit samples through the selected execution adapter.

Parameters:

Returns:

ExecutionHandle[dict[str, int]] — ExecutionHandle[dict[str, int]]: Immediate local result or lazy IBM job handle.

Raises:

• Exception — If request validation, compilation, or submission fails.

QiskitTranspiler [source]¶

class QiskitTranspiler(Transpiler['QuantumCircuit'])

Qiskit engine transpiler.

Converts Qamomile QKernels into Qiskit QuantumCircuits.

Parameters:

Example:

from qamomile.qiskit import QiskitTranspiler
import qamomile 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 = QiskitTranspiler()
circuit = transpiler.to_circuit(bell_state)
print(circuit.draw())

Constructor¶

def __init__(
    self,
    use_native_composite: bool = True,
    use_native_pauli_evolution: bool = True,
) -> None

Initialize the Qiskit transpiler.

Parameters:

Methods¶

executor¶

def executor(
    self,
    backend: Any = None,
    *,
    estimator: Any = None,
    api_key: str | None = None,
    instance_crn: str | None = None,
    mode: Any = None,
    options: QiskitExecutionOptions | None = None,
    sampler_options: Any = None,
    estimator_options: Any = None,
    pass_manager: Any = None,
    service: Any = None,
) -> QiskitExecutor

Create a local or IBM Quantum executor with the same execution API.

Parameters:

Returns:

QiskitExecutor — Executor configured for the selected execution target.

Raises:

• TypeError — If options is not a QiskitExecutionOptions instance.

• ValueError — If credentials are incomplete or arguments conflict.

• ImportError — If IBM execution is requested without its SDK extra.

• QiskitBackendNotFoundError — If the selected account and instance have no matching backend.

• Exception — If SDK authentication or executor setup fails.

Example:

executor = transpiler.executor(
    backend="your_backend_name",
    api_key=api_key,
    instance_crn=instance_crn,
)
job = executable.sample(executor, shots=1024)

Submodules¶

• qamomile.qiskit.emitter

• qamomile.qiskit.execution

• qamomile.qiskit.materializer

• qamomile.qiskit.observable

• qamomile.qiskit.runtime

• qamomile.qiskit.runtime_execution

• qamomile.qiskit.transpiler