More serverless tweaks

docs/guides/serverless-first-program.ipynb

@@ -10,6 +10,7 @@
     "description: How to create a parallel transpilation program and deploy it to IBM Quantum Platform to use as a reusable remote service.\n",
     "---\n",
     "\n",
+    "{/* cspell:ignore mypath  */}\n",
     "\n",
     "# Write your first Qiskit Serverless program"
    ]
@@ -55,49 +56,26 @@
     "    **Qiskit Serverless is getting an upgrade, and its features are changing fast.** During this development phase, find release notes and the most recent documentation at the [Qiskit Serverless GitHub](https://qiskit.github.io/qiskit-serverless/index.html) page.\n",
     "</Admonition>\n",
     "\n",
-    "This example demonstrates how to use `qiskit-serverless` tools to create a parallel transpilation program, and then implement `qiskit-ibm-catalog` to deploy your program to IBM Quantum Platform to use as a reusable remote service.\n",
+    "This example demonstrates how to use `qiskit-serverless` tools to create a parallel transpilation program, and then implement `qiskit-ibm-catalog` to upload your program to IBM Quantum Platform to use as a reusable remote service.\n",
     "\n",
-    "Workflow overview:\n",
+    "## Workflow overview\n",
     "\n",
-    "1. Create local program file that transpiles a circuit\n",
-    "1. Add code to your program to receive inputs (`circuits`, `backend_name`, and `optimization_level`)\n",
-    "1. Authenticate to the Qiskit Runtime service and load a backend\n",
+    "1. Create a local directory and empty program file (`./source_files/transpile_remote.py`)\n",
+    "1. Add code to your program that, when uploaded to Qiskit Serverless, will transpile a circuit\n",
     "1. Use `qiskit-ibm-catalog` to authenticate to Qiskit Serverless\n",
