qiskit-documentation/docs/guides/execution-modes-rest-api.ipynb

543 lines
21 KiB
Plaintext

{
"cells": [
{
"cell_type": "markdown",
"id": "38b90986-2529-4974-9dbd-931f3089b7fa",
"metadata": {},
"source": [
"# Execution modes using REST API"
]
},
{
"cell_type": "markdown",
"id": "d501206a-c250-4df7-befc-317678659d32",
"metadata": {
"tags": [
"version-info"
]
},
"source": []
},
{
"cell_type": "markdown",
"id": "2153584e-5711-4168-a4a5-0b94d02dd3e7",
"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/execution-modes-rest-api)\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/execution-modes-rest-api)\n",
"</Admonition>\n",
"</CloudContent>\n",
"\n",
"You can run your Qiskit primitive workloads using REST APIs in one of three execution modes, depending on your needs: job, session, and batch. This topic explains these modes.\n",
"\n",
"<Admonition type=\"note\">\n",
" This documentation utilizes the Python `requests` module to demonstrate the Qiskit Runtime REST API. However, this workflow can be executed using any language or framework that supports working with REST APIs. Refer to the [API reference documentation](/docs/api/runtime/tags/jobs) for details.\n",
"</Admonition>\n",
"\n",
"## Job mode with REST API\n",
"\n",
"In job mode, a single primitive request of the Estimator or the Sampler is made without a context manager. See how to run a quantum circuit using [Estimator](primitives-rest-api#estimator-primitive-with-rest-api) and [Sampler](primitives-rest-api#sampler-primitive-with-rest-api) for some examples.\n",
"\n",
"## Session mode with REST API\n",
"\n",
"A session is a Qiskit Runtime feature that lets you efficiently run multi-job iterative workloads on quantum computers. Using sessions helps avoid delays caused by queuing each job separately, which can be particularly useful for iterative tasks that require frequent communication between classical and quantum resources. More details about Sessions can be found in the [documentation](./execution-modes).\n",
"\n",
"<CloudContent>\n",
"<Admonition type=\"note\">\n",
"Open Plan users cannot submit session jobs.\n",
"</Admonition>\n",
"</CloudContent>\n",
"\n",
"### Start a session\n",
"\n",
"Begin by creating a session and obtaining a session ID.\n",
"\n",
"<LegacyContent>\n",
"```python\n",
"import json\n",
"\n",
"sessionsUrl = \"https://api.quantum-computing.ibm.com/runtime/sessions\"\n",
"auth_id = \"Bearer <YOUR_API_TOKEN>\"\n",
"backend = \"<BACKEND_NAME>\"\n",
"\n",
"headersList = {\n",
" \"Accept\": \"application/json\",\n",
" 'Authorization':auth_id,\n",
" \"Content-Type\": \"application/json\"\n",
"}\n",
"\n",
"payload = json.dumps({\n",
" \"backend\": backend,\n",
" \"instance\": \"hub1/group1/project1\",\n",
"})\n",
"\n",
"response = requests.request(\"POST\", sessionsUrl, data=payload, headers=headersList)\n",
"\n",
"sessionId = response.json()['id']\n",
"\n",
"print(response.json())\n",
"```\n",
"Output\n",
"```text\n",
"{'id': 'crw9s7cdbt40008jxesg'}\n",
"```\n",
"</LegacyContent>\n",
"\n",
"\n",
"<CloudContent>\n",
"```python\n",
"import json\n",
"import requests\n",
"\n",
"sessionsUrl = \"https://quantum.cloud.ibm.com/api/v1/sessions\"\n",
"auth_id = \"Bearer <YOUR_BEARER_TOKEN>\"\n",
"backend = \"<BACKEND_NAME>\"\n",
"crn = \"<SERVICE-CRN>\"\n",
"\n",
"headersList = {\n",
" \"Accept\": \"application/json\",\n",
" \"Content-Type\": \"application/json\",\n",
" \"Authorization\": auth_id,\n",
" \"Service-CRN\": crn\n",
"}\n",
"\n",
"payload = json.dumps({\n",
" \"backend\": backend,\n",
" \"mode\": 'dedicated',\n",
"})\n",
"\n",
"response = requests.request(\"POST\", sessionsUrl, data=payload, headers=headersList)\n",
"\n",
"sessionId = response.json()['id']\n",
"\n",
"print(response.json())\n",
"```\n",
"Output\n",
"```text\n",
"{'id': 'crw9s7cdbt40008jxesg'}\n",
"```\n",
"</CloudContent>\n",
"\n",
"### Close a session\n",
"\n",
"It is good practice to close a `Session` when all jobs are done. This will reduce wait time for subsequent users.\n",
"\n",
"<LegacyContent>\n",
"```python\n",
"closureURL=\"https://api.quantum-computing.ibm.com/runtime/sessions/\"+sessionId+\"/close\"\n",
"\n",
"headersList = {\n",
" \"Accept\": \"application/json\",\n",
" \"Authorization\": auth_id,\n",
"}\n",
"\n",
"closure_response = requests.request(\n",
" \"DELETE\",\n",
" closureURL,\n",
" headers=headersList\n",
" )\n",
"\n",
"print(\"Session closure response ok?:\",closure_response.ok,closure_response.text)\n",
"```\n",
"Output\n",
"```text\n",
"Session closure response ok?: True\n",
"```\n",
"</LegacyContent>\n",
"\n",
"<CloudContent>\n",
"```python\n",
"closureURL=\"https://quantum.cloud.ibm.com/api/v1/sessions/\"+sessionId+\"/close\"\n",
"\n",
"headersList = {\n",
" \"Accept\": \"application/json\",\n",
" \"Authorization\": auth_id,\n",
" \"Service-CRN\": crn\n",
"}\n",
"\n",
"closure_response = requests.request(\n",
" \"DELETE\",\n",
" closureURL,\n",
" headers=headersList\n",
" )\n",
"\n",
"print(\"Session closure response ok?:\",closure_response.ok,closure_response.text)\n",
"```\n",
"Output\n",
"```text\n",
"Session closure response ok?: True\n",
"```\n",
"</CloudContent>\n",
"\n",
"## Batch mode with REST API\n",
"\n",
"Alternatively, you can submit a batch job by specifying the `mode` in the request payload. Batch mode can help shorten processing time if all jobs can be provided at the outset. Learn about batch mode in the [introduction to execution modes](./execution-modes#batch-mode) guide.\n",
"\n",
"<LegacyContent>\n",
"```python\n",
"import json\n",
"import requests\n",
"\n",
"sessionsUrl = \"https://api.quantum-computing.ibm.com/runtime/sessions\"\n",
"\n",
"headersList = {\n",
" \"Accept\": \"application/json\",\n",
" 'Authorization':auth_id,\n",
" 'Content-Type': 'application/json'\n",
"}\n",
"\n",
"payload = json.dumps({\n",
" \"backend\": backend,\n",
" \"instance\": \"hub1/group1/project1\",\n",
" \"mode\": \"batch\"\n",
"})\n",
"\n",
"response = requests.request(\"POST\", sessionsUrl, data=payload, headers=headersList)\n",
"\n",
"sessionId = response.json()['id']\n",
"```\n",
"</LegacyContent>\n",
"\n",
"<CloudContent>\n",
"```python\n",
"import json\n",
"import requests\n",
"\n",
"sessionsUrl = \"https://quantum.cloud.ibm.com/api/v1/sessions\"\n",
"\n",
"headersList = {\n",
" \"Accept\": \"application/json\",\n",
" \"Authorization\": auth_id,\n",
" \"Service-CRN\": crn,\n",
" 'Content-Type': 'application/json'\n",
"}\n",
"\n",
"payload = json.dumps({\n",
" \"backend\": backend,\n",
" \"instance\": \"hub1/group1/project1\",\n",
" \"mode\": \"batch\"\n",
"})\n",
"\n",
"response = requests.request(\"POST\", sessionsUrl, data=payload, headers=headersList)\n",
"\n",
"sessionId = response.json()['id']\n",
"```\n",
"</CloudContent>\n",
"\n",
"## Examples of jobs submitted in a session\n",
"\n",
"Once a session is set up, one or more Sampler or Estimator jobs can be submitted to the same session by specifying the session ID.\n",
"\n",
"<Admonition type=\"note\">\n",
" The `<parameter values>` in a `PUB` can either be a single parameter or a list of parameters. It also supports `numpy` broadcasting.\n",
"</Admonition>\n",
"\n",
"### Estimator jobs in session mode\n",
"\n",
"<LegacyContent>\n",
"<Tabs>\n",
" <TabItem value=\"1 circuit, 4 observables\" label=\"1 circuit, 4 observables\">\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'estimator',\n",
" \"backend\": backend,\n",
" \"hub\": \"hub1\",\n",
" \"group\": \"group1\",\n",
" \"project\": \"project1\",\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [obs1, obs2, obs3, obs4]]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"\n",
"}\n",
"```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"1 circuit, 4 observables, 2 parameter sets\" label=\"1 circuit, 4 observables, 2 parameter sets\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'estimator',\n",
" \"backend\": backend,\n",
" \"hub\": \"hub1\",\n",
" \"group\": \"group1\",\n",
" \"project\": \"project1\",\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [[obs1], [obs2], [obs3], [obs4]], [[vals1], [vals2]]]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"}\n",
"```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"2 circuits, 2 observables\" label=\"2 circuits, 2 observables\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'estimator',\n",
" \"backend\": backend,\n",
" \"hub\": \"hub1\",\n",
" \"group\": \"group1\",\n",
" \"project\": \"project1\",\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, obs1],[resulting_qasm, obs2]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"}\n",
"```\n",
" </TabItem>\n",
"</Tabs>\n",
"\n",
"### Sampler jobs in session mode\n",
"\n",
"<Tabs>\n",
" <TabItem value=\"1 circuit, no parameters\" label=\"1 circuit, no parameters\">\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'sampler',\n",
" \"backend\": backend,\n",
" \"hub\": \"hub1\",\n",
" \"group\": \"group1\",\n",
" \"project\": \"project1\",\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"\n",
"}\n",
"```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"1 circuit, 3 parameter sets\" label=\"1 circuit, 3 parameter sets\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'sampler',\n",
" \"backend\": backend,\n",
" \"hub\": \"hub1\",\n",
" \"group\": \"group1\",\n",
" \"project\": \"project1\",\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [vals1, vals2, vals3]]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"}\n",
"```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"2 circuits, 1 parameter set\" label=\"2 circuits, 1 parameter set\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'sampler',\n",
" \"backend\": backend,\n",
" \"hub\": \"hub1\",\n",
" \"group\": \"group1\",\n",
" \"project\": \"project1\",\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [val1]],[resulting_qasm,None,100]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"}\n",
"```\n",
" </TabItem>\n",
"</Tabs>\n",
"</LegacyContent>\n",
"\n",
"\n",
"\n",
"<CloudContent>\n",
" <Tabs>\n",
" <TabItem value=\"1 circuit, 4 observables\" label=\"1 circuit, 4 observables\">\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'estimator',\n",
" \"backend\": backend,\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [obs1, obs2, obs3, obs4]]], #primitive unified blocs (PUBs) containing one circuit each.\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"\n",
" }\n",
" ```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"1 circuit, 4 observables, 2 parameter sets\" label=\"1 circuit, 4 observables, 2 parameter sets\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'estimator',\n",
" \"backend\": backend,\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [[obs1], [obs2], [obs3], [obs4]], [[vals1], [vals2]]]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
" }\n",
" ```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"2 circuits, 2 observables\" label=\"2 circuits, 2 observables\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'estimator',\n",
" \"backend\": backend,\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, obs1],[resulting_qasm, obs2]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
" }\n",
" ```\n",
" </TabItem>\n",
" </Tabs>\n",
"\n",
"### Sampler jobs in session mode\n",
"\n",
" <Tabs>\n",
" <TabItem value=\"1 circuit, no parameters\" label=\"1 circuit, no parameters\">\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'sampler',\n",
" \"backend\": backend,\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
"\n",
" }\n",
" ```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"1 circuit, 3 parameter sets\" label=\"1 circuit, 3 parameter sets\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'sampler',\n",
" \"backend\": backend,\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [vals1, vals2, vals3]]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
" }\n",
" ```\n",
" </TabItem>\n",
"\n",
" <TabItem value=\"2 circuits, 1 parameter set\" label=\"2 circuits, 1 parameter set\">\n",
"\n",
" ```python\n",
" job_input = {\n",
" 'program_id': 'sampler',\n",
" \"backend\": backend,\n",
" \"session_id\": sessionId, # This specifies the previously created Session\n",
" \"params\": {\n",
" \"pubs\": [[resulting_qasm, [val1]],[resulting_qasm,None,100]], #primitive unified blocs (PUBs) containing one circuit each\n",
" \"options\":{\n",
" \"transpilation\":{\"optimization_level\": 1},\n",
" \"twirling\": {\"enable_gates\": True,\"enable_measure\": True},\n",
" # \"dynamical_decoupling\": {\"enable\": True, \"sequence_type\": \"XpXm\"}, #(optional)\n",
" },\n",
" }\n",
" }\n",
" ```\n",
" </TabItem>\n",
" </Tabs>\n",
"</CloudContent>\n",
"\n",
"## Next steps\n",
"\n",
"<Admonition type=\"tip\" title=\"Recommendations\">\n",
" - Review detailed [Sampler and Estimator](primitives-rest-api) primitives examples using REST API.\n",
" - Learn how to [transpile circuits using REST API](./transpile-rest-api).\n",
" - Read [Migrate to V2 primitives](/docs/migration-guides/v2-primitives).\n",
" - Practice with primitives by working through the [Cost function lesson](https://learning.quantum.ibm.com/course/variational-algorithm-design/cost-functions#primitives) in IBM Quantum&reg; Learning.\n",
" - Learn how to transpile locally in the [Transpile](./transpile) section.\n",
"</Admonition>"
]
}
],
"metadata": {
"description": "How to run a quantum computing job in a Qiskit Runtime session.",
"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": "Execution modes using REST API"
},
"nbformat": 4,
"nbformat_minor": 4
}