{ "cells": [ { "cell_type": "markdown", "id": "cf056b55", "metadata": {}, "source": [ "# Accessing info with `cirq-superstaq`\n", "This tutorial will cover the information you can access on your account and related jobs and targets using `cirq-superstaq`." ] }, { "cell_type": "markdown", "id": "domestic-bryan", "metadata": {}, "source": [ "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Infleqtion/client-superstaq/blob/main/docs/source/get_started/access_info/access_info_css.ipynb) [![Launch Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Infleqtion/client-superstaq/HEAD?labpath=docs/source/get_started/access_info/access_info_css.ipynb)" ] }, { "cell_type": "markdown", "id": "88ddd716", "metadata": {}, "source": [ "## Imports and API Token\n", "\n", "As usual, we'll begin with importing requirements and setting up access to Superstaq. This tutorial uses `cirq-superstaq`, our Superstaq client for Cirq. You can install it and relevant dependencies by running `pip install cirq-superstaq`." ] }, { "cell_type": "code", "execution_count": 1, "id": "1a637717", "metadata": {}, "outputs": [], "source": [ "# Requirements to use cirq-superstaq\n", "try:\n", " import cirq\n", " import cirq_superstaq as css\n", "except ImportError:\n", " print(\"Installing cirq-superstaq...\")\n", " %pip install --quiet 'cirq-superstaq[examples]'\n", " print(\"Installed cirq-superstaq.\")\n", " print(\"You may need to restart the kernel to import newly installed packages.\")\n", " import cirq\n", " import cirq_superstaq as css" ] }, { "cell_type": "markdown", "id": "dc8f8407", "metadata": {}, "source": [ "Now, we instantiate a service provider in `cirq-superstaq` with `Service()`. Supply the Superstaq API token by providing the token as an argument of `css.Service()` or setting it as an environment variable (see [this guide](https://superstaq.readthedocs.io/en/latest/get_started/basics/basics_css.html#Set-up-access-to-Superstaq%E2%80%99s-API))." ] }, { "cell_type": "code", "execution_count": 2, "id": "e536b251", "metadata": {}, "outputs": [], "source": [ "service = css.Service()" ] }, { "cell_type": "markdown", "id": "42932197", "metadata": {}, "source": [ "## Account Information" ] }, { "cell_type": "markdown", "id": "10fc81e6", "metadata": {}, "source": [ "The `service` class gives you a means to retrieve information regarding your Superstaq account. Currently, you can use `service` to retrieve your Superstaq balance." ] }, { "cell_type": "code", "execution_count": 3, "id": "f0730b90", "metadata": { "scrolled": true }, "outputs": [ { "data": { "text/plain": [ "'20 credits'" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "service.get_balance()" ] }, { "cell_type": "markdown", "id": "f8b82611", "metadata": {}, "source": [ "If are interested in increasing your balance or have more information on your user role, please reach out to us at superstaq@infleqtion.com or join our [Slack workspace](https://join.slack.com/t/superstaq/shared_invite/zt-1wr6eok5j-fMwB7dPEWGG~5S474xGhxw)." ] }, { "cell_type": "markdown", "id": "332617c4", "metadata": {}, "source": [ "## Backend Information\n", "In addition to account information, the ``Service`` object also gives you a list of all the devices and simulators to which you have access, as well as additional information about those targets.\n", "\n", "* `get_targets()`: Retrieves a list of available targets. This method also accepts the following boolean keyword arguments to filter the targets returned: `simulator`, `supports_submit`, `supports_submit_qubo`, `supports_compile`, `available`, and `retired`.\n", "* `target_info(\"\")`: Retrieve information on your selected backend, such as number of qubits, native gate set, where `` is the name of the desired backend" ] }, { "cell_type": "code", "execution_count": 4, "id": "7ab7e0ff", "metadata": { "scrolled": false }, "outputs": [ { "data": { "text/plain": [ "[Target(target='aqt_keysight_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='aqt_zurich_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='aws_dm1_simulator', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='aws_sv1_simulator', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='aws_tn1_simulator', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='cq_sqale_simulator', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='cq_sqorpius_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='cq_sqorpius_simulator', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='eeroq_wonderlake_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ibmq_brisbane_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ibmq_fez_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ibmq_kyiv_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ibmq_kyoto_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ibmq_osaka_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ibmq_sherbrooke_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ibmq_torino_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ionq_aria-1_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='ionq_aria-2_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=False, retired=False),\n", " Target(target='ionq_forte-1_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=False, retired=False),\n", " Target(target='ionq_ion_simulator', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='iqm_garnet_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=False, retired=False),\n", " Target(target='qscout_peregrine_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='qtm_h1-1_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='qtm_h1-1e_simulator', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='qtm_h2-1_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='rigetti_ankaa-2_qpu', supports_submit=True, supports_submit_qubo=False, supports_compile=True, available=True, retired=False),\n", " Target(target='rigetti_aspen-m-3_qpu', supports_submit=False, supports_submit_qubo=False, supports_compile=True, available=False, retired=False),\n", " Target(target='ss_unconstrained_simulator', supports_submit=True, supports_submit_qubo=True, supports_compile=True, available=True, retired=False)]" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "service.get_targets()" ] }, { "cell_type": "code", "execution_count": 5, "id": "b474be61", "metadata": { "scrolled": false }, "outputs": [ { "data": { "text/plain": [ "{'num_qubits': 127,\n", " 'target': 'ibmq_brisbane_qpu',\n", " 'coupling_map': [[0, 1],\n", " [0, 14],\n", " [1, 0],\n", " [1, 2],\n", " [2, 1],\n", " [2, 3],\n", " [3, 2],\n", " [3, 4],\n", " [4, 3],\n", " [4, 5],\n", " [4, 15],\n", " [5, 4],\n", " [5, 6],\n", " [6, 5],\n", " [6, 7],\n", " [7, 6],\n", " [7, 8],\n", " [8, 7],\n", " [8, 9],\n", " [8, 16],\n", " [9, 8],\n", " [9, 10],\n", " [10, 9],\n", " [10, 11],\n", " [11, 10],\n", " [11, 12],\n", " [12, 11],\n", " [12, 13],\n", " [12, 17],\n", " [13, 12],\n", " [14, 0],\n", " [14, 18],\n", " [15, 4],\n", " [15, 22],\n", " [16, 8],\n", " [16, 26],\n", " [17, 12],\n", " [17, 30],\n", " [18, 14],\n", " [18, 19],\n", " [19, 18],\n", " [19, 20],\n", " [20, 19],\n", " [20, 21],\n", " [20, 33],\n", " [21, 20],\n", " [21, 22],\n", " [22, 15],\n", " [22, 21],\n", " [22, 23],\n", " [23, 22],\n", " [23, 24],\n", " [24, 23],\n", " [24, 25],\n", " [24, 34],\n", " [25, 24],\n", " [25, 26],\n", " [26, 16],\n", " [26, 25],\n", " [26, 27],\n", " [27, 26],\n", " [27, 28],\n", " [28, 27],\n", " [28, 29],\n", " [28, 35],\n", " [29, 28],\n", " [29, 30],\n", " [30, 17],\n", " [30, 29],\n", " [30, 31],\n", " [31, 30],\n", " [31, 32],\n", " [32, 31],\n", " [32, 36],\n", " [33, 20],\n", " [33, 39],\n", " [34, 24],\n", " [34, 43],\n", " [35, 28],\n", " [35, 47],\n", " [36, 32],\n", " [36, 51],\n", " [37, 38],\n", " [37, 52],\n", " [38, 37],\n", " [38, 39],\n", " [39, 33],\n", " [39, 38],\n", " [39, 40],\n", " [40, 39],\n", " [40, 41],\n", " [41, 40],\n", " [41, 42],\n", " [41, 53],\n", " [42, 41],\n", " [42, 43],\n", " [43, 34],\n", " [43, 42],\n", " [43, 44],\n", " [44, 43],\n", " [44, 45],\n", " [45, 44],\n", " [45, 46],\n", " [45, 54],\n", " [46, 45],\n", " [46, 47],\n", " [47, 35],\n", " [47, 46],\n", " [47, 48],\n", " [48, 47],\n", " [48, 49],\n", " [49, 48],\n", " [49, 50],\n", " [49, 55],\n", " [50, 49],\n", " [50, 51],\n", " [51, 36],\n", " [51, 50],\n", " [52, 37],\n", " [52, 56],\n", " [53, 41],\n", " [53, 60],\n", " [54, 45],\n", " [54, 64],\n", " [55, 49],\n", " [55, 68],\n", " [56, 52],\n", " [56, 57],\n", " [57, 56],\n", " [57, 58],\n", " [58, 57],\n", " [58, 59],\n", " [58, 71],\n", " [59, 58],\n", " [59, 60],\n", " [60, 53],\n", " [60, 59],\n", " [60, 61],\n", " [61, 60],\n", " [61, 62],\n", " [62, 61],\n", " [62, 63],\n", " [62, 72],\n", " [63, 62],\n", " [63, 64],\n", " [64, 54],\n", " [64, 63],\n", " [64, 65],\n", " [65, 64],\n", " [65, 66],\n", " [66, 65],\n", " [66, 67],\n", " [66, 73],\n", " [67, 66],\n", " [67, 68],\n", " [68, 55],\n", " [68, 67],\n", " [68, 69],\n", " [69, 68],\n", " [69, 70],\n", " [70, 69],\n", " [70, 74],\n", " [71, 58],\n", " [71, 77],\n", " [72, 62],\n", " [72, 81],\n", " [73, 66],\n", " [73, 85],\n", " [74, 70],\n", " [74, 89],\n", " [75, 76],\n", " [75, 90],\n", " [76, 75],\n", " [76, 77],\n", " [77, 71],\n", " [77, 76],\n", " [77, 78],\n", " [78, 77],\n", " [78, 79],\n", " [79, 78],\n", " [79, 80],\n", " [79, 91],\n", " [80, 79],\n", " [80, 81],\n", " [81, 72],\n", " [81, 80],\n", " [81, 82],\n", " [82, 81],\n", " [82, 83],\n", " [83, 82],\n", " [83, 84],\n", " [83, 92],\n", " [84, 83],\n", " [84, 85],\n", " [85, 73],\n", " [85, 84],\n", " [85, 86],\n", " [86, 85],\n", " [86, 87],\n", " [87, 86],\n", " [87, 88],\n", " [87, 93],\n", " [88, 87],\n", " [88, 89],\n", " [89, 74],\n", " [89, 88],\n", " [90, 75],\n", " [90, 94],\n", " [91, 79],\n", " [91, 98],\n", " [92, 83],\n", " [92, 102],\n", " [93, 87],\n", " [93, 106],\n", " [94, 90],\n", " [94, 95],\n", " [95, 94],\n", " [95, 96],\n", " [96, 95],\n", " [96, 97],\n", " [96, 109],\n", " [97, 96],\n", " [97, 98],\n", " [98, 91],\n", " [98, 97],\n", " [98, 99],\n", " [99, 98],\n", " [99, 100],\n", " [100, 99],\n", " [100, 101],\n", " [100, 110],\n", " [101, 100],\n", " [101, 102],\n", " [102, 92],\n", " [102, 101],\n", " [102, 103],\n", " [103, 102],\n", " [103, 104],\n", " [104, 103],\n", " [104, 105],\n", " [104, 111],\n", " [105, 104],\n", " [105, 106],\n", " [106, 93],\n", " [106, 105],\n", " [106, 107],\n", " [107, 106],\n", " [107, 108],\n", " [108, 107],\n", " [108, 112],\n", " [109, 96],\n", " [109, 114],\n", " [110, 100],\n", " [110, 118],\n", " [111, 104],\n", " [111, 122],\n", " [112, 108],\n", " [112, 126],\n", " [113, 114],\n", " [114, 109],\n", " [114, 113],\n", " [114, 115],\n", " [115, 114],\n", " [115, 116],\n", " [116, 115],\n", " [116, 117],\n", " [117, 116],\n", " [117, 118],\n", " [118, 110],\n", " [118, 117],\n", " [118, 119],\n", " [119, 118],\n", " [119, 120],\n", " [120, 119],\n", " [120, 121],\n", " [121, 120],\n", " [121, 122],\n", " [122, 111],\n", " [122, 121],\n", " [122, 123],\n", " [123, 122],\n", " [123, 124],\n", " [124, 123],\n", " [124, 125],\n", " [125, 124],\n", " [125, 126],\n", " [126, 112],\n", " [126, 125]],\n", " 'supports_midcircuit_measurement': True,\n", " 'native_gate_set': ['ecr', 'id', 'rz', 'sx', 'x'],\n", " 'max_experiments': 300,\n", " 'max_shots': 100000,\n", " 'processor_type': {'family': 'Eagle', 'revision': 3},\n", " 'open_pulse': True,\n", " 'supports_dynamic_circuits': True}" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "service.target_info(\"ibmq_brisbane_qpu\") # retrieving information about IBM's Brisbane device" ] }, { "cell_type": "markdown", "id": "541a58fe", "metadata": {}, "source": [ "## Job Information\n", "Jobs submitted through Superstaq contain the following information:\n", "\n", "* `job_id()`: Unique identifier for the job.\n", "* `status()`: Overall status of the job (Submitted, Queued, Running, Failed, Canceled, or Done). Note that an `index` argument can be passed optionally to retreive the status of a specific job indexed by `index` in a batch job. \n", "* `target()`: Device the job was run on.\n", "* `counts()`: Counts from the result of the job run. Note this can return a list, so you must specify an `index` if you want to retrieve a specific counts dictionary (corresponding to the circuit with the same `index`).\n", "* `num_qubits()`: Number of qubits for the job. Note this can return a list, so you must specify an `index` if you want to retrieve the corresponding number of qubits to a particular circuit. \n", "* `repetitions()`: Number of repetitions for the job.\n", "* `input_circuits()`: Retrieves original (i.e., not compiled) circuit(s) for job. Note this returns a list and you must specify an `index` if you want to retrieve a single/specific circuit.\n", "* `compiled_circuits()`: Retrieves compiled circuit(s) from submitted job. Note this returns a list and you must specify an `index` if you want to retrieve a single/specific circuit.\n", "\n", "Note that jobs live in our database for a limited amount of time. Typically, they have a lifespan of 1 year." ] }, { "cell_type": "code", "execution_count": 6, "id": "dbd6a92a", "metadata": {}, "outputs": [], "source": [ "# Creating a circuit using Cirq\n", "qubits = cirq.LineQubit.range(2)\n", "circuit = cirq.Circuit(\n", " cirq.H(qubits[0]),\n", " cirq.CNOT(qubits[0], qubits[1]),\n", " cirq.measure(qubits[0]),\n", " cirq.measure(qubits[1]),\n", ")\n", "\n", "# Submitting the circuit to IBM's Brisbane QPU\n", "job = service.create_job(\n", " circuit, repetitions=100, method=\"dry-run\", target=\"ibmq_brisbane_qpu\"\n", ") # Specify \"dry-run\" as the method to submit & run a Superstaq simulation" ] }, { "cell_type": "code", "execution_count": 7, "id": "67e69bbb", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'99685f6e-20b2-42c7-8847-5ae0b4973eb6'" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.job_id()" ] }, { "cell_type": "code", "execution_count": 8, "id": "6adf4b5b", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'Done'" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.status()" ] }, { "cell_type": "code", "execution_count": 9, "id": "c2047fe0", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'ibmq_brisbane_qpu'" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.target()" ] }, { "cell_type": "code", "execution_count": 10, "id": "db8d558a", "metadata": { "scrolled": true }, "outputs": [ { "data": { "text/plain": [ "{'00': 60, '11': 40}" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.counts(index=0)" ] }, { "cell_type": "code", "execution_count": 11, "id": "ae538a31", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "2" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.num_qubits(index=0)" ] }, { "cell_type": "code", "execution_count": 12, "id": "86bbcc46", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "100" ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.repetitions()" ] }, { "cell_type": "code", "execution_count": 13, "id": "68a77180", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
0: ───H───@───M───\n",
       "          │\n",
       "1: ───────X───M───
" ], "text/plain": [ "0: ───H───@───M───\n", " │\n", "1: ───────X───M───" ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.input_circuits(index=0)" ] }, { "cell_type": "code", "execution_count": 14, "id": "d9882d03", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
41: ───Rz(1.5π)───X^0.5───AceCR+-(Z side)───│───M('q(0)')───\n",
       "                          │                 │\n",
       "53: ───X^0.5──────────────AceCR+-(X side)───│───M('q(1)')───
" ], "text/plain": [ "41: ───Rz(1.5π)───X^0.5───AceCR+-(Z side)───│───M('q(0)')───\n", " │ │\n", "53: ───X^0.5──────────────AceCR+-(X side)───│───M('q(1)')───" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.compiled_circuits(index=0)" ] }, { "cell_type": "markdown", "id": "c065f1d7", "metadata": {}, "source": [ "Additionally, you may cancel the current job (or, optionally, a sub-job by passing an `index` argument) if it is not in a terminal state like so:" ] }, { "cell_type": "code", "execution_count": 15, "id": "2e34f51e", "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "SuperstaqWarning: Job '99685f6e-20b2-42c7-8847-5ae0b4973eb6' cannot be cancelled: it already has status Done\n", " self._client.cancel_jobs(ids_to_cancel, **kwargs)\n" ] } ], "source": [ "job.cancel()" ] }, { "cell_type": "markdown", "id": "04576f3e", "metadata": {}, "source": [ "Lastly, you may also retrieve the information described above on a previously submitted `cirq-superstaq` job with `service.get_job('')`:" ] }, { "cell_type": "code", "execution_count": 16, "id": "560076e9", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
0: ───H───@───M───\n",
       "          │\n",
       "1: ───────X───M───
" ], "text/plain": [ "0: ───H───@───M───\n", " │\n", "1: ───────X───M───" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job_id = job.job_id() # Here we use the job ID from above, but this can be any old job ID\n", "job_old = service.get_job(job_id)\n", "job_old.input_circuits(index=0)" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "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.9.16" } }, "nbformat": 4, "nbformat_minor": 5 }