Update instance selection behavior (#2375)

* Filter by pricing type

* Add remaining warnings

* Update init warning msg

* Add release note & backend warning

* Fix unit tests

* Update tests & refactor

* Integration tests

* Update msg wording

* Update unit tests

* Formatting

* Make channel optional

* Prioritize free/trial instances

* Add end paratheses

* Fix lint & typing

* Fix black

* Apply suggestion from @ElePT

Co-authored-by: Elena Peña Tapia <[email protected]>

* Apply suggestion from @ElePT

Co-authored-by: Elena Peña Tapia <[email protected]>

* Remove extra space

---------

Co-authored-by: Elena Peña Tapia <[email protected]>

Author: kt474

qiskit_ibm_runtime/accounts/account.py

@@ -350,12 +350,16 @@ def list_instances(self) -> List[Dict[str, Any]]:
                     plan_name = (
                         catalog_result.get("overview_ui", {}).get("en", {}).get("display_name", "")
                     )
+                    pricing_type = (
+                        catalog_result.get("metadata", {}).get("pricing", {}).get("type", "")
+                    )
                     crns.append(
                         {
                             "crn": item.get("crn"),
                             "plan": plan_name.lower(),
                             "name": item.get("name"),
                             "tags": item.get("tags"),
+                            "pricing_type": pricing_type.lower(),
                         }
                     )
 

qiskit_ibm_runtime/accounts/management.py

@@ -180,8 +180,9 @@ def get(
             saved_account = read_config(filename=filename, name=name)
             if not saved_account:
                 raise AccountNotFoundError(f"Account with the name {name} does not exist on disk.")
+            logger.warning("Loading saved account: %s", name)
             return Account.from_saved_format(saved_account)
-
+        logger.warning("Loading default saved account")
         channel_ = channel or os.getenv("QISKIT_IBM_CHANNEL") or _DEFAULT_CHANNEL_TYPE
         env_account = cls._from_env_variables(channel_)
         if env_account is not None:

qiskit_ibm_runtime/qiskit_runtime_service.py

@@ -109,8 +109,9 @@ def __init__(
         ``token``. The ``local`` channel doesn't require authentication.
         For non-local channels, it is recommended to always provide the relevant ``instance``
         to minimize API calls. If an ``instance`` is not defined, the service will fetch all
-        instances accessible within the
-        account, filtered by ``region``, ``plans_preference``, and ``tags``.
+        instances accessible within the account, filtered by ``region``, ``plans_preference``,
+        and ``tags``. If ``plans_preference`` is not set, free and trial instances will be prioritized
+        over paid instances.
 
         The service will attempt to load an account from file if (a) no explicit ``token``
         was provided during instantiation  or (b) a ``name`` is specified, even if an explicit
@@ -231,6 +232,37 @@ def __init__(
         else:
             self._api_clients = {}
             instance_backends = self._resolve_cloud_instances(instance)
+            instance_names = [instance.get("name") for instance in self._backend_instance_groups]
+            instance_plan_names = {
+                instance.get("plan") for instance in self._backend_instance_groups
+            }
+
+            tags_str = ", ".join(self._tags) if self._tags else "None"
+            region_str = self._region if self._region else "us-east, eu-de"
+            if self._plans_preference:
+                joined_preferences: str = ", ".join(self._plans_preference)
+                plans_preference_str = f", plans_preference: {joined_preferences})"
+            else:
+                joined_plan_names = ", ".join(instance_plan_names)
+                plans_preference_str = f"), and available plans: ({joined_plan_names})"
+
+            filters = f"(tags: {tags_str}, " f"region: {region_str}" f"{plans_preference_str}"
+
+            logger.warning(
+                "Instance was not set at service instantiation. %s"
+                "Based on the following filters: %s, "
+                "the available account instances are: %s. "
+                "If you need a specific instance set it explicitly either by "
+                "using a saved account with a saved default instance or passing it "
+                "in directly to QiskitRuntimeService().",
+                (
+                    ""
+                    if self._plans_preference
+                    else "Free and trial plan instances will be prioritized. "
+                ),
+                filters,
+                ", ".join(instance_names),
+            )
             for inst, _ in instance_backends:
                 self._get_or_create_cloud_client(inst)
 
@@ -292,6 +324,13 @@ def _filter_instances_by_saved_preferences(self) -> None:
             self._backend_instance_groups = sorted(
                 filtered_groups, key=lambda d: plans.index(d["plan"])
             )
+        else:
+            # if plans_preference is not set, prioritize free and trial plans
+            ordered_pricing_types = ["free", "trial", "paygo", "paid", "subscription"]
+            self._backend_instance_groups = sorted(
+                self._backend_instance_groups,
+                key=lambda d: ordered_pricing_types.index(d["pricing_type"]),
+            )
 
         if not self._backend_instance_groups:
             error_string = ""
@@ -349,14 +388,28 @@ def _discover_account(
                     proxies=proxies,
                     verify=verify_,
                 )
+                logger.warning(
+                    "Loading account with the given token. A saved account will not be used."
+                )
             else:
                 if url:
                     logger.warning("Loading default %s account. Input 'url' is ignored.", channel)
                 account = AccountManager.get(filename=filename, name=name, channel=channel)
-        elif any([token, url]):
-            # Let's not infer based on these attributes as they may change in the future.
+        elif token:
+            account = Account.create_account(
+                channel="ibm_quantum_platform",
+                token=token,
+                url=url,
+                instance=instance,
+                proxies=proxies,
+                verify=verify_,
+            )
+            logger.warning(
+                "Loading account with the given token. A saved account will not be used."
+            )
+        elif url:
             raise ValueError(
-                "'channel' is required if 'token', or 'url' is specified but 'name' is not."
+                "'url' is not valid as a standalone parameter. Try also passing in 'token' or 'name'."
             )
 
         # channel is not defined yet, get it from the AccountManager
@@ -525,9 +578,25 @@ def backends(
                 if name not in backends_available:
                     continue
                 backends_available = [name]
+            else:
+                for inst_details in self._backend_instance_groups:
+                    if inst == inst_details["crn"]:
+                        logger.warning(
+                            "Loading instance: %s, plan: %s",
+                            inst_details["name"],
+                            inst_details["plan"],
+                        )
             for backend_name in backends_available:
                 if backend_name in unique_backends:
                     continue
+                if name:
+                    for inst_details in self._backend_instance_groups:
+                        if inst == inst_details["crn"]:
+                            logger.warning(
+                                "Using instance: %s, plan: %s",
+                                inst_details["name"],
+                                inst_details["plan"],
+                            )
                 unique_backends.add(backend_name)
                 self._get_or_create_cloud_client(inst)
                 if backend := self._create_backend_obj(
@@ -582,25 +651,20 @@ def _resolve_cloud_instances(self, instance: Optional[str]) -> List[Tuple[str, L
             return [(default_crn, self._discover_backends_from_instance(default_crn))]
         if not self._all_instances:
             self._all_instances = self._account.list_instances()
-            instance_names = [instance.get("name") for instance in self._all_instances]
-            logger.warning(
-                "Instance was not set at service instantiation. A relevant instance from all available "
-                "account instances will be selected based on the desired action. "
-                "Available account instances are: %s. "
-                "If you need the instance to be fixed, set it explicitly.",
-                ", ".join(instance_names),
-            )
         if not self._backend_instance_groups:
             self._backend_instance_groups = [
                 {
+                    "name": inst["name"],
                     "crn": inst["crn"],
                     "plan": inst["plan"],
                     "backends": self._discover_backends_from_instance(inst["crn"]),
                     "tags": inst["tags"],
+                    "pricing_type": inst["pricing_type"],
                 }
                 for inst in self._all_instances
             ]
             self._filter_instances_by_saved_preferences()
+
         return [(inst["crn"], inst["backends"]) for inst in self._backend_instance_groups]
 
     def _get_or_create_cloud_client(self, instance: str) -> None:

release-notes/unreleased/2375.update.rst

@@ -0,0 +1,14 @@
+When :class:`.QiskitRuntimeService` is initialized without an instance 
+and there is no saved account instance, there will now be a warning detailing 
+the current filters (``tags``, ``region``, ``plans_preference``) and available instances. If ``plans_preference``
+is not set, free and trial plan instances will be prioritized over paid instances. 
+
+Additional warnings have also been added to make the current active insance more clear:
+
+    - Warning messages to tell users whether they're using a saved account or a new account.
+    - When retrieving a backend and an instance is automatically selected, there will be a warning with
+      the instance name and plan type. 
+
+It is now also possible to initialize :class:`.QiskitRuntimeService` with just a token. Since the ``ibm_quantum``
+channel name has been removed and both the ``ibm_cloud`` and ``ibm_quantum_platform`` channels point to the same
+API, the ``channel`` parameter is no longer required. ``ibm_quantum_platform`` is the default channel.

test/integration/test_account.py

@@ -70,11 +70,44 @@ class TestQuantumPlatform(IBMIntegrationTestCase):
 
     def test_initializing_service_no_instance(self):
         """Test initializing without an instance."""
-        service = QiskitRuntimeService(
-            token=self.dependencies.token, channel="ibm_quantum_platform", url=self.dependencies.url
-        )
-        self.assertTrue(service)
-        self.assertTrue(service.backends())
+
+        # no default instance and no filters
+        with self.assertLogs("qiskit_ibm_runtime", level="WARNING") as logs:
+            service = QiskitRuntimeService(
+                token=self.dependencies.token,
+                channel="ibm_quantum_platform",
+                url=self.dependencies.url,
+            )
+            self.assertTrue(service)
+            message = logs.output[1]
+            self.assertIn("Free and trial", message)
+
+        # no defualt instance and plans_preference
+        with self.assertLogs("qiskit_ibm_runtime", level="WARNING") as logs:
+            service = QiskitRuntimeService(
+                token=self.dependencies.token,
+                channel="ibm_quantum_platform",
+                url=self.dependencies.url,
+                plans_preference=["internal"],
+            )
+            self.assertTrue(service)
+            message = logs.output[1]
+            self.assertNotIn("Free and trial", message)
+            self.assertIn("available account instances are", message)
+
+        # no defualt instance and region
+        region = "us-east"
+        with self.assertLogs("qiskit_ibm_runtime", level="WARNING") as logs:
+            service = QiskitRuntimeService(
+                token=self.dependencies.token,
+                channel="ibm_quantum_platform",
+                url=self.dependencies.url,
+                region=region,
+            )
+            self.assertTrue(service)
+            message = logs.output[1]
+            self.assertIn("Free and trial", message)
+            self.assertIn(f"region: {region}", message)
 
     def test_backends_default_instance(self):
         """Test that default instance returns the correct backends."""

test/unit/mock/fake_runtime_service.py

@@ -41,13 +41,19 @@ class FakeRuntimeService(QiskitRuntimeService):
         {
             "crn": "crn:v1:bluemix:public:quantum-computing:my-region:a/...:...::",
             "tags": ["services"],
+            "name": "test-instance",
+            "pricing_type": "free",
+            "plan": "internal",
         }
     ]
 
     DEFAULT_INSTANCES = [
         {
             "crn": "crn:v1:bluemix:public:quantum-computing:my-region:a/...:...::",
             "tags": ["services"],
+            "name": "test-instance",
+            "pricing_type": "free",
+            "plan": "internal",
         }
     ]
 
@@ -110,10 +116,12 @@ def _resolve_cloud_instances(self, instance: Optional[str]) -> List[Tuple[str, L
         if not self._backend_instance_groups:
             self._backend_instance_groups = [
                 {
+                    "name": inst["name"],
                     "crn": inst["crn"],
                     "plan": inst.get("plan"),
                     "backends": self._discover_backends_from_instance(inst["crn"]),
                     "tags": inst.get("tags"),
+                    "pricing_type": inst["pricing_type"],
                 }
                 for inst in self._all_instances
             ]

test/unit/test_account.py

@@ -632,17 +632,24 @@ def test_enable_account_by_channel(self):
                 self.assertEqual(service._account.token, token)
 
     def test_enable_account_by_token_url(self):
-        """Test initializing account by token or url."""
+        """Test initializing account by token."""
         token = uuid.uuid4().hex
         subtests = [
             {"token": token},
-            {"url": "some_url"},
             {"token": token, "url": "some_url"},
         ]
         for param in subtests:
             with self.subTest(param=param):
-                with self.assertRaises(ValueError):
-                    _ = FakeRuntimeService(**param)
+                with temporary_account_config_file(channel="ibm_quantum_platform", token=token):
+                    service = FakeRuntimeService(**param)
+                    self.assertTrue(service._account)
+
+    def test_enable_account_by_url_error(self):
+        """Test initializing account by url gives an error."""
+        token = uuid.uuid4().hex
+        with temporary_account_config_file(channel="ibm_quantum_platform", token=token):
+            with self.assertRaises(ValueError):
+                _ = FakeRuntimeService(url="some_url")
 
     def test_enable_account_by_name_and_other(self):
         """Test initializing account by name and other."""
@@ -779,12 +786,12 @@ def test_enable_account_by_env_token_url(self):
             "QISKIT_IBM_URL": url,
             "QISKIT_IBM_INSTANCE": "my_crn",
         }
-        subtests = [{"token": token}, {"url": url}, {"token": token, "url": url}]
+        subtests = [{"token": token}, {"token": token, "url": url}]
         for extra in subtests:
             with self.subTest(extra=extra):
-                with custom_envs(envs) as _, self.assertRaises(ValueError) as err:
-                    _ = FakeRuntimeService(**extra)
-                self.assertIn("token", str(err.exception))
+                with custom_envs(envs) as _:
+                    service = FakeRuntimeService(**extra)
+                    self.assertTrue(service._account)
 
     def test_enable_account_bad_name(self):
         """Test initializing account by bad name."""