Encapsulate qsharp.estimate into Circuit (#428)

Author: wavefunction91

docs/source/conf.py

@@ -206,8 +206,7 @@
     (r"py:class", r"qdk::chemistry::data::SumPauliOperatorExpression"),
     (r"py:class", r"qdk::chemistry::algorithms::HamiltonianConstructor"),
     (r"py:class", r"^SumPauliOperatorExpression$"),
-    (r"py:class", r"qsharp._native.*"),
-    (r"py:class", r"qsharp._qsharp.*"),
+    (r"py:class", r"qsharp\..*"),  # qsharp has no intersphinx inventory
 ]
 
 # Configure output for to-dos

examples/qpe_stretched_n2.ipynb

@@ -323,7 +323,6 @@
    "outputs": [],
    "source": [
     "import qdk_chemistry.plugins.qiskit # Enable Qiskit plugin capabilities # noqa: F401\n",
-    "from qdk.openqasm import estimate\n",
     "from qdk.widgets import Circuit\n",
     "\n",
     "# Generate state preparation circuit for the sparse state using the regular isometry method (Qiskit)\n",
@@ -335,7 +334,7 @@
     "\n",
     "# Print logical qubit counts estimated from the circuit\n",
     "df = pd.DataFrame(\n",
-    "    estimate(regular_isometry_circuit.get_qasm()).logical_counts.items(),\n",
+    "    regular_isometry_circuit.estimate().logical_counts.items(),\n",
     "    columns=['Logical Estimate', 'Counts']\n",
     ")\n",
     "display(df)"
@@ -364,7 +363,14 @@
     "sparse_isometry_circuit = state_prep.run(wfn_trial)\n",
     "\n",
     "# Visualize the sparse isometry circuit, idle and classical qubits are removed\n",
-    "display(Circuit(sparse_isometry_circuit.get_qsharp_circuit()))"
+    "display(Circuit(sparse_isometry_circuit.get_qsharp_circuit()))\n",
+    "\n",
+    "# Print logical qubit counts estimated from the circuit\n",
+    "df = pd.DataFrame(\n",
+    "    sparse_isometry_circuit.estimate().logical_counts.items(),\n",
+    "    columns=['Logical Estimate', 'Counts']\n",
+    ")\n",
+    "display(df)"
    ]
   },
   {

examples/state_prep_energy.ipynb

@@ -304,7 +304,6 @@
             "outputs": [],
             "source": [
                 "import pandas as pd\n",
-                "from qdk.openqasm import estimate\n",
                 "from qdk.widgets import Circuit\n",
                 "\n",
                 "# Generate state preparation circuit for the sparse state using the regular isometry method (Qiskit)\n",
@@ -315,7 +314,7 @@
                 "display(Circuit(regular_isometry_circuit.get_qsharp_circuit()))\n",
                 "\n",
                 "# Print logical qubit counts estimated from the circuit\n",
-                "df = pd.DataFrame(estimate(regular_isometry_circuit.get_qasm()).logical_counts.items(), columns=['Logical Estimate', 'Counts'])\n",
+                "df = pd.DataFrame(regular_isometry_circuit.estimate().logical_counts.items(), columns=['Logical Estimate', 'Counts'])\n",
                 "display(df)"
             ]
         },
@@ -342,7 +341,6 @@
             "source": [
                 "import pandas as pd\n",
                 "from qdk.widgets import Circuit\n",
-                "import qsharp\n",
                 "\n",
                 "# Generate state preparation circuit for the sparse state via sparse isometry (GF2 + X)\n",
                 "state_prep = create(\"state_prep\", \"sparse_isometry_gf2x\")\n",
@@ -353,9 +351,7 @@
                 "\n",
                 "# Print logical qubit counts estimated from the circuit\n",
                 "df = pd.DataFrame(\n",
-                "    qsharp.estimate(\n",
-                "        sparse_isometry_circuit._qsharp_factory.program, None, *sparse_isometry_circuit._qsharp_factory.parameter.values()\n",
-                "        ).logical_counts.items(), columns=['Logical Estimate', 'Counts'])\n",
+                "    sparse_isometry_circuit.estimate().logical_counts.items(), columns=['Logical Estimate', 'Counts'])\n",
                 "display(df)"
             ]
         },

python/src/qdk_chemistry/data/circuit.py

@@ -19,6 +19,7 @@
 
 import h5py
 import qsharp._native
+import qsharp.estimator
 import qsharp.openqasm
 from qsharp.openqasm import OutputSemantics
 
@@ -192,6 +193,33 @@ def get_qsharp_circuit(self, prune_classical_qubits: bool = False) -> qsharp._na
 
         raise RuntimeError("The quantum circuit is not set in a Q# format.")
 
+    def estimate(
+        self,
+        params: dict[str, Any] | list[Any] | qsharp.estimator.EstimatorParams | None = None,
+    ) -> qsharp.estimator.EstimatorResult:
+        """Estimate resources for the quantum circuit.
+
+        Args:
+            params: Resource estimation parameters. Accepts a dict, list, or ``qsharp.estimator.EstimatorParams``.
+
+        Returns:
+            qsharp.estimator.EstimatorResult: The estimated resources.
+
+        Raises:
+            RuntimeError: If no suitable circuit representation is available for estimation.
+
+        """
+        if self._qsharp_factory is not None:
+            return qsharp.estimate(
+                self._qsharp_factory.program,
+                params,
+                *self._qsharp_factory.parameter.values(),
+            )
+        if self.qasm is not None:
+            return qsharp.openqasm.estimate(self.qasm, params)
+
+        raise RuntimeError("Cannot estimate resources: no Q# factory data or QASM representation is available.")
+
     def get_qiskit_circuit(self):
         """Convert the Circuit to a Qiskit QuantumCircuit.
 

python/tests/test_circuit.py

@@ -408,3 +408,58 @@ def test_cannot_add_new_attributes(self):
         # Attempting to add a new attribute should raise an error
         with pytest.raises(AttributeError):
             circuit.new_attr = "value"
+
+
+class TestCircuitEstimate:
+    """Test cases for Circuit.estimate method."""
+
+    def test_estimate_from_factory(self):
+        """Test that estimate works with Q# factory data."""
+        state_prep_params = {
+            "rowMap": [1, 0],
+            "stateVector": [0.6, 0.0, 0.0, 0.8],
+            "expansionOps": [],
+            "numQubits": 2,
+        }
+        qsharp_factory = QsharpFactoryData(
+            program=QSHARP_UTILS.StatePreparation.MakeStatePreparationCircuit,
+            parameter=state_prep_params,
+        )
+        circuit = Circuit(qsharp_factory=qsharp_factory)
+        result = circuit.estimate()
+        assert result is not None
+        assert hasattr(result, "logical_counts")
+
+    def test_estimate_from_qasm(self):
+        """Test that estimate works with QASM representation."""
+        qasm_with_t = """
+            OPENQASM 3.0;
+            include "stdgates.inc";
+            qubit[2] q;
+            bit[2] c;
+            h q[0];
+            t q[0];
+            cx q[0], q[1];
+            c[0] = measure q[0];
+            c[1] = measure q[1];
+        """
+        circuit = Circuit(qasm=qasm_with_t)
+        result = circuit.estimate()
+        assert result is not None
+        assert hasattr(result, "logical_counts")
+
+    def test_estimate_raises_with_qir_only(self):
+        """Test that estimate raises when only QIR representation is available."""
+        qir = qsharp.openqasm.compile("""
+            OPENQASM 3.0;
+            include "stdgates.inc";
+            qubit[2] q;
+            bit[2] c;
+            h q[0];
+            cx q[0], q[1];
+            c[0] = measure q[0];
+            c[1] = measure q[1];
+        """)
+        circuit = Circuit(qir=qir)
+        with pytest.raises(RuntimeError, match="Cannot estimate resources"):
+            circuit.estimate()