quri_parts.quantinuum.backend.sampling module

TketCircuitConverter

A function converting a QURI Parts circuit to a pytket circuit.

QUANTINUUM_MAX_SHOTS_PER_ITEM = 10000

Fallback for the maximum number of shots per job item on Quantinuum-hosted devices (H-Series). QuantinuumSamplingBackend prefers the limit that Nexus reports for the device (max_n_shots) and uses this value when it is not reported or the device check is skipped.

class QuantinuumSamplingResult(backend_results)

Bases: SamplingResult

A result of a sampling job executed through Quantinuum Nexus.

Parameters:

backend_results (Sequence[BackendResult]) – pytket results of the job items. Counts of all items are merged.

property counts: backend.SamplingCounts

Measurement counts merged over all job items.

property backend_results: Sequence[BackendResult]

Raw pytket results, one per job item.

class QuantinuumSamplingJob(job_ref, timeout=None)

Bases: SamplingJob

A sampling job submitted to Quantinuum Nexus.

Parameters:
  • job_ref (ExecuteJobRef) – The Nexus execute job reference.

  • timeout (Optional[float]) – Seconds to wait for the job in result(). None falls back to the QNEXUS_DEFAULT_JOB_TIMEOUT_SECONDS environment variable if set, otherwise waits without limit.

classmethod from_id(job_id, timeout=None)

Recreate a job object from a Nexus execute job id.

This allows retrieving results in a different process, e.g. after an HPC batch job ends.

Raises:

BackendError – If the job cannot be fetched from Nexus (including when not logged in) or is not an execute job.

Parameters:
  • job_id (str)

  • timeout (float | None)

Return type:

QuantinuumSamplingJob

property job_ref: ExecuteJobRef

The Nexus execute job reference.

property id: str

The Nexus job id, usable with from_id().

status()

Query the current status of the job from Nexus.

Raises:

BackendError – If the status cannot be fetched from Nexus (including when not logged in).

Return type:

JobStatusEnum

cancel()

Request cancellation of the job.

Raises:

BackendError – If the request fails (including when not logged in).

Return type:

None

result()

Wait for the job to finish and return the merged sampling result.

Raises:

BackendError – If the job fails, is cancelled, times out, cannot be reached (including when not logged in) or returns results other than pytket circuit results.

Return type:

QuantinuumSamplingResult

class QuantinuumSamplingBackend(device_name=None, *, backend_config=None, project='quri-parts', circuit_converter=<function convert_circuit>, circuit_transpiler=None, check_device=True, compile_on_nexus=True, optimisation_level=2, max_shots=None, compile_timeout=None, result_timeout=None, job_name_prefix='quri-parts', compile_kwargs={}, execute_kwargs={})

Bases: SamplingBackend

A sampling backend for Quantinuum devices accessed through Nexus.

Examples

>>> import qnexus as qnx
>>> qnx.login()  # once per machine; tokens are stored in ~/.qnx/auth
>>> backend = QuantinuumSamplingBackend("H2-1E")
>>> job = backend.sample(circuit, shots=1000)
>>> job.result().counts

The device names an account can use are listed by qnexus:

>>> from qnexus.models import IssuerEnum
>>> qnx.devices.get_all(issuers=[IssuerEnum.QUANTINUUM]).df()

A Nexus-hosted simulator (no HQC needed) can be used by passing the config explicitly:

>>> backend = QuantinuumSamplingBackend(backend_config=qnx.AerConfig())
Parameters:
  • device_name (Optional[str]) – Name of a Quantinuum device, emulator or syntax checker, e.g. "H2-1", "H2-1E" or "H2-1SC". Which names the account can use is listed by qnexus.devices.get_all(issuers=[IssuerEnum.QUANTINUUM]). Helios names are rejected (not supported yet).

  • backend_config (Optional[qnx.BackendConfig]) – A qnexus backend config. Overrides device_name and allows any Nexus backend (QuantinuumConfig, AerConfig, …) except HeliosConfig.

  • project (Union[str, ProjectRef]) – The Nexus project (name or ProjectRef) that holds the uploaded circuits and jobs. A project with the given name is created if it does not exist.

  • circuit_converter (TketCircuitConverter) – A function converting a QURI Parts circuit to a pytket circuit.

  • circuit_transpiler (Optional[CircuitTranspiler]) – A QURI Parts transpiler applied to the circuit before conversion. Whether or not one is given, Pauli and PauliRotation gates are decomposed afterwards, because the pytket converter cannot convert them.

  • check_device (bool) – If True (default) and the config is a QuantinuumConfig, the first sample() call fetches the account’s device list once and raises BackendError listing the available devices if the device is not among them, instead of letting the job fail on Nexus. Set False to skip the extra request.

  • compile_on_nexus (bool) – If True, the uploaded circuit is compiled on Nexus for the target backend before execution. If False, the circuit is executed as uploaded; it must then already satisfy the backend’s gate set (e.g. via circuit_transpiler).

  • optimisation_level (int) – TKET optimisation level (0-3) used by the Nexus compile job.

  • max_shots (Optional[int]) – A request with more shots is split into several job items of at most max_shots shots inside a single Nexus job, and the counts are merged in the result. If not given and backend_config is a QuantinuumConfig, the limit that Nexus reports for the device (max_n_shots) is used once the device check has run, and QUANTINUUM_MAX_SHOTS_PER_ITEM (10000) before that or when it is not reported. None (no split) for other configs.

  • compile_timeout (Optional[float]) – Seconds to wait for the compile job. None means no limit (or QNEXUS_DEFAULT_JOB_TIMEOUT_SECONDS if set).

  • result_timeout (Optional[float]) – Seconds to wait for the execute job in QuantinuumSamplingJob.result().

  • job_name_prefix (str) – Prefix of the circuit and job names shown on Nexus.

  • compile_kwargs (Mapping[str, Any]) – Additional keyword arguments for qnexus.start_compile_job().

  • execute_kwargs (Mapping[str, Any]) – Additional keyword arguments for qnexus.start_execute_job(), e.g. max_cost. They reach the execute job only; to run both the compile and the execute job under an organisation group, set user_group on the QuantinuumConfig instead. Note that qnexus applies a scalar max_cost (HQC limit) to each job item, so when a request is split by max_shots into n items the job may cost up to n * max_cost. A list max_cost must have one entry per item; its length is checked before anything is uploaded.

property backend_config: Annotated[AerConfig | AerStateConfig | AerUnitaryConfig | BraketConfig | QuantinuumConfig | IBMQConfig | IBMQEmulatorConfig | QulacsConfig | SeleneConfig | SelenePlusConfig | HeliosConfig, FieldInfo(annotation=NoneType, required=True, discriminator='type')]

The Nexus backend config used for compile and execute jobs.

property max_shots: int | None

Maximum shots per job item (None means no split).

property project: ProjectRef

The Nexus project.

Resolved (and created if needed) on first access.

Raises:

BackendError – If the project cannot be fetched or created on Nexus (including when not logged in).

sample(circuit, shots)

Upload, compile (optional) and submit the circuit as a Nexus execute job. Returns as soon as the execute job is submitted.

Raises:
  • ValueError – If shots is not positive, or if max_cost in execute_kwargs is a list whose length differs from the number of job items.

  • BackendError – If the device is not available to the account (see check_device) or any step on Nexus fails, including when not logged in.

Parameters:
Return type:

SamplingJob