qamomile.hugr.execution

Select local Selene or a Nexus device for HUGR program execution.

Overview¶

Classes¶

HugrExecutionTarget [source]¶

class HugrExecutionTarget(StrEnum)

Identify a supported HUGR execution destination.

Attributes¶

• HELIOS

• NEXUS

• SELENE

HugrExecutor [source]¶

class HugrExecutor

Execute HUGR packages on local Selene or Nexus devices.

The nexus destination selects HUGR or QIR submission from the device configured in :class:NexusExecutionOptions. The existing helios destination remains an alias for Nexus execution. Nexus authentication starts on the first submission or restoration, and project names are resolved internally when submitting a job.

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())
>>> h2 = HugrExecutor(
...     "nexus", options=NexusExecutionOptions(system_name="H2-1E")
... )

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: Package,
    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.

NexusExecutionOptions [source]¶

class NexusExecutionOptions

Configure execution on a Helios or H2 target through Nexus.

Parameters:

Raises:

• ValueError — If a numeric option, project name, region, or config is invalid.

Constructor¶

def __init__(
    self,
    project: Any | None = None,
    backend_config: Any | None = None,
    system_name: str = 'Helios-1',
    name: str = 'qamomile-hugr',
    max_cost: float | None = None,
    n_qubits: int | None = None,
    credential_name: str | None = None,
    user_group: str | None = None,
    target_region: str | NexusRegion | None = None,
    poll_interval_seconds: float = 1.0,
    timeout_seconds: float | None = None,
) -> None

Attributes¶

• backend_config: Any | None

• credential_name: str | None

• max_cost: float | None

• n_qubits: int | None

• name: str

• poll_interval_seconds: float

• project: Any | None

• system_name: str

• target_region: str | NexusRegion | None

• timeout_seconds: float | None

• user_group: str | None

SeleneExecutionOptions [source]¶

class SeleneExecutionOptions

Configure local Selene execution.

Parameters:

Raises:

• ValueError — If a numeric option is invalid.

• TypeError — If the seed or capacity is not an integer.

Constructor¶

def __init__(
    self,
    seed: int | None = None,
    n_qubits: int | None = None,
    timeout_seconds: float | None = None,
    build_dir: Path | None = None,
) -> None

Attributes¶

• build_dir: Path | None

• n_qubits: int | None

• seed: int | None

• timeout_seconds: float | None