feat: Added cost_confidence API on jobs, hugr and qir

Author: qfreewilll

integration/test_jobs.py

@@ -8,6 +8,7 @@
 
 import pandas as pd
 import pytest
+from hugr.package import Package
 from pytket.backends.backendinfo import BackendInfo
 from pytket.backends.backendresult import BackendResult
 from pytket.circuit import Circuit
@@ -26,6 +27,7 @@
     ExecutionResultRef,
     IncompleteJobItemRef,
     JobRef,
+    ProjectRef,
     Ref,
 )
 
@@ -674,3 +676,35 @@ def test_job_cost(
     result_ref = results[0]
     assert isinstance(result_ref, ExecutionResultRef)
     assert result_ref.cost is not None
+
+
+def test_job_cost_confidence(
+    test_case_name: str,
+    create_project: Callable[[str], ContextManager[ProjectRef]],
+    qa_hugr_package: Package,
+) -> None:
+    """Test the cost confidence of a Hugr program on a cost checking device,
+    and that the cost confidence is available using jobs.cost_confidence()."""
+
+    with create_project(f"project for {test_case_name}") as project_ref:
+        hugr_ref = qnx.hugr.upload(
+            hugr_package=qa_hugr_package,
+            name=f"hugr for {test_case_name}",
+            project=project_ref,
+        )
+
+        # Check that we can get a cost confidence estimate (using Helios-1SC)
+        execute_job_ref = qnx.start_execute_job(
+            programs=[hugr_ref],
+            n_shots=[10],
+            # No other parameters matter for cost estimation, so construct a minimal costing config
+            backend_config=qnx.QuantinuumConfig(device_name="Helios-1SC"),
+            project=project_ref,
+            name="Circuit cost confidence estimation job",
+        )
+
+        qnx.jobs.wait_for(execute_job_ref)
+
+        cost_confidence = qnx.jobs.cost_confidence(execute_job_ref)
+        assert isinstance(cost_confidence, list)
+        assert len(cost_confidence) > 0

integration/test_qir.py

@@ -247,6 +247,32 @@ def test_costing_qir_on_NG_devices(
         assert isinstance(cost, float)
 
 
+def test_qir_cost_confidence(
+    test_case_name: str,
+    create_qir_in_project: Callable[[str, str, bytes], ContextManager[QIRRef]],
+) -> None:
+    """Test the cost confidence of a QIR program on a cost checking device."""
+
+    project_name = f"project for {test_case_name}"
+    qir_name = f"qir for {test_case_name}"
+
+    with create_qir_in_project(
+        project_name,
+        qir_name,
+        make_qir_bitcode_from_file("base.ll"),
+    ) as qir_ref:
+        project_ref = qnx.projects.get(name=project_name)
+
+        # Check that we can get a cost confidence estimate (using Helios-1SC)
+        cost_confidence = qnx.qir.cost_confidence(
+            programs=[qir_ref],
+            n_shots=[10],
+            project=project_ref,
+        )
+        assert isinstance(cost_confidence, list)
+        assert len(cost_confidence) > 0
+
+
 def make_qir_bitcode_from_file(filename: str) -> bytes:
     with open(
         Path("tests/data").resolve() / filename,

integration/test_qsys_jobs.py

@@ -114,3 +114,27 @@ def test_hugr_costing(
             project=project_ref,
         )
         assert isinstance(cost, float)
+
+
+def test_hugr_cost_confidence(
+    test_case_name: str,
+    create_project: Callable[[str], ContextManager[ProjectRef]],
+    qa_hugr_package: Package,
+) -> None:
+    """Test the cost confidence of a Hugr program on a cost checking device."""
+
+    with create_project(f"project for {test_case_name}") as project_ref:
+        hugr_ref = qnx.hugr.upload(
+            hugr_package=qa_hugr_package,
+            name=f"hugr for {test_case_name}",
+            project=project_ref,
+        )
+
+        # Check that we can get a cost confidence estimate (using Helios-1SC)
+        cost_confidence = qnx.hugr.cost_confidence(
+            programs=[hugr_ref],
+            n_shots=[10],
+            project=project_ref,
+        )
+        assert isinstance(cost_confidence, list)
+        assert len(cost_confidence) > 0

qnexus/client/circuits.py

@@ -355,7 +355,7 @@ def cost(
         syntax_checker_device_name = syntax_checker
 
     if not syntax_checker_device_name.startswith("H2-"):
-        raise ValueError("Cicuit cost estimation is only supported for H2-x systems.")
+        raise ValueError("Circuit cost estimation is only supported for H2-x systems.")
 
     if not syntax_checker_device_name.endswith("SC"):
         syntax_checker_device_name += "SC"

qnexus/client/hugr.py

@@ -4,6 +4,7 @@
 uploaded to Nexus before stability is achieved might not work in the future.
 """
 
+import warnings
 import base64
 from datetime import datetime
 from typing import Any, Literal, Union, cast
@@ -287,6 +288,11 @@ def cost(
     """
     import qnexus as qnx
 
+    warnings.warn(
+        "hugr.cost() is deprecated. Please update to use hugr.cost_confidence() instead.",
+        category=DeprecationWarning,
+    )
+
     if isinstance(programs, HUGRRef):
         programs = [programs]
 
@@ -302,6 +308,40 @@ def cost(
     return cast(float, status.cost)
 
 
+def cost_confidence(
+    programs: HUGRRef | list[HUGRRef],
+    n_shots: int | list[int],
+    project: ProjectRef | None = None,
+    system_name: Literal["Helios-1"] = "Helios-1",
+) -> list[tuple[float, float]]:
+    """Estimate the cost (in HQC) of running Hugr programs for n_shots
+    number of shots on a Quantinuum Helios system.
+
+    Returns a list of tuples of (cost, confidence) for each job item.
+
+    NB: This will execute a costing job on a dedicated cost estimation device.
+        Once run, the cost will be visible also in the Nexus web portal
+        as part of the job.
+    """
+    import qnexus as qnx
+
+    if isinstance(programs, HUGRRef):
+        programs = [programs]
+
+    job_ref = qnx.start_execute_job(
+        programs=cast(list[ExecutionProgram], programs),
+        n_shots=n_shots,
+        # No other parameters matter for cost estimation, so construct a minimal costing config
+        backend_config=QuantinuumConfig(device_name=f"{system_name}SC"),
+        project=project,
+        name="Circuit cost confidence estimation job",
+    )
+
+    qnx.jobs.wait_for(job_ref)
+
+    return qnx.jobs.cost_confidence(job_ref)
+
+
 @merge_scope_from_context
 def _fetch_by_id(
     hugr_id: UUID | str, scope: ScopeFilterEnum = ScopeFilterEnum.USER

qnexus/client/jobs/__init__.py

@@ -60,6 +60,7 @@
     SystemRef,
     WasmModuleRef,
 )
+
 from qnexus.models.scope import ScopeFilterEnum
 from qnexus.models.utils import assert_never
 
@@ -659,6 +660,7 @@ def cost(
     job: CompileJobRef | ExecuteJobRef, scope: ScopeFilterEnum = ScopeFilterEnum.USER
 ) -> float:
     """Get the HQC cost of a job from a JobRef."""
+
     resp = get_nexus_client().get(
         f"/api/jobs/v1beta3/{job.id}",
         params={"scope": scope.value},
@@ -671,3 +673,35 @@ def cost(
     job_status = resp_data["attributes"]["status"]
     cost = job_status.get("cost")
     return float(cost) if cost is not None else 0.0
+
+
+@merge_scope_from_context
+def cost_confidence(
+    job: CompileJobRef | ExecuteJobRef, scope: ScopeFilterEnum = ScopeFilterEnum.USER
+) -> list[tuple[float, float]]:
+    """
+    Get the HQC cost and confidence of a job from a JobRef.
+
+    Returns a list of tuples of (cost, confidence) for each job item.
+    """
+    resp = get_nexus_client().get(
+        f"/api/jobs/v1beta3/{job.id}", params={"scope": scope.value}
+    )
+    if resp.status_code != 200:
+        raise qnx_exc.ResourceFetchFailed(
+            message=resp.text, status_code=resp.status_code
+        )
+
+    # Loop over all items from the API and gather cost_confidence_items
+    resp_data = resp.json()["data"]
+    items = resp_data["attributes"]["definition"]["items"]
+    cost_confidence_items = []
+    for i, item in enumerate(items):
+        cost_confidence_items.append(
+            (
+                float(item["status"].get("cost", 0.0)),
+                float(item["status"].get("cost_confidence", -1.0)),
+            )
+        )
+
+    return cost_confidence_items

qnexus/client/qir.py

@@ -1,5 +1,6 @@
 """Client API for QIR in Nexus."""
 
+import warnings
 import base64
 from datetime import datetime
 from typing import Any, Literal, Union, cast
@@ -266,6 +267,11 @@ def cost(
     """
     import qnexus as qnx
 
+    warnings.warn(
+        "qir.cost() is deprecated. Please update to use qir.cost_confidence() instead.",
+        category=DeprecationWarning,
+    )
+
     if isinstance(programs, QIRRef):
         programs = [programs]
 
@@ -281,6 +287,39 @@ def cost(
     return cast(float, status.cost)
 
 
+def cost_confidence(
+    programs: QIRRef | list[QIRRef],
+    n_shots: int | list[int],
+    project: ProjectRef | None = None,
+    system_name: Literal["Helios-1"] = "Helios-1",
+) -> list[tuple[float, float]]:
+    """Estimate the cost (in HQC) of running QIR programs for n_shots
+    number of shots on a Quantinuum Helios system.
+
+    Returns a list of tuples of (cost, confidence) for each job item.
+
+    NB: This will execute a costing job on a dedicated cost estimation device.
+        Once run, the cost will be visible also in the Nexus web portal
+        as part of the job.
+    """
+    import qnexus as qnx
+
+    if isinstance(programs, QIRRef):
+        programs = [programs]
+
+    job_ref = qnx.start_execute_job(
+        programs=cast(list[ExecutionProgram], programs),
+        n_shots=n_shots,
+        backend_config=QuantinuumConfig(device_name=f"{system_name}SC"),
+        project=project,
+        name="QIR cost estimation job",
+    )
+
+    qnx.jobs.wait_for(job_ref)
+
+    return qnx.jobs.cost_confidence(job_ref)
+
+
 @merge_scope_from_context
 def _fetch_by_id(
     qir_id: UUID | str, scope: ScopeFilterEnum = ScopeFilterEnum.USER