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).
QuantinuumSamplingBackendprefers 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:
SamplingResultA 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:
SamplingJobA 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().Nonefalls back to theQNEXUS_DEFAULT_JOB_TIMEOUT_SECONDSenvironment 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:
- property job_ref: ExecuteJobRef¶
The Nexus execute job reference.
- 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:
- 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:
SamplingBackendA 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 byqnexus.devices.get_all(issuers=[IssuerEnum.QUANTINUUM]). Helios names are rejected (not supported yet).backend_config (Optional[qnx.BackendConfig]) – A
qnexusbackend config. Overridesdevice_nameand allows any Nexus backend (QuantinuumConfig,AerConfig, …) exceptHeliosConfig.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,
PauliandPauliRotationgates are decomposed afterwards, because the pytket converter cannot convert them.check_device (bool) – If True (default) and the config is a
QuantinuumConfig, the firstsample()call fetches the account’s device list once and raisesBackendErrorlisting 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_shotsshots inside a single Nexus job, and the counts are merged in the result. If not given andbackend_configis aQuantinuumConfig, the limit that Nexus reports for the device (max_n_shots) is used once the device check has run, andQUANTINUUM_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.
Nonemeans no limit (orQNEXUS_DEFAULT_JOB_TIMEOUT_SECONDSif 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, setuser_groupon theQuantinuumConfiginstead. Note thatqnexusapplies a scalarmax_cost(HQC limit) to each job item, so when a request is split bymax_shotsintonitems the job may cost up ton * max_cost. A listmax_costmust 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 (
Nonemeans 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
shotsis not positive, or ifmax_costinexecute_kwargsis 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:
circuit (ImmutableQuantumCircuit)
shots (int)
- Return type: