Update qiskit submission sample notebook to use AzureQuantumProvider method (#2794)

This PR updates the qiskit submission notebook to demonstrate the more
streamlined approach to submitting qiskit to azure using the
`AzureQuantumProvider` class. It also retains instructions for how to
manually convert qiskit to QIR for submission.

Author: ScottCarda-MS

samples/python_interop/submit_qiskit_circuit_to_azure.ipynb

@@ -7,29 +7,29 @@
    "source": [
     "# Submitting Qiskit Circuits to Azure Quantum with the QDK\n",
     "\n",
-    "This notebook shows how to take an arbitrary Qiskit `QuantumCircuit`, compile it to QIR using the Quantum Development Kit (QDK) Python APIs, and submit it as a job to an Azure Quantum target. It also demonstrates how to handle parameterized circuits by binding parameters before submission."
+    "This notebook demonstrates two ways to run Qiskit `QuantumCircuit` jobs on Azure Quantum using the QDK: (A) direct submission via `AzureQuantumProvider` for a streamlined workflow, and (B) an explicit OpenQASM 3 → QIR compilation path for transparency and artifact inspection. It also shows how to handle parameterized circuits by binding parameters prior to execution."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "2b838c23",
    "metadata": {},
    "source": [
-    "The workflow demonstrated here:\n",
+    "This workflow demonstrates two methods of submission:\n",
     "\n",
+    "### A. Direct submission via `AzureQuantumProvider` (recommended when available)\n",
+    "1. Build (or load) a Qiskit `QuantumCircuit`.\n",
+    "2. Reference an existing Azure Quantum workspace with `qdk.azure.Workspace`.\n",
+    "3. Instantiate `AzureQuantumProvider(workspace)` and pick a backend (`provider.get_backend(<target_name>)`).\n",
+    "4. Call `backend.run(circuit, shots, job_name=...)` and fetch results (`job.result().get_counts(circuit)`).\n",
+    "\n",
+    "### B. Submit via OpenQASM compilation (explicit OpenQASM → QIR → submit)\n",
     "1. Build (or load) a Qiskit `QuantumCircuit`.\n",
     "2. Convert it to OpenQASM 3 text (`qiskit.qasm3.dumps`).\n",
-    "3. Compile that OpenQASM 3 source to QIR with `qdk.openqasm.compile`.\n",
-    "4. Create (or attach to) an Azure Quantum workspace with `qdk.azure.Workspace`.\n",
+    "3. Compile the OpenQASM 3 source to QIR with `qdk.openqasm.compile` (choose a `TargetProfile`).\n",
+    "4. Reference an existing Azure Quantum workspace with `qdk.azure.Workspace`.\n",
     "5. Select a target (e.g. a simulator such as `rigetti.sim.qvm`).\n",
-    "6. Submit the QIR payload and retrieve measurement results.\n",
-    "\n",
-    "Why use the QDK in this flow?\n",
-    "\n",
-    "- Local compilation: QIR generation happens locally—no external CLI needed.\n",
-    "- Consistency: The same compiler stack powers Q#, OpenQASM, and (via translation) Qiskit interoperability.\n",
-    "\n",
-    "This notebook focuses strictly on submission. For local resource estimation of Qiskit circuits, see the separate estimation sample."
+    "6. Submit the QIR payload (`target.submit(qir, job_name, shots)`), then retrieve results (`job.get_results()`)."
    ]
   },
   {
@@ -128,19 +128,66 @@
     "location = 'westus'"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cdae59f7",
+   "metadata": {},
+   "source": [
+    "### Approach A: Using Azure Quantum Provider\n",
+    "\n",
+    "Here we use the recommended submission method with `AzureQuantumProvider` to submit the Qiskit circuit straight to an Azure Quantum backend. This avoids having to explicitly do QASM translation or QIR compilation steps."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "d9a0f59b",
    "metadata": {},
    "outputs": [],
+   "source": [
+    "from qdk.azure import Workspace\n",
+    "from qdk.azure.qiskit import AzureQuantumProvider\n",
+    "\n",
+    "def submit_qiskit_circuit_to_azure_provider(circuit, target_name, name, shots=100):\n",
+    "\n",
+    "    workspace = Workspace(\n",
+    "        subscription_id=subscription_id,\n",
+    "        resource_group=resource_group,\n",
+    "        name=workspace_name,\n",
+    "        location=location,\n",
+    "    )\n",
+    "\n",
+    "    provider = AzureQuantumProvider(workspace)\n",
+    "    backend = provider.get_backend(target_name)\n",
+    "    job = backend.run(circuit, shots, job_name=name)\n",
+    "    return job.result().get_counts(circuit)\n",
+    "\n",
+    "provider_counts = submit_qiskit_circuit_to_azure_provider(circuit, \"rigetti.sim.qvm\", \"qiskit-provider-job\")\n",
+    "print(provider_counts)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fbf60412",
+   "metadata": {},
+   "source": [
+    "### Approach B: Submit via OpenQASM compilation\n",
+    "\n",
+    "Below we show the longer path that exposes intermediate artifacts. This is useful if you want to inspect or transform OpenQASM/QIR, or integrate with tooling that consumes QIR directly.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ee47d6f6",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "from qiskit import qasm3\n",
     "from qdk.openqasm import compile\n",
-    "from qdk.azure import Workspace\n",
     "from qdk import TargetProfile\n",
     "\n",
-    "def submit_qiskit_circuit_to_azure(circuit, target_name, name, shots=100):\n",
+    "def submit_qiskit_circuit_to_azure_via_qasm(circuit, target_name, name, shots=100):\n",
     "    qasm3_str = qasm3.dumps(circuit)\n",
     "    qir = compile(qasm3_str, target_profile=TargetProfile.Base)\n",
     "\n",
@@ -154,7 +201,7 @@
     "    job = target.submit(qir, name, shots=shots)\n",
     "    return job.get_results()\n",
     "\n",
-    "results = submit_qiskit_circuit_to_azure(circuit, \"rigetti.sim.qvm\", \"qiskit-job\")\n",
+    "results = submit_qiskit_circuit_to_azure_via_qasm(circuit, \"rigetti.sim.qvm\", \"qiskit-via-qasm-job\")\n",
     "print(results)"
    ]
   },
@@ -165,7 +212,7 @@
    "source": [
     "## Parameterized Qiskit circuits\n",
     "\n",
-    "Many algorithms use symbolic parameters. Before compiling to QIR and submitting, all circuit parameters must be bound to numeric values. Below we build a simple entangling ladder, apply a rotation parameterized by θ across all qubits, then uncompute the entanglement and measure the first qubit."
+    "Many algorithms use symbolic parameters. Before submitting to azure (or before compiling to QIR), all circuit parameters must be bound to numeric values. Below we build a simple entangling ladder, apply a rotation parameterized by `θ` across all qubits, then uncompute the entanglement and measure the first qubit."
    ]
   },
   {
@@ -178,7 +225,6 @@
     "from qiskit import QuantumCircuit\n",
     "from qiskit.circuit import Parameter\n",
     "\n",
-    "\n",
     "def get_parameterized_circuit(n = 5) -> QuantumCircuit:\n",
     "    theta = Parameter(\"θ\")\n",
     "    qc = QuantumCircuit(n, 1)\n",
@@ -194,10 +240,12 @@
     "    return qc\n",
     "\n",
     "# Build the symbolic (parameterized) circuit\n",
-    "circuit = get_parameterized_circuit()\n",
+    "parameterized_circuit = get_parameterized_circuit()\n",
     "\n",
     "# Bind θ to a numeric value, then visualize the bound circuit\n",
-    "circuit.assign_parameters({\"θ\": 0.5}).draw(output=\"text\")"
+    "bound_circuit = parameterized_circuit.assign_parameters({\"θ\": 0.5})\n",
+    "\n",
+    "bound_circuit.draw(output=\"text\")"
    ]
   },
   {
@@ -207,7 +255,7 @@
    "source": [
     "## Submitting a bound parameterized circuit\n",
     "\n",
-    "Below we reuse the parameterized circuit from above, bind θ to 0.5, and submit the resulting (fully concrete) circuit to the Azure Quantum target using the same helper function as before. The printed result shows the measurement counts. Change the value of θ (or loop over several values) to explore how the outcome distribution varies."
+    "Here we submit the `bound_circuit` from above using the recommended `AzureQuantumProvider` approach. The printed result shows the measurement counts. Change the value of `θ` (or loop over several values) to explore how the outcome distribution varies."
    ]
   },
   {
@@ -217,11 +265,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Reuse the previously defined parameterized circuit\n",
-    "# (circuit is symbolic and must have θ bound to a value before submission)\n",
-    "\n",
-    "results = submit_qiskit_circuit_to_azure(\n",
-    "    circuit.assign_parameters({\"θ\": 0.5}),\n",
+    "results = submit_qiskit_circuit_to_azure_provider(\n",
+    "    bound_circuit,\n",
     "    \"rigetti.sim.qvm\",\n",
     "    \"qiskit-parameterized-job\"\n",
     ")\n",
@@ -245,7 +290,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.8"
+   "version": "3.13.9"
   }
  },
  "nbformat": 4,

source/qdk_package/pyproject.toml

@@ -14,11 +14,11 @@ dependencies = ["qsharp==0.0.0"]
 
 [project.optional-dependencies]
 jupyter = ["qsharp-widgets==0.0.0", "qsharp-jupyterlab==0.0.0"]
-azure = ["azure-quantum>=3.2.0"]
+azure = ["azure-quantum>=3.5.0"]
 qiskit = ["qiskit>=1.2.2,<3.0.0"]
 all = [
   "qsharp-widgets==0.0.0",
-  "azure-quantum>=3.2.0",
+  "azure-quantum>=3.5.0",
   "qiskit>=1.2.2,<3.0.0",
   "qsharp-jupyterlab==0.0.0",
 ]

source/qdk_package/src/qdk/azure/qiskit.py

@@ -0,0 +1,18 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""qdk.azure.qiskit: re-export of azure.quantum.qiskit symbols.
+
+Requires installation: ``pip install \"qdk[azure,qiskit]\"``.
+
+Example:
+    from qdk.azure.qiskit import <symbol>
+
+"""
+
+try:
+    from azure.quantum.qiskit import *  # pyright: ignore[reportWildcardImportFromLibrary]
+except Exception as ex:
+    raise ImportError(
+        "qdk.azure.qiskit requires the azure and qiskit extras. Install with 'pip install \"qdk[azure,qiskit]\"'."
+    ) from ex