-    "1. Upload the program result\n",
-    "1. Run the program"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "id": "b186515d-7686-43c3-94a6-187eba0808b9",
-   "metadata": {
-    "editable": true,
-    "slideshow": {
-     "slide_type": ""
-    },
-    "tags": [
-     "remove-cell"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "# This cell is hidden from users, it just creates a new folder\n",
-    "from pathlib import Path\n",
+    "1. Upload the program to Qiskit Serverless\n",
     "\n",
-    "Path(\"./source_files\").mkdir(exist_ok=True)"
+    "Once you have completed the workflow steps above, you can then run your uploaded program to transpile the circuit by following the [Run your first Qiskit Serverless workload remotely](/docs/guides/serverless-run-first-workload) guide."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "cad16f43-8548-4849-a4b8-09059a8b747c",
    "metadata": {},
    "source": [
-    "## Example: remote transpilation with Qiskit Serverless\n",
+    "## Example: Remote transpilation with Qiskit Serverless\n",
     "\n",
-    "Start with the following example that transpiles a `circuit` against a given `backend` and target `optimization_level`, and gradually add more elements to deploy your workload to Qiskit Serverless.\n",
-    "\n",
-    "Serverless uploads the contents of a specific directory (in this example, the `source_files` directory) to run remotely. Once these are set up, you can adjust `transpile_remote.py` to fetch inputs and return outputs.\n",
+    "This example walks you through creating and adding to a program file that, when you upload it to Qiskit Serverless, will transpile a `circuit` against a given `backend` and target `optimization_level`.\n",
     "\n",
     "<Admonition type=\"tip\">\n",
     "Qiskit Serverless requires setting up your workload’s `.py` files into a dedicated directory. The following structure is an example of good practice:\n",
@@ -111,12 +89,43 @@
     "```\n",
     "</Admonition>\n",
     "\n",
-    "First, run the following code cell to create a program file, `./source_files/transpile_remote.py`, which you will upload to Qiskit Serverless."
+    "Serverless uploads the contents of a specific directory (in this example, the `source_files` directory) to run remotely. Once these are set up, you can adjust `transpile_remote.py` to fetch inputs and return outputs.\n",
+    "\n",
+    "### Create the directory and an empty program file\n",
+    "\n",
+    "First, create a directory named `source_files`, then create a program file in the directory, so that its path is `./source_files/transpile_remote.py`. This is the file you will upload to Qiskit Serverless."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a9b3fb7d-abd6-4a3e-b9b1-b21202d8db6d",
+   "metadata": {},
+   "source": [
+    "### Add code to your program file\n",
+    "\n",
+    "Populate your program file with the following code, then save it.\n",
+    "\n",
+    "<Admonition type=\"caution\" title=\"This Jupyter notebook contains hidden cells and IPython magic commands\">\n",
+    "Note that if you download this notebook and run all cells, a hidden cell will create the `source_files` directory, and IPython magic commands embedded in some of the cells will automatically create and append to the `./source_files/transpile_remote.py` file. You can view the hidden cell and magic commands when you open the downloaded notebook file.\n",
+    "</Admonition>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "214eb803-d1fa-4ac0-b955-8b24717086f4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This cell is hidden from users, it just creates a new folder\n",
+    "from pathlib import Path\n",
+    "\n",
+    "Path(\"./source_files\").mkdir(exist_ok=True)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "64722041-22ed-42bd-8d83-d8e9f5e5b55b",
    "metadata": {
     "editable": true,
@@ -125,15 +134,7 @@
     },
     "tags": []
    },
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Writing ./source_files/transpile_remote.py\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "%%writefile ./source_files/transpile_remote.py\n",
     "\n",
@@ -154,27 +155,19 @@
    "id": "7e80b5bb-0f76-43d1-a68c-97b4b22cc88a",
    "metadata": {},
    "source": [
-    "### Get program arguments\n",
+    "### Add code to get program arguments\n",
     "\n",
-    "Your initial `transpile_remote.py` has three inputs: `circuits`, `backend_name`, and `optimization_level`. Serverless is currently limited to only accept serializable inputs and outputs. For this reason, you cannot pass in `backend` directly, so use `backend_name` as a string instead.\n",
+    "Now add the following code to your program file, which sets up program arguments.\n",
     "\n",
-    "The following cell appends code to your `transpile_remote.py` file."
+    "Your initial `transpile_remote.py` has three inputs: `circuits`, `backend_name`, and `optimization_level`. Serverless is currently limited to only accept serializable inputs and outputs. For this reason, you cannot pass in `backend` directly, so use `backend_name` as a string instead."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "6819379b-d7b2-4fda-9e6b-459eec748a79",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Appending to ./source_files/transpile_remote.py\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "%%writefile --append ./source_files/transpile_remote.py\n",
     "\n",
@@ -192,25 +185,19 @@
    "id": "5ae9fb12-f06f-4f7d-8f37-1d872285deab",
    "metadata": {},
    "source": [
-    "At this point, you can get your backend with `QiskitRuntimeService` and add your existing program with the following code.\n",
+    "### Add code that calls the backend\n",
+    "\n",
+    "Add the following code to your program file, which calls your backend with `QiskitRuntimeService`.\n",
     "\n",
     "The following code assumes that you have already followed the process to save your credentials by using `QiskitRuntimeService.save_account`, and will load your default saved account unless you specify otherwise. See [Save your login credentials](/docs/guides/save-credentials) and [Initialize your Qiskit Runtime service account](/docs/guides/initialize-account) for more information."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "id": "4b0c7d24-9b87-4e00-bb1d-f82aa967cb1d",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Appending to ./source_files/transpile_remote.py\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "%%writefile --append ./source_files/transpile_remote.py\n",
     "\n",
@@ -225,23 +212,17 @@
    "id": "61e7cb3b-6d62-4b68-817a-39c0c1d95a9b",
    "metadata": {},
    "source": [
-    "Finally, you can run `transpile_remote()` across all `circuits` passed in, and return the `transpiled_circuits` as a result:"
+    "### Add code to transpile\n",
+    "\n",
+    "Finally, add the following code to your program file. This code runs `transpile_remote()` across all `circuits` passed in, and return the `transpiled_circuits` as a result:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "041e7f85-e9e8-424d-8694-d54316225cc4",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Appending to ./source_files/transpile_remote.py\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Each circuit is being transpiled and will populate the array\n",
     "%%writefile --append ./source_files/transpile_remote.py\n",
@@ -261,11 +242,10 @@
    "id": "dac118ab-e447-4ddd-a5f8-d13e3953db76",
    "metadata": {},
    "source": [
-    "## Upload to Qiskit Serverless\n",
-    "\n",
-    "The previous section created a program to be run remotely. The following code cells upload that program to Qiskit Serverless, before running the workload (which is demonstrated in the [Run your first Qiskit Serverless workload remotely](/docs/guides/serverless-run-first-workload) guide).\n",
+    "<span id=\"upload-to-qiskit-serverless\"></span>\n",
+    "### Authenticate to Qiskit Serverless\n",
     "\n",
-    "Use `qiskit-ibm-catalog` to authenticate to `QiskitServerless` with your API key (use your same key as before, or you can create a new API key on the [IBM Quantum Platform dashboard](https://quantum.cloud.ibm.com))."
+    "Use `qiskit-ibm-catalog` to authenticate to `QiskitServerless` with your API key (you can use your `QiskitRuntimeService` API key, or create a new API key on the [IBM Quantum Platform dashboard](https://quantum.cloud.ibm.com))."
    ]
   },
   {
@@ -286,7 +266,9 @@
    "id": "a0f64820-5fb1-41b9-9cb4-5095d0b5db43",
    "metadata": {},
    "source": [
-    "Now you can upload the program. Qiskit Serverless compresses the contents of `working_dir` (in this case, `source_files`) into a `tar`, which is uploaded and cleaned up after. The `entrypoint` identifies the main program executable for Qiskit Serverless to run."
+    "### Run code to upload\n",
+    "\n",
+    "Run the following code to upload the program. Qiskit Serverless compresses the contents of `working_dir` (in this case, `source_files`) into a `tar`, which is uploaded and cleaned up after. The `entrypoint` identifies the main program executable for Qiskit Serverless to run."
    ]
   },
   {
@@ -329,7 +311,9 @@
    "id": "3a840c18-3010-4d05-91cb-592e2692c1d7",
    "metadata": {},
    "source": [
-    "To check if it successfully uploaded, use `serverless.list()`:"
+    "### Verify upload\n",
+    "\n",
+    "To check if it successfully uploaded, use `serverless.list()`, as in the following code:"
    ]
   },
   {
@@ -408,16 +392,6 @@
     "        break"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "6ff556c1-64bb-41ae-9c6c-9019a3cab9ca",
-   "metadata": {},
-   "source": [
-    "<Admonition type=\"tip\">\n",
-    "Currently, the [Workloads table](https://quantum.cloud.ibm.com/workloads) on IBM Quantum Platform only reflects Qiskit Runtime workloads. To see the status of your Qiskit Serverless workloads, use `job.status()`. Find an example in the [Run your first Qiskit Serverless workload remotely](/docs/guides/serverless-run-first-workload#serverless-job-status) guide.\n",
-    "</Admonition>"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "a416b143-6f70-49dc-ab2f-ad66f042cab1",

docs/guides/serverless-run-first-workload.ipynb

@@ -48,7 +48,7 @@
     "\n",
     "This section explores how to use `qiskit-ibm-catalog` to list programs available in Qiskit Serverless, pass inputs into these programs, run them remotely, check their status, and retrieve results and logs.\n",
     "\n",
-    "Be sure you have authenticated to Qiskit Serverless using your [API key](https://quantum.cloud.ibm.com/) (see [Upload to Qiskit Serverless](/docs/guides/serverless-first-program#upload-to-qiskit-serverless) for instructions)."
+    "Be sure you have followed the workflow in [Write your first Qiskit Serverless program](/docs/guides/serverless-first-program) before you begin."
    ]
   },
   {