Consolidate initialization information

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"

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')
 
 
+<span id="create-instance"></span>
 ### 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.
@@ -72,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.
 
 <span id="cloud-save"></span>
-### 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.
 
+<Admonition type="note" title="Notes">
+      * 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.
+</Admonition>
+
 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 = "<your-API-token>"
     ```
-2. Initialize the service.
-<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 (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.
-</Admonition>
+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="<IBM Cloud CRN or instance name>", # 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="<account-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="<IBM Cloud CRN or instance name>", # Optional
+    plans_preference="['open', 'premium']", # Optional
+    region="<region>", # Optional
+    name="<account-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.
-
-    <Admonition type="note" title="Notes">
-      * 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.
-    </Admonition>
+    ...
+  ```
 
+See the [Initialize the service](/docs/guides/initialize-account) guide for more details about instantiating the `QiskitRuntimeService`.
 
 ## Next steps
 

docs/guides/initialize-account.mdx

@@ -0,0 +1,96 @@
+---
+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. Ensure that you are a member of an IBM Cloud account [set up your own IBM Cloud account.](https://quantum.cloud.ibm.com/registration)
+   <Admonition type="note" title="Notes">
+   - 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.
+   </Admonition>
+
+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)
+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.
+
+
+<span id="access-credentials"></span>
+## 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
+
+<Admonition type="note">
+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.
+</Admonition>
+
+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=<cloud_api_key>, instance=<instance_CRN>)
+```
+
+<span id="explicit"></span>
+### 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=<cloud_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.
+
+<span id="saved"></span>
+### 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:
+
+<span id="auto-select"></span>
+### 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
+
+<Admonition type="tip" title="Recommendations">
+   - [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.
+
+</Admonition>

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"

scripts/js/commands/checkPatternsIndex.ts

@@ -47,6 +47,7 @@ const ALLOWLIST_MISSING_FROM_TOC: Set<string> = 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",