qamomile.qiskit.runtime_execution

Adapt Qiskit Runtime primitive jobs to Qamomile execution handles.

Overview¶

Classes¶

ExecutionError [source]¶

class ExecutionError(QamomileCompileError)

Error during program execution.

ExecutionHandle [source]¶

class ExecutionHandle(ABC, Generic[ResultT])

Expose an engine execution without forcing immediate result retrieval.

Attributes¶

• native: object | None Return the wrapped provider-native task when available.

Methods¶

cancel¶

def cancel(self) -> None

Request best-effort cancellation.

Cancellation is intentionally not reported as a boolean because providers may accept a request after execution has already started. Call :meth:status to observe the eventual state.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return optional provider execution metadata.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Provider metadata such as timestamps or usage.

raw_status¶

def raw_status(self) -> object

Return provider-specific status information.

Returns:

object — Provider status value, or the normalized status when no richer value exists.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return serializable remote execution references.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Secret-free provider references.

result¶

def result(self, timeout: float | None = None) -> ResultT

Wait for and return the engine-neutral raw result.

Parameters:

Returns:

ResultT — Raw result normalized by the engine executor.

Raises:

• TimeoutError — If the local wait expires before completion.

result_async¶

def result_async(self, timeout: float | None = None) -> ResultT

Wait asynchronously for the engine-neutral raw result.

Parameters:

Returns:

ResultT — Raw result normalized by the engine executor.

Raises:

• TimeoutError — If the local wait expires before completion.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture one remote execution without fetching its result.

Adapters exposing several logical references must override this method with an explicit reconstruction structure. A provider reference may itself contain multiple physical job IDs.

Returns:

ExecutionSnapshot — One opaque provider execution.

Raises:

• ValueError — If references are absent or their grouping is unknown.

status¶

def status(self) -> JobStatus

Return the current provider-independent execution status.

Returns:

JobStatus — Current normalized status.

ExecutionReference [source]¶

class ExecutionReference

Store secret-free identifiers needed to restore remote execution.

Parameters:

Raises:

• ValueError — If the provider name or any job identifier is empty.

• TypeError — If identifiers or context have incompatible types.

Constructor¶

def __init__(
    self,
    provider: str,
    job_ids: tuple[str, ...],
    target: str | None = None,
    group_id: str | None = None,
    context: Mapping[str, str] = dict(),
) -> None

Attributes¶

• context: Mapping[str, str]

• group_id: str | None

• job_ids: tuple[str, ...]

• provider: str

• target: str | None

Methods¶

from_dict¶

@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> ExecutionReference

Reconstruct a provider reference from JSON-compatible data.

Parameters:

Returns:

ExecutionReference — Validated provider execution reference.

Raises:

• KeyError — If a required provider or job identifier field is absent.

• TypeError — If a field has an incompatible type.

• ValueError — If provider or job identifiers are empty.

to_dict¶

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

Convert the provider reference to JSON-compatible data.

Returns:

dict[str, Any] — dict[str, Any]: Provider identifiers and decoding context without credentials or SDK objects.

ExecutionSnapshot [source]¶

class ExecutionSnapshot

Store a remote leaf, a local value, or an ordered execution group.

Provider leaves may identify several physical jobs or produce native batch results. Composite children retain their result boundaries independently of the number of provider identifiers. Local values contain raw engine-neutral results, before the executable applies its public result conversion. Trees and local values support at most 100 levels of nesting.

Parameters:

Raises:

• TypeError — If fields or local result types are unsupported.

• ValueError — If fields conflict with the node kind or values are invalid.

Constructor¶

def __init__(
    self,
    kind: str | ExecutionSnapshotKind,
    reference: ExecutionReference | None = None,
    value: Any = None,
    children: tuple[ExecutionSnapshot, ...] = (),
) -> None

Attributes¶

• children: tuple[ExecutionSnapshot, ...]

• kind: str | ExecutionSnapshotKind

• reference: ExecutionReference | None

• value: Any

Methods¶

from_dict¶

@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> ExecutionSnapshot

Reconstruct an execution tree with strict node and value validation.

Parameters:

Returns:

ExecutionSnapshot — Validated execution structure.

Raises:

• TypeError — If node fields have incompatible types.

• ValueError — If kinds, fields, references, or local values are invalid.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Collect provider leaves in order without discarding tree structure.

This list supports diagnostics; restoration uses the complete tree.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Detached remote references in order.

Raises:

• TypeError — If mutable reference fields became incompatible.

• ValueError — If mutable reference fields became invalid.

restore¶

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

Reattach remote leaves and rebuild local values and ordered groups.

The callback must reattach an existing provider execution. This method neither retrieves remote results nor submits any execution.

Parameters:

Returns:

ExecutionHandle[Any] — ExecutionHandle[Any]: Reconstructed raw execution lifecycle.

Raises:

• TypeError — If local data is unsupported or the callback returns an incompatible handle.

• ValueError — If local values or references became invalid.

• Exception — If the provider restoration callback fails.

to_dict¶

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

Serialize the execution tree and type-preserving local values.

Returns:

dict[str, Any] — dict[str, Any]: JSON-compatible execution tree.

Raises:

• TypeError — If mutable local data was changed to unsupported types.

• ValueError — If mutable local data or references became invalid.

ExecutionSnapshotKind [source]¶

class ExecutionSnapshotKind(StrEnum)

Identify the reconstruction contract of an execution snapshot node.

Attributes¶

• COMPOSITE

• LOCAL

• REMOTE

JobStatus [source]¶

class JobStatus(Enum)

Describe a provider-independent execution state.

The numeric values of the original four states remain stable for serialization compatibility.

Attributes¶

• CANCELLED

• CANCELLING

• COMPLETED

• FAILED

• PARTIAL

• PENDING

• QUEUED

• RUNNING

• UNKNOWN

RuntimeExecutionHandle [source]¶

class RuntimeExecutionHandle(ExecutionHandle[ResultT], Generic[ResultT])

Expose one Runtime primitive job without blocking its submission.

Result retrieval runs once in a daemon thread so local wait limits also work with injected Qiskit primitive jobs whose result() method has no timeout argument. Expiring a wait neither cancels nor resubmits the job.

Parameters:

Constructor¶

def __init__(
    self,
    job: Any,
    decoder: Callable[[Any], ResultT],
    reference: ExecutionReference | None = None,
) -> None

Initialize lazy retrieval and provider lifecycle delegation.

Parameters:

Attributes¶

• native: object Return the wrapped primitive job.

Methods¶

cancel¶

def cancel(self) -> None

Request cancellation when the primitive job is unfinished.

Raises:

• ExecutionError — If the status query or cancellation request fails.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return native Runtime job metrics when supported.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Provider metrics or an empty mapping when the local job does not expose metrics.

Raises:

• ExecutionError — If native metric retrieval fails.

raw_status¶

def raw_status(self) -> object

Read the native string or Qiskit status enum.

Returns:

object — Unmodified provider status.

Raises:

• ExecutionError — If the native status query fails.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return the job’s secret-free restoration reference when available.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: One remote reference or an empty tuple when no restoration service was configured.

result¶

def result(self, timeout: float | None = None) -> ResultT

Wait for the decoded primitive result with a local wait limit.

Successful results and execution failures are cached. A provider-side result-wait timeout permits another retrieval attempt, while an expired local wait leaves the existing retrieval running.

Parameters:

Returns:

ResultT — Cached or newly decoded primitive result.

Raises:

• ValueError — If the timeout is negative, boolean, or non-finite.

• TimeoutError — If the local or provider result wait expires.

• ExecutionError — If execution or result decoding fails.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture a Runtime reference or an already decoded result.

Restorable jobs retain their provider reference after result retrieval. Without a reference, result retrieval must have completed successfully before capturing its cached value. This method never starts retrieval, queries the provider, or waits for another result caller.

Returns:

ExecutionSnapshot — One remote reference or a detached local value.

Raises:

• TypeError — If a cached result contains unsupported objects.

• ValueError — If no reference or successful cached result exists, or the cached value is nonfinite, cyclic, or nested too deeply.

status¶

def status(self) -> JobStatus

Return the normalized provider or cached result status.

Returns:

JobStatus — Current provider-independent execution state.

Raises:

• ExecutionError — If the native job status cannot be retrieved.