qamomile.hugr

HUGR program-graph target for Qamomile.

The engine lowers prepared hierarchical Qamomile semantics directly to a HUGR package. It deliberately bypasses circuit segmentation and CircuitProgram so function boundaries, typed dataflow, and hybrid control can be preserved. Generated quantum operations use the same tket.* extensions as Guppy, making the result interoperable with the Guppy/HUGR ecosystem.

Destructive measurements consume qubits with MeasureFree. Projections retain their measured state with Measure. Direct measurement/reset pairs use MeasureReset when their quantum wire and ordering permit fusion. Opaque measurement bits are converted to the existing native Boolean carrier.

HugrExecutable.qir and qir_info expose the latest complete H2 payloads and detached restoration metadata from ordinary sample and run calls. These records are ready before authentication or upload and survive a lost submission response. Compatible consecutive H2 calls reuse the exact bytes. Existing typed jobs, snapshots, and restoration keep their usual contracts.

Overview¶

Classes¶

HugrCompilationPlan [source]¶

class HugrCompilationPlan

Describe the callable symbols emitted into one HUGR module.

Parameters:

Constructor¶

def __init__(self, definitions: tuple[CallableRef, ...]) -> None

Attributes¶

• definitions: tuple[CallableRef, ...]

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.

• qir: bytes | tuple[bytes, ...] | None Return the last successfully prepared H2 operation’s exact QIR.

• qir_info: dict[str, Any] | None Return detached JSON-compatible metadata for the latest H2 operation.

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.

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.

HugrTarget [source]¶

class HugrTarget

Plan, lower, package, and validate a Guppy-compatible HUGR target.

Attributes¶

• name: str Return the stable compilation target name.

Methods¶

compile¶

def compile(
    self,
    program: PreparedModule,
    plan: HugrCompilationPlan,
) -> CompiledProgram[Any]

Lower a prepared semantic module directly to a HUGR package.

Parameters:

Returns:

CompiledProgram[Any] — CompiledProgram[Any]: HUGR package and target metadata.

Raises:

• ImportError — If HUGR or TKET extension packages are unavailable.

• EmitError — If a semantic operation has no HUGR lowering yet.

plan¶

def plan(self, program: PreparedModule) -> HugrCompilationPlan

Select reachable body-backed callables for HUGR functions.

Parameters:

Returns:

HugrCompilationPlan — Stable callable-definition order.

Raises:

• CallableDefinitionConflictError — If one source callable produced multiple specialized bodies that cannot share one HUGR symbol.

validate¶

def validate(self, artifact: Any) -> None

Validate a HUGR package with the native Rust-backed validator.

Parameters:

Raises:

• ImportError — If the HUGR package is unavailable.

• HugrCliError — If HUGR validation rejects the package.

HugrTranspiler [source]¶

class HugrTranspiler

Build HUGR executables and Guppy-compatible compiled packages.

Use transpile() for a program with run() and sample() methods, or compile() for a compiled package with its ABI and metadata.

Parameters:

Constructor¶

def __init__(self, config: CompilerConfig | None = None) -> None

Initialize the direct program-graph transpiler.

Parameters:

Attributes¶

• compiler

• target

Methods¶

compile¶

def compile(
    self,
    kernel: QKernelLike,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> CompiledProgram[Any]

Compile a qkernel directly to a validated HUGR package.

Return the compilation result without execution methods. Use transpile() to prepare an executable, including runtime array shapes and expectation-value measurement programs.

Parameters:

Returns:

CompiledProgram[Any] — CompiledProgram[Any]: Validated hugr.package.Package artifact.

Raises:

• ImportError — If HUGR dependencies are unavailable.

• ValueError — If compile-time bindings overlap runtime parameters.

• QamomileCompileError — If semantic preparation or HUGR lowering rejects the program.

• HugrCliError — If target-native validation rejects the package.

executor¶

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

Create an executor for a selected HUGR destination.

Parameters:

Returns:

HugrExecutor — Destination-independent public executor.

Raises:

• ValueError — If target is unknown.

• TypeError — If options do not match the destination.

to_hugr¶

def to_hugr(
    self,
    kernel: QKernelLike,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> Any

Return only the validated HUGR package artifact.

Parameters:

Returns:

Any — hugr.package.Package artifact.

Raises:

• ImportError — If HUGR dependencies are unavailable.

• ValueError — If compile-time bindings overlap runtime parameters.

• QamomileCompileError — If semantic preparation or HUGR lowering rejects the program.

• HugrCliError — If target-native validation rejects the package.

transpile¶

def transpile(
    self,
    kernel: QKernelLike,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
    *,
    parameter_shapes: dict[str, tuple[int, ...]] | None = None,
) -> HugrExecutable

Transpile a qkernel into an executable for Selene and Nexus devices.

Parameters:

Returns:

HugrExecutable — Native packages with run() and sample() methods accepting a HUGR executor and runtime bindings.

Raises:

• ValueError — If compile-time bindings overlap runtime parameters.

• QamomileCompileError — If semantics or target capabilities are invalid.

• Exception — If native HUGR validation 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

NexusRegion [source]¶

class NexusRegion(StrEnum)

Select a supported Nexus execution region.

Attributes¶

• SG

• US

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

Submodules¶

• qamomile.hugr.executable

• qamomile.hugr.execution

• qamomile.hugr.lowerer

• qamomile.hugr.transpiler