diff --git a/docs/guides/serverless-first-program.ipynb b/docs/guides/serverless-first-program.ipynb index 5a9da5e3771..f9225fe5a59 100644 --- a/docs/guides/serverless-first-program.ipynb +++ b/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,37 +56,16 @@ " **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", "\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." ] }, { @@ -93,11 +73,9 @@ "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", "\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", "\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", + "" + ] + }, + { + "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,7 +212,9 @@ "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:" ] }, { @@ -233,15 +222,7 @@ "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", + "\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": [ - "\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", - "" - ] - }, { "cell_type": "markdown", "id": "a416b143-6f70-49dc-ab2f-ad66f042cab1", diff --git a/docs/guides/serverless-run-first-workload.ipynb b/docs/guides/serverless-run-first-workload.ipynb index 110b090d207..2c7582294fc 100644 --- a/docs/guides/serverless-run-first-workload.ipynb +++ b/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." ] }, {