Updating Qiskit Serverless docs to support Qiskit 2.x

docs/getting_started/basic/01_running_program.ipynb

@@ -2,43 +2,85 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "id": "66030e20-b384-4dcf-9c5f-7664f7ad1693",
+   "id": "0544343d-7181-4016-a4f4-fb9df39c4bad",
    "metadata": {},
    "source": [
     "# Running a Qiskit Function as a function\n",
     "\n",
-    "In this tutorial, we will write a basic Qiskit Function using Qiskit Serverless. We will show how to run the function remotely and retrieve the results from the serverless client.\n",
+    "In this tutorial, you’ll learn how to create and run a <b>Qiskit Function</b> using <b>Qiskit Serverless</b>. A Qiskit Function is a self-contained Python script that can execute quantum workloads remotely on serverless infrastructure.\n",
+    "We’ll start by writing a simple function that:\n",
+    "\n",
+    " - Builds a two-qubit quantum circuit to create a Bell state.\n",
+    " - Transpiles the circuit for a target backend.\n",
+    " - Runs the circuit using the Sampler primitive.\n",
+    " - Saves the results so they can be retrieved later.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "77472550-b841-4546-b475-032eb4b62f99",
+   "metadata": {},
+   "source": [
+    "#### Install dependencies\n",
+    "\n",
+    "Before we begin, make sure the required packages are installed in your notebook environment:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "aa3aa259-e7c9-48c0-baa8-fe958280b0ad",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install qiskit qiskit-ibm-runtime qiskit-serverless"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "66030e20-b384-4dcf-9c5f-7664f7ad1693",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## Prep Work\n",
     "\n",
     "### Writing the Qiskit Function\n",
     "\n",
-    "First, we need to write the function code and save it to a file called [function.py](./source_files/function.py). This function creates a two-qubit quantum circuit that prepares a Bell state, measures the result, and saves the measured probability distribution.\n",
+    "First, we need to write the function code and save it to a file called [function.py](./source_files/function.py). This function will contain the logic for our Qiskit Function. For this example, we will creates a two-qubit quantum circuit that prepares a Bell state, measures the result, and saves the measured probability distribution.\n",
     "\n",
     "The code for the function is shown below:\n",
     "\n",
     "```python\n",
     "from qiskit import QuantumCircuit\n",
-    "from qiskit.primitives import Sampler\n",
-    "\n",
+    "from qiskit.transpiler import generate_preset_pass_manager\n",
+    "from qiskit_ibm_runtime import SamplerV2 as Sampler\n",
+    "from qiskit_ibm_runtime.fake_provider import FakeVigoV2\n",
     "from qiskit_serverless import save_result\n",
     "\n",
     "# all print statement will be available in job logs\n",
     "print(\"Running function...\")\n",
     "\n",
-    "# creating circuit\n",
+    "# Step 1: Create a Bell-state circuit\n",
     "circuit = QuantumCircuit(2)\n",
     "circuit.h(0)\n",
     "circuit.cx(0, 1)\n",
     "circuit.measure_all()\n",
     "\n",
-    "# running Sampler primitive\n",
-    "sampler = Sampler()\n",
-    "quasi_dists = sampler.run(circuit).result().quasi_dists\n",
+    "# Step 2: Transpile for a fake backend (for demonstration)\n",
+    "backend = FakeVigoV2()\n",
+    "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n",
+    "isa_circuit = pm.run(circuit)\n",
     "\n",
-    "# save results of function execution, \n",
-    "# which will be accessible by calling `.result()`\n",
+    "# Step 3: Run the Sampler primitive\n",
+    "sampler = Sampler(backend)\n",
+    "quasi_dists = sampler.run([isa_circuit]).result()[0].data.meas.get_counts()\n",
+    "\n",
+    "\n",
+    "# Step 4: Save results so they can be retrieved later by calling `.result()`\n",
     "save_result(quasi_dists)\n",
     "print(\"Completed running function.\")\n",
     "```\n",
+    "Now that we’ve written our Qiskit Function, the next step is to deploy it to the serverless environment so it can run remotely.\n",
     "\n",
     "### Deploying the function\n",
     "\n",
@@ -86,6 +128,7 @@
    "source": [
     "client = ServerlessClient(\n",
     "    token=os.environ.get(\"GATEWAY_TOKEN\", \"awesome_token\"),\n",
+    "    instance=os.environ.get(\"GATEWAY_INSTANCE\", \"an_awesome_crn\"),\n",
     "    host=os.environ.get(\"GATEWAY_HOST\", \"http://localhost:8000\"),\n",
     "    # If you are using the kubernetes approach the URL must be http://localhost\n",
     ")\n",
@@ -98,17 +141,17 @@
    "id": "4dd85621-9ab0-4f34-9ab4-07ad773c5e00",
    "metadata": {},
    "source": [
+    "### Create a Qiskit Function object\n",
     "\n",
-    "\n",
-    "`QiskitFunction` accepts couple of required parameters:\n",
+    "A `QiskitFunction` represents the function you want to run. It includes:\n",
     "\n",
     "- title - name of the Qiskit Function\n",
-    "- entrypoint - name of python file you want to execute\n",
-    "- working_dir - directory where  your script is located (directory size must be less than 50MB). This is optional parameter and will be current folder by default.\n",
+    "- entrypoint - the name of the python file that will be executed.\n",
+    "- working_dir - directory where your script is located (directory size must be less than 50MB). This is optional parameter and will be current folder by default.\n",
     "\n",
-    "> Warning! All content of `working_dir` will be shipped to cluster for execution\n",
+    "This tells the serverless system what code to run and what supporting files to include. Everything in working_dir will be packaged and shipped to the compute node.\n",
     "\n",
-    "> Warning! Execution of `upload` function ships All content of `working_dir`.  When the contents of `working_dir` is changed, the `upload` function must be called again to update the shipped directory contents."
+    "> Warning! All content of `working_dir` will be shipped to cluster for execution\n"
    ]
   },
   {
@@ -132,9 +175,30 @@
     "from qiskit_serverless import QiskitFunction\n",
     "\n",
     "function = QiskitFunction(\n",
-    "    title=\"my-first-function\", entrypoint=\"function.py\", working_dir=\"./source_files/\"\n",
-    ")\n",
+    "    title=\"my-first-function\",\n",
+    "    entrypoint=\"function.py\",\n",
+    "    working_dir=\"./source_files/\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a23d9f80-6634-48ca-9cc0-5c2146101848",
+   "metadata": {},
+   "source": [
+    "### Upload the function\n",
+    "Once the function object is created, upload it to the gateway so it can be executed later:\n",
     "\n",
+    "> Warning! Execution of `upload` function ships All content of `working_dir`.  When the contents of `working_dir` is changed, the `upload` function must be called again to update the shipped directory contents."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f2a17837-e4b8-4ea4-a9ed-97358a06f705",
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "client.upload(function)"
    ]
   },
@@ -143,9 +207,9 @@
    "id": "3e5326e2-9ff8-48e8-a8a9-18716633fd01",
    "metadata": {},
    "source": [
-    "### Running the QiskitFunction\n",
+    "## Running the QiskitFunction\n",
     "\n",
-    "After deploying the QiskitFunction, we can see our function in a `list` of availiable functions."
+    "After deploying the QiskitFunction, we can he function by its title:"
    ]
   },
   {
@@ -175,7 +239,7 @@
    "id": "135eda5f",
    "metadata": {},
    "source": [
-    "We can run any function by calling `run` method on function object."
+    "We can run any function by calling `run` method on function object. This will make the job run on the gateway:"
    ]
   },
   {
@@ -187,7 +251,7 @@
     {
      "data": {
       "text/plain": [
-       "<Job | 860c98e2-ec3c-4197-8042-115ec3c6f5e8>"
+       "<Job | a8b0be5a-ff24-4132-b706-9bac096790ae>"
       ]
      },
      "execution_count": 5,
@@ -205,22 +269,22 @@
    "id": "39ee31d2-3553-4e19-bcb9-4cccd0df0e4c",
    "metadata": {},
    "source": [
-    "[Job](https://qiskit.github.io/qiskit-serverless/stubs/qiskit_serverless.core.Job.html#qiskit_serverless.core.Job) instances have a `status()` method to check status of the function execution."
+    "A [Job](https://qiskit.github.io/qiskit-serverless/stubs/qiskit_serverless.core.Job.html#qiskit_serverless.core.Job) instances have a `status()` method to check status of the function execution. It will help us monitor the status of our job:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 6,
    "id": "cc7ccea6-bbae-4184-ba7f-67b6c20a0b0b",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "'DONE'"
+       "'QUEUED'"
       ]
      },
-     "execution_count": 15,
+     "execution_count": 6,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -234,22 +298,22 @@
    "id": "f496adbe-3d82-4aad-b86b-6adb3b9d287d",
    "metadata": {},
    "source": [
-    "`Job` instances also have a `result()` method for retrieving results. The `result()` method will not return until the job is done running the function."
+    "We can retrieve the result by calling the `result()` method of an instanced `Job` object. The `result()` method will not return until the job is done running the function."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 7,
    "id": "ca05d063",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "{'00': 539, '11': 485}"
+       "{'11': 535, '00': 489}"
       ]
      },
-     "execution_count": 16,
+     "execution_count": 7,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -263,20 +327,20 @@
    "id": "719d3572",
    "metadata": {},
    "source": [
-    "To inspect the logs from a function, access them from the ``Job`` instance."
+    "To inspect the logs from a function for debugging or analysis, you can access them from the ``Job`` instance."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 8,
    "id": "eb5ec85f",
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2024-12-05 17:26:40,785\tINFO job_manager.py:531 -- Runtime env is setting up.\n",
+      "2025-11-03 10:03:01,072\tINFO job_manager.py:531 -- Runtime env is setting up.\n",
       "Running function...\n",
       "Completed running function.\n",
       "\n"
@@ -308,9 +372,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "Python (qiskit_serverless test venv)",
    "language": "python",
-   "name": "python3"
+   "name": "qiskit_serverless_test_venv"
   },
   "language_info": {
    "codemirror_mode": {
@@ -322,7 +386,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "version": "3.13.7"
   }
  },
  "nbformat": 4,