deutsch's algorithm.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deutsch’s Algorithm\n",
    "\n",
    "We have a function which takes in a bit and outputs a bit. This can be represented as \\( f: \\{0, 1\\} \\rightarrow \\{0, 1\\} \\).\n",
    "\n",
    "The function \\( f \\) has a property; either it is constant or balanced.\n",
    "\n",
    "- If constant, the outputs are the same regardless of the inputs, i.e., \\( f(0) = f(1) \\).\n",
    "- If balanced, the outputs are balanced across their possibilities, i.e., if \\( f(0) = 0 \\) then \\( f(1) = 1 \\) or if \\( f(0) = 1 \\) then \\( f(1) = 0 \\).\n",
    "\n",
    "The question we would like to answer is if the function is constant or balanced.\n",
    "\n",
    "Classically, if we are given a function \\( f \\), we can solve to find its property via the code below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Treat the code snippet below like a black box, i.e., you don't have access to the value of the property argument and can just query f with different inputs.\n",
    "\n",
    "\n",
    "def f(x, property='constant'):\n",
    "\n",
    "    if property == 'constant':\n",
    "\n",
    "        # The output is a 1 regardless of the input; we can also make the output to be 0.\n",
    "\n",
    "        if x == 0:\n",
    "            return 1\n",
    "        elif x == 1:\n",
    "            return 1\n",
    "\n",
    "    if property == 'balanced':\n",
    "\n",
    "        # The output depends on the input.\n",
    "\n",
    "        if x == 0:\n",
    "            return 1\n",
    "        elif x == 1:\n",
    "            return 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us now classically find out if the function we defined above is constant or balanced."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The function is constant\n"
     ]
    }
   ],
   "source": [
    "if f(0) == 0:\n",
    "    if f(1) == 0:\n",
    "        print('The function is constant')\n",
    "    elif f(1) == 1:\n",
    "        print('The function is balanced')\n",
    "\n",
    "elif f(0) == 1:\n",
    "    if f(1) == 1:\n",
    "        print('The function is constant')\n",
    "    elif f(1) == 0:\n",
    "        print('The function is balanced')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you step through the `if` statements above, you will see that we require two calls to the function to determine its property. That is, we have to query twice.\n",
    "\n",
    "The claim is that Deutsch’s algorithm can solve for this property with one function evaluation, demonstrating quantum advantage.\n",
    "\n",
    "Below, we first go through the math and then the implementation in CUDA Quantum."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# XOR Operation\n",
    "\n",
    "The XOR (exclusive OR) operation follows the rules of addition modulo 2. For example, a quick way to perform the XOR calculation is if the result of the addition is an even number, the result is 0; otherwise, it is 1.\n",
    "\n",
    "# Quantum Oracles\n",
    "\n",
    "Suppose we have a function \\( f \\). We can compute this function on a quantum computer using oracles, which we treat as black box functions that yield the output with an appropriate sequence of logic gates.\n",
    "\n",
    "An oracle represented as \\( U_f \\) allows us to transform the state \\( |x\\rangle|y\\rangle \\) into \\( |x\\rangle|y \\oplus f(x)\\rangle \\). If \\( y = 0 \\), then \\( |x\\rangle|0 \\oplus f(x)\\rangle = |x\\rangle|f(x)\\rangle \\).\n",
    "\n",
    "This is remarkable because by setting \\( y = 0 \\), we can extract the value of \\( f(x) \\) by measuring the value of the second qubit.\n",
    "\n",
    "# Phase Oracle\n",
    "\n",
    "Since \\( f(x) \\) can be either 0 or 1, we have that \\( f(x) = 0 \\) or \\( f(x) = 1 \\).\n",
    "\n",
    "Similarly, \\( f(\\bar{x}) = 0 \\) or \\( f(\\bar{x}) = 1 \\), where the bar on top of \\( x \\) denotes ‘not \\( x \\)’.\n",
    "\n",
    "Let us now prove a result which we shall use later:\n",
    "\n",
    "\\[ U_f|x\\rangle|-\\rangle = (-1)^{f(x)}|x\\rangle|-\\rangle \\]\n",
    "\n",
    "In summary, \\( U_f \\) applies a phase to \\( |-\\rangle \\) based on the value of \\( f(x) \\), leaving the \\( x \\) qubit unchanged.\n",
    "\n",
    "# Quantum Parallelism\n",
    "\n",
    "Consider:\n",
    "\n",
    "\\[ U_f \\left( \\frac{1}{\\sqrt{2}}(|0\\rangle + |1\\rangle) \\right)|-\\rangle = \\frac{1}{\\sqrt{2}} \\left( |0\\rangle(-1)^{f(0)} + |1\\rangle(-1)^{f(1)} \\right)|-\\rangle \\]\n",
    "\n",
    "We have calculated information about both \\( f(0) \\) and \\( f(1) \\) simultaneously. Quantum mechanics allows for parallelism by exploiting the ability of superposition states.\n",
    "\n",
    "# Deutsch's Algorithm\n",
    "\n",
    "Our aim is to find out if \\( f \\) is a constant or a balanced function. If constant, \\( f(0) = f(1) \\), and if balanced, \\( f(0) \\neq f(1) \\).\n",
    "\n",
    "We step through the circuit diagram below and follow the math after the application of each gate.\n"
   ]
  },
  {
   "attachments": {
    "image.png": {
     "image/png": "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"
    }
   },
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![image.png](attachment:image.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the result we proved in the phase oracle section above:\n",
    "\n",
    "We now drop the second qubit in the \\( |-\\rangle \\) state from our derivations as the figure above has no further gate operations acting on it. Remember, our aim is to determine if \\( f \\) is a constant or a balanced function. We have the following options:\n",
    "\n",
    "We can now measure the first qubit to yield either a \\( |0\\rangle \\) or a \\( |1\\rangle \\) to determine if \\( f \\) is constant or balanced.\n",
    "\n",
    "Deutsch’s algorithm may not be practically useful but it does demonstrate quantum advantage since it uses one function call to determine the property of \\( f \\) in comparison to two for classical methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import the CUDA-Q package and set the target to run on NVIDIA GPUs.\n",
    "\n",
    "import cudaq\n",
    "import numpy as np\n",
    "\n",
    "from typing import List\n",
    "\n",
    "cudaq.set_target(\"nvidia\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Here we input the values of [f(0), f(1)] which allows us to represent constant or balanced functions.\n",
    "\n",
    "fx = [0, 1]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     ╭───╮          ╭───╮\n",
      "q0 : ┤ h ├───────●──┤ h ├\n",
      "     ├───┤╭───╮╭─┴─╮╰───╯\n",
      "q1 : ┤ x ├┤ h ├┤ x ├─────\n",
      "     ╰───╯╰───╯╰───╯     \n",
      "\n",
      "f(x) is a balanced function\n"
     ]
    }
   ],
   "source": [
    "# Let us now code up the circuit shown above following the state Psi after each step.\n",
    "\n",
    "qubit_count = 2\n",
    "\n",
    "\n",
    "@cudaq.kernel\n",
    "def kernel(fx: List[int]):\n",
    "    qubit_0 = cudaq.qubit()\n",
    "    qubit_1 = cudaq.qubit()\n",
    "\n",
    "    # Psi 0\n",
    "    x(qubit_1)\n",
    "\n",
    "    # Psi 1\n",
    "    h(qubit_0)\n",
    "    h(qubit_1)\n",
    "\n",
    "    # Psi 2 - oracle\n",
    "    if fx[0] == 1:\n",
    "        x.ctrl(qubit_0, qubit_1)\n",
    "        x(qubit_1)\n",
    "\n",
    "    if fx[1] == 1:\n",
    "        x.ctrl(qubit_0, qubit_1)\n",
    "\n",
    "    # Psi 3\n",
    "    h(qubit_0)\n",
    "\n",
    "    # Measure the qubit to yield if the function is constant or balanced.\n",
    "    mz(qubit_0)\n",
    "\n",
    "\n",
    "print(cudaq.draw(kernel, fx))\n",
    "\n",
    "result = cudaq.sample(kernel, fx, shots_count=1)\n",
    "\n",
    "if np.array(result)[0] == '0':\n",
    "    print('f(x) is a constant function')\n",
    "elif np.array(result)[0] == '1':\n",
    "    print('f(x) is a balanced function')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "cuda-quantum",
   "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}