qamomile.braket

Amazon Braket engine for Qamomile.

Design intent: this package concretizes the engine-neutral circuit IR as native Amazon Braket Circuit objects. The transpiler and executor depend only on Qamomile’s public circuit and observable APIs plus the optional amazon-braket-sdk dependency; the compiler core never depends on Braket.

Static terminal measurements are retained as Qamomile mapping metadata and performed by the executor. Engine-specific gate control, inversion, global phase, parameter binding, and Pauli-evolution lowering stay at this emit boundary rather than leaking into the shared IR.

Overview¶

Functions¶

hamiltonian_to_braket_observable [source]¶

def hamiltonian_to_braket_observable(hamiltonian: qm_o.Hamiltonian) -> 'Observable'

Convert a Qamomile Hamiltonian to a Braket observable.

A scalar-only Hamiltonian is represented on qubit zero because Braket observables always address at least one qubit. The executor evaluates such Hamiltonians locally and does not add that synthetic qubit to a task.

Parameters:

Returns:

'Observable' — Native Braket observable, including all coefficients.

Raises:

• ValueError — If a coefficient has a non-negligible imaginary part.

Classes¶

BraketExecutionOptions [source]¶

class BraketExecutionOptions

Configure Braket task and batch submission without flat kwargs.

Parameters:

Raises:

• ValueError — If options contain executor-owned argument names or an invalid numeric value.

Constructor¶

def __init__(
    self,
    s3_destination_folder: tuple[str, str] | None = None,
    reservation_arn: str | None = None,
    max_parallel: int | None = None,
    poll_timeout_seconds: float | None = None,
    poll_interval_seconds: float | None = None,
    batch_max_retries: int = 0,
    task_options: Mapping[str, Any] = dict(),
    batch_options: Mapping[str, Any] = dict(),
) -> None

Attributes¶

• batch_max_retries: int

• batch_options: Mapping[str, Any]

• max_parallel: int | None

• poll_interval_seconds: float | None

• poll_timeout_seconds: float | None

• reservation_arn: str | None

• s3_destination_folder: tuple[str, str] | None

• task_options: Mapping[str, Any]

Methods¶

batch_kwargs¶

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

Build keyword arguments for a Braket task batch.

Returns:

dict[str, Any] — dict[str, Any]: Validated device.run_batch keyword arguments.

task_kwargs¶

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

Build keyword arguments for one Braket task.

Returns:

dict[str, Any] — dict[str, Any]: Validated device.run keyword arguments.

BraketExecutor [source]¶

class BraketExecutor(QuantumExecutor['Circuit'])

Submit Braket circuits to a local simulator or injected AWS device.

The default device is created lazily, so importing qamomile.braket remains safe when the optional SDK dependency is absent.

Parameters:

Constructor¶

def __init__(
    self,
    device: Any = None,
    *,
    estimation_shots: int = 0,
    options: BraketExecutionOptions | None = None,
    run_kwargs: Mapping[str, Any] | None = None,
) -> None

Initialize the Braket executor.

Parameters:

Raises:

• ValueError — If estimation_shots is negative or both option forms are supplied.

Attributes¶

• capabilities: ExecutionCapabilities Describe lifecycle and estimation features for the target device.

• device: Any Return the configured device, creating a local simulator lazily.

Methods¶

bind_parameters¶

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

Bind Qamomile runtime parameters into a Braket circuit.

Parameters:

Returns:

'Circuit' — New circuit with all required parameters bound.

Raises:

• ValueError — If a required binding is absent.

estimate¶

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

Estimate a Qamomile Hamiltonian expectation value.

Exact estimation submits one Braket task containing one result type per Pauli term. Shot-based estimation submits one task per term so non-commuting terms remain valid on devices with sampled result types.

Parameters:

Returns:

float — Real expectation value including the constant term.

Raises:

• ValueError — If params do not match Braket’s parameter order or if the result has a non-negligible imaginary component.

• RuntimeError — If a Braket task omits an expectation result.

execute¶

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

Sample a Braket circuit and return Qamomile-ordered counts.

Parameters:

Returns:

dict[str, int] — dict[str, int]: Counts with the highest qubit index on the left. A zero-qubit circuit returns {"": shots}.

Raises:

• RuntimeError — If the Braket result omits measurement counts.

restore¶

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

Restore AWS quantum tasks from their serializable references.

Parameters:

Returns:

ExecutionHandle[Any] — ExecutionHandle[Any]: Restored sampling or expectation handle.

Raises:

• ValueError — If the reference provider or decoding context is invalid.

• TypeError — If the configured device has no AWS session.

submit_estimate¶

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

Submit Braket expectation tasks without retrieving their results.

Parameters:

Returns:

ExecutionHandle[float] — ExecutionHandle[float]: Lazy exact or shot-based result handle.

Raises:

• ValueError — If the Hamiltonian is non-Hermitian, target precision is unsupported, or exact execution targets a QPU.

submit_sample¶

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

Submit a native Braket sampling task without waiting for results.

Parameters:

Returns:

ExecutionHandle[dict[str, int]] — ExecutionHandle[dict[str, int]]: Lazy Braket execution handle.

BraketTranspiler [source]¶

class BraketTranspiler(Transpiler['Circuit'])

Transpile Qamomile quantum kernels to Amazon Braket circuits.

Methods¶

executor¶

def executor(
    self,
    device: Any = None,
    *,
    estimation_shots: int = 0,
    options: BraketExecutionOptions | None = None,
    run_kwargs: Mapping[str, Any] | None = None,
) -> BraketExecutor

Create a Braket executor.

Parameters:

Returns:

BraketExecutor — Configured task-backed executor.

Raises:

• ValueError — If executor options are invalid.

Submodules¶

• qamomile.braket.execution

• qamomile.braket.materializer

• qamomile.braket.observable

• qamomile.braket.transpiler