Skip to content

More serverless tweaks #4715

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abbycross merged 19 commits into from
Apr 6, 2026
Merged

More serverless tweaks #4715

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
5802ca6
code that creates file
abbycross Feb 24, 2026
a7f68e8
cspell:ignore
abbycross Feb 24, 2026
bc80eba
baby steps
abbycross Feb 24, 2026
69de71b
change to caution
abbycross Feb 24, 2026
995e615
Update serverless-first-program.ipynb
abbycross Feb 24, 2026
4144991
./fix
abbycross Feb 24, 2026
64be50b
wording
abbycross Feb 24, 2026
d8e1ac5
simplify headers
abbycross Feb 24, 2026
98fddb0
fix internal links
abbycross Feb 24, 2026
f5d5d55
move cell that creates dir
abbycross Feb 27, 2026
b8442ec
Remove Run from the workflow, specify
abbycross Feb 27, 2026
89b577b
rmv note about workloads table
abbycross Feb 27, 2026
525da01
tox -e fix
abbycross Feb 27, 2026
244c15f
Merge branch 'main' into ajc/serverless-feedback
abbycross Mar 31, 2026
4e9570a
add language about writefile
abbycross Mar 31, 2026
450c232
put in all relevant places
abbycross Mar 31, 2026
ef891cb
add link
abbycross Mar 31, 2026
746dc12
Apply suggestions from code review
abbycross Mar 31, 2026
bb4998a
catch the rest of the future tense
abbycross Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/guides/function-template-hamiltonian-simulation.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@
"\n",
"First, write a function template for Hamiltonian simulation that uses the [AQC-Tensor Qiskit addon](https://qiskit.github.io/qiskit-addon-aqc-tensor/) to map the problem description to a reduced-depth circuit for execution on hardware.\n",
"\n",
"Throughout, the code is saved to `./source_files/template_hamiltonian_simulation.py`. This file is the function template you can upload to and run remotely with Qiskit Serverless."
"If you download this page and view it locally in a notebook editor, you will see some of the code cells contain the [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#cellmagic-writefile) `%%writefile`. This magic command saves the code to `./source_files/template_hamiltonian_simulation.py`, which is the function template you can upload to and run remotely with Qiskit Serverless."
]
},
{
Expand Down
164 changes: 71 additions & 93 deletions docs/guides/serverless-first-program.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
Expand Down Expand Up @@ -56,49 +57,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)"
"After uploading your program , you can run it 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",
"\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",
"## Example: Remote transpilation with 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",
Comment thread
abbycross marked this conversation as resolved.
"\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",
Expand All @@ -112,12 +90,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. After 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\">\n",
"If you're reading the code cells locally in a notebook, you will see the `%%writefile` [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#cellmagic-writefile). Executing cells with this magic command saves them to disk rather than executing them.\n",
"</Admonition>"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "214eb803-d1fa-4ac0-b955-8b24717086f4",
"metadata": {},
"outputs": [],
"source": [
"# This cell is hidden from users, it 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,
Expand All @@ -126,17 +135,10 @@
},
"tags": []
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Writing ./source_files/transpile_remote.py\n"
]
}
],
"outputs": [],
"source": [
"%%writefile ./source_files/transpile_remote.py\n",
"# If you include the preceding `%%writefile` command (visible only when you read this locally in a notebook), running this cell saves to disk rather than executing the code.\n",
"\n",
"from qiskit.transpiler import generate_preset_pass_manager\n",
"\n",
Expand All @@ -155,29 +157,22 @@
"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",
"# If you include the preceding `%%writefile` command (visible only when you read this locally in a notebook), running this cell saves to disk rather than executing the code.\n",
"\n",
"from qiskit_serverless import get_arguments, save_result, distribute_task, get\n",
"\n",
Expand All @@ -193,27 +188,22 @@
"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",
"# If you include the preceding `%%writefile` command (visible only when you read this locally in a notebook), running this cell saves to disk rather than executing the code.\n",
"\n",
"from qiskit_ibm_runtime import QiskitRuntimeService\n",
"\n",
Expand All @@ -226,27 +216,22 @@
"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 returns 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",
"# If you include the preceding `%%writefile` command (visible only when you read this locally in a notebook), running this cell saves to disk rather than executing the code.\n",
"\n",
"# Each circuit is being transpiled and will populate the array\n",
"results = [\n",
" transpile_remote(circuit, 1, backend)\n",
" for circuit in circuits\n",
Expand All @@ -262,11 +247,10 @@
"id": "dac118ab-e447-4ddd-a5f8-d13e3953db76",
"metadata": {},
"source": [
"## Upload to Qiskit Serverless\n",
"<span id=\"upload-to-qiskit-serverless\"></span>\n",
"### Authenticate 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",
"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))."
]
},
{
Expand All @@ -287,7 +271,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 then cleaned up. The `entrypoint` identifies the main program executable for Qiskit Serverless to run."
]
},
{
Expand Down Expand Up @@ -330,7 +316,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:"
]
},
{
Expand Down Expand Up @@ -409,16 +397,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",
Expand Down
Loading
Loading