scnc
/
qiskit-documentation
mirror of https://github.com/Qiskit/documentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
qiskit-documentation/docs/guides/instances.ipynb

237 lines
19 KiB
Plaintext
Raw Permalink Blame History

{
"cells": [
{
"cell_type": "markdown",
"id": "570d961d-2bc0-4e3a-b556-51e01eb8b7b2",
"metadata": {},
"source": [
"{/* cspell:ignore nbsp */}\n",
"# Create and manage instances"
]
},
{
"cell_type": "markdown",
"id": "cd3587eb-80b3-43fd-983d-f10f697d2b35",
"metadata": {
"tags": [
"version-info"
]
},
"source": []
},
{
"cell_type": "markdown",
"id": "496d6624-8bf1-4e84-aaac-ecfd7e3b58a3",
"metadata": {},
"source": [
"<LegacyContent>\n",
"<Admonition type=\"note\">\n",
"This documentation is relevant to IBM Quantum&reg; Platform Classic. If you need the newer version, go to the new [IBM Quantum Platform documentation.](https://quantum.cloud.ibm.com/docs/guides/instances)\n",
"</Admonition>\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"<Admonition type=\"note\">\n",
"This documentation is relevant to the new IBM Quantum&reg; Platform. If you need the previous version, return to the [IBM Quantum Platform Classic documentation.](https://docs.quantum.ibm.com/guides/instances)\n",
"</Admonition>\n",
"</CloudContent>\n",
"\n",
"<LegacyContent>\n",
"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.\n",
"\n",
"<Admonition type=\"note\">\n",
" IBM Cloud&reg; 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, create, and edit 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.\n",
"</Admonition>\n",
"\n",
"![Alice, Bob, and Charlie are all in Hub A. Hub A has Group 1 and 2. Alice and Bob are in Group 1. Charlie is in Group 2. Group 1 has Project X and Y. Alice is in both projects. Bob is only in project X. Group 2 has Project Z. Charlie is in project Z. Therefore, Charlie's instance is Hub-A/Group-2/Project-Z.](/docs/images/guides/instances/providers1.avif \"Hub / group / project hierarchy\")\n",
"\n",
"The hub/group/project hierarchy that makes up an IBM Quantum instance.\n",
"\n",
"Users with a public account automatically belong to the ibm-q/open/main [Open Plan](#open-plan). For organizations outside of IBM&reg;, designated hub or group administrators assign users to instances.\n",
"\n",
"The instances that you can access are listed at the bottom of your [Account page](https://quantum.ibm.com/account).\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"Access to IBM Quantum Platform services is controlled by the **instances** to which you are assigned. Users can belong to more than one instance at any given time.\n",
"\n",
"An instance is a deployment of Qiskit Runtime. You need a different instance for every service plan (such as Open or Standard) you use in every region that you want to use. The account manager and anyone with enough permission can create an instance and define its configuration, such as its allocations, usage limits, quantum computers, and user permissions. Each instance is identified by a unique Cloud Resource Name (CRN). This CRN is used when sending workloads from your Qiskit programs.\n",
"\n",
"The IBM Quantum Platform [dashboard](https://quantum.cloud.ibm.com/) displays the instances to which you have access. You can view full details, edit, and delete instances on the [Instances page.](https://quantum.cloud.ibm.com/instances)\n",
"\n",
"It is important that you understand which instance you are using, because all instances that are not associated with the Open Plan incur a cost.\n",
"</CloudContent>\n",
"<span id=\"open-plan\"></span>\n",
"## Open Plan instance\n",
"<LegacyContent>\n",
"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 quantum computers allocated to the plan fairly, **an individual can have no more than three jobs running and/or in the queue (across all quantum computers) at the same time.** Submitting more than three jobs at a time will return error [#3458](../errors#3458), and additional jobs will be canceled.\n",
"\n",
"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.\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"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 quantum computers allocated to the plan fairly, **an individual can have no more than three jobs running and/or in the queue (across all quantum computers) at the same time.** Submitting more than three jobs at a time will return error [#3458](../errors#3458), and additional jobs will be canceled.\n",
"\n",
"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.\n",
"\n",
"<span id=\"standard-plan\"></span>\n",
"## Standard Plan instance\n",
"\n",
"By default, users who sign up for an IBM Quantum account are assigned to the Standard Plan, which is a paid plan. To use this plan, you must create an instance and assign it to the plan. All workloads sent to QPUs by using this plan incur a charge.\n",
"</CloudContent>\n",
"<LegacyContent>\n",
"## View your instances\n",
"\n",
"You can see information about your instances programmatically or in the user interface.\n",
"\n",
"### List your instances programmatically\n",
"\n",
"You can use [the `instances()` method](../api/qiskit-ibm-runtime/qiskit-runtime-service#instances) to list your instances programmatically.\n",
"\n",
"<span id=\"switch-instances\"></span>\n",
"### View instances on IBM Quantum Platform\n",
"\n",
"The IBM Quantum Platform dashboard, Compute resources, and Workloads pages display information such as usage metrics, workloads, and quantum computers based on your instance. If you have access to multiple instances, use the dropdown in the menu bar to switch between instances.\n",
"\n",
"<Admonition type=\"note\">\n",
" The instance switcher does not appear in the Administration application.\n",
" </Admonition>\n",
"\n",
"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 (alphabetically) open instance is shown.\n",
"\n",
"## How jobs relate to instances\n",
"\n",
"When you execute a task using an IBM Quantum service (for example, sending circuits to a quantum computer), 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**.\n",
"\n",
"## How usage affects job priority within an instance\n",
"\n",
"*This section applies to Premium Plan users only, since their access includes multiple instances.*\n",
"When determining which jobs to run, the [fair-share scheduler](/docs/guides/fair-share-scheduler) takes into account an instance's [usage](/docs/guides/estimate-job-run-time) compared to its allocation. For example, an instance with a large allocation that has already run many jobs, or has run one very long job, might have a lower priority when compared to an instance with a smaller allocation but very low usage.\n",
"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).\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"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 view an instance's usage on the [Instances](https://quantum.cloud.ibm.com/instances) page, or, for those with the proper authority, the [Analytics](https://quantum.cloud.ibm.com/analytics) page. Note that the pages might show different usage numbers because the Instance page shows usage in a 28-day rolling window prior to the current timestamp, while the Analytics page uses full-day boundaries.\n",
"</CloudContent>\n",
"\n",
"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.\n",
"\n",
"An alert displays on an instance's usage when it has exceeded its allocation.\n",
"\n",
"<span id=\"connect-instance\"></span>\n",
"## Specify an instance in your code\n",
"<LegacyContent>\n",
"You can specify an instance when initializing the service or when choosing a quantum computer. 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).\n",
"\n",
"```python\n",
"\n",
"# Optional: List all the instances you can access.\n",
"from qiskit_ibm_runtime import QiskitRuntimeService\n",
"from qiskit_ibm_runtime import SamplerV2\n",
"service = QiskitRuntimeService(channel='ibm_quantum')\n",
"print(service.instances())\n",
"\n",
"# Optional: Specify it at service level.\n",
"# This becomes the default unless overwritten.\n",
"service = QiskitRuntimeService(channel='ibm_quantum', instance=\"hub1/group1/project1\")\n",
"backend1 = service.backend(\"ibm_fez\")\n",
"\n",
"# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used.\n",
"backend2 = service.backend(\"ibm_fez\", instance=\"hub2/group2/project2\")\n",
"\n",
"sampler1 = SamplerV2(mode=backend1) # this will use hub1/group1/project1\n",
"sampler2 = SamplerV2(mode=backend2) # this will use hub2/group2/project2\n",
"```\n",
"\n",
"<Admonition type=\"note\">\n",
"If you do not specify an instance, the code will select one in the following order:\n",
"\n",
"1. If your account only has access to one instance, it is selected by default.\n",
"2. If your account has access to multiple instances but only one can access the requested QPU, the instance with access is selected. If this instance is not associated with a free plan, a cost will be incurred.\n",
"3. In all other cases, the code selects the first instance other than the Open Plan instance that has access to the quantum computer. If this instance is not associated with a free plan, a cost will be incurred.\n",
"</Admonition>\n",
"\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"You must use the CRN to specify an instance to use; either when initializing the service or when sending the workload to a QPU. The instance's CRN is listed on the [Platform dashboard](https://quantum.cloud.ibm.com/). Before running the below code, follow the steps to [save an account.](/docs/guides/cloud-setup#cloud-save)\n",
"\n",
"```python\n",
"# Specify an instance at service level. This becomes the default unless overwritten.\n",
"service = QiskitRuntimeService(instance=\"<CRN>\")\n",
"backend = service.backend(\"<QPU-name>\")\n",
"```\n",
"\n",
"<span id=\"add-instance\"></span>\n",
"## Add an instance\n",
"\n",
"1. To add an instance to your account, first ensure you have the correct account and region selected in the account switcher in the top header.\n",
" <span id=\"regions\"></span>\n",
" <Admonition type=\"note\" title=\"About regions\">\n",
" The instance will be created in the selected region. This region determines these important characteristics:\n",
" * Which QPUs are available.\n",
" * Where the jobs' classical computation, such as compilation, takes place.\n",
" * Where the user's workflow data remains.\n",
"\n",
" The workflow data includes the input circuits, circuit parameters, and quantum computation results. It does not include metadata, such as number of shots, size of circuits, or other job statistics.\n",
"\n",
" To avoid exposure of the user's workflow data to a global Distributed Denial of Service protection layer, you can use [Virtual Private Endpoints](https://cloud.ibm.com/docs/overview?topic=overview-endpoints-support). `qiskit-ibm-runtime` supports this through the [private_endpoint parameter](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service).\n",
" </Admonition>\n",
"\n",
"1. From the dashboard Instances pane, click **View all**, or go to the [Instances](https://quantum.cloud.ibm.com/instances) page from the main menu.\n",
"1. From the Instances page, click *Create instance&nbsp;+*. Enter a name and optionally add tags. If you have access to more than one resource group in IBM Cloud&reg;, you can choose to change the resource group this instance belongs to. See [Managing resource groups](https://cloud.ibm.com/docs/account?topic=account-rgs&interface=ui) and [Giving access to resources in resource groups](https://cloud.ibm.com/docs/account?topic=account-rgs_manage_access) for more information.\n",
"1. Select the plan this instance is associated with (for example, Premium Plan), then enter the number of minutes to allocate to this instance. The unallocated time available to use appears under the allocation entry box. If this instance is not associated with a free plan, a cost will be incurred when this instance is used to run workloads.\n",
"1. From the Instances page, click **Create instance**. Enter a name and optionally add tags. If you have access to more than one resource group in IBM Cloud&reg;, you can choose to change the resource group this instance belongs to. See [Managing resource groups](https://cloud.ibm.com/docs/account?topic=account-rgs&interface=ui) and [Giving access to resources in resource groups](https://cloud.ibm.com/docs/account?topic=account-rgs_manage_access) for more information.\n",
"1. Select the plan this instance is associated with (for example, Premium Plan), then enter the number of minutes to allocate to this instance. The unallocated time available to use appears under the allocation entry box.\n",
"1. Click **Next**. A list of the QPUs the instance can access is shown. If you want the instance to have access to all the QPUs listed (and all QPUs added to this plan in the future), click **Next**. To customize which QPUs can be accessed with this instance, click the \"Customize allocated compute resources\" toggle. Select specific QPUs that this instance can access, then click **Next**.\n",
" <Admonition type=\"note\">\n",
" If you customize the allocated compute resources, the available QPUs will never be automatically updated, regardless of any changes made to the parent plan. However, you can manually add or remove QPUs later. If you do not customize them, you will always have access to any QPU the account has access on the plan. So if in the future there is a new system added to the plan, the instance automatically has access to it.\n",
" </Admonition>\n",
"1. Click **Create instance**. You can now view the instance on the [Instances](https://quantum.cloud.ibm.com/instances) page. If you have set up multiple plans on your account, each plan type has its own tab on the Instances table.\n",
"\n",
"A \"collaborators\" access group is automatically created for this instance. Users added to this access group can use the time allocated to this instance. You can [modify or create additional access groups](/docs/guides/access-groups) by using the IBM Cloud console.\n",
"\n",
"\n",
"## Edit an instance and its allocation\n",
"\n",
"Find the instance on the [Instances](https://quantum.cloud.ibm.com/instances) page. Click the overflow menu at the end the instance's row, and select Edit details.\n",
"</CloudContent>\n",
"\n",
"<LegacyContent>\n",
"## Leave an instance\n",
"\n",
"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**.\n",
"\n",
"![Screenshot of the Account page.](/docs/images/guides/instances/leaving1.avif \"Leave instance\")\n",
"</LegacyContent>\n",
"<CloudContent>\n",
"## Next steps\n",
"\n",
"<Admonition type=\"tip\" title=\"Recommendations\">\n",
" - [Work with access groups](/docs/guides/access-groups)\n",
" - [Manage users.](/docs/guides/invite-and-manage-users)\n",
"</Admonition>\n",
"</CloudContent>"
]
}
],
"metadata": {
"description": "What IBM Quantum Platform instances are and how to use them",
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3"
},
"title": "Create and manage instances"
},
"nbformat": 4,
"nbformat_minor": 4
}
Reference in New Issue View Git Blame Copy Permalink