Add new channel and allow instance selection with new platform (#2239)

* add new channel name & deprecate ibm_cloud

* wip cloud account prefs

* save account & backend logic

* fix service.backends() logic

* fix backends() logic, add plan filter, address comments

* more docs, still use ibm_cloud in examples

* refactor logic, new discussed implentation

* update release note

* allow init with no instance

* refactor/cleanup

* support instance as name

* add & fix tests

* refactor no instance case

* add warning msg and docs for account_id

* update tests and docs

* fix account preferences & add test

* allow instance name in backend(), handle instances w same name

* set default channel, cache backend objs

* update instances() & IQP classic fixes

* update unit tests

* fix staging

* add try/except for invalid instances

* update integration tests

* remove account_id & fix plan name logic

* fix staging & simplify urls

* * Allow for multiple clients within a QiskitRuntimeService

* Confirm they work for job and session retrieval

* Update docstrings to include all channels and clarify when methods are used

* Update deprecation messages to fit docstrings

* Fix unit tests

* Update mocks

* Refactor backends method

* Refactor job retrieval

* Add distinct urls for ibm_quantum_platform and ibm_cloud

* Remove resolve_crn

* Error on wrong plan list

* Update link

* Fix error msg

* Follow-ups

* URL resolution

* Fix URL resolution with ibm_quantum_platform. Region needs to be specified for non-default regions (non-US)

* fix typing & lint

* fix instance check & new iqp url

* update release note

* update new iqp url logic

* Improve documentation of instances() method

* Release note edits

* Minimize new client creation

---------

Co-authored-by: ElePT <epenatap@gmail.com>
Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com>

Author: kt474

CONTRIBUTING.md

@@ -141,10 +141,10 @@ When a single backend is retrieved with the `instance` parameter,
 
 .. code:: python
 
-  service.backend('ibm_torino', instance='ibm-q/open/main')
-  # raises error if torino is not in ibm-q/open/main but in a different instance
+  service.backend('ibm_torino', instance='IBM_CLOUD_INSTANCE')
+  # raises error if torino is not in given instance but in a different instance
   # the user has access to
-  service = QiskitRuntimeService(channel="ibm_quantum", instance="ibm-q/open/main")
+  service = QiskitRuntimeService(channel="ibm_cloud", instance="IBM_CLOUD_INSTANCE")
   service.backend('ibm_torino') # raises the same error
 
 if the backend is not in the instance, but in a different one the user
@@ -213,20 +213,13 @@ make integration-test
 
 ###### Configuration
 
-Integration tests require an environment configuration and can be run against both IBM Quantum APIs (`ibm_quantum`, and `ibm_cloud`).
+Integration tests require an environment configuration and can be run against the IBM Quantum Platform API
+(`ibm_quantum_platform` channel).
 
-Sample configuration for IBM Quantum
-```bash
-QISKIT_IBM_TOKEN=...                                            # IBM Quantum API token
-QISKIT_IBM_URL=https://auth.quantum.ibm.com/api                 # IBM Quantum API URL
-QISKIT_IBM_INSTANCE=ibm-q/open/main                             # IBM Quantum provider to use (hub/group/project)
-QISKIT_IBM_QPU=...                                              # IBM Quantum Processing Unit to use
-```
-
-Sample configuration for IBM Cloud
+Sample configuration for IBM Cloud (ibm_quantum_platform)
 ```bash
 QISKIT_IBM_TOKEN=...                                            # IBM Cloud API key
-QISKIT_IBM_URL=https://cloud.ibm.com                            # Cloud URL
+QISKIT_IBM_URL=https://quantum.cloud.ibm.com                    # Cloud URL
 QISKIT_IBM_INSTANCE=crn:v1:bluemix:...                          # The CRN value of the Quantum service instance
 QISKIT_IBM_QPU=...                                              # The Quantum Processing Unit to use
 ```

README.md

@@ -30,11 +30,14 @@ pip install qiskit-ibm-runtime
 
 ### Qiskit Runtime service on IBM Quantum Platform
 
+| :warning: The ibm_quantum channel option is deprecated and will be sunset on 1 July. For help migrating to the ibm_cloud channel, read the [migration guide.](https://quantum.cloud.ibm.com/docs/migration-guides/classic-iqp-to-cloud-iqp)
+|:---------------------------|
+
 You will need your IBM Quantum API token to authenticate with the runtime service:
 
 1. Create an IBM Quantum account or log in to your existing account by visiting the [IBM Quantum login page].
 
-1. Copy (and optionally regenerate) your API token from your
+2. Copy (and optionally regenerate) your API token from your
    [IBM Quantum account page].
 
 ### Qiskit Runtime service on IBM Cloud
@@ -60,8 +63,9 @@ from qiskit_ibm_runtime import QiskitRuntimeService
 # Save an IBM Cloud account.
 QiskitRuntimeService.save_account(channel="ibm_cloud", token="MY_IBM_CLOUD_API_KEY", instance="MY_IBM_CLOUD_CRN")
 
-# Save an IBM Quantum account.
-QiskitRuntimeService.save_account(channel="ibm_quantum", token="MY_IBM_QUANTUM_TOKEN")
+# 'ibm_quantum_platform' and 'ibm_cloud' point to the same channel so they can be used interchangeably
+# In a future releases 'ibm_cloud' will be deprecated and removed in favor of 'ibm_quantum_platform'
+QiskitRuntimeService.save_account(channel="ibm_quantum_platform", token="MY_IBM_CLOUD_API_KEY", instance="MY_IBM_CLOUD_CRN")
 ```
 
 Once the account is saved on disk, you can instantiate the service without any arguments:
@@ -96,14 +100,8 @@ from qiskit_ibm_runtime import QiskitRuntimeService
 
 # For an IBM Cloud account.
 ibm_cloud_service = QiskitRuntimeService(channel="ibm_cloud", token="MY_IBM_CLOUD_API_KEY", instance="MY_IBM_CLOUD_CRN")
-
-# For an IBM Quantum account.
-ibm_quantum_service = QiskitRuntimeService(channel="ibm_quantum", token="MY_IBM_QUANTUM_TOKEN")
 ```
 
-| :warning: The ibm_quantum channel option is deprecated and will be sunset on 1 July. For help migrating to the ibm_cloud channel, read the [migration guide.](https://quantum.cloud.ibm.com/docs/migration-guides/classic-iqp-to-cloud-iqp)
-|:---------------------------|
-
 ## Primitives
 
 All quantum applications and algorithms level are fundamentally built using these steps:
@@ -281,23 +279,23 @@ This code returns `Job result is [4.] at theta = 1.575674623307102` using only n
 
 Access to IBM Quantum Platform channel is controlled by the instances (previously called providers) to which you are assigned. An instance is defined by a hierarchical organization of hub, group, and project. A hub is the top level of a given hierarchy (organization) and contains within it one or more groups. These groups are in turn populated with projects. The combination of hub/group/project is called an instance. Users can belong to more than one instance at any time.
 
-> **_NOTE:_** IBM Cloud instances are different from IBM Quantum Platform instances.  IBM Cloud does not use the hub/group/project structure for user management. To view and create IBM Cloud instances, visit the [IBM Cloud Quantum Instances page](https://cloud.ibm.com/quantum/instances).
+> **_NOTE:_** IBM Cloud instances are different from IBM Quantum Platform classic instances.  IBM Cloud does not use the hub/group/project structure for user management. To view and create IBM Cloud instances, visit the [IBM Cloud Quantum Instances page](https://cloud.ibm.com/quantum/instances).
 
 To view a list of your instances, visit your [account settings page](https://www.quantum.ibm.com/account) or use the `instances()` method.
 
 You can specify an instance when initializing the service or provider, or when picking a backend:
 
 ```python
 # Optional: List all the instances you can access.
-service = QiskitRuntimeService(channel='ibm_quantum')
+service = QiskitRuntimeService(channel='ibm_cloud')
 print(service.instances())
 
 # Optional: Specify the instance at service level. This becomes the default unless overwritten.
-service = QiskitRuntimeService(channel='ibm_quantum', instance="hub1/group1/project1")
+service = QiskitRuntimeService(channel='ibm_cloud', instance="IBM_CLOUD_INSTANCE")
 backend1 = service.backend("ibmq_manila")
 
 # Optional: Specify the instance at the backend level, which overwrites the service-level specification when this backend is used.
-backend2 = service.backend("ibmq_manila", instance="hub2/group2/project2")
+backend2 = service.backend("ibmq_manila", instance="IBM_CLOUD_INSTANCE")
 
 sampler1 = Sampler(mode=backend1)    # this will use hub1/group1/project1
 sampler2 = Sampler(mode=backend2)    # this will use hub2/group2/project2

qiskit_ibm_runtime/__init__.py

@@ -143,9 +143,8 @@
 can use the :meth:`QiskitRuntimeService.save_account` method to save the credentials
 on disk.
 
-Qiskit Runtime is available on both IBM Cloud and IBM Quantum, and you can specify
-``channel="ibm_cloud"`` for IBM Cloud and ``channel="ibm_quantum"`` for IBM Quantum. The default
-is IBM Cloud.
+Qiskit Runtime is available on IBM Cloud, and you can specify the channel with
+``channel="ibm_cloud"`` or ``channel="ibm_quantum_platform"``.
 
 Runtime Jobs
 ------------

qiskit_ibm_runtime/accounts/__init__.py

@@ -14,7 +14,7 @@
 Account management functionality related to the IBM Runtime Services.
 """
 
-from .account import Account, AccountType, ChannelType
+from .account import Account, AccountType, ChannelType, RegionType, PlanType
 from .management import AccountManager
 from .exceptions import (
     AccountNotFoundError,