docs/source/tutorials/qcloud_sdk.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "38c73e8c",
   "metadata": {},
   "source": [
    "# tensorcircuit SDK for QCloud（230220 ver）"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f77a17c8",
   "metadata": {},
   "source": [
    "## import the package\n",
    "\n",
    "``apis`` is temporarily as the entry point submodule for qcloud"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8595b0b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import tensorcircuit as tc\n",
    "from tensorcircuit.cloud import apis\n",
    "from tensorcircuit.cloud.wrapper import batch_expectation_ps\n",
    "from tensorcircuit.compiler.qiskit_compiler import qiskit_compile\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "faece4fa",
   "metadata": {},
   "source": [
    "## setup the token\n",
    "\n",
    "The users need an API token from tQuK to connect to the server and submit tasks, the token only need be set once and it is then written to the local computer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "06e38047",
   "metadata": {},
   "outputs": [],
   "source": [
    "apis.set_token(\"foobar\")\n",
    "# only required running once for a given laptop"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f3e53835",
   "metadata": {},
   "source": [
    "## list providers/devices/properties\n",
    "\n",
    "Get basic info of devices and device information"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59dc5c6f",
   "metadata": {},
   "outputs": [],
   "source": [
    "apis.list_providers()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d231e5c3",
   "metadata": {},
   "outputs": [],
   "source": [
    "apis.list_devices(\"tencent\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "be41de9d",
   "metadata": {},
   "outputs": [],
   "source": [
    "apis.list_devices(\"tencent\", state=\"on\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e2ab9a2c",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "apis.list_properties(device=\"9gmon\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aaec43c3",
   "metadata": {},
   "outputs": [],
   "source": [
    "d = apis.get_device(\"9gmon\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f57b5239",
   "metadata": {},
   "outputs": [],
   "source": [
    "d.list_properties()[\"bits\"][8]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f6470346",
   "metadata": {},
   "outputs": [],
   "source": [
    "d.topology()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1823e172",
   "metadata": {},
   "outputs": [],
   "source": [
    "d.native_gates()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e407e5c7",
   "metadata": {},
   "outputs": [],
   "source": [
    "d.topology_graph(visualize=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "148b9b40",
   "metadata": {},
   "source": [
    "## Task submit and the results"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc7645ab",
   "metadata": {},
   "source": [
    "Basic task submission syntax below, here we use a simulator backend on tQuK `simulator:tc`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "94404d7a",
   "metadata": {},
   "outputs": [],
   "source": [
    "c = tc.Circuit(1)\n",
    "c.H(0)\n",
    "\n",
    "t = apis.submit_task(device=\"simulator:tc\", circuit=c, shots=1024)\n",
    "print(t.details())\n",
    "t.results(blocked=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fab152bb",
   "metadata": {},
   "source": [
    "``blocked=True`` can wait until the task is finished or failed (rasing an error)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "617cbd84",
   "metadata": {},
   "outputs": [],
   "source": [
    "t.status()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6e686be",
   "metadata": {},
   "outputs": [],
   "source": [
    "t.get_device()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e550c80",
   "metadata": {},
   "source": [
    "resubmit a job with the same source (device/shots) and command (circuit)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "77dddd16",
   "metadata": {},
   "outputs": [],
   "source": [
    "t1 = t.resubmit()\n",
    "t1.details(blocked=True, prettify=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e227f48a",
   "metadata": {},
   "source": [
    "``t.details`` can also permit the ``blocked=True`` option, which waits until the task is finished or failed (no error raised).\n",
    "\n",
    "Also note by using ``prettfiy=True`` option, we have python datatime object for the timestamp which is easy to read but hard for io (not directly json serializable anymore) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c795e68",
   "metadata": {},
   "source": [
    "## local provider enable quick debugging and testing\n",
    "\n",
    "TC comes with a local provider which behaves as a simple cloud provider but run the circuit locally"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "570159fe",
   "metadata": {},
   "outputs": [],
   "source": [
    "apis.set_provider(\"local\")\n",
    "# using tc simulator on local device: your own laptop is your server\n",
    "apis.list_devices()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fd99ee01",
   "metadata": {},
   "outputs": [],
   "source": [
    "c = tc.Circuit(2)\n",
    "c.h(0)\n",
    "c.cx(0, 1)\n",
    "\n",
    "# exactly the same API as tQuK\n",
    "t = apis.submit_task(circuit=c, device=\"testing\", shots=8192)\n",
    "t.results(blocked=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb62ed45",
   "metadata": {},
   "outputs": [],
   "source": [
    "tl = apis.list_tasks()\n",
    "tl"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "045a19ef",
   "metadata": {},
   "outputs": [],
   "source": [
    "id_ = tl[0].__str__()\n",
    "print(id_)\n",
    "t = apis.get_task(id_)\n",
    "t.details()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "510f8d82",
   "metadata": {},
   "outputs": [],
   "source": [
    "id_ = tl[0].__str__()\n",
    "print(id_.split(\"~~\")[1])\n",
    "t = apis.get_task(id_)\n",
    "t.details()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e359725",
   "metadata": {},
   "source": [
    "As shown above, the task can be indexed either with device information or not (as long as we use ``set_provider``)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "307eeb42",
   "metadata": {},
   "outputs": [],
   "source": [
    "# back to tencent server for demonstration below\n",
    "apis.set_provider(\"tencent\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9bf0d5ca",
   "metadata": {},
   "source": [
    "## GHZ state on real device and readout mitigation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2cc7c82c",
   "metadata": {},
   "outputs": [],
   "source": [
    "nqubit = 9\n",
    "shots = 4096\n",
    "c = tc.Circuit(nqubit)\n",
    "c.H(8)\n",
    "c.cnot(8, 4)\n",
    "c.cnot(4, 0)\n",
    "c.cnot(0, 2)\n",
    "c.cnot(2, 6)\n",
    "\n",
    "# above we dirct assign physical qubits\n",
    "\n",
    "t = apis.submit_task(\n",
    "    circuit=c, shots=shots, device=\"9gmon\", enable_qos_qubit_mapping=False\n",
    ")\n",
    "raw_count = t.results(blocked=True)\n",
    "# blocked = True will block the process until the result is returned\n",
    "# the default behavior is blocked=False, where only one query is made and raise error when the task is incomplete\n",
    "\n",
    "# note we explicitly turn off qubit mapping from qos, which gurantee our logical circuit are identical to the physical one.\n",
    "# but one should ensure the topology link in the logical circuit is compatible with the target device"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80b617b4",
   "metadata": {},
   "source": [
    "In the below, we use tensorcircuit builtin powerful tool for readout mitigation: ``tc.results.rem.ReadoutMit``, it supports various method for calibriation and mitigation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2ed2419",
   "metadata": {},
   "outputs": [],
   "source": [
    "mit = tc.results.rem.ReadoutMit(\"9gmon?o=0\")\n",
    "# here o=0 is a short for disable qubit mapping and gate decomposition at the backend server\n",
    "mit.cals_from_system(nqubit, shots, method=\"local\")\n",
    "# local calibriation\n",
    "miti_count = mit.apply_correction(raw_count, nqubit, method=\"constrained_least_square\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07cacbed",
   "metadata": {},
   "source": [
    "By attaching ``?o=0`` after the device string, we have the same effect of setting ``enable_qos_qubit_mapping=False`` (o=1)\n",
    "and ``enable_qos_gate_decomposition=False`` (o=2), and both of them are by default True (o=3).\n",
    "\n",
    "We can define the REM class by using more customizable function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "09a498b1",
   "metadata": {},
   "outputs": [],
   "source": [
    "def run(cs, shots):\n",
    "    \"\"\"batch mode\"\"\"\n",
    "    ts = apis.submit_task(\n",
    "        circuit=cs, shots=shots, device=\"9gmon\", enable_qos_qubit_mapping=False\n",
    "    )\n",
    "    return [t.results(blocked=True) for t in ts]\n",
    "\n",
    "\n",
    "mit = tc.results.rem.ReadoutMit(run)\n",
    "mit.cals_from_system(nqubit, shots, method=\"local\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "139700b3",
   "metadata": {},
   "outputs": [],
   "source": [
    "raw_count = tc.results.counts.marginal_count(raw_count, [8, 4, 0, 2, 6])\n",
    "miti_count = tc.results.counts.marginal_count(miti_count, [8, 4, 0, 2, 6])\n",
    "# only keep the result for qubit 8, 4, 0, 2, 6 and in that exact order"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "093ec74c",
   "metadata": {},
   "outputs": [],
   "source": [
    "tc.results.counts.plot_histogram([raw_count, miti_count])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4bd6569",
   "metadata": {},
   "outputs": [],
   "source": [
    "ideal_count = tc.results.counts.vec2count(c.probability(), prune=True)\n",
    "# we can obtain analytic count results by ``c.probability()`` method, and ``vec2count`` with transform the vector as a dict\n",
    "\n",
    "ideal_count = tc.results.counts.marginal_count(ideal_count, [8, 4, 0, 2, 6])\n",
    "tc.results.counts.kl_divergence(\n",
    "    ideal_count, raw_count\n",
    "), tc.results.counts.kl_divergence(ideal_count, miti_count)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "91720f2c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# we can directly check local readout matrix on each qubit\n",
    "print(\"readout matrix\")\n",
    "for i, m in enumerate(mit.single_qubit_cals):\n",
    "    print(\"qubit %s:\" % i)\n",
    "    print(m)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c88101c",
   "metadata": {},
   "source": [
    "Apart from calibriation from real experiments, we can access the readout error matrix from API (which is fast but may be not that up to date)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ecca1aab",
   "metadata": {},
   "outputs": [],
   "source": [
    "mit = tc.results.rem.ReadoutMit(\"9gmon?o=0\")\n",
    "mit.cals_from_api(nqubit)\n",
    "mit.single_qubit_cals[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "422d0a1b",
   "metadata": {},
   "source": [
    "## Abstraction of three layers of qubits and the mappings\n",
    "\n",
    "In the above example, the circuit is not compiled by the frontend: tc or backend: qos, in the follows, we will introduce circuit compiling and the new abstraction on different level of qubits.\n",
    "\n",
    "New abstraction on qubits: positional qubits, logical qubits, physical qubits, we need two more mappings: ``positional_logical_mapping`` and ``logical_physical_mapping``.\n",
    "\n",
    "The separation between positional and logical qubits is due to partial measurement, while the seperation between logical and physical qubits are from circuit compiling onto hardware, including swap inserting (where the last swap is omitted, current qos behavior), qubit routing (i.e. initial mapping).\n",
    "\n",
    "Now we do the GHZ preparation on another chip, but use mapping and partial measurement abstraction this time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4a12dd32",
   "metadata": {},
   "outputs": [],
   "source": [
    "# logical circuit for GHZ-5\n",
    "\n",
    "c = tc.Circuit(5)\n",
    "c.h(0)\n",
    "for i in range(4):\n",
    "    c.cx(i, i + 1)\n",
    "for i in range(5):\n",
    "    c.measure_instruction(i)\n",
    "\n",
    "# We map the circuit on the physical qubits by hand\n",
    "\n",
    "c1 = c.initial_mapping({0: 8, 1: 4, 2: 0, 3: 2, 4: 6}, n=9)\n",
    "positional_logical_mapping = c1.get_positional_logical_mapping()\n",
    "positional_logical_mapping"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb7e4b4b",
   "metadata": {},
   "outputs": [],
   "source": [
    "c1.draw()  # circuit after mapping"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39d0c16c",
   "metadata": {},
   "outputs": [],
   "source": [
    "t = apis.submit_task(\n",
    "    circuit=c1, shots=shots, device=\"9gmon\", enable_qos_qubit_mapping=False\n",
    ")\n",
    "raw_count = t.results(blocked=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2bbecbd",
   "metadata": {},
   "outputs": [],
   "source": [
    "logical_physical_mapping = t.details()[\"optimization\"][\"pairs\"]\n",
    "logical_physical_mapping\n",
    "# this mapping is identical since we disable qos qubit mapping above"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d59fa9b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "mit = tc.results.rem.ReadoutMit(\"9gmon?o=0\")\n",
    "mit.cals_from_system(9, shots, method=\"local\")\n",
    "miti_count = mit.apply_correction(\n",
    "    raw_count,\n",
    "    [8, 4, 0, 2, 6],\n",
    "    positional_logical_mapping=positional_logical_mapping,\n",
    "    logical_physical_mapping=logical_physical_mapping,\n",
    "    method=\"square\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "07d7acfd",
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_histogram([raw_count, miti_count])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03d5c6cf",
   "metadata": {},
   "source": [
    "We can have another way to understand logical qubits: we could treat 0-4 in the original circuit as logical qubits, then we will have the following convention and the circuit after initial mapping as the physical one (abstraction reference shift)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ad81141a",
   "metadata": {},
   "outputs": [],
   "source": [
    "miti_count = mit.apply_correction(\n",
    "    raw_count,\n",
    "    [0, 1, 2, 3, 4],\n",
    "    positional_logical_mapping=None,\n",
    "    logical_physical_mapping={0: 8, 1: 4, 2: 0, 3: 2, 4: 6},\n",
    "    method=\"square\",\n",
    ")\n",
    "# note how the None by default implies an identity mapping"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f564d224",
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_histogram([raw_count, miti_count])\n",
    "# the results should be exactly the same, since they are just the same thing using different reference system"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32d753ff",
   "metadata": {},
   "source": [
    "The above abstraction is rather low level where the compiling is done by hand and we recommend the following api for users (**the highly recommended way**).\n",
    "\n",
    "The recommended approach heavily depends on the frontend compiling via qiskit (builtin support in tc)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2711fdb3",
   "metadata": {},
   "outputs": [],
   "source": [
    "# 0. acquire readout mitigation class\n",
    "\n",
    "mit = tc.results.rem.ReadoutMit(\"20xmon?o=0\")\n",
    "mit.cals_from_system(20)\n",
    "\n",
    "# 1. define the logical circuit\n",
    "\n",
    "n = 5\n",
    "c = tc.Circuit(n)\n",
    "c.h(0)\n",
    "for i in range(n - 1):\n",
    "    c.cx(i, i + 1)\n",
    "for i in reversed(range(n)):\n",
    "    c.measure_instruction(i)\n",
    "\n",
    "# 2. compile the circuit\n",
    "\n",
    "d = apis.get_device(\"20xmon\")\n",
    "\n",
    "c1, info = qiskit_compile(\n",
    "    c,\n",
    "    compiled_options={\n",
    "        \"basis_gates\": d.native_gates(),\n",
    "        \"optimization_level\": 3,\n",
    "        \"coupling_map\": d.topology(),\n",
    "    },\n",
    ")\n",
    "\n",
    "\n",
    "# 3. submit the job and get the raw result\n",
    "\n",
    "t = apis.submit_task(\n",
    "    circuit=c1,\n",
    "    shots=8192,\n",
    "    device=d,\n",
    "    enable_qos_qubit_mapping=False,\n",
    "    enable_qos_gate_decomposition=False,\n",
    ")\n",
    "raw_count = t.results(blocked=True)\n",
    "\n",
    "# 4. obtain the mitigated result in terms of distribution or expectation\n",
    "\n",
    "print(\"distribution\", mit.apply_correction(raw_count, n, method=\"square\", **info))\n",
    "print(\"<Z0Z1>\", mit.expectation(raw_count, [0, 1], **info))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84b26c27",
   "metadata": {},
   "outputs": [],
   "source": [
    "info  # compiling info and the qubit mapping are recorded automatically"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f5b63e46",
   "metadata": {},
   "outputs": [],
   "source": [
    "tc.results.counts.plot_histogram(\n",
    "    [raw_count, mit.apply_correction(raw_count, n, method=\"square\", **info)]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2b28dbe",
   "metadata": {},
   "source": [
    "And the **all-in-one API**: ``batch_expectation_ps`` with circuit generating, grouping, compiling, optimization and error mitigation support is as shown below, the API is also consistent with numerical simulations, basically the API capture all the workflow shown in above cell with extra enhancement"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "35ba52b4",
   "metadata": {},
   "outputs": [],
   "source": [
    "c = tc.Circuit(2)\n",
    "c.h(0)\n",
    "c.cz(0, 1)\n",
    "c.x(1)\n",
    "print(\"numerical results: [<X_0>, <X_0Z_1>]\", batch_expectation_ps(c, [[1, 0], [1, 3]]))\n",
    "print(\n",
    "    \"hardware results: [<X_0>, <X_0Z_1>]\",\n",
    "    batch_expectation_ps(c, [[1, 0], [1, 3]], \"20xmon\"),\n",
    ")\n",
    "print(\n",
    "    \"numerical results: <X_0> + 0.5* <X_0Z_1>\",\n",
    "    batch_expectation_ps(c, [[1, 0], [1, 3]], ws=[1, 0.5]),\n",
    ")\n",
    "print(\n",
    "    \"hardware results: <X_0> + 0.5* <X_0Z_1>\",\n",
    "    batch_expectation_ps(c, [[1, 0], [1, 3]], \"20xmon\", ws=[1, 0.5]),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f13baa43",
   "metadata": {},
   "source": [
    "batch submission is possible with multiple circuits in a list and the return is a list of task, respectively. The batch mechanism are supported both on real chips and simulators."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "db3e59b5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# we can also do a batch submission for the real hardware chip, simply by provide a circuit list\n",
    "\n",
    "c = tc.Circuit(2)\n",
    "c.h(0)\n",
    "\n",
    "c1 = tc.Circuit(2)\n",
    "c1.h(1)\n",
    "\n",
    "ts = apis.submit_task(device=\"20xmon\", circuit=[c, c1], shots=1024)\n",
    "\n",
    "for t in ts:\n",
    "    print(t.results(blocked=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d2c56b6",
   "metadata": {},
   "source": [
    "## measure on partial of the qubits\n",
    "\n",
    "Note the return order should ideally follow the measure order in the instructions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9ac0b2fe",
   "metadata": {},
   "outputs": [],
   "source": [
    "# directly partial measure via qiskit\n",
    "\n",
    "from qiskit.circuit import QuantumCircuit\n",
    "\n",
    "qc = QuantumCircuit(9, 9)\n",
    "qc.x(8)\n",
    "qc.x(6)\n",
    "qc.measure(8, 8)\n",
    "qc.measure(2, 2)\n",
    "qc.measure(6, 6)\n",
    "\n",
    "t = apis.submit_task(circuit=qc, shots=shots, device=\"9gmon?o=0\")\n",
    "print(t.results(blocked=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ea3ea0f",
   "metadata": {},
   "source": [
    " The above case also indicates that tc ``submit_task`` API directly support Qiskit ``QuantumCircuit`` object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5ce371e9",
   "metadata": {},
   "outputs": [],
   "source": [
    "# directly partial measure on tc\n",
    "\n",
    "# recommended approach\n",
    "\n",
    "nqubit = 9\n",
    "shots = 4096\n",
    "c = tc.Circuit(nqubit)\n",
    "c.x(8)\n",
    "c.x(6)\n",
    "c.measure_instruction(8)\n",
    "c.measure_instruction(2)\n",
    "c.measure_instruction(6)\n",
    "\n",
    "t = apis.submit_task(circuit=c, shots=shots, device=\"9gmon?o=0\")\n",
    "print(t.results(blocked=True))\n",
    "print(c.get_positional_logical_mapping())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e431f862",
   "metadata": {},
   "source": [
    "partial measurment also supported via the simulator on the cloud"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c6150317",
   "metadata": {},
   "outputs": [],
   "source": [
    "nqubit = 9\n",
    "shots = 4096\n",
    "c = tc.Circuit(nqubit)\n",
    "c.x(8)\n",
    "c.x(6)\n",
    "c.measure_instruction(8)\n",
    "c.measure_instruction(2)\n",
    "c.measure_instruction(6)\n",
    "\n",
    "t = apis.submit_task(circuit=c, shots=shots, device=\"simulator:tc\")\n",
    "print(t.results(blocked=True))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "40bdf80d",
   "metadata": {},
   "outputs": [],
   "source": [
    "nqubit = 9\n",
    "shots = 4096\n",
    "c = tc.Circuit(nqubit)\n",
    "c.x(8)\n",
    "c.x(6)\n",
    "c.measure_instruction(8)\n",
    "c.measure_instruction(2)\n",
    "c.measure_instruction(6)\n",
    "\n",
    "t = apis.submit_task(circuit=c, shots=shots, device=\"simulator:aer\")\n",
    "print(t.results(blocked=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20b8b1d5",
   "metadata": {},
   "source": [
    "## two level compiling system\n",
    "\n",
    "We provide compiling support at frond end (via tc-qiskit pipeline) and at back end (in qos).\n",
    "The front end option is enabled by ``compiled=True`` (default to False) and also with an optional dict for ``qiskit.transpile`` arguments called ``compiled_options``. For advanced users, we recommand you to separately deal with the circuit compiling and submission as we discussed above as the recommended approach. The backend qos compiling is controlled by ``enable_qos_qubit_mapping`` and ``enable_qos_gate_decomposition`` (all default to True). The ``?o=int`` str after the device name can overide qos compiling options. We strongly recommend the users only use one part of the compiling in case confusing and conflicts. For front end compiling, though the built-in compiling via ``compiled`` switch in ``submit_task`` is handy, we recommend the advanced user to use standalone compiling module as shown above, i.e. explicitly call ``qiskit_compile``, the advantage for the latter is we can obtain qubit mapping information at the same time for further error mitigation pipelines."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "03aed751",
   "metadata": {},
   "outputs": [],
   "source": [
    "# directly use built-in mitigation with expectation evaluation + front-end (tc/qiskit) compiling system\n",
    "\n",
    "nqubit = 3\n",
    "shots = 8192\n",
    "c = tc.Circuit(nqubit)\n",
    "c.h(0)\n",
    "c.rz(0, theta=0.4)\n",
    "c.x(0)\n",
    "c.y(0)\n",
    "c.h(1)\n",
    "c.rx(2, theta=0.7)\n",
    "c.ry(1, theta=-1.2)\n",
    "c.cnot(0, 1)\n",
    "c.cnot(2, 0)\n",
    "c.h(1)\n",
    "c.x(2)\n",
    "\n",
    "print(\"exact: \", [np.real(c.expectation_ps(z=[i])).tolist() for i in range(nqubit)])\n",
    "\n",
    "t = apis.submit_task(\n",
    "    circuit=c,\n",
    "    shots=shots,\n",
    "    device=\"9gmon\",\n",
    "    compiled=True,\n",
    "    enable_qos_qubit_mapping=False,\n",
    "    enable_qos_gate_decomposition=False,\n",
    ")\n",
    "\n",
    "ct = t.results(blocked=True)\n",
    "\n",
    "mit = tc.results.readout_mitigation.ReadoutMit(\"9gmon?o=0\")\n",
    "mit.cals_from_system(3, shots=8192, method=\"local\")\n",
    "\n",
    "print(\n",
    "    \"experiments (mitigated directly via expectation): \",\n",
    "    [mit.expectation(ct, [i]) for i in range(nqubit)],\n",
    ")\n",
    "\n",
    "# no need to provider mapping in mit as there is no mapping in this case,\n",
    "# compiled=True itself doesn't enable front end qubit routing\n",
    "\n",
    "print(\n",
    "    \"experiments (mitigated using lstm): \",\n",
    "    [\n",
    "        tc.results.counts.expectation(mit.apply_correction(ct, 3, method=\"square\"), [i])\n",
    "        for i in range(nqubit)\n",
    "    ],\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "60e9d6d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "c.draw()  # target circuit: mimic a VQA case"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a45fa6f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# use backend compiling system enabled by qos and the very handy built-in auto mitigation\n",
    "# (only works without qubit mapping at front end)\n",
    "\n",
    "nqubit = 3\n",
    "shots = 8192\n",
    "c = tc.Circuit(nqubit)\n",
    "c.h(0)\n",
    "c.rz(0, theta=0.4)\n",
    "c.x(0)\n",
    "c.y(0)\n",
    "c.h(1)\n",
    "c.rx(2, theta=0.7)\n",
    "c.ry(1, theta=-1.2)\n",
    "c.cnot(0, 1)\n",
    "c.cnot(2, 0)\n",
    "c.h(1)\n",
    "c.x(2)\n",
    "\n",
    "print(\"exact: \", [np.real(c.expectation_ps(z=[i])) for i in range(nqubit)])\n",
    "\n",
    "t = apis.submit_task(\n",
    "    circuit=c,\n",
    "    shots=shots,\n",
    "    device=\"9gmon\",\n",
    "    compiled=False,\n",
    "    enable_qos_qubit_mapping=True,\n",
    "    enable_qos_gate_decomposition=True,\n",
    ")\n",
    "\n",
    "ct = t.results(blocked=True, mitigated=True)\n",
    "# auto mitigation with backend qubit mapping considered\n",
    "\n",
    "\n",
    "print(\n",
    "    \"experiments (mitigated): \",\n",
    "    [tc.results.counts.expectation(ct, [i]) for i in range(nqubit)],\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cf2d2690",
   "metadata": {},
   "outputs": [],
   "source": [
    "# inspect compiling results from the tc and qos for the task, we can directly get the circuit objects from prettified details\n",
    "\n",
    "c_complied_before_qos = t.details(prettify=True)[\"frontend\"]\n",
    "c_complied_after_qos = t.details(prettify=True)[\"backend\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b2b4b1e9",
   "metadata": {},
   "outputs": [],
   "source": [
    "c_complied_before_qos.draw()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1af33b6",
   "metadata": {},
   "outputs": [],
   "source": [
    "c_complied_after_qos.draw(output=\"mpl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ad85e14",
   "metadata": {},
   "source": [
    "dry run mode to query compiled circuit only from qos (not really sending the circuit to chips), we can use ``qos_dry_run=True`` option\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7fee9a15",
   "metadata": {},
   "outputs": [],
   "source": [
    "nqubit = 3\n",
    "shots = 8192\n",
    "c = tc.Circuit(nqubit)\n",
    "c.h(0)\n",
    "c.h(1)\n",
    "c.rx(2, theta=0.7)\n",
    "c.ry(1, theta=-1.2)\n",
    "c.cnot(0, 1)\n",
    "c.cnot(2, 0)\n",
    "c.h(1)\n",
    "\n",
    "\n",
    "t = apis.submit_task(\n",
    "    circuit=c,\n",
    "    shots=shots,\n",
    "    device=\"9gmon\",\n",
    "    compiled=True,\n",
    "    enable_qos_qubit_mapping=True,\n",
    "    enable_qos_gate_decomposition=True,\n",
    "    qos_dry_run=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e262a682",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "t.details(prettify=True, blocked=True)[\"backend\"].draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea015c48",
   "metadata": {},
   "source": [
    "## scalable readout simulation and mitigation\n",
    "\n",
    "Via TensorCircuit, we provide the capability to do scalable (20+ qubits) readout error simulation and mitigation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2b509155",
   "metadata": {},
   "outputs": [],
   "source": [
    "# scalable readout error simulation on tQuK with tensorcircuit backend using tensor network approach\n",
    "\n",
    "c = tc.Circuit(3)\n",
    "t = apis.submit_task(circuit=c, device=\"simulator:tcn1\", shots=8192)\n",
    "t.results(blocked=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71f634ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "t.results(mitigated=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7533330d",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "c = tc.Circuit(25)\n",
    "t = apis.submit_task(circuit=c, device=\"simulator:tcn1\", shots=8192)\n",
    "t.results(blocked=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06281585",
   "metadata": {},
   "source": [
    "Simulator device also support batch submission"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cdfb639c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# batch submission to the simulator\n",
    "cs = []\n",
    "for i in range(15):\n",
    "    c = tc.Circuit(15)\n",
    "    c.x(i)\n",
    "    cs.append(c)\n",
    "ts = apis.submit_task(circuit=cs, device=\"simulator:tcn1\", shots=8192)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8d8217e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# mitigated with m3 scalable on count dict\n",
    "c = tc.Circuit(15)\n",
    "c.x(0)\n",
    "t = apis.submit_task(circuit=c, device=\"simulator:tcn1\", shots=8192)\n",
    "\n",
    "mit = tc.results.readout_mitigation.ReadoutMit(\"simulator:tcn1\")\n",
    "mit.cals_from_system(15)\n",
    "\n",
    "raw_count = t.results(blocked=True)\n",
    "mit.apply_correction(raw_count, 15, method=\"M3_auto\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "292f9b11",
   "metadata": {},
   "outputs": [],
   "source": [
    "# mitigated scalable directly on expectation: not a wrapper for count but a new algorithm!\n",
    "# see eq 6 in https://arxiv.org/pdf/2006.14044.pdf\n",
    "\n",
    "mit.expectation(raw_count, [0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd454737",
   "metadata": {},
   "source": [
    "## list task and get previous task\n",
    "\n",
    "get history tasks and their details, so that your experimental data are always accessible with detailed meta data on the cloud"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2b80411b",
   "metadata": {},
   "outputs": [],
   "source": [
    "apis.list_tasks()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8dffbcfd",
   "metadata": {},
   "outputs": [],
   "source": [
    "apis.list_tasks(device=\"9gmon\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5e29190d",
   "metadata": {},
   "outputs": [],
   "source": [
    "t = apis.get_task(\"d77bec2f-ab07-4dbc-a273-caa8b23a921c\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d24ddc18",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "t.details()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "706c9c08",
   "metadata": {},
   "outputs": [],
   "source": [
    "t = apis.get_task(\"tencent::9gmon~~e32bb488-5ee9-4b07-8217-1e78ceb4bde3\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8ad61cb9",
   "metadata": {},
   "outputs": [],
   "source": [
    "t.details(prettify=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a5426c97",
   "metadata": {},
   "outputs": [],
   "source": [
    "t.results()"
   ]
  }
 ],
 "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.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}