115 lines
8.7 KiB
Plaintext
115 lines
8.7 KiB
Plaintext
---
|
|
title: Instances
|
|
description: What IBM Quantum Platform instances are and how to use them
|
|
---
|
|
# Instances
|
|
|
|
Access to IBM Quantum™ Platform services 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 given time.
|
|
|
|
<Admonition type="note">
|
|
IBM Cloud® instances are different from IBM Quantum Platform instances. IBM Cloud does not use the hub/group/project structure for user management. This section describes instances in IBM Quantum Platform. To view and create IBM Cloud instances, visit the [IBM Cloud Quantum Instances page](https://cloud.ibm.com/quantum/instances). Click the name of an instance to see details such as your CRN for that instance, what compute resources are available to you by using that instance, and what jobs you have run on that instance.
|
|
</Admonition>
|
|
|
|
|
|
|
|
The hub/group/project hierarchy that makes up an IBM Quantum instance.
|
|
|
|
Users with a public account automatically belong to the ibm-q/open/main [Open Plan](#open-plan). For organizations outside of IBM®, designated hub or group administrators assign users to instances.
|
|
|
|
To see the instances to which you have access, look at the bottom of your [Account page](https://quantum.ibm.com/account).
|
|
|
|
|
|
|
|
<span id="open-plan"></span>
|
|
## Open Plan instance
|
|
|
|
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 QPU allocated to the plan fairly, **an individual can have no more than three jobs running and/or in the queue (across all QPUs) at the same time.** Submitting more than three jobs at a time will return error [#3458](../errors#3458), and additional jobs will be canceled.
|
|
|
|
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.
|
|
|
|
## View your instances
|
|
|
|
You can see information about your instances programmatically or in the user interface.
|
|
|
|
### List your instances programmatically
|
|
|
|
You can view a list of your instances on your [account settings page](https://quantum.ibm.com/account), or you can use [the `instances()` method](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.QiskitRuntimeService#instances).
|
|
|
|
<span id="switch-instances"></span>
|
|
### View instances in the IBM Quantum interface
|
|
|
|
Within the [IBM Quantum interface](https://quantum.ibm.com/), the IBM Quantum Platform dashboard, Compute resources, and Jobs pages display information such as usage metrics, jobs, and QPUs based on your instance. If you have access to multiple instances, use the dropdown in the menu bar to switch between instances.
|
|
|
|
<Admonition type="note">
|
|
The instance switcher does not appear in the Administration application.
|
|
</Admonition>
|
|
|
|
If you switch to a different instance, it is remembered the next time you log on and, assuming that it's still a valid instance, information pertaining to that instance is displayed. By default, the first premium instance you have access to is used. If you do not have any premium instances, the first open instance is shown.
|
|
<Admonition type="note">
|
|
The "first" instance is determined alphabetically.
|
|
</Admonition>
|
|
|
|
## How jobs relate to instances
|
|
|
|
When you execute a task using an IBM Quantum service (for example, sending circuits to a QPU), a **job** instance is returned to you. Regardless of which service is being used, a job can track the progress of the submission through IBM Quantum, and retrieve the final computation results. Because services are coupled to instances, the jobs created from these services are also tied to the specific instance being used. Therefore, **if a user is removed from an instance, their jobs and the associated results are no longer accessible**.
|
|
|
|
## How usage affects job priority within an instance
|
|
|
|
*This section applies to Premium Plan users only, since their access includes multiple instances.* When determining which jobs to run, the [fair-share scheduler](./fair-share-scheduler) takes into account an instance's [usage](execution-modes#usage) compared to its allocation. For example, an instance that has already run many jobs might have a lower priority when compared to an instance that has very low usage, depending on allocation.
|
|
|
|
The jobs you run and the jobs run by other collaborators in the same instance count toward the reported usage for that instance. You can see the usage for an instance on your [dashboard](https://quantum.ibm.com/) (use the [instance switcher](#switch-instances) at the top of the page to change which instance is reflected on your dashboard).
|
|
|
|
If an instance has been marked as "limited" by your administrator (you will see a "**Remaining**" column in the usage area) and the instance exceeds its allocation (defined by your administrator) within the 28-day rolling window, any active workload will continue running (including sessions) but pending workloads will remain in the queue until more time is available. If an instance is not limited and the instance exceeds its allocation, jobs run with that instance are likely to run at a lower priority and experience longer queue times.
|
|
|
|
An alert displays on an instance's usage when it has exceeded its allocation.
|
|
|
|
|
|
_Collaborator's dashboard view, reflecting an instance that has exceeded its specified limit_
|
|
|
|
|
|
_Collaborator's dashboard view, reflecting an instance (with no limit specified) that has exceeded its allocation_
|
|
|
|
<span id="connect-instance"></span>
|
|
## Specify an instance in your code
|
|
|
|
You can specify an instance when initializing the service or when choosing a QPU. You can copy the service-level code by clicking the three dots by the instance name on the Instances section of the [Account overview page](https://quantum.ibm.com/account).
|
|
|
|
```python
|
|
|
|
# Optional: List all the instances you can access.
|
|
service = QiskitRuntimeService(channel='ibm_quantum')
|
|
print(service.instances())
|
|
|
|
# Optional: Specify it at service level. This becomes the default unless overwritten.
|
|
service = QiskitRuntimeService(channel='ibm_quantum', instance="hub1/group1/project1")
|
|
backend1 = service.backend("ibmq_manila")
|
|
|
|
# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used.
|
|
backend2 = service.backend("ibmq_manila", instance="hub2/group2/project2")
|
|
|
|
sampler1 = SamplerV2(mode=backend1) # this will use hub1/group1/project1
|
|
sampler2 = SamplerV2(mode=backend2) # this will use hub2/group2/project2
|
|
```
|
|
|
|
<Admonition type="note">
|
|
If you do not specify an instance, the code will select one in the following order:
|
|
|
|
1. If your account only has access to one instance, it is selected by default.
|
|
2. If your account has access to multiple instances but only one can access the requested QPU, the instance with access is selected.
|
|
3. In all other cases, the code selects the first instance other than `ibm-q/open/main` that has access to the QPU.
|
|
</Admonition>
|
|
|
|
|
|
## Leave an instance
|
|
|
|
To leave an instance, visit the instance list on your [Account page.](https://quantum.ibm.com/account) Select the instance you wish to leave, then select the overflow menu and choose *Leave instance*.
|
|
|
|
|
|
|
|
## Next steps
|
|
|
|
<Admonition type="tip" title="Recommendations">
|
|
- Try the [Grover's algorithm](https://learning.quantum.ibm.com/tutorial/grovers-algorithm) tutorial.
|
|
- Review the [QiskitRuntimeService instances method](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.QiskitRuntimeService#instances) reference.
|
|
</Admonition>
|