Skip to content

Document new runtime options #3246

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

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Document new runtime options #3246

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a870b52
Can specify CRN or instance name
beckykd Jun 2, 2025
c328d92
update provider values to use quantum_platform
beckykd Jun 6, 2025
3db69a0
can set account preferences
beckykd Jun 9, 2025
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
11 changes: 8 additions & 3 deletions docs/guides/cloud-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,21 +49,26 @@ Your user account is associated with one or more [instances](./instances) that g

1. Find your access credentials.
1. Find your API key. From the [dashboard](https://quantum.cloud.ibm.com/), create your API key, then copy it to a secure location so you can use it for authentication.
2. Find your CRN from the Instances section of the dashboard. Click the icon to copy your CRN for the instance you want to use, then save it in a secure location so you can use it for authentication.
2. Optional: Find your CRN from the Instances section of the dashboard. Click the icon to copy your CRN for the instance you want to use, then save it in a secure location so you can use it to identify the instance.

1. <span id="cloud-save"></span>**If you are working in a trusted Python environment (such as on a personal laptop or workstation),** use the `save_account()` method to save your credentials locally. ([Skip to the next step](#cloud-untrusted) if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Cloud.) To use `save_account()`, activate a Python virtual environment. Then, run Python in your virtual environment and enter the following:


```python
token = "<your-API-token>"
```
<Admonition type="Note">
When an instance CRN or name is passed in, only backends and jobs from that instance are available. If an instance is not specified, all backends and jobs across all instances in your account are available. In this case, when a backend is specified, an instance that can access that backend is found and used.
</Admonition>

```python
from qiskit_ibm_runtime import QiskitRuntimeService
service = QiskitRuntimeService.save_account(
token=token, # Your token is confidential.
# Do not share your key in public code.
instance="<IBM Cloud CRN>",
instance="<IBM Cloud CRN or instance name>", # Optionally specify the instance to use.
plans_preference="['plan-type1', 'plan-type2']", # Optionally set the types of plans to prioritize. This is ignored if the instance is specified.
region="<region>", # Optionally set the region to prioritize.
name="<account-name>", # Optionally name this set of account credentials.
set_as_default=True, # Optionally set these as your default credentials.
)
Expand Down Expand Up @@ -101,7 +106,7 @@ Your user account is associated with one or more [instances](./instances) that g
service = QiskitRuntimeService(
# Delete your key on the API keys page after entering this code:
token="<IBM Cloud API key>",
instance="<IBM Cloud CRN>"
instance="<IBM Cloud CRN or instance name>"
)
```

Expand Down
22 changes: 17 additions & 5 deletions docs/guides/instances.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,16 +53,16 @@
"<CloudContent>\n",
"Access to IBM Quantum Platform services is controlled by the **instances** to which you are assigned. Users can belong to more than one instance at any given time.\n",
"\n",
"An instance is a deployment of Qiskit Runtime. You need a different instance for every service plan (such as Open or Standard) you use in every region that you want to use. The account manager and anyone with enough permission can create an instance and define its configuration, such as its allocations, usage limits, quantum computers, and user permissions. Each instance is identified by a unique Cloud Resource Name (CRN). This CRN is used when sending workloads from your Qiskit programs.\n",
"An instance is a deployment of Qiskit Runtime. You need a different instance for every service plan (such as Open or Standard) you use in every region that you want to use. The account manager and anyone with enough permission can create an instance and define its configuration, such as its allocations, usage limits, quantum computers, and user permissions. Each instance is identified by a unique Cloud Resource Name (CRN). This CRN can be used when sending workloads from your Qiskit programs.\n",
"\n",
"The IBM Quantum Platform [dashboard](https://quantum.cloud.ibm.com/) displays the instances to which you have access. You can view full details, edit, and delete instances on the [Instances page.](https://quantum.cloud.ibm.com/instances)\n",
"The IBM Quantum Platform [dashboard](https://quantum.cloud.ibm.com/) displays the instances to which you have access. Depending on your access, you can view full details, edit, and delete instances on the [Instances page.](https://quantum.cloud.ibm.com/instances)\n",
"\n",
"It is important that you understand which instance you are using, because all instances that are not associated with the Open Plan incur a cost.\n",
"</CloudContent>\n",
"<span id=\"open-plan\"></span>\n",
"## Open Plan instance\n",
"<LegacyContent>\n",
"By default, users who sign up for an IBM Quantum account are assigned to the Open Plan and the Open Plan's instance, `ibm-q/open/main`. To guarantee that everyone can use the quantum computers allocated to the plan fairly, **an individual can have no more than three jobs running and/or in the queue (across all quantum computers) at the same time.** Submitting more than three jobs at a time will return error [#3458](../errors#3458), and additional jobs will be canceled.\n",
"By default, users who sign up for an IBM Quantum account are assigned to the Open Plan and the Open Plan's instance, `ibm-q/open/main`. To guarantee that everyone can use the quantum computers allocated to the plan fairly, **an individual can have no more than three jobs running or queued (across all quantum computers) at the same time.** Submitting more than three jobs at a time will return error [#3458](../errors#3458), and additional jobs will be canceled.\n",
"\n",
"Those using the Open Plan instance have up to 10 minutes total of quantum time per month, which resets at 00:00:00 UTC on the first of each calendar month. Open Plan users can track their usage on the [Platform dashboard,](https://quantum.ibm.com/) [Workloads,](https://quantum.ibm.com/workloads) and [Account](https://quantum.ibm.com/account) pages.\n",
"</LegacyContent>\n",
Expand Down Expand Up @@ -149,10 +149,22 @@
"\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"You must use the CRN to specify an instance to use; either when initializing the service or when sending the workload to a QPU. The instance's CRN is listed on the [Platform dashboard](https://quantum.cloud.ibm.com/). Before running the below code, follow the steps to [save an account.](/docs/guides/cloud-setup#cloud-save)\n",
"You can use the CRN or instance name to specify an instance to use; either when initializing the service or when sending the workload to a QPU. When an instance is passed in, only backends and jobs from that instance are available.\n",
"\n",
"<Admonition type=\"note\">\n",
"If an instance is not included, all backends and jobs across all instances in your account are available. In this case, when a backend is specified, an instance that can access the backend is found and used in the following order:\n",
"\n",
"1. If your account only has access to one instance, it is selected by default.\n",
"1. If an instance was passed into [`save_account()`,](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#save_account) it is used.\n",
"2. If your account has access to multiple instances but only one can access the requested QPU, the instance with access is selected. If this instance is not associated with a free plan, a cost will be incurred.\n",
"3. If your account has access to multiple instances that can access the requested QPU, the system uses your specified plan preferences (set on the [`QiskitRuntimeService()`](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#qiskitruntimeservice) initializer or the [`save_account()`](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#save_account) method) to choose a plan and instance.\n",
"</Admonition>\n",
"\n",
"The instance's CRN is listed on the [Platform dashboard](https://quantum.cloud.ibm.com/). Before running the below code, follow the steps to [save an account.](/docs/guides/cloud-setup#cloud-save)\n",
"\n",
"```python\n",
"# Specify an instance at service level. This becomes the default unless overwritten.\n",
"# Optional: Specify an instance at service level.\n",
"# This becomes the default unless overwritten.\n",
"service = QiskitRuntimeService(instance=\"<CRN>\")\n",
"backend = service.backend(\"<QPU-name>\")\n",
"```\n",
Expand Down
2 changes: 1 addition & 1 deletion docs/guides/native-gates.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@
"\n",
"from qiskit_ibm_runtime import QiskitRuntimeService\n",
"\n",
"service = QiskitRuntimeService(channel=\"ibm_cloud\")\n",
"service = QiskitRuntimeService(channel=\"ibm_quantum_platform\")\n",
"\n",
"for backend in service.backends():\n",
" config = backend.configuration()\n",
Expand Down
9 changes: 7 additions & 2 deletions docs/guides/retired-qpus.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,11 +114,16 @@
"```\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"\n",
"<Admonition type=\"Note\">\n",
"Passing in a Cloud Resource Name (CRN) or name in the following code is optional. When it is passed in, only backends and jobs from that instance are available. If an instance is not specified, all backends and jobs across all instances in your account are available. In this case, when a backend is specified, an instance that can access that backend is found and used.\n",
"</Admonition>\n",
"\n",
"```python\n",
"from qiskit_ibm_runtime import QiskitRuntimeService\n",
"\n",
"# Load your IBM Quantum account(s). Replace \"<IBM Cloud CRN>\" with your desired instance's CRN\n",
"service = QiskitRuntimeService(channel=\"ibm_cloud\", instance=\"<IBM Cloud CRN>\")\n",
"# Load your IBM Quantum account. Replace \"<IBM Cloud CRN>\" with your desired instance's CRN or name.\n",
"service = QiskitRuntimeService(channel=\"ibm_quantum_platform\", instance=\"<IBM Cloud CRN or Name>\")\n",
"\n",
"# Retrieve a single job by id\n",
"job = service.job(<job_id>)\n",
Expand Down
127 changes: 127 additions & 0 deletions docs/guides/retired-qpus.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
title: Retired QPUs
description: A list of IBM quantum processing units (QPUs) that are now retired

---


# Retired QPUs

<LegacyContent>
<Admonition type="note">
This documentation is relevant to IBM Quantum&reg; Platform Classic. If you need the newer version, go to the new [IBM Quantum Platform documentation.](https://quantum.cloud.ibm.com/docs/guides/retired-qpus)
</Admonition>

The following IBM&reg; quantum processing units (QPUs) have been retired. For the full list of available QPUs, see the [Compute resources page](https://quantum.ibm.com/services/resources). By default, the information is shown in the card view, but you can use the view switchers (![view-switcher icon](/docs/images/guides/retired-qpus/view-switcher1.avif)) at the top right to change to a sortable table view.
</LegacyContent>
<CloudContent>
<Admonition type="note">
This documentation is relevant to the new IBM Quantum&reg; Platform. If you need the previous version, return to the [IBM Quantum Platform Classic documentation.](https://docs.quantum.ibm.com/guides/retired-qpus)
</Admonition>

The following IBM&reg; quantum processing units (QPUs) have been retired. For the full list of available QPUs, see the [Compute resources page](https://quantum.cloud.ibm.com/computers).
</CloudContent>

<Admonition type="note">
To retrieve jobs from a retired QPU, see [these instructions.](#retrieve)
</Admonition>


| QPU name | Qubit count | Retirement date (Year - month - day) |
| ----------------- | ----------- | --------------- |
| ibm_kyiv | **127** | 2025-04-18 |
| ibm_nazca | **127** | 2024-12-04 |
| ibm_kyoto | **127** | 2024-09-05 |
| ibm_osaka | **127** | 2024-08-13 |
| ibm_cusco | **127** | 2024-08-13 |
| ibm_algiers | **27** | 2024-04-30 |
| ibm_cairo | **27** | 2024-04-30 |
| ibm_hanoi | **27** | 2024-04-30 |
| ibmq_kolkata | **27** | 2024-04-01 |
| ibmq_mumbai | **27** | 2024-04-01 |
| ibm_ithaca | **65** | 2024-01-24 |
| ibm_nairobi | **7** | 2023-11-28 |
| ibm_lagos | **7** | 2023-11-28 |
| ibm_perth | **7** | 2023-11-28 |
| ibm_auckland | **27** | 2023-11-09 |
| ibmq_guadalupe | **16** | 2023-10-27 |
| ibmq_lima | **5** | 2023-09-26 |
| ibmq_belem | **5** | 2023-09-26 |
| ibmq_quito | **5** | 2023-09-26 |
| ibmq_manila | **5** | 2023-09-26 |
| ibmq_jakarta | **7** | 2023-09-26 |
| ibm_seattle | **433** | 2023-09-07 |
| ibm_washington | **127** | 2023-06-03 |
| ibmq_oslo | **7** | 2023-05-04 |
| ibmq_geneva | **27** | 2023-05-04 |
| ibmq_montreal | **27** | 2023-04-11 |
| ibmq_toronto | **27** | 2023-04-11 |
| ibmq_armonk | **1** | 2022-07-07 |
| ibmq_brooklyn | **65** | 2022-06-28 |
| ibmq_bogota | **5** | 2022-06-17 |
| ibmq_santiago | **5** | 2022-06-17 |
| ibmq_casablanca | **7** | 2022-03-02 |
| ibmq_sydney | **27** | 2022-01-11 |
| ibmq_dublin | **27** | 2021-11-16 |
| ibmq_manhattan | **65** | 2021-09-22 |
| ibmq_5_yorktown | **5** | 2021-08-09 |
| ibmq_16_melbourne | **15** | 2021-08-09 |
| ibmq_paris | **27** | 2021-06-30 |
| ibmq_rome | **5** | 2021-06-30 |
| ibmq_athens | **5** | 2021-06-30 |
| ibmq_berlin | **27** | 2020-12-31 |
| ibmq_boeblingen | **20** | 2021-01-31 |
| ibmq_ourense | **5** | 2021-01-15 |
| ibmq_vigo | **5** | 2021-01-15 |
| ibmq_valencia | **5** | 2021-01-15 |
| ibmq_rochester | **53** | 2020-10-31 |
| ibmq_cambridge | **28** | 2020-10-31 |
| ibmq_almaden | **20** | 2020-08-31 |
| ibmq_singapore | **20** | 2020-08-31 |
| ibmq_johannesburg | **20** | 2020-08-31 |
| ibmq_essex | **5** | 2020-08-31 |
| ibmq_burlington | **5** | 2020-08-31 |
| ibmq_london | **5** | 2020-08-31 |


<span id="retrieve"></span>
## Retrieve a job from a retired QPU

Use the following code to retrieve a job from a retired QPU.

<LegacyContent>
```python
from qiskit_ibm_runtime import QiskitRuntimeService

# Load your IBM Quantum account(s). Replace "hub/group/project" with your desired instance
service = QiskitRuntimeService(channel="ibm_quantum", instance="hub/group/project")

# Retrieve a single job by id
job = service.job(<job_id>)

# Retrieve a batch of jobs. Filtering options can be found in the QiskitRuntimeService.jobs api reference
jobs = service.jobs(backend_name=<backend_name>)
```
</LegacyContent>
<CloudContent>

<Admonition type="Note">
Passing in a Cloud Resource Name (CRN) or name in the following code is optional. When it is passed in, only backends and jobs from that instance are available. If an instance is not specified, all backends and jobs across all instances in your account are available. In this case, when a backend is specified, an instance that can access that backend is found and used.
</Admonition>

```python
from qiskit_ibm_runtime import QiskitRuntimeService

# Load your IBM Quantum account. Replace "<IBM Cloud CRN>" with your desired instance's CRN or name.
service = QiskitRuntimeService(channel="ibm_quantum_platform", instance="<IBM Cloud CRN or Name>")

# Retrieve a single job by id
job = service.job(<job_id>)

# Retrieve a batch of jobs. Filtering options can be found in the QiskitRuntimeService.jobs api reference
jobs = service.jobs(backend_name=<backend_name>)
```
</CloudContent>
<Admonition type="note" title="Deprecated provider packages">
`service.jobs()` returns jobs run from both `qiskit-ibm-runtime` and the deprecated `qiskit-ibm-provider` package. Jobs submitted by the older (also deprecated) `qiskit-ibmq-provider` package are no longer available.
</Admonition>
2 changes: 1 addition & 1 deletion docs/guides/serverless-port-code.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@
"qc_random = [(random_circuit(20, 20, measure=True)) for _ in range(30)]\n",
"optimization_level = 3\n",
"\n",
"service = QiskitRuntimeService(channel=\"ibm_cloud\")\n",
"service = QiskitRuntimeService(channel=\"ibm_quantum_platform\")\n",
"backend = service.get_backend(backend_name)\n",
"\n",
"pass_manager = generate_preset_pass_manager(\n",
Expand Down
4 changes: 2 additions & 2 deletions docs/guides/setup-channel.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ Alternatively, you can also access quantum processors with REST APIs, enabling y

```python
service = QiskitRuntimeService(
channel="ibm_cloud", # `channel` distinguishes between different account types
channel="ibm_quantum_platform", # `channel` distinguishes between different account types
token=token, # Your token is confidential.
# Take care not to share your key in public code.
instance="<IBM Cloud CRN>",
Expand Down Expand Up @@ -299,7 +299,7 @@ Alternatively, you can also access quantum processors with REST APIs, enabling y
from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(
channel="ibm_cloud",
channel="ibm_quantum_platform",
# Delete your key on the API keys page after entering this code:
token="<IBM Cloud API key>",
instance="<IBM Cloud CRN>"
Expand Down
Loading