From bc80bf86392e02cdf302115d2b280bf7899c35c8 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 9 Sep 2025 13:59:21 -0500 Subject: [PATCH 1/4] Consolidate initialization information --- docs/guides/_toc.json | 5 ++++ docs/guides/cloud-setup.mdx | 3 +- docs/guides/initialize-account.mdx | 35 +++++++++++++++++++++++ qiskit_bot.yaml | 4 +++ scripts/js/commands/checkPatternsIndex.ts | 1 + 5 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 docs/guides/initialize-account.mdx diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index de6aab2b8ab..f14c882cf10 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -35,6 +35,11 @@ "url": "/docs/guides/cloud-setup-rest-api", "platform": "cloud" }, + { + "title": "Initialize your Qiskit Runtime service account", + "url": "/docs/guides/initialize-account", + "platform": "cloud" + }, { "title": "Online lab environments", "url": "/docs/guides/online-lab-environments" diff --git a/docs/guides/cloud-setup.mdx b/docs/guides/cloud-setup.mdx index 4df83e24a23..30ed960ff2e 100644 --- a/docs/guides/cloud-setup.mdx +++ b/docs/guides/cloud-setup.mdx @@ -34,6 +34,7 @@ Your user account is associated with one or more [instances,](./instances) ident ![The IBM Quantum Platform header is shown. The account switcher is to the right of the search bar. The region switcher is to the right of the account switcher.](/docs/images/guides/cloud-setup/IQP-Header.svg 'IBM Quantum Platform header') + ### 1. Create an instance Go to the [IBM Quantum Platform dashboard.](https://quantum.cloud.ibm.com) If you have one or more instances shown, skip this step. Otherwise, follow these steps to create an instance. @@ -95,7 +96,7 @@ When an instance CRN or name is passed in, only backends and jobs from that inst plans_preference="['open', 'premium']", # Optionally set the types of plans to prioritize. This is ignored if the instance is specified. # Additionally, instances of a certain plan type are excluded if the plan name is not specified. region="us-east", # Optionally set the region to prioritize. Accepted values are 'us-east' or 'eu-de'. This is ignored if the instance is specified. - name="", # Optionally name this set of account credentials. + name="", # Optionally name this set of account credentials. set_as_default=True, # Optionally set these as your default credentials. ) ``` diff --git a/docs/guides/initialize-account.mdx b/docs/guides/initialize-account.mdx new file mode 100644 index 00000000000..6f7a668bdb7 --- /dev/null +++ b/docs/guides/initialize-account.mdx @@ -0,0 +1,35 @@ +--- +title: Initialize your Qiskit Runtime service account +description: How to initialize your Qiskit Runtime account, with the option of saving credentials for easy use. + +--- + +# Initialize your Qiskit Runtime service account + +Before using Qiskit Runtime, you have to initialize your account by submitting credentials. These credentials can be submitted each time you run a job, or you can save them for reuse. + +## Before you begin + +Ensure that you have completed these steps: + +1. If you do not already have one, set up an [IBM Cloud account.](https://quantum.cloud.ibm.com/registration) + + You can have multiple IBM Cloud accounts. You can access any of your IBM Cloud accounts at any time from the account switcher in the header of the [IBM Quantum Platform interface](https://quantum.cloud.ibm.com). + + +2. Create (or have access to) at least one instance. + 1. Log in to [IBM Quantum Platform](https://quantum.cloud.ibm.com) with an IBMid or Google account. If you don't have one, you are guided through creating one. + 1. Make sure that the correct account and region are selected in the account switcher in the header, as shown in the following image. + + The region controls where your jobs are run and where the job data is kept. You can access either region by using the same API key, but you can only see and access the instances that were created in the region that you're logged in to. + + ![The IBM Quantum Platform header is shown. The account switcher is to the right of the search bar. The region switcher is to the right of the account switcher.](/docs/images/guides/cloud-setup/IQP-Header.svg 'IBM Quantum Platform header') + + 1. Go to the [IBM Quantum Platform dashboard.](https://quantum.cloud.ibm.com) If you have one or more instances shown, you're done with this step. Otherwise, [create an instance.](/docs/guides/cloud-setup#create-instance) + + +## Next steps + + + - + diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index ad28246a177..536e7bdec84 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -242,6 +242,10 @@ notifications: - "@beckykd" "docs/guides/primitives": - "@ElePT" + "docs/guides/initialize-account": + - "@ElePT" + - "@beckykd" + - "@abbycross" "docs/guides/primitives-examples": - "@jyu00" - "@beckykd" diff --git a/scripts/js/commands/checkPatternsIndex.ts b/scripts/js/commands/checkPatternsIndex.ts index 63943f32457..8e7b2bba1c5 100644 --- a/scripts/js/commands/checkPatternsIndex.ts +++ b/scripts/js/commands/checkPatternsIndex.ts @@ -47,6 +47,7 @@ const ALLOWLIST_MISSING_FROM_TOC: Set = new Set([ "/docs/guides/instances", "/docs/guides/access-instances-platform-apis", "/docs/guides/cloud-setup", + "/docs/guides/initialize-account", "/docs/guides/cloud-setup-untrusted", "/docs/guides/cloud-setup-invited", "/docs/guides/cloud-setup-rest-api", From 9982e5bd7410d19aa1afc75fdd3473cde596ef51 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 11 Sep 2025 16:02:42 -0500 Subject: [PATCH 2/4] Add more content --- docs/guides/initialize-account.mdx | 50 ++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/guides/initialize-account.mdx b/docs/guides/initialize-account.mdx index 6f7a668bdb7..4b960a08a70 100644 --- a/docs/guides/initialize-account.mdx +++ b/docs/guides/initialize-account.mdx @@ -12,9 +12,11 @@ Before using Qiskit Runtime, you have to initialize your account by submitting c Ensure that you have completed these steps: -1. If you do not already have one, set up an [IBM Cloud account.](https://quantum.cloud.ibm.com/registration) - - You can have multiple IBM Cloud accounts. You can access any of your IBM Cloud accounts at any time from the account switcher in the header of the [IBM Quantum Platform interface](https://quantum.cloud.ibm.com). +1. Ensure that you are a member of an IBM Cloud account [set up your own IBM Cloud account.](https://quantum.cloud.ibm.com/registration) + + - To avoid adding your credit card information, you can set up a 30-day trial account and optionally upgrade it later. + - You can have multiple IBM Cloud accounts. You can access any of your IBM Cloud accounts at any time from the account switcher in the header of the [IBM Quantum Platform interface](https://quantum.cloud.ibm.com). + - If you are invited to join an IBM Cloud account, you will get an email invitation to join the account. Follow the instructions in that email. 2. Create (or have access to) at least one instance. @@ -27,6 +29,48 @@ Ensure that you have completed these steps: 1. Go to the [IBM Quantum Platform dashboard.](https://quantum.cloud.ibm.com) If you have one or more instances shown, you're done with this step. Otherwise, [create an instance.](/docs/guides/cloud-setup#create-instance) + +## Find your access credentials + +1. Find your API key (also referred to as an _API token_). 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. The token will not be visible again, so make sure it's copied somewhere. Note that you can use a single API key to connect to any region. +2. Optional: Find the instance you want to use from the [Instances](https://quantum.cloud.ibm.com/instances) page. Click the icon to copy its CRN, then save it in a secure location so you can use it to identify the instance. + + +## Connect Qiskit with your service instance + + +This guide is designed for `qiskit_ibm_runtime` v0.42 or later. If you are using an earlier version of `qiskit_ibm_runtime`, certain features will not be enabled. In these cases, we recommend always providing a value for channel, token, and instance, either explicitly or through a saved account. + + +The basic code to connect Qiskit with your Qiskit Runtime service instance follows. However, there are several different ways to customize the `QiskitRuntimeService` options, depending on your needs. These options are described in the following sections. + +```python +from qiskit_ibm_runtime import QiskitRuntimeService + +service = QiskitRuntimeService(channel=channel, token=token, instance=instance) +``` + + +### Quick start path: Specify credentials explicitly + +The fastest way to get a `QiskitRuntimeService` running is direct instantiation method: explicitly providing the API token (key) and CRN (instance identifier). See [Find your access credentials](#access-credentials) section if necessary. + +```python +from qiskit_ibm_runtime import QiskitRuntimeService + +service = QiskitRuntimeService(token=*API_key*, instance=*instance_CRN*) +``` + +This path is reliable but can be tedious if you need to load the same details repeatedly. To avoid loading your credentials multiple times, if you are working in a trusted Python environment (such as on a personal laptop or workstation), you can use saved account credentials, as described in the following section. + +Although the `instance` input parameter is optional, it is recommended that you always provide this information, unless you want to use a single service to work with several instances. In this situation, see the [automatic instance selection](#auto-select) section. + + +### Quick start path: Specify saved credentials + + +### Automatically select the instance +Use the information in this section if you want Qiskit Runtime to automatically select the instance. ## Next steps From 29c95f9e1af7ce21523077547c70f24e555ab536 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 12 Sep 2025 09:09:59 -0500 Subject: [PATCH 3/4] add link --- docs/guides/initialize-account.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/initialize-account.mdx b/docs/guides/initialize-account.mdx index 4b960a08a70..76402622643 100644 --- a/docs/guides/initialize-account.mdx +++ b/docs/guides/initialize-account.mdx @@ -75,5 +75,5 @@ Use the information in this section if you want Qiskit Runtime to automatically ## Next steps - - + - [Create and manage instances](/docs/guides/instances) From 5aca98f09d19870ff9cc3d089cda0f3019dac7dd Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 12 Sep 2025 15:29:17 -0500 Subject: [PATCH 4/4] moving along --- docs/guides/cloud-setup.mdx | 70 +++++++++++++++++------------- docs/guides/initialize-account.mdx | 25 +++++++++-- 2 files changed, 62 insertions(+), 33 deletions(-) diff --git a/docs/guides/cloud-setup.mdx b/docs/guides/cloud-setup.mdx index 30ed960ff2e..9c7e161ed71 100644 --- a/docs/guides/cloud-setup.mdx +++ b/docs/guides/cloud-setup.mdx @@ -73,54 +73,66 @@ Your user account is associated with one or more [instances,](./instances) ident 2. Optional: Find the instance you want to use from the [Instances](https://quantum.cloud.ibm.com/instances) page. Click the icon to copy its CRN, then save it in a secure location so you can use it to identify the instance. -### 3. Connect Qiskit with your service instance +### 3. Save your access credentials 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, then use them to initialize the service. + + * If you are not using a trusted environment, follow the instructions in [Initialize the service in an untrusted environment](/docs/guides/cloud-setup-untrusted) instead. For example, if you are using a public comptuer. + * Follow [these instructions](/docs/guides/cloud-setup-rest-api) if you want to connect by using the REST API instead of using Qiskit. + * If necessary, use [this information](/docs/guides/quickstart-steps-org#firewall) to configure your firewall to enable access to the IBM Quantum API endpoints. + + 1. Ensure you are working in an active Python environment with the [Qiskit SDK and Qiskit Runtime installed](/docs/guides/install-qiskit#local). 1. Activate the Python virtual environment, run Python in your virtual environment, and enter the following: ```python token = "" ``` -2. Initialize the service. - -When an instance CRN or name is passed in, only backends and jobs from that instance are available. If an instance is not specified (allowed in Qiskit Runtime v0.40.1 and later), 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. - +2. Save your credentials. Run this once per account you want to save. ```python from qiskit_ibm_runtime import QiskitRuntimeService - service = QiskitRuntimeService.save_account( - token="token", # IBM Cloud API key. - # Your token is confidential. Do not share your token in public code. - instance="", # Optionally specify the instance to use. - plans_preference="['open', 'premium']", # Optionally set the types of plans to prioritize. This is ignored if the instance is specified. - # Additionally, instances of a certain plan type are excluded if the plan name is not specified. - region="us-east", # Optionally set the region to prioritize. Accepted values are 'us-east' or 'eu-de'. This is ignored if the instance is specified. - name="", # Optionally name this set of account credentials. - set_as_default=True, # Optionally set these as your default credentials. + + QiskitRuntimeService.save_account( + token="token", + instance="", # Optional + plans_preference="['open', 'premium']", # Optional + region="", # Optional + name="", # Optional + set_as_default=True, # Optional + overwrite=True, # Optional ) ``` +Options: + +-**`token`**: IBM Cloud API key. Your token is confidential. Do not share your token in public code. +-**`instance`**: Optionally specify the instance to use. +-**`plans_preference`**: Optionally set the types of plans to prioritize. This is ignored if the instance is specified. Available options are 'open' and 'premium'. Instances of a certain plan type are excluded if the plan name is not specified. For example, if [`open`] is passed in, only open plan instances are available. +-**`region`**: Optionally set the region to use. Accepted values are 'us-east' and 'eu-de'. This is ignored if the instance is specified. +-**`name`**: Optionally name this set of account credentials. +-**`set_as_default`**: Set the value to `True` to save these as your default credentials. If you save only one account, it is automatically set as the default. +-**`overwrite`**: Set this value to `True` to update your default credentials. - ```python +#### Considerations + +* If you are saving multiple accounts, consider using the `name` parameter to differentiate them. +* Credentials are saved to `$HOME/.qiskit/qiskit-ibm.json`. Do not manually edit this file. +* If you don't save your credentials, you must specify them every time you start a new session. +* If you manually specify your credentials, a saved account will not be used. + +### 4. Initialize the service + +Every time you need to instantiate a `QiskitRuntimeService` with the default saved account, run the following: + + ```python from qiskit_ibm_runtime import QiskitRuntimeService - # If you named your credentials, optionally specify the name here, as follows: - # QiskitRuntimeService(name='account-name') - # If you don't specify a name, the default credentials are loaded. service = QiskitRuntimeService() - ``` - * If you are saving multiple accounts, consider using the `name` parameter to differentiate them. - * Credentials are saved to `$HOME/.qiskit/qiskit-ibm.json`. Do not manually edit this file. - * If you don't save your credentials, you must specify them every time you start a new session. - * If you specify your credentials, a saved account will not be used. - - - * Follow [these instructions](/docs/guides/cloud-setup-untrusted) to authenticate to IBM Cloud if you are not using a trusted environment. For example, if you are using a public comptuer. - * Follow [these instructions](/docs/guides/cloud-setup-rest-api) if you want to connect by using the REST API instead of using Qiskit. - * If necessary, use [this information](/docs/guides/quickstart-steps-org#firewall) to configure your firewall to enable access to the IBM Quantum API endpoints. - + ... + ``` +See the [Initialize the service](/docs/guides/initialize-account) guide for more details about instantiating the `QiskitRuntimeService`. ## Next steps diff --git a/docs/guides/initialize-account.mdx b/docs/guides/initialize-account.mdx index 76402622643..b8ee61ad0e0 100644 --- a/docs/guides/initialize-account.mdx +++ b/docs/guides/initialize-account.mdx @@ -15,7 +15,7 @@ Ensure that you have completed these steps: 1. Ensure that you are a member of an IBM Cloud account [set up your own IBM Cloud account.](https://quantum.cloud.ibm.com/registration) - To avoid adding your credit card information, you can set up a 30-day trial account and optionally upgrade it later. - - You can have multiple IBM Cloud accounts. You can access any of your IBM Cloud accounts at any time from the account switcher in the header of the [IBM Quantum Platform interface](https://quantum.cloud.ibm.com). + - You can have multiple IBM Cloud accounts. You can access any of your IBM Cloud accounts at any time from the account switcher in the header of the [IBM Quantum Platform interface.](https://quantum.cloud.ibm.com) - If you are invited to join an IBM Cloud account, you will get an email invitation to join the account. Follow the instructions in that email. @@ -28,6 +28,9 @@ Ensure that you have completed these steps: ![The IBM Quantum Platform header is shown. The account switcher is to the right of the search bar. The region switcher is to the right of the account switcher.](/docs/images/guides/cloud-setup/IQP-Header.svg 'IBM Quantum Platform header') 1. Go to the [IBM Quantum Platform dashboard.](https://quantum.cloud.ibm.com) If you have one or more instances shown, you're done with this step. Otherwise, [create an instance.](/docs/guides/cloud-setup#create-instance) +1. Ensure you are working in an active Python environment with the [Qiskit SDK and Qiskit Runtime installed.](/docs/guides/install-qiskit#local) +1. Activate the Python virtual environment and run Python in your virtual environment. + ## Find your access credentials @@ -47,7 +50,7 @@ The basic code to connect Qiskit with your Qiskit Runtime service instance follo ```python from qiskit_ibm_runtime import QiskitRuntimeService -service = QiskitRuntimeService(channel=channel, token=token, instance=instance) +service = QiskitRuntimeService(channel=, token=, instance=) ``` @@ -58,7 +61,7 @@ The fastest way to get a `QiskitRuntimeService` running is direct instantiation ```python from qiskit_ibm_runtime import QiskitRuntimeService -service = QiskitRuntimeService(token=*API_key*, instance=*instance_CRN*) +service = QiskitRuntimeService(token=, instance=) ``` This path is reliable but can be tedious if you need to load the same details repeatedly. To avoid loading your credentials multiple times, if you are working in a trusted Python environment (such as on a personal laptop or workstation), you can use saved account credentials, as described in the following section. @@ -68,12 +71,26 @@ Although the `instance` input parameter is optional, it is recommended that you ### Quick start path: Specify saved credentials +You can use the following snippet as a quick start reference as long as you instantiate the service precisely as indicated in this example. For more info on the mechanisms used to save and load accounts, and possible variations from this example, see section C: + ### Automatically select the instance Use the information in this section if you want Qiskit Runtime to automatically select the instance. +If you provide a token but don't provide an instance CRN when instantiating the service, the QiskitRuntimeService authenticates to the account identified by the token and relies on automatic instance selection to choose the most relevant instance for the requested task. If you have several instances available within your account, the service automatically switches between available instances, depending on the resource requested and these `QiskitRuntimeService` options (if set): `plans_preference`, `region`, `tags`. + +- **`plans_preference`**: The types of instance plans to prioritize. For example, if [`open`] is passed in, only open plan instances are available. + +region: Specify the instance region. Accepted values are `us-east` and `eu-de`. + +tags: Specify the instance tags. Accepts a list of tag name strings. + ## Next steps - - [Create and manage instances](/docs/guides/instances) + - [Create and manage instances.](/docs/guides/instances) + - [Initialize the service in an untrusted environment.](/docs/guides/cloud-setup-untrusted) + - [Set up to use IBM Quantum Platform with REST API.](/docs/guides/could-setup-rest-api) + - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. +