tutorials/introduction/measure.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Measuring quantum states in QuAIRKit\n",
    "\n",
    "This tutorial demonstrates how to perform quantum measurement using QuAIRKit.\n",
    "\n",
    "**Table of Contents**\n",
    "\n",
    "- [Quantum measurement](#Quantum-measurement)\n",
    "- [Perform measurement](#perform-measurement)\n",
    "- [Positive operator-valued measurement](#positive-operator-valued-measurement)\n",
    "- [Batch measurement](#batch-measurement)\n",
    "- [Sampled measurements](#sampled-measurements)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time\n",
    "import traceback\n",
    "\n",
    "import quairkit as qkit\n",
    "from quairkit.database import *\n",
    "from quairkit.loss import *\n",
    "from quairkit.qinfo import *\n",
    "\n",
    "qkit.set_dtype(\"complex128\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quantum measurement\n",
    "\n",
    "The idea of measurement comes from one of the four postulates in quantum mechanics.\n",
    "\n",
    "> Postulate 3 [1]\n",
    ">\n",
    "> *Quantum measurement*s are described by a collection $\\{M_m\\}$ of measurement operators. These are operators acting on the state space of the system being measured. The index $m$ refers to the measurement outcomes that may occur in the experiment. If the state of the quantum system is $|\\psi\\rangle$ immediately before the measurement, then the probability that result $m$ occurs is given by\n",
    "> $$p(m) = \\langle\\psi|  M_m^\\dagger M_m |\\psi\\rangle \\tag{1}$$\n",
    "> and the state of the system after the measurement is\n",
    "> $$\\frac{M_m |\\psi\\rangle}{\\sqrt{\\langle\\psi| M_m^\\dagger M_m |\\psi\\rangle}}\\tag{2}$$\n",
    "> \n",
    "> where the measurement operators satisfy the completeness equation,\n",
    "> $$\\sum_m M_m^\\dagger M_m = I.\\tag{3}$$\n",
    "> The completeness equation expresses the fact that probabilities sum to one，\n",
    "> $$\\sum_m p(m) = \\sum_m \\langle \\psi \\vert M_m^\\dagger M_m \\vert \\psi \\rangle= 1\\tag{4}$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Such operator set $\\{M_m\\}$ is called a *Positive Operator-Valued Measure* (POVM). When all $M_m$ are orthogonal projectors  (i.e., $M_m M_{m'} = \\delta_{m,m'}M_m$ and $M = M^\\dagger$), this set is called a *Projection-valued Measure* (PVM). The quantum measurement described by PVM is called a *projective measurement*. \n",
    "\n",
    "Users can perform projective measurements based on the eigenbasis of an observable. For example, one can generate a PVM for the Pauli matrix $X$ as an observable.\n",
    "According to the spectral decomposition theorem, the Pauli matrix $X$ has the decomposition: $X = \\sum_m P_m$, where the set $\\{P_m\\}$ forms a Projection-valued Measure."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Projection-valued measure: \n",
      "tensor([[[ 0.5000+0.j,  0.5000+0.j],\n",
      "         [ 0.5000+0.j,  0.5000+0.j]],\n",
      "\n",
      "        [[ 0.5000+0.j, -0.5000+0.j],\n",
      "         [-0.5000+0.j,  0.5000+0.j]]])\n"
     ]
    }
   ],
   "source": [
    "pvm = pauli_str_povm(\"x\")\n",
    "print(f\"Projection-valued measure: \\n{pvm}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Perform measurement"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Projective measurements in QuAIRKit are mainly called by a torch Module `Measure`. There are several ways to initialize a `Measure` instance:\n",
    "\n",
    "1. Set computational measurement by default, i.e., $M_m = \\{|m\\rangle\\langle m|\\}$\n",
    "2. Set measurement by given Pauli string(s)\n",
    "3. Set measurement by given PVM(s) in *torch.Tensor*\n",
    "\n",
    "For `Measure` instances initialized in the first two ways, if the measurement is across all qubits, then the output state(s) will always be recognized as pure state(s)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "op = Measure()  # computational measure\n",
    "op = Measure(\"x\")  # x measure on a qubit\n",
    "op = Measure(pvm)  # measure with a pvm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Measure accepts the `State` instances and an (optional) measure position as input and returns the measurement result. Note that if the measure only happens on a part of the system, then the argument `qubits_idx` should be specified. The following example is to measure the first subsystem of state $\\rho$ with the PVM defined before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The probability distribution of outcome tensor([0.6159, 0.3841])\n"
     ]
    }
   ],
   "source": [
    "op = Measure(pvm)\n",
    "rho = random_state(num_qubits=2, rank=2)\n",
    "prob = op(rho, qubits_idx=[0])  # measure rho\n",
    "print(\"The probability distribution of outcome\", prob)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Users can get the collapsed state by setting `keep_state = True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The collapsed state for each outcome is \n",
      "-----------------------------------------------------\n",
      " Backend: density_matrix\n",
      " System dimension: [2, 2]\n",
      " System sequence: [0, 1]\n",
      " Batch size: [2]\n",
      "\n",
      " # 0:\n",
      "[[ 0.23+0.j   -0.08+0.21j  0.23+0.j   -0.08+0.21j]\n",
      " [-0.08-0.21j  0.27+0.j   -0.08-0.21j  0.27+0.j  ]\n",
      " [ 0.23+0.j   -0.08+0.21j  0.23+0.j   -0.08+0.21j]\n",
      " [-0.08-0.21j  0.27+0.j   -0.08-0.21j  0.27+0.j  ]]\n",
      " # 1:\n",
      "[[ 0.26+0.j   -0.16+0.02j -0.26+0.j    0.16-0.02j]\n",
      " [-0.16-0.02j  0.24+0.j    0.16+0.02j -0.24+0.j  ]\n",
      " [-0.26+0.j    0.16-0.02j  0.26+0.j   -0.16+0.02j]\n",
      " [ 0.16+0.02j -0.24+0.j   -0.16-0.02j  0.24+0.j  ]]\n",
      "-----------------------------------------------------\n",
      "\n"
     ]
    }
   ],
   "source": [
    "prob, collapsed_state = op(rho, qubits_idx=[0], keep_state=True)\n",
    "print(\"The collapsed state for each outcome is\", collapsed_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The probability of particular measurement outcome is obtained via setting `desired_result=x`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The probability for obtaining outcome 1 is tensor([0.3841]), with outcome state \n",
      "-----------------------------------------------------\n",
      " Backend: density_matrix\n",
      " System dimension: [2, 2]\n",
      " System sequence: [0, 1]\n",
      "[[ 0.26+0.j   -0.16+0.02j -0.26+0.j    0.16-0.02j]\n",
      " [-0.16-0.02j  0.24+0.j    0.16+0.02j -0.24+0.j  ]\n",
      " [-0.26+0.j    0.16-0.02j  0.26+0.j   -0.16+0.02j]\n",
      " [ 0.16+0.02j -0.24+0.j   -0.16-0.02j  0.24+0.j  ]]\n",
      "-----------------------------------------------------\n",
      "\n"
     ]
    }
   ],
   "source": [
    "x = \"1\"\n",
    "prob, collapsed_state = op(\n",
    "    rho, qubits_idx=[0], keep_state=True, desired_result=x\n",
    ")  # return the second outcome\n",
    "print(\n",
    "    f\"The probability for obtaining outcome {x} is {prob}, with outcome state\",\n",
    "    collapsed_state,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Users can also directly call the attribute `measure` of `State` instances for simple measurement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The probability distribution of outcome tensor([0.3633, 0.6367])\n",
      "The collapsed state for each outcome is \n",
      "-----------------------------------------------------\n",
      " Backend: density_matrix\n",
      " System dimension: [2]\n",
      " System sequence: [0]\n",
      " Batch size: [2]\n",
      "\n",
      " # 0:\n",
      "[[0.5+0.j 0.5+0.j]\n",
      " [0.5+0.j 0.5+0.j]]\n",
      " # 1:\n",
      "[[ 0.5+0.j -0.5+0.j]\n",
      " [-0.5+0.j  0.5+0.j]]\n",
      "-----------------------------------------------------\n",
      "\n"
     ]
    }
   ],
   "source": [
    "rho = random_state(num_qubits=1, rank=2)\n",
    "prob = rho.measure(pvm)  # same as Measure(pvm)(rho)\n",
    "print(\"The probability distribution of outcome\", prob)\n",
    "prob, collapsed_state = rho.measure(\n",
    "    pvm, keep_state=True\n",
    ")  # same as Measure(pvm)(rho, keep_state=True)\n",
    "print(\"The collapsed state for each outcome is\", collapsed_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Positive operator-valued measurement"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "POVMs are the generalization of PVMs, describing the effect on a subsystem of a projective measurement performed on a larger system. In QuAIRKit, we can perform positive operator-valued measurement by  `State.measure`, with `is_povm` set to True.\n",
    "\n",
    "Computation for POVM is often more efficient than that for PVM, as it directly computes the probability. However, its potential lack of a unique post-measurement state makes it less useful in practice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Time for measuring with pvm: 0.0090117455s\n",
      "Time for measuring with povm: 0.0029997826s\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Traceback (most recent call last):\n",
      "  File \"C:\\Users\\Cloud\\AppData\\Local\\Temp\\ipykernel_21928\\2671688636.py\", line 11, in <module>\n",
      "    rho.measure(pvm, is_povm=True, keep_state=True)\n",
      "  File \"c:\\Users\\Cloud\\anaconda3\\envs\\quair_test\\lib\\site-packages\\quairkit\\core\\state\\backend\\__init__.py\", line 702, in measure\n",
      "    raise ValueError(\n",
      "ValueError: `is_povm` and `keep_state` cannot be both True, since a general POVM does not distinguish states.\n"
     ]
    }
   ],
   "source": [
    "start_time = time.time()\n",
    "prob = rho.measure(pvm)\n",
    "print(f\"Time for measuring with pvm: {time.time() - start_time:.10f}s\")\n",
    "\n",
    "\n",
    "start_time = time.time()\n",
    "prob = rho.measure(pvm, is_povm=True)\n",
    "print(f\"Time for measuring with povm: {time.time() - start_time:.10f}s\")\n",
    "\n",
    "try:\n",
    "    rho.measure(pvm, is_povm=True, keep_state=True)\n",
    "except ValueError:\n",
    "    traceback.print_exc()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Batch measurement"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "QuAIRKit supports batched measurement under the broadcasting rule, which includes either one or multiple PVMs, one or multiple input states, or both. This means that users can perform different measurements at the same time. The broadcasting rule is summarized as follows:\n",
    "\n",
    "| PVM with size m    | State      | Probability       |\n",
    "|:----------------:|:---------------------:|:---------------------:|\n",
    "| [None, ...]   | [None, ...] | [m] |\n",
    "| [None, ...] | [n, ...]       | [n, m] |\n",
    "| [n, ...] | [None, ...]       | [n, m] |\n",
    "| [n, ...] | [n, ...]       | [n, m] |\n",
    "| [n, ...] | [p, ...]       | Error |\n",
    "\n",
    "Here the first dimension indicates the batch size of PVMs and input states.\n",
    "\n",
    "- The first row refers to 1 PVM set with m elements, and 1 state to be measured, so there is m outcomes to form a probability distribution.\n",
    "- The second row means there is 1 PVM set with m elements, and n state to be measured. Therefore, same measurement is implemented for different states.\n",
    "- The third row denotes n PVM sets with m elements, and 1 state to be measured. Different measurements will be executed for one state.\n",
    "- The fourth row means there are n PVM sets with m elements each and n states, to perform corresponding measurements for every state.\n",
    "\n",
    "Notice that the number of PVM sets should be consistent with the number of states, as it is shown in the last row."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Users can also initialize a batch Measure instance via a Pauli string, or directly input the batched PVM in *torch.Tensor*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The tensor shape of the measurement: torch.Size([3, 2, 2, 2])\n"
     ]
    }
   ],
   "source": [
    "op = Measure([\"x\", \"y\", \"z\"])  # measure states by x, y, z basis, respectively\n",
    "\n",
    "list_pvm = pauli_str_povm([\"x\", \"y\", \"z\"])\n",
    "\n",
    "print(f\"The tensor shape of the measurement: {list_pvm.shape}\")\n",
    "\n",
    "op = Measure(list_pvm)  # equivalent to Measure(['x', 'y', 'z'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As shown by the above table, users are able to apply `Measure` to a single state,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The measured states for the first batch is \n",
      "-----------------------------------------------------\n",
      " Backend: density_matrix\n",
      " System dimension: [2]\n",
      " System sequence: [0]\n",
      " Batch size: [2]\n",
      "\n",
      " # 0:\n",
      "[[0.5+0.j 0.5+0.j]\n",
      " [0.5+0.j 0.5+0.j]]\n",
      " # 1:\n",
      "[[ 0.5+0.j -0.5+0.j]\n",
      " [-0.5+0.j  0.5+0.j]]\n",
      "-----------------------------------------------------\n",
      " with prob distribution tensor([0.3633, 0.6367])\n"
     ]
    }
   ],
   "source": [
    "prob, collapsed_state = op(rho, keep_state=True)\n",
    "print(\n",
    "    \"The measured states for the first batch is\",\n",
    "    collapsed_state[0],\n",
    "    f\"with prob distribution {prob[0]}\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or apply `Measure` to a batched state. Note that the batch dimension needs to be matched."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The measured states for the first batch is \n",
      "-----------------------------------------------------\n",
      " Backend: state_vector\n",
      " System dimension: [2]\n",
      " System sequence: [0]\n",
      " Batch size: [2]\n",
      "\n",
      " # 0:\n",
      "[0.68-0.18j 0.68-0.18j]\n",
      " # 1:\n",
      "[ 0.63-0.32j -0.63+0.32j]\n",
      "-----------------------------------------------------\n",
      " with prob distribution tensor([0.8764, 0.1236])\n"
     ]
    }
   ],
   "source": [
    "batch_size = 3\n",
    "list_rho = random_state(num_qubits=1, size=batch_size)\n",
    "\n",
    "prob, collapsed_state = op(list_rho, keep_state=True)\n",
    "print(\n",
    "    \"The measured states for the first batch is\",\n",
    "    collapsed_state[0],\n",
    "    f\"with prob distribution {prob[0]}\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sampled measurements\n",
    "\n",
    "Users can use `quairkit.qinfo.prob_sample` to determine shots of measurement based on given probability distributions. The function is used to simulate the outcomes of quantum measurements. When users perform a quantum measurement, the result is probabilistic, namely, outcomes are generated with different probabilities. The `prob_sample` function allows users to simulate this by generating samples (or \"shots\") based on a provided probability distribution.\n",
    "\n",
    "For example, if users simulate 1024 shots, the output might be \n",
    "```plaintext\n",
    "{'00': tensor([98, ...]), '01': tensor([230, ...]), '10': tensor([300, ...]), '11': tensor([396, ...])}\n",
    "```\n",
    "which means that:\n",
    "- `00` occurred 98 times,\n",
    "- `01` occurred 230 times,\n",
    "- `10` occurred 300 times,\n",
    "- `11` occurred 396 times.\n",
    "\n",
    "Users can also adjust the argument `binary` and `proportional` to change the output format:\n",
    "\n",
    "- `binary` is False: the dictionary index is in the decimal system. \n",
    "- `proportional` is True: values are transformed into proportions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3 probability distributions are\n",
      " tensor([[0.8764, 0.1236],\n",
      "        [0.3707, 0.6293],\n",
      "        [0.6343, 0.3657]])\n",
      "\n",
      "The outcomes of quantum measurements:\n",
      "{'0': tensor([913, 349, 641]), '1': tensor([111, 675, 383])}\n",
      "\n",
      "The outcomes of quantum measurements with the decimal system of dictionary system:\n",
      " {'0': tensor([908, 402, 645]), '1': tensor([116, 622, 379])}\n",
      "\n",
      "The outcomes of quantum measurements in proportion:\n",
      " {'0': tensor([0.8809, 0.3799, 0.6299]), '1': tensor([0.1191, 0.6201, 0.3701])}\n"
     ]
    }
   ],
   "source": [
    "batch_size = 3\n",
    "print(f\"{batch_size} probability distributions are\\n\", prob)\n",
    "\n",
    "print(f\"\\nThe outcomes of quantum measurements:\\n{prob_sample(prob)}\")\n",
    "print(\n",
    "    f\"\\nThe outcomes of quantum measurements with the decimal system of dictionary system:\\n\",\n",
    "    prob_sample(prob, binary=False),\n",
    ")\n",
    "print(\n",
    "    f\"\\nThe outcomes of quantum measurements in proportion:\\n\",\n",
    "    prob_sample(prob, proportional=True),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "[1] Nielsen, Michael A., and Isaac L. Chuang. Quantum computation and quantum information. Vol. 2. Cambridge: Cambridge university press, 2001."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Table: A reference of notation conventions in this tutorial.*\n",
    "\n",
    "| Symbol        | Variant          | Description                               |\n",
    "|:---------------:|:------------------:|-------------------------------------------|\n",
    "|$p$| $p(x),p(m)$ | probability distribution|\n",
    "| $M_m$ || measurement operator|\n",
    "|$M_m^\\dagger$ || conjugate transpose of $M_m$|\n",
    "| $\\{\\vert m \\rangle \\langle m \\vert\\}$||computational basis|\n",
    "|$\\delta_{m,m'}$||Kronecker delta|"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "---------VERSION---------\n",
      "quairkit: 0.3.0\n",
      "torch: 2.5.1+cpu\n",
      "numpy: 1.26.0\n",
      "scipy: 1.14.1\n",
      "matplotlib: 3.10.0\n",
      "---------SYSTEM---------\n",
      "Python version: 3.10.16\n",
      "OS: Windows\n",
      "OS version: 10.0.26100\n",
      "---------DEVICE---------\n",
      "CPU: ARMv8 (64-bit) Family 8 Model 1 Revision 201, Qualcomm Technologies Inc\n"
     ]
    }
   ],
   "source": [
    "qkit.print_info()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "quair_test",
   "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.10.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}