Updates to Qiskit and Cirq Python Interop Sample Notebooks (#3075)

This updates the azure-submission notebooks for Cirq and Qiskit,
breaking out the manual QASM -> QIR method of submission into its own
notebook and using the interop layer classes for the Cirq and Qiskit
notebooks, including information about how noisy shot results are
handled.
Also adds a notebook about how to run circuits from Cirq and Qiskit on
our local neutral atom simulator, including how to handle noisy results.

Author: ScottCarda-MS

build.py

@@ -702,8 +702,10 @@ def run_ci_historic_benchmark():
             or f.startswith("iterative_phase_estimation.")
             or f.startswith("repeat_until_success.")
             or f.startswith("python-deps.")
-            or f.startswith("submit_qiskit_circuit_to_azure.")
             or f.startswith("cirq_submission_to_azure.")
+            or f.startswith("neutral_atom_simulator.")
+            or f.startswith("qir_circuit_submission_to_azure.")
+            or f.startswith("qiskit_submission_to_azure")
             or f.startswith("pennylane_submission_to_azure.")
             or f.startswith("benzene.")
             or f.startswith("parallel_teleport.")

samples/python_interop/cirq_submission_to_azure.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# Submitting Cirq Circuits to Azure Quantum with the QDK\n",
     "\n",
-    "This notebook shows how to take a Cirq `Circuit`, export it to OpenQASM 3, compile that OpenQASM 3 source to QIR using the Quantum Development Kit (QDK) Python APIs, and submit it as a job to an Azure Quantum target."
+    "This notebook demonstrates how to run Cirq `Circuit` jobs on Azure Quantum using `AzureQuantumService` from the QDK."
    ]
   },
   {
@@ -17,12 +17,10 @@
    "source": [
     "The workflow demonstrated here:\n",
     "\n",
-    "1. Build (or load) a Cirq `Circuit`.\n",
-    "2. Convert it to OpenQASM 3 text via `circuit.to_qasm(version=\"3.0\")`.\n",
-    "3. Compile the OpenQASM 3 source to QIR with `qdk.openqasm.compile`.\n",
-    "4. Connect to (or create) an Azure Quantum workspace using `qdk.azure.Workspace`.\n",
-    "5. Pick a target (e.g., a simulator like `rigetti.sim.qvm`).\n",
-    "6. Submit the QIR payload and retrieve measurement results."
+    "1. Build a Cirq `Circuit` with named measurement keys.\n",
+    "2. Reference an existing Azure Quantum workspace with `AzureQuantumService`.\n",
+    "3. Browse available targets via `service.targets()`.\n",
+    "4. Call `service.create_job(program=circuit, repetitions=..., target=...)` and fetch results (`job.results()`)."
    ]
   },
   {
@@ -32,7 +30,7 @@
    "source": [
     "## Prerequisites\n",
     "\n",
-    "Ensure the `qdk` package is installed with `azure` and `cirq` extras. If not, install dependencies below."
+    "This notebook assumes the `qdk` package with Azure Quantum and Cirq support is installed. You can install everything with:"
    ]
   },
   {
@@ -50,7 +48,12 @@
    "id": "20b9ed32",
    "metadata": {},
    "source": [
-    "After installing, restart the kernel if necessary. Verify imports:"
+    "This installs:\n",
+    "- The base `qdk` package (compiler, OpenQASM/QIR tooling)\n",
+    "- Azure Quantum client dependencies for submission\n",
+    "- Cirq for circuit construction\n",
+    "\n",
+    "After installing, restart the notebook kernel if it was already running. You can verify installation with:"
    ]
   },
   {
@@ -68,8 +71,9 @@
    "id": "e2b111db",
    "metadata": {},
    "source": [
-    "## Submitting a simple Cirq circuit\n",
-    "We'll build a small circuit creating a superposition on one qubit and flipping another, then measuring both. Afterwards we submit it to an Azure Quantum target."
+    "## Build a simple Cirq circuit\n",
+    "\n",
+    "We start with a Bell-state circuit with two named measurement keys — one per qubit. Named keys are required so the result dictionary has clearly labeled registers."
    ]
   },
   {
@@ -79,15 +83,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Build a simple circuit\n",
+    "import cirq\n",
+    "\n",
     "q0, q1 = cirq.LineQubit.range(2)\n",
-    "simple_circuit = cirq.Circuit(\n",
+    "circuit = cirq.Circuit(\n",
     "    cirq.H(q0),\n",
-    "    cirq.measure(q0, key='m0'),\n",
-    "    cirq.X(q1),\n",
-    "    cirq.measure(q1, key='m1'),\n",
+    "    cirq.CNOT(q0, q1),\n",
+    "    cirq.measure(q0, key=\"q0\"),\n",
+    "    cirq.measure(q1, key=\"q1\"),\n",
     ")\n",
-    "print(simple_circuit)"
+    "print(circuit)"
    ]
   },
   {
@@ -96,7 +101,8 @@
    "metadata": {},
    "source": [
     "## Configure Azure Quantum workspace connection\n",
-    "Replace the placeholder values below with your own subscription, resource group, workspace name, and location."
+    "\n",
+    "To connect to an Azure workspace replace the following variables with your own values."
    ]
   },
   {
@@ -113,42 +119,42 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "9f336702",
+   "cell_type": "markdown",
+   "id": "184b6e57",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "from qdk.openqasm import compile\n",
-    "from qdk.azure import Workspace\n",
-    "from qdk import TargetProfile\n",
-    "\n",
-    "def submit_cirq_circuit_to_azure(circuit: cirq.Circuit, target_name: str, name: str, shots: int = 100):\n",
-    "    # 1. Export to OpenQASM 3\n",
-    "    qasm3_str = circuit.to_qasm(version='3.0')\n",
-    "    # 2. Compile to QIR with a base target profile\n",
-    "    qir = compile(qasm3_str, target_profile=TargetProfile.Base)\n",
-    "    # 3. Connect workspace\n",
-    "    workspace = Workspace(\n",
-    "        subscription_id=subscription_id,\n",
-    "        resource_group=resource_group,\n",
-    "        name=workspace_name,\n",
-    "        location=location,\n",
-    "    )\n",
-    "    # 4. Select target (string e.g. 'rigetti.sim.qvm' or other available target)\n",
-    "    target = workspace.get_targets(target_name)\n",
-    "    # 5. Submit QIR payload\n",
-    "    job = target.submit(qir, name, shots=shots)\n",
-    "    return job.get_results()"
+    "## Submit the circuit to Azure Quantum\n",
+    "\n",
+    "`AzureQuantumService` exposes Azure Quantum targets as Cirq-compatible target objects. When you call `service.targets()`, the SDK returns one of two kinds of target:\n",
+    "\n",
+    "- **Provider-specific targets** — Some hardware vendors (e.g. IonQ, Quantinuum) ship dedicated Cirq target classes with native integration for their APIs, handling gate translation and result parsing using hardware-specific logic.\n",
+    "- **Generic QIR targets** — For any other target that accepts QIR input, the SDK automatically wraps it as an `AzureGenericQirCirqTarget`. These compile the Cirq circuit to OpenQASM 3 and then to QIR internally, so you don't have to manage those steps manually.\n",
+    "\n",
+    "In practice `service.targets()` selects the right type for each target — you use the same `service.create_job()` call regardless of which target type is returned."
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "a0436202",
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9f336702",
    "metadata": {},
+   "outputs": [],
    "source": [
-    "### Submit the simple circuit\n",
-    "(Make sure you changed the workspace credentials above.)"
+    "from qdk.azure import Workspace\n",
+    "from azure.quantum.cirq import AzureQuantumService\n",
+    "\n",
+    "workspace = Workspace(\n",
+    "    subscription_id=subscription_id,\n",
+    "    resource_group=resource_group,\n",
+    "    name=workspace_name,\n",
+    "    location=location,\n",
+    ")\n",
+    "\n",
+    "service = AzureQuantumService(workspace)\n",
+    "\n",
+    "# List available targets\n",
+    "for target in service.targets():\n",
+    "    print(f\"{target.name:45s}  {type(target).__name__}\")"
    ]
   },
   {
@@ -158,19 +164,53 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Uncomment after setting workspace credentials\n",
-    "# results = submit_cirq_circuit_to_azure(simple_circuit, 'rigetti.sim.qvm', 'cirq-simple-job')\n",
-    "# print(results)"
+    "from collections import Counter\n",
+    "\n",
+    "# Replace with any target name from the list above\n",
+    "target_name = \"rigetti.sim.qvm\"\n",
+    "\n",
+    "job = service.create_job(\n",
+    "    program=circuit,\n",
+    "    repetitions=100,\n",
+    "    name=\"cirq-bell-job\",\n",
+    "    target=target_name,\n",
+    ")\n",
+    "print(f\"Job {job.job_id()} submitted — waiting for results...\")\n",
+    "\n",
+    "result = job.results()\n",
+    "\n",
+    "# Combine separate measurement keys into joint bitstrings\n",
+    "keys = sorted(result.measurements.keys())\n",
+    "joint = Counter(\n",
+    "    \"\".join(str(int(result.measurements[k][i][0])) for k in keys)\n",
+    "    for i in range(len(result.measurements[keys[0]]))\n",
+    ")\n",
+    "total = sum(joint.values())\n",
+    "print(f\"\\nResults ({total} shots)  [keys: {', '.join(keys)}]:\")\n",
+    "for bitstring, count in sorted(joint.items()):\n",
+    "    print(f\"  {bitstring}: {count:4d}  ({count/total:.1%})\")"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "1478e88a",
    "metadata": {},
    "source": [
-    "## Notes\n",
-    "- Ensure all measurement keys appear before any classical condition usage if you introduce classical controls.\n",
-    "- Multi-target or custom gates may need full decomposition before submission if they produce unsupported classical constructs."
+    "## Handling qubit loss on noisy hardware\n",
+    "\n",
+    "On some hardware backends — particularly neutral-atom and trapped-ion devices — a qubit may be lost before measurement (e.g. an atom is ejected from the trap). When this happens, the backend records `\"-\"` in the bitstring position for that qubit rather than `\"0\"` or `\"1\"`. Because loss shots contain non-binary characters, they cannot be included in standard measurement arrays, which assume a fixed binary alphabet. The SDK therefore separates them automatically.\n",
+    "\n",
+    "The `cirq.ResultDict` returned by `job.results()` exposes two ways to access shots:\n",
+    "\n",
+    "| Field | What it contains |\n",
+    "|---|---|\n",
+    "| **`result.measurements[key]`** | NumPy int8 array of accepted shots only (no `\"-\"`), shape `(accepted_shots, num_qubits)` |\n",
+    "| **`result.raw_measurements()[key]`** | String array of all shots (loss shots have `\"-\"`), same key structure as `measurements` |\n",
+    "| **`result.raw_shots`** | The original shot objects exactly as returned by the backend |\n",
+    "\n",
+    "Use `result.measurements` for any downstream analysis that expects clean binary arrays. Use `result.raw_measurements()` and `result.raw_shots` to inspect loss patterns — for example, to calculate the overall loss rate or identify which qubit positions are being lost most frequently.\n",
+    "\n",
+    "> **Tip**: A high loss rate may indicate hardware instability or a circuit that is too deep for the current calibration."
    ]
   }
  ],