Qamomile v0.15.2 - Qamomile Documentation

Qamomile v0.15.2 adds QSVT eigenstate filtering to select low-energy states for optimization problems, Quantinuum H2 execution through Nexus, and support for reading the current shot number in HUGR programs.

pip install qamomile==0.15.2

Breaking Changes¶

Specify a cost limit for Helios submissions¶

When submitting a new job to Helios, specify a cost limit with max_cost in NexusExecutionOptions. Submission raises an error before sending the job if no limit is set.

Limit the Qiskit dependency version¶

The Qiskit integration now requires qiskit>=2.3.0,<3.

New Features¶

Eigenstate filtering with QSVT¶

The quantum optimization module now includes QSVTEigenstateFilterConverter, which implements eigenstate filtering using QSVT (Quantum Singular Value Transform). Given an optimization problem, the converter can build a quantum circuit implementing the algorithm and convert execution results into a format appropriate for the input. This expands Qamomile’s optimization module and algorithm support.

See QSVT Filtering to solve Graph Partitioning for usage.

Expanded HUGR execution support¶

The following additions concern HUGR execution. To use them, install Qamomile with the hugr extra.

pip install "qamomile[hugr]==0.15.2"

Execute HUGR programs on Quantinuum H2 through Nexus¶

Qamomile now supports Quantinuum H2 as a HUGR execution target. When you select H2 with HugrExecutor("nexus"), Qamomile converts the program to QIR and validates it locally before upload. H2 execution supports only Python 3.11 and 3.12. Python 3.13 and later are not supported.

Configure an executor for H2 hardware:

from qamomile.hugr import HugrExecutor, NexusExecutionOptions

executor = HugrExecutor(
    "nexus",
    options=NexusExecutionOptions(system_name="H2-1", project="qamomile-demo"),
)

Pass this executor to your executable’s sample() method to submit a job. For the emulator, use system_name="H2-1E". A Nexus account and access to the selected device are required. This expands Qamomile’s execution support. Submission to Helios is also supported by selecting Helios with system_name, but Qamomile execution on hardware or emulators has only been verified with H2 devices.

See HUGR Support for an execution example.

H2 syntax checks¶

Use system_name="H2-1SC" to check programs that use shot numbers or fixed-size arrays before running them on hardware. Refresh the status with job.status() to make provider-reported costs available through job.metadata(). Syntax checks do not return measurement results, so job.result() raises an error.

Inspect and reuse H2 QIR¶

Use program.qir to retrieve the QIR generated by H2 sample() or run() calls, and program.qir_info to retrieve metadata such as submission names and targets. Generated QIR and metadata remain available after a network error. Consecutive calls on the same executable reuse the QIR when conversion conditions match, including switching from a syntax check to H2 hardware. Reusing QIR still submits a new job.

Read the current shot number¶

qmc.get_current_shot() returns the current shot number as a UInt. Use it inside a quantum kernel to select gates or entries in fixed-size classical tables for each shot.

You can select different Pauli gates for each shot to implement techniques such as Pauli twirling. Running these variations as multiple shots of one program can reduce preparation and submission time compared with generating and submitting a separate circuit for every shot, allowing faster overall execution. This expands what you can express in Qamomile quantum kernels and extends execution support.

When using Guppy as a native input to H2 and calling its get_current_shot function, shot numbers start at zero on the Selene emulator and at one on H2 devices. Qamomile accounts for this difference so that shot numbers start at zero with both execution methods.

See HUGR Support for an example using get_current_shot().

Access fixed-size arrays by shot number on H2¶

H2 programs now support fixed-size array lookups by shot number, such as values[qmc.get_current_shot()]. This supports UInt and Bit arrays with known values, including indices formed by adding or multiplying the shot number by nonnegative constants.

Update arrays of measurement results¶

HUGR programs can now update arrays of measurement results inside loops and conditional branches. For example, saving an element with old = bits[0] before flipping that element preserves the original value in old. Programs containing these array updates previously failed during conversion.

Documentation¶

Added QSVT Filtering to solve Graph Partitioning, covering circuit construction, measurement selection, and a Python loop that searches for the lowest energy.
Added Quantum Phase Estimation (QPE), comparing a circuit built from individual steps with the built-in qmc.qpe function and examining how the number of qubits affects precision and gate counts.
Refreshed the documentation homepage with Qamomile’s motivations, features, and links to examples.
Added HUGR Support.