{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Simon's Algorithm\n", "\n", "**Abstract:** We study a quantum algorithm known as Simon's algorithm, which provided the first example of an exponential speedup over the best known classical algorithm by using a quantum computer to solve a particular problem. Originally published in 1994, Simon's algorithm was a precursor to Shor's well-known factoring algorithm, and it served as inspiration for many of the seminal works in quantum computation that followed. \n", "\n", "This notebook is aimed at users with some basic knowledge of quantum computing and quantum circuits.\n", "\n", "### Table of Contents\n", "* [Simon's Problem Statement](#statement)\n", " * [Example for n=3](#example)\n", "* [Classical Complexity](#classicalcomplexity)\n", "* [Quantum Algorithm for Simon's Problem](#quantumalgorithm)\n", " * [Quantum Circuit](#circuit)\n", " * [Running Simon's Algorithm](#runningintro)\n", " * [Classical Post-Processing](#postprocessintro)\n", "* [Quantum Complexity](#quantumcomplexity)\n", "* [Implementing Simon's Algorithm in Amazon Braket](#implementation)\n", "* [References](#references)\n", "* [Appendix](#appendix)\n", " * [Implementing an Oracle Function](#oracleimplementation)\n", " * [Implementing the Classical Post-Processing](#appendixpostprocessing)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Simon's Problem Statement: \n", "\n", "Suppose we’re given a function $f:\\{0,1\\}^n \\rightarrow \\{0,1\\}^n$ that maps bit strings to bit strings along with the promise that\n", "$$\\forall x,y \\in \\{0,1\\}^n, \\quad f(x) = f(y) \\iff x=y\\oplus s,$$\n", "for some unknown $n$-bit string $s \\in \\{0,1\\}^n$, and where $\\oplus$ means bitwise addition modulo 2.\n", "\n", "Said another way, there exists an unknown string $s$ such that, $\\forall x, \\; f(x)=f(x\\oplus s)$. When $s$ is non-zero, the function is two-to-one as it maps *exactly* two inputs to every unique output.\n", "\n", "The goal of Simon's problem is to determine if $f$ is one-to-one, or two-to-one, or equivalently to find the secret string $s$.\n", "\n", "Since we're given the promise that $f(x)=f(y)\\implies x=y\\oplus s$, this means that $s=x\\oplus y$ whenever $f(x)=f(y)$. Thus, one way to solve this problem is to find two inputs to the function $f$ that produce the *same* output; $s$ is then the XOR of those two input strings. See [[1]](#References) for more details." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

Example for n=3:

\n", "\n", "Consider the function $f:\\{0,1\\}^3\\to\\{0,1\\}^3$ defined by the truth table below. \n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
$$x$$
$$f(x)$$
$$000$$
$$000$$
$$001$$
$$001$$
$$010$$
$$001$$
$$011$$
$$000$$
$$100$$
$$100$$
$$101$$
$$101$$
$$110$$
$$101$$
$$111$$
$$100$$
\n", "\n", " \n", " \n", "By inspection, we can see that $f$ satisfies the properties described in the statement of Simon's problem. In particular, note that each output $f(x)$ appears twice for two distinct inputs. We are given the promise that, for each of these two inputs $x$ and $y$ with the same output $f(x)=f(y)$, we have $x \\oplus s = y$ for a yet to be determined $s$, and therefore $x\\oplus y = s$.\n", "\n", "For concreteness, notice that the input strings $001$ and $010$ are both mapped by $f$ to the same output string $001$. Taking the bitwise XOR of $001$ and $010$ we obtain the secret string $s$:\n", "\n", "$$s=001 \\oplus 010 = 011$$\n", "\n", "Therefore, in this example, the secret string is $s = 011$.\n", " \n", " \n", "In this specific example, we also see that the string $000$ is mapped to itself. Since $x\\oplus y=s$ for two inputs $x$ and $y$ with the same output, we must have that $s$ is also mapped to $000$, since $s=000\\oplus s$. Indeed, we see that $011$ maps to $000$, as expected.\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "## Classical Complexity\n", "\n", "To solve Simon's problem classically, one needs to find two different inputs $x$ and $y$ for which $f(x)=f(y)$. As we saw above, one can then determine $s=x\\oplus y$. How hard is it to find two distinct inputs that map to the same output, given the function $f$ as a black box? For $n$-bit strings, there are $2^n$ possible inputs. Thus, in the worst case, one would need to check at most $2^n$ different inputs to find a pair that maps to the same output; this provides an upper bound on the required query complexity.\n", "\n", "It turns out that a *lower* bound on the classical query complexity of Simon's algorithm can also be found: $\\Omega ({\\sqrt {2^{n}}})$. Proving this lower bound requires a little more work and is outside the scope of this notebook, so instead we will just provide some intuition.\n", "\n", "As mentioned above, the goal is to find a pair of input strings $x$ and $y$ that map to the *same* output string $f(x)=f(y)$ -- a collision. Finding a collision in a set is an instance of the well-known (generalized) birthday problem [[2]](#References): within a group of people, what is the probability that two of them share the same birthday? One can turn this problem around and ask \"how many people do we need in a room to ensure that the probability that at least two of them share a birthday is greater than some fixed number?\" This latter question gets to the heart of solving Simon's problem classically: how many queries to the function $f$ do we need to make to guarantee that we find a collision, with high probability? In the case of the birthday problem, we would need enough people in the room so that when we generate all possible pairings of people, we would have about 365 possible pairs. That way, we'd have a good chance that at least one of those pairs of people share a birthday. Using this intuition, we need to query $f$ enough times to generate a set of *pairs* with roughly the same size as the number of possible inputs ($2^n$). If we make $k$ queries to the function $f$, we can generate ${k \\choose 2}=\\frac{k(k-1)}{2}\\sim k^2$ pairs. Thus, we need to make $k$ queries such that ${k\\choose 2}\\gtrsim 2^n$ to have a high probability of generating a collision, and therefore, $k>\\Omega(\\sqrt{2^n})$." ] }, { "attachments": { "image.png": { "image/png": "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IgKCHImwm5QAAQIECBAgQIAAAQLtKSDIUVvfb7vttt6T/MWhgHL377zzztoGT3jrKMhQvI799tsv4YoaM/1JJ51Usq5ojZtttlmIQjl9v+bOnRt++MMflmwfhTmix31VFhDkqGzjGQIECBAgQIAAAQIECBDIh4AgRz76aBUECBAgQIAAAQIECBDIhIAgR21tKhcKKA4/FO4PHz48fPrpp7UNnvDWZ511VkmA4fLLL0+4ovqn/8tf/lKypqg/UTDjvffeiw1+3333hVVXXTW2fbTPJZdcEtveA18JCHJ8ZeEeAQIECBAgQIAAAQIECORTQJAjn321KgIECBAgQIAAAQIECKRSQJCjtrZsscUWZU/0FwIchdutt966toFTsPWOO+5Ysrbnn38+BVUNvoR//vOfIbo8TKEnhdsodND364MPPii5pEph28Lt5MmT++7i+yIBQY4iDHcJECBAgAABAgQIECBAIJcCghy5bKtFESBAgAABAgQIECBAIJ0CghzV92XhwoVh2LBhsWBA4WR/8e2pp55a/cAp2HLJkiVhxIgRvWuLAhA9PT0pqGzwJXzve9/rXU9xb/785z/HBj333HPLblvY78wzz4zt44GvBAQ5vrJwjwABAgQIECBAgAABAgTyKSDIkc++WhUBAgQIECBAgAABAgRSKSDIUX1bbr/99n5P9hdO+ke3d9xxR/UDp2DL6LIixfXvt99+Kahq8CW8++67Ibq8TfGaCvfnzZsXG7jc66CwfXQ7ffr02D4e+EpAkOMrC/cIECBAgAABAgQIECBAIJ8Cghz57KtVESBAgAABAgQIECBAIJUC5U5gz549O5W1Jl3UySefXDYYUHzCP7ofBQg+/fTTpMutaf6f/vSnJWu7/PLLa9o/bRufdtppJesp9Gj8+PFlS42CK4Vt+t6uu+66YfHixWX38+D/FxDkcCQQIECAAAECBAgQIECAQN4FBDny3mHrI0CAAAECBAgQIECAQIoEBDmqb8ZWW21V8WR/8cn/aLusfW2//fYla3v++eeztoSSer/2ta+VrKfQn4MOOqhku8I306ZNK7t9Z2dnePzxxwubua0gIMhRAcbDBAgQIECAAAECBAgQIJAbAUGO3LTSQggQIECAAAECBAgQIJB+AUGO6nr02WefVbxURyEkULg95ZRTqhs0JVstWrQojBgxojfI0NXVFXp6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QY66URqIAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIFCbgCBHbX7OJkCAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAjUTUCQo26UBiJAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQI1CYgyFGbn7MJECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAnUTEOSoG6WBCBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQK1CQhy1ObnbAIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIBA3QQEOepGaSACBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAQG0Cghy1+TmbAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIFA3AUGOulEaiAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBQm4AgR21+ziZAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQI1E1AkKNulAYiQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECNQmIMhRm5+zCRAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQJ1ExDkqBulgQgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECtQkIctTm52wCBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAQN0EBDnqRmkgAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgEBtAoIctfk5mwABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBQN4H/A7fCMzYWtmgcAAAAAElFTkSuQmCC" } }, "cell_type": "markdown", "metadata": {}, "source": [ "## Quantum Algorithm for Simon's Problem\n", "\n", "Simon's algorithm is a scheme for solving the problem above using exponentially fewer queries to the function $f$. In order for Simon's algorithm to work, one needs to be able to implement the unknown function $f$ using quantum logic. That is, given an input *quantum state* $|x\\rangle$, one needs a *unitary* $U_f$ satisfying\n", "$$U_f|x\\rangle |0\\rangle = |x\\rangle |f(x)\\rangle.$$\n", "This unitary is an *oracle* for $f$, and the goal is to query it as few times as possible to learn the secret string $s$.\n", "\n", "### Quantum Circuit\n", "\n", "Simon's algorithm involves both quantum and classical components. The quantum part of Simon's algorithm is used to query the oracle efficiently, while the classical component is used to process measurement results and determine the hidden string $s$. A circuit for the quantum component of Simon's algorithm is shown below.\n", "
\n", "\n", "
\n", "\n", "For a function $f$ acting on $n$-bit strings, the circuit above acts on $2n$ qubits, as needed for the definition of $U_f$. Only the first $n$ qubits are measured; the remaining qubits are unused after the application of $U_f$.\n", "\n", "### Running Simon's Algorithm\n", "To solve Simon's problem, one needs to run the quantum circuit above several times. After each run of the circuit, the measurements of the first $n$ qubits produce an output bit string, which we denote by $z$.\n", "\n", "An analysis of the circuit above shows that each output bit string $z$ satisfies the following condition:\n", "$$ z\\cdot s = 0 \\; \\mod{2}.$$\n", "\n", "Let us now analyze the above circuit step-by-step:\n", "1. Initialize all qubits in the $|0\\rangle$ state. That is, we start in the state $|0\\rangle^{\\otimes n} \\otimes |0\\rangle^{\\otimes n}$. We will use the shorthand $|0\\rangle^{\\otimes n}\\equiv |0^n\\rangle$\n", "2. Apply Hadamard gates to each of the first $n$ qubits, placing them in the equal superposition state: $$\\frac{1}{\\sqrt{2^n}}\\sum_{x \\in \\{0, 1\\}^n} |x\\rangle |0^n\\rangle$$.\n", "3. Apply the oracle $U_f$, which computes the function $f$ into the last $n$ qubits, giving the state $$\\frac{1}{\\sqrt{2^n}}\\sum_{x \\in \\{0, 1\\}^n} |x\\rangle |f(x)\\rangle$$\n", "4. Measure the last $n$ qubits, giving a random result $f(x)$. If $f$ is one-to-one, this output of $f$ corresponds to an input of $x$. If $f$ is two-to-one, the output of $f$ corresponds to an input of either either $x$ or $y = x \\oplus s$, where $x$ and $y$ are the two different inputs to $f$ that gave the *same* output $f(x)=f(y)$. Hence we are left with the first $n$ qubits in the state;\n", "
A. $|x\\rangle$,                    if $f$ is one-to-one;
\n", "
B. $\\frac{1}{\\sqrt{2}} (|x\\rangle + |y\\rangle)$, where $x \\oplus y = s$,  if $f$ is two-to-one.
\n", " Note that this step is not strictly necessary, since we do not need the measurement result, but we include it as it makes the analysis easier.\n", "5. Apply Hadamard gates to each of the first $n$ qubits. If $f$ is one-to-one, the state $|x\\rangle$ is mapped to $$H^{\\otimes n} |x\\rangle = \\frac{1}{\\sqrt{2^n}} \\sum_{z \\in \\{0, 1\\}^n} (-1)^{x \\cdot z}|z\\rangle,$$\n", " where $x\\cdot z$ is the dot product between the two strings represented as vectors (modulo 2).\n", " \n", " Similarly, if $f$ is two-to-one, the state $\\frac{1}{\\sqrt{2}}(|x\\rangle + |y\\rangle)$ is mapped to $$\\frac{1}{\\sqrt{2^{n+1}}} \\sum_{z \\in \\{0, 1\\}^n} [(-1)^{x \\cdot z} + (-1)^{y \\cdot z}]|z\\rangle$$.\n", "6. Measure the first $n$ qubits.\n", " 1. If $f$ is one-to-one, measurements return a random bit string $z$ uniformly chosen from $\\{0,1\\}^n$.\n", " 2. If $f$ is two-to-one, measurements return a random bit string $z$ such that $x \\cdot z = y \\cdot z \\,\\mathrm{mod}\\, 2$, since otherwise the amplitude $(-1)^{x \\cdot z} + (-1)^{y \\cdot z}$ cancels out. Using the criterion for Simons problem (i.e,. $f(x)=f(y) \\implies x=y\\oplus s$), we find that\n", "\\begin{align*}\n", "x\\cdot z &= y\\cdot z & \\mod{2}\\\\\n", "x\\cdot z &= (x\\oplus s)\\cdot z & \\mod{2}\\\\\n", "x\\cdot z &= x\\cdot z\\oplus s\\cdot z & \\mod{2}\\\\\n", "0 &= s\\cdot z & \\mod{2}\n", "\\end{align*}\n", " \n", " \n", " Thus, in both cases we obtain a random bit string $z$ such that $s \\cdot z = 0$.\n", "\n", "Therefore, each time we run the quantum circuit above, we find a bit string $z$ that is orthogonal to the secret string $s$. \n", "\n", "### Classical Post-Processing\n", "From the measurement results $\\{z_1, \\dots, z_k\\}$, we can form a system of equations:\n", "$$ \\begin{aligned}z_{1}\\cdot s&=0\\mod{2}\\\\z_{2}\\cdot s&=0\\mod{2}\\\\&\\,\\,\\vdots \\\\z_{k}\\cdot s&=0\\mod{2}\\end{aligned}$$ \n", "\n", "There are $k$ equations and $n$ unknowns (the elements of $s$). If we run the quantum part enough times so that we find $n$ **independent** equations, then we can solve these equations (using, e.g., Gaussian elimination) to recover the secret string $s$. This is precisely the classical post-processing required: solve the system of equations found above to recover the string $s$. We refer the interested reader to the [Appendix](#Classical-post-processing) for details." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Quantum Complexity\n", "How many queries do we need to make to $U_f$ in the quantum case? Above we saw that we need to run the quantum part of the algorithm $k$ times to generate a system of equations. We need to find $n$ linearly independent equations for the system to be determined. Thus, we need at least $n$ queries to $U_f$ to find such a system. It is possible, however, that we will get the same measurement outcome on different runs of the quantum algorithm, so we would need to re-do those runs that do not produce distinct measurement outcomes. Fortunately, these repeated outcomes are unlikely, so we only need $O(n)$ queries to the oracle $U_f$.\n", "\n", "Comparing the quantum and classical algorithms, we saw that the classical algorithm requires at least $\\Omega(2^{0.5 n})$ queries to $f$, whereas the quantum algorithm requires only $O(n)$. Thus, we have established an *exponential* speedup by using the quantum algorithm above." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Implementing Simon's Algorithm in Amazon Braket" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "# Imports and Setup\n", "from braket.circuits import Circuit, circuit\n", "from braket.devices import LocalSimulator\n", "import numpy as np\n", "\n", "import matplotlib.pyplot as plt\n", "%matplotlib inline\n", "\n", "# Sets the device to run the circuit on\n", "device = LocalSimulator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We also import a method called `simons_oracle`, which generates a circuit implementing an example oracle function. The code for `simons_oracle` is defined in the `simons_utils.py` module, and it is shown in the [Appendix](#Implementing-an-oracle-function) for completeness. " ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "#Import local utils\n", "from simons_utils import simons_oracle" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We now define the secret string, $s$:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "The secret string is: 101011\n" ] } ], "source": [ "s = '101011'\n", "\n", "# Other examples to try:\n", "# s = '011'\n", "# s = '00000'\n", "# s = '1'\n", "# Generate a random string of random length from 1 to 10:\n", "# s=\"\".join(str(np.random.randint(2)) for _ in range(np.random.randint(1,10)))\n", "\n", "print(\"The secret string is: \"+ s)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Circuit Definition\n", "\n", "We now define the quantum circuit for Simon's algorithm:\n", "1. Apply Hadamard gates to the first $n$-qubits. \n", "\n", "\n", "2. Query the oracle (i.e., the $U_f$ gate). In this example, the oracle is defined dynamically, based on our chosen value of $s$. You can try experimenting with different values of $s$ (with differing lengths).\n", "\n", "\n", "3. Apply Hadamard gates to the first $n$-qubits.\n" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "T : |0| 1 | 2 |3|4|5|6|\n", " \n", "q0 : -H-C-----------C---C-C-C-H-\n", " | | | | | \n", "q1 : -H-|-C---------|-H-|-|-|---\n", " | | | | | | \n", "q2 : -H-|-|-C-------|-H-|-|-|---\n", " | | | | | | | \n", "q3 : -H-|-|-|-C-----|-H-|-|-|---\n", " | | | | | | | | \n", "q4 : -H-|-|-|-|-C---|-H-|-|-|---\n", " | | | | | | | | | \n", "q5 : -H-|-|-|-|-|-C-|-H-|-|-|---\n", " | | | | | | | | | | \n", "q6 : ---X-|-|-|-|-|-X---|-|-|---\n", " | | | | | | | | \n", "q7 : -----X-|-|-|-|-----|-|-|---\n", " | | | | | | | \n", "q8 : -------X-|-|-|-----X-|-|---\n", " | | | | | \n", "q9 : ---------X-|-|-------|-|---\n", " | | | | \n", "q10 : -----------X-|-------X-|---\n", " | | \n", "q11 : -------------X---------X---\n", "\n", "T : |0| 1 | 2 |3|4|5|6|\n" ] } ], "source": [ "n = len(s)\n", "\n", "circ = Circuit()\n", "\n", "# Apply Hadamard gates to first n qubits\n", "circ.h(range(n)) \n", "\n", "# Now apply the Oracle for f\n", "circ.simons_oracle(s)\n", "\n", "# Apply Hadamard gates to the first n qubits\n", "circ.h(range(n)) \n", "\n", "\n", "print(circ)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Now run the circuit\n", "\n", "We need enough shots to obtain $n$ linearly independent bit strings in the output measurements. We have chosen `4n` shots in the example below, just to be on the safe side." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "task = device.run(circ, shots=4*n)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Analyze the results\n", "\n", "We can retrieve the measurement results on all $2n$ qubits as follows:" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYIAAAFICAYAAABdiflbAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4xLjMsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+AADFEAAAgAElEQVR4nO2de7wlVXXnv4tHm0QQ0e5ApGmaiYAyJiJ2kDzMGAUDzGdADVFQwkMMmURJjMlIM2YIkoegcaJxEOUTA2oSkZgJdgwIJiKOIU1oCG8EOjw7GGgRHwlRBNf8UXXp0+fufc7Z61bVvbB/38+nPveeXXvVXrX3rr2qaq/ay9wdIYQQ9bLNYisghBBicZEhEEKIypEhEEKIypEhEEKIypEhEEKIytlusRUoZfny5b569erFVkMIIZ5UXHPNNV919xWpfU86Q7B69Wo2bNiw2GoIIcSTCjO7J7dPr4aEEKJyZAiEEKJyZAiEEKJyZAiEEKJyZAiEEKJyZAiEEKJyejMEZvYnZvagmd2U2W9m9kdmttHMbjCz/fvSRQghRJ4+nwjOBw6ZsP9QYK92Owk4p0ddhBBCZOjNELj7F4GvTchyBPAxb1gPPNPMfqgvfYQQQqRZzC+LdwPuG/m9qU37ynhGMzuJ5qmBVatWhQtcvfZvZs5795n/tUhmLv9QMk+lc4nI6PyfOuff57lEZJ4M5981izlZbIm0ZLg0dz/X3de4+5oVK5JLZQghhAiymIZgE7D7yO+VwP2LpIsQQlTLYhqCdcCxrffQgcA33H3eayEhhBD90tscgZl9AngZsNzMNgG/DWwP4O4fAi4GDgM2Ao8AJ/SlixBCiDy9GQJ3P3rKfgfe3Ff5QgghZkNfFgshROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROXIEAghROX0agjM7BAzu83MNprZ2sT+VWZ2uZn9k5ndYGaH9amPEEKI+fRmCMxs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", "text/plain": [ "
" ] }, "metadata": { "needs_background": "light" }, "output_type": "display_data" } ], "source": [ "result = task.result()\n", "\n", "counts = result.measurement_counts\n", "plt.bar(counts.keys(), counts.values());\n", "plt.xlabel('bit strings');\n", "plt.ylabel('counts');\n", "plt.xticks(rotation=90)\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Aggregate the results" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The measurements are performed on all $2n$ qubits, but we are only interested in the first $n$ qubits. Thus, we need to aggregate the results by ignoring the measurement outcomes on the last $n$ qubits:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "scrolled": true }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "
" ] }, "metadata": { "needs_background": "light" }, "output_type": "display_data" } ], "source": [ "new_results = {}\n", "for bitstring, count in result.measurement_counts.items():\n", " # Only keep the outcomes on first n qubits\n", " trunc_bitstring = bitstring[:n]\n", " # Add the count to that of the of truncated bit string\n", " new_results[trunc_bitstring] = new_results.get(trunc_bitstring, 0) + count\n", "\n", "plt.bar(new_results.keys(), new_results.values())\n", "plt.xlabel('bit strings');\n", "plt.ylabel('counts');\n", "plt.xticks(rotation=70)\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In practice, we only need the measurement results (i.e., the bit strings, not the counts) from the first $n$ qubits. These measurement outcomes correspond to bit strings that satisfy the equations:\n", "$$ \\begin{aligned}z_{1}\\cdot s&=0\\mod{2}\\\\z_{2}\\cdot s&=0\\mod{2}\\\\&\\,\\,\\vdots \\\\z_n\\cdot s&=0\\mod{2}\\end{aligned}$$ \n", "\n", "With these $n$ linear equations in hand, we can use classical post-processing to solve for the unknown string $s$.\n", "\n", "Note that we may have too many bit strings in the above, since we ran the task with $2n$ shots just to be safe. In this case, not all of the bit strings will be linearly independent. Moreover, the all-zeros string $0\\dots0$ may also be an outcome, but this bit string satisfies the equations above trivially, so we exclude it if needed." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "At this stage, the quantum portion of Simon's algorithm is complete. Any remaining steps are just classical postprocessing, which we cover in the Appendix." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### References\n", "[1] Wikipedia: [Simon's Problem](https://en.wikipedia.org/wiki/Simon%27s_problem)\n", "\n", "[2] Wikipedia: [Birthday Problem](https://en.wikipedia.org/wiki/Birthday_problem)\n", "\n", "[3] Wikipedia: [Computing a kernel by Gaussian elimination](https://en.wikipedia.org/wiki/Kernel_(linear_algebra)#Computation_by_Gaussian_elimination)\n", "\n", "[4] StackExchange: [Sympy: Solving Matrices in a finite field](https://stackoverflow.com/questions/31190182/sympy-solving-matrices-in-a-finite-field)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "---" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Appendix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Implementing an Oracle Function" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In order to run the algorithm, we will need a unitary function that we can use as an oracle to query the function $f$.\n", "\n", "There are many possible ways of implementing a function with the desired property that $f(x)=f(y) \\implies x=y\\oplus s$. We will pick one implementation that is commonly used in example code, and we will try to give some intuition for why this oracle works." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Classical Intuition Behind the Function $f$\n", "Generating a function that is one-to-one is conceptually straightforward, as any such function of the bit strings $\\{0,1\\}^n$ will just be a permutation of the inputs. Generating a two-to-one function is a little trickier, though there are many ways to do it. The goal is to define a function that splits the inputs into two groups, such that one element from each group maps to the same output (i.e., $x$ must be in one group, while $x\\oplus s$ must be in the other group.)\n", "\n", "We will implement one simple choice for $f$, in which we define the split based on the value of one of the bits in the string. In this way, exactly half of the inputs will have that bit with value $0$, while the other half will have that bit with value $1$. \n", "\n", "Our approach will be to choose a flag bit in the input bit strings that we will use to split the inputs. We then $\\mathrm{XOR}$ the input string with $s$ whenever the flag bit is $1$. With this definition, half of the input strings will be untouched, while half of the strings will be $\\mathrm{XOR}$'ed with $s$. Clearly, this function does nothing to the all-zeros string $0\\dots 0$, since any choice of the flag bit will always be $0$. Thus, we need to ensure that our definition also maps the string $s$ to the all-zeros string $0\\dots 0$. In other words, we need to ensure that our flag bit is $1$ when the input string is $s$. One way to ensure the function acts correctly on the input $s$ is to just define the flag bit to be the first bit in the string $s$ that is equal to $1$. For example, if $s=011$, we can choose the flag bit to be the second bit. Concretely:\n", "$$f(x) = \\left\\{\\begin{array}{lr}\n", "x, & \\text{if } x_j=0\\\\\n", "x\\oplus s, & \\text{if } x_j=1\\\\\n", "\\end{array}\\right\\},$$\n", "where $x_j$ is the $j^\\text{th}$ bit of $x$, and $j$ is the flag bit in $s$." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "

Example for n=3:

\n", "\n", "We now revisit the example in the introduction. Suppose the secret string $s=011$. Since the first appearance of $1$ in $s$ occurs at the second bit, we will use the second bit in the input strings as our flag bit. We take the $\\mathrm{XOR}$ of the input with $s$ whenever the flag bit in the input is 1. This definition results in the following truth table: \n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
$$x$$
$$f(x)$$
$$000$$
$$000$$
$$001$$
$$001$$
$$010$$
$$001$$
$$011$$
$$000$$
$$100$$
$$100$$
$$101$$
$$101$$
$$110$$
$$101$$
$$111$$
$$100$$
\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We leave it as an exercise to the reader to verify that this definition works for any input string size (i.e., $n$ for inputs $\\{0,1\\}^n$, and that it is in fact two-to-one, rather than many-to-one. Note that the function defined in this way is not a general two-to-one function, but it is simple a choice that is easy to implement both classically and as a quantum circuit." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Quantum Implementation of $U_f$\n", "We now define the unitary using the `@circuit.subroutine` functionality of the Amazon Braket SDK. The following code was imported from the `simons_utils.py` module, and is shown below for reference. \n", "\n", "In the quantum setting, we first copy the input register into some ancillary qubits:\n", "$$ |x\\rangle|0\\rangle\\mapsto |x\\rangle|x\\rangle.$$\n", "We then perform the quantum analog of $\\mathrm{XOR}$, which means we apply an $X$ gate to the $k^\\text{th}$ qubit whenever the $k^\\text{th}$ bit of $s$ is $1$. However, we only apply this $X$ gate when the flag qubit is also $|1\\rangle$. Thus, our $X$ gate becomes a $\\mathrm{CNOT}$ gate between the flag qubit on the input register, and the $k^\\text{th}$ qubit on the output." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```python\n", "from braket.circuits import Circuit, circuit\n", "\n", "@circuit.subroutine(register=True)\n", "def simons_oracle(secret_s: str):\n", " \"\"\"\n", " Quantum circuit implementing a particular oracle for Simon's problem. Details of this implementation are\n", " explained in the Simons Algorithm demo notebook.\n", "\n", " Args:\n", " secret_s (str): secret string we wish to find\n", " \"\"\"\n", " # Find the index of the first 1 in s, to be used as the flag bit\n", " flag_bit=secret_s.find('1')\n", " \n", " n=len(secret_s)\n", " \n", " circ = Circuit()\n", " # First copy the first n qubits, so that |x>|0> -> |x>|x>\n", " for i in range(n):\n", " circ.cnot(i, i+n)\n", " \n", " # If flag_bit=-1, s is the all-zeros string, and we do nothing else.\n", " if flag_bit != -1:\n", " # Now apply the XOR with s whenever the flag bit is 1.\n", " for index,bit_value in enumerate(secret_s):\n", " \n", " if bit_value not in ['0','1']:\n", " raise Exception ('Incorrect char \\'' + bit_value + '\\' in secret string s:' + secret_s)\n", " \n", " # XOR with s whenever the flag bit is 1.\n", " # In terms of gates, XOR means we apply an X gate only whenever the corresponding bit in s is 1.\n", " # Applying this X only when the flag qubit is 1 means this is a CNOT gate.\n", " if(bit_value == '1'):\n", " circ.cnot(flag_bit,index+n)\n", " return circ\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Implementing the Classical Post-Processing\n", "\n", "We will now solve the system of linear equations above using Gaussian elimination. We first convert the results into matrix form, then we use `sympy`'s `Matrix.rref()` method to transform the matrix into reduced row echelon form. " ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": [ "!pip3 install sympy --quiet\n", "from sympy import Matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Generate a matrix from the bit string outputs. We first check that we have sufficiently many output strings to be able to solve the system of equations. If not: output and error and re-run the algorithm." ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "The result in matrix form is :\n", "[1, 0, 0, 0, 0, 1]\n", "[0, 1, 0, 0, 0, 0]\n", "[0, 0, 1, 0, 0, 1]\n", "[1, 1, 1, 1, 1, 1]\n", "[0, 1, 1, 0, 1, 0]\n", "[0, 1, 1, 1, 1, 0]\n", "[1, 0, 1, 0, 1, 1]\n", "[0, 1, 0, 0, 1, 1]\n", "[1, 1, 0, 1, 0, 1]\n", "[1, 1, 0, 0, 0, 1]\n", "[0, 0, 1, 1, 0, 1]\n", "[0, 1, 0, 1, 0, 0]\n", "[0, 1, 1, 0, 0, 1]\n", "[0, 0, 1, 0, 1, 0]\n", "[1, 0, 1, 1, 1, 1]\n", "[1, 0, 1, 0, 0, 0]\n", "[0, 1, 1, 1, 0, 1]\n", "[1, 0, 0, 1, 0, 1]\n", "[1, 0, 0, 1, 1, 0]\n", "[0, 0, 0, 0, 0, 0]\n" ] } ], "source": [ "if len(new_results.keys()) < len(s):\n", " raise Exception ('System will be underdetermined. Minimum ' + str(n) + ' bistrings needed, but only '\n", " + str(len(new_results.keys())) +' returned. Please rerun Simon\\'s algorithm.')\n", "string_list = []\n", "\n", "for key in new_results.keys():\n", "# if key!= \"0\"*n:\n", " string_list.append( [ int(c) for c in key ] )\n", " \n", "print('The result in matrix form is :')\n", "for a in string_list:\n", " print (a)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now solve the system $Ms=0$ by finding the kernel of $M$. We do this using Gaussian elimination on the augmented matrix $\\left[A|I\\right]$ to bring it to row echelon form. Converting the solution to numbers $\\mathrm{mod }\\,2$, we can then read off the solution from the last row of the reduced matrix. See [[3]](#References) and [[4]](#References) for more details." ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "scrolled": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Secret string: 101011\n", "Result string: 101011\n", "We found the correct answer.\n" ] } ], "source": [ "M=Matrix(string_list).T\n", "\n", "# Construct the agumented matrix\n", "M_I = Matrix(np.hstack([M,np.eye(M.shape[0],dtype=int)]))\n", "\n", "# Perform row reduction, working modulo 2. We use the iszerofunc property of rref\n", "# to perform the Gaussian elimination over the finite field.\n", "M_I_rref = M_I.rref(iszerofunc=lambda x: x % 2==0)\n", "\n", "# In row reduced echelon form, we can end up with a solution outside of the finite field {0,1}.\n", "# Thus, we need to revert the matrix back to this field by treating fractions as a modular inverse.\n", "# Since the denominator will always be odd (i.e. 1 mod 2), it can be ignored.\n", "\n", "# Helper function to treat fractions as modular inverse:\n", "def mod2(x):\n", " return x.as_numer_denom()[0] % 2\n", "\n", "# Apply our helper function to the matrix\n", "M_I_final = M_I_rref[0].applyfunc(mod2)\n", "\n", "# Extract the kernel of M from the remaining columns of the last row, when s is nonzero.\n", "if all(value == 0 for value in M_I_final[-1,:M.shape[1]]):\n", " result_s=\"\".join(str(c) for c in M_I_final[-1,M.shape[1]:])\n", "\n", "# Otherwise, the sub-matrix will be full rank, so just set s=0...0\n", "else:\n", " result_s='0'*M.shape[0]\n", "\n", "# Check whether result_s is equal to initial s:\n", "print ('Secret string: ' + s)\n", "print ('Result string: ' + result_s)\n", "if (result_s == s):\n", " print ('We found the correct answer.')\n", "else:\n", " print ('Error. The answer is wrong!')" ] } ], "metadata": { "kernelspec": { "display_name": "braket060", "language": "python", "name": "braket060" }, "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.7.6" } }, "nbformat": 4, "nbformat_minor": 2 }