qamomile.hugr.executable

Expose typed jobs for direct HUGR program graphs.

Overview¶

Functions¶

resolve_runtime_bindings [source]¶

def resolve_runtime_bindings(
    compiled: CompiledProgram[Any],
    bindings: Mapping[str, Any] | None = None,
) -> dict[str, Any]

Restore public argument values from whole or indexed runtime bindings.

Whole and indexed forms may be used for different arguments. Specifying a container alongside any of its indexed descendants is ambiguous and rejected. Fixed dictionary entries follow the public ABI order; dictionaries whose keys remain runtime values require an explicit whole mapping.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: Independently owned whole arguments in native port order, dict[str, Any] — containing canonical bool, int, and finite float values. dict[str, Any] — Input mappings and their containers are never mutated.

Raises:

• TypeError — If binding names or values have incompatible types.

• ValueError — If names conflict, are missing or unexpected, or values violate the fixed shape or scalar domain of the ABI.

• EmitError — If a public input has no supported native HUGR carrier.

• ImportError — If optional HUGR dependencies are unavailable.

Classes¶

HugrExecutable [source]¶

class HugrExecutable

Execute a HUGR artifact through a destination-independent typed API.

HugrTranspiler.transpile also prepares shot-based expectation programs. Existing CompiledProgram[Package] values can be wrapped directly.

Parameters:

Constructor¶

def __init__(self, compiled: CompiledProgram[Any]) -> None

Own a compiled artifact and its public ABI.

Parameters:

Attributes¶

• abi: ProgramABI Return a defensive copy of the public input and output contract.

• artifact: Any Return the native package retained by the executable.

• has_parameters: bool Report whether execution requires runtime arguments.

• metadata: CompilationMetadata Return target compilation provenance.

• parameter_names: list[str] Return runtime argument names in native input-port order.

Methods¶

restore¶

def restore(
    self,
    executor: HugrExecutor,
    snapshot: JobSnapshot,
    bindings: Mapping[str, Any] | None = None,
) -> Job[Any]

Restore a typed local or remote job using the same compiled program.

Parameters:

Returns:

Job[Any] — Job[Any]: Restored sample, single-run, or expectation job.

Raises:

• ValueError — If the execution layout, identity, or operation is invalid.

• Exception — If runtime validation or provider retrieval fails.

run¶

def run(
    self,
    executor: HugrExecutor,
    bindings: Mapping[str, Any] | None = None,
    *,
    shots: int | None = None,
    estimation: EstimationAccuracy | None = None,
) -> RunJob[Any] | ExpvalJob

Execute one ordinary shot or compute a program’s expectations.

For an expectation, ShotBased specifies measurements per nonidentity Pauli term; total device shots scale with that term count.

Parameters:

Returns:

RunJob[Any] | ExpvalJob — RunJob[Any] | ExpvalJob: Typed single return or estimated expectation.

Raises:

• ValueError — If runtime values or shots are invalid.

• TypeError — If an expectation accuracy policy is unrecognized.

• NotImplementedError — If exact or target-precision estimation is requested.

• Exception — If target compilation or provider submission fails.

sample¶

def sample(
    self,
    executor: HugrExecutor,
    shots: int = 1024,
    bindings: Mapping[str, Any] | None = None,
) -> Job[SampleResult[Any]]

Sample the typed program with runtime parameter values.

Parameters:

Returns:

Job[SampleResult[Any]] — Job[SampleResult[Any]]: Deferred structured sample counts.

Raises:

• ValueError — If shots, bindings, or operation are invalid.

• Exception — If compilation or provider submission fails.

HugrExecutor [source]¶

class HugrExecutor

Execute HUGR packages on local Selene or Nexus Helios.

Parameters:

Raises:

• ValueError — If the destination is unknown.

• TypeError — If options belong to another destination.

Example:

>>> executor = HugrExecutor(options=SeleneExecutionOptions(seed=7))
>>> remote = HugrExecutor("helios", options=NexusExecutionOptions())

Constructor¶

def __init__(
    self,
    target: str | HugrExecutionTarget = HugrExecutionTarget.SELENE,
    *,
    options: SeleneExecutionOptions | NexusExecutionOptions | None = None,
) -> None

Initialize the destination and local compilation cache.

Parameters:

Raises:

• ValueError — If the destination is unknown.

• TypeError — If options are incompatible with the destination.

Attributes¶

• capabilities: ExecutionCapabilities Describe this destination’s actual execution features.

• options

• target

Methods¶

retrieve¶

def retrieve(self, reference: ExecutionReference) -> ExecutionHandle[list[dict[str, Any]]]

Restore a remote tagged execution without resubmitting it.

Parameters:

Returns:

ExecutionHandle[list[dict[str, Any]]] — ExecutionHandle[list[dict[str, Any]]]: Restored remote handle.

Raises:

• ValueError — If the destination is local or reference is invalid.

• Exception — If the provider cannot retrieve the referenced job.

submit¶

def submit(self, package: Any, shots: int = 1024) -> ExecutionHandle[list[dict[str, Any]]]

Submit a zero-argument HUGR entrypoint with recorded outputs.

Use HugrExecutable for ABI-aware runtime arguments and typed jobs.

Parameters:

Returns:

ExecutionHandle[list[dict[str, Any]]] — ExecutionHandle[list[dict[str, Any]]]: Tagged values for each shot.

Raises:

• ValueError — If shots is invalid or output tags repeat.

• ImportError — If destination dependencies are missing.

• RuntimeError — If the simulator returns an incorrect shot count.

• Exception — If provider compilation or submission fails